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.

docs/final-structure-cleanup/results.json

@@ -0,0 +1,44 @@
+{
+  "date": "2026-09-12",
+  "baseline": {
+    "artifact": "mandelbrot-cleaned-all/index.html",
+    "bytes": 212483,
+    "gzip9_bytes_shell": 53779
+  },
+  "final": {
+    "index_bytes": 208576,
+    "gzip9_bytes_shell": 52563,
+    "sha256": "8355da57e2f546c4e1cbeb2237e9dbfb65168b6d4c254929a2b02078c086a935",
+    "wgsl_kernels": 19,
+    "persistent_test_html": false,
+    "definition_only_locals_or_functions": 0
+  },
+  "change": {
+    "index_bytes": -3907,
+    "index_percent": -1.8387,
+    "gzip9_bytes_shell": -1216,
+    "gzip9_percent": -2.2616
+  },
+  "kernel_equivalence": {
+    "kernel_object_keys_including_version": 20,
+    "byte_identical_without_normalization": 9,
+    "byte_identical_after_removing_old_unused_FIELD_INTERIOR_LIKELY_line": 20,
+    "behavioral_kernel_changes": 0
+  },
+  "regression": {
+    "status": "PASS",
+    "runs_after_warmup": 12,
+    "median_ms": 54.8059,
+    "min_ms": 47.6742,
+    "max_ms": 71.0208
+  },
+  "browser_smoke": {
+    "script_syntax": "PASS",
+    "temporary_file_cleanup_on_connection_failure": "PASS",
+    "real_webgpu_run": "not available in this environment"
+  },
+  "fixed_bugs": [
+    "cancelRender production typo truestate.token++",
+    "render error/cancellation typo returnfinishRenderClock(...)"
+  ]
+}