publish

docs/final-structure-cleanup/IMPLEMENTATION.md

@@ -0,0 +1,83 @@
+# Final structure cleanup — 2026-09-12
+
+## Intent
+
+Finish the structural cleanup after the component pruning pass without changing Mandelbrot numerical behavior. The production HTML is now the single source of truth for both release and regression.
+
+## Changes
+
+### Single source of truth
+
+- Removed the persistent `tests/index.test.html` copy.
+- `tests/regression.mjs` now parses and executes production `index.html` directly.
+- `tests/browser_smoke.mjs` generates a temporary instrumented page from production `index.html`, then removes it even when browser connection fails.
+- Added a regression assertion that a persistent test HTML copy must not reappear.
+
+### Correctness fixes found during cleanup
+
+- Fixed `cancelRender()` export cancellation/generation update. The production-only typo `truestate.token++` is gone; export cancellation and `state.token++` are separate operations.
+- Fixed the render cancellation/error path that called the nonexistent `returnfinishRenderClock(...)` token. Cancelled generations now close the render clock correctly and return.
+
+### Removed write-only state and UI churn
+
+Removed production state that had no readers:
+
+- `lastEngine`
+- `frontierRounds`
+- `frontierPixels`
+- `frontierEscaped`
+- `frontierIter`
+- `frontierMinimumIter`
+- `frontierConverged`
+- `gpuUnavailable`
+- `qualityIter`
+- `refineMs`
+- `lastRender`
+- `gpuStage`
+
+Progress-only `lastEngine` assignments and their no-op `updateStats()` calls were removed. The user-visible status continues to derive from `drawState`, unresolved counts, temporal fill, render clock, and GPU error state.
+
+### Renderer diagnostics
+
+Removed retained diagnostics that were never consumed:
+
+- `this.adapter`
+- `this.adapterInfo`
+- `this.compilation`
+- `this.uncapturedErrors`
+
+Shader compilation errors are still checked and thrown immediately. The latest uncaptured GPU error is still copied to `state.gpuError`. Device-loss stage tracking stays in renderer-local `activeGpuStage` / `lastCompletedGpuStage`.
+
+### Fixed-point / WGSL dead definitions
+
+- Removed production-only unused `fromDec()` and `decimalRequiredBits()` helpers. Test decimal conversion now lives only in the test harness.
+- Removed unused WGSL `FIELD_INTERIOR_LIKELY`.
+- All 19 surviving kernels are byte-identical to the pre-cleanup kernels after deleting that single unused constant line.
+- Simplified stale reference-selector comments and redundant return logic.
+
+### Export metadata
+
+Both export paths now call one `buildExportMetadata()` function. Common fields now have one definition for:
+
+- finite-budget completion
+- membership certification
+- precision policy
+- iteration policy
+- view coordinates
+- palette description
+- renderer/shader version
+- pixel contract
+
+Path-specific tile/ring fields are added only when applicable.
+
+### Small dead-code cleanup
+
+- Removed dead `dispatchWork` local after correction accounting was deleted.
+- Removed dead `sampleCount`, `lastUi`, and final-frame `elapsed` locals.
+- Renamed stale `reusePreview` to `reusePriorField` and the no-frame `PREVIEW` draw-state label to `PENDING`.
+
+## Verification
+
+`node tests/regression.mjs` passes and directly executes production JS. It covers routing, finite-budget semantics, staged operation-limit scoring, exact interior proof, integer-grid history reuse, nearby reference reuse, Worker lifecycle, correction pipeline count, export cancellation/generation behavior, common export metadata, pinned WGSL hashes, and CPU worker smoke tests.
+
+The optional browser smoke script passes syntax validation. A real WebGPU browser run is not claimed in this environment.