Verify production-client migration and record Phase 1 measurements

perf/README.md

@@ -141,3 +141,43 @@ node perf/hidden-timers.mjs
 ```
 Exits with code 0 on success, or code 1 if any interval fails to pause, fails to resume, or if page errors occur.
 
+## Phase 1 production-client migration
+
+Build the production fixture locally without contacting the unavailable production
+site (COMMON.md takes precedence over the older live-tag instructions above):
+
+```bash
+perf/make-shell-fixture.sh b77938a 1175f1a1d2c1
+node perf/migration.mjs                    # Chromium and WebKit
+node perf/migration.mjs --browser webkit  # one browser
+```
+
+The harness archives the actual `b77938a` server and uses the reconstructed old
+frontend, isolated database/media/upload paths, and an ephemeral origin behind the
+`lossy` throttle/stall proxy. It restarts onto the current server and frontend at
+that same origin, then invokes the OLD application's update check and clicks its
+actual Refresh UI button. Assertions cover one banner, exactly one reload, cleared
+update-attempt state, all new SHELL entries with correct hashes, no script errors,
+and offline boot. Plain, stale `?v=<oldTag>` and `?__ytpfresh=` asset responses are
+also compared byte-for-byte with the current files. Results are stored in
+`perf/results/phase1-migration-2026-10-07.json`; scratch trees are removed on exit.
+No service-worker source is patched or simulated. Offline checks stop Bun and
+block the proxy; WebKit avoids its broken native setOffline API. Known WebKit
+transport errors for disconnected version/recommendation requests are verified
+separately from script errors.
+
+The current server snapshots static bytes at boot; restart it after frontend
+changes. `ASSET_HASHING=0` restores the previous single-tag stamp/cache behavior.
+The manifest's tag hashes sorted canonical metadata: CSS/JS URLs are stamped
+before hashing the index, with its derived build-meta placeholder intact. The
+published index/SW hashes describe their final served bytes after tag injection;
+these derived hashes are not fed recursively into their own build identity.
+
+JS-created workers/importScripts/dynamic imports retain their existing plain URLs
+in Phase 1. Adding a separate loader would require changing the intentionally
+unchanged SHELL; worker import URL propagation belongs with the client migration.
+WASM binaries are embedded in the existing `sha256-wasm.js`/`loudness-wasm.js`,
+which receive hashed URLs as HTML scripts. Font preloads retain plain URLs to match
+`fonts.css`; the webmanifest and its icon URLs also stay plain and precached.
+`piano-engine.mjs` is manifested but is historically absent from SHELL; this
+existing offline piano limitation is deferred to the loader phase.