@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md

@@ -1,359 +1,359 @@
-# v0.9.1 Batch 1 report: PWA hard-gate isolation
-
-## 1. VERDICT
-
-`PASS_V0_9_1_BATCH1_PWA_HARD_GATE_ISOLATED`
-
-The PWA server-down hard gate is now a self-contained experiment. It passes when
-selected alone and when the whole PWA file runs. No production file changed. No
-product defect was found.
-
-This report covers Batch 1 only. v0.9.1 is not released. Full repository
-regression and cross-platform release readiness are not complete. Batch 2 owns
-them.
-
-## 2. Repository identity
-
-1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
-2. Package: `@dailephd/my-frontend-observer`, version `0.9.0` (unchanged)
-3. Branch: `feature/v0.9.1-pwa-hard-gate-isolation`, created from `master`
-4. Starting HEAD: `985d0ce47a070fd9f84eae478f4098df00d57bd8` (merge of PR #15)
-5. Released baseline: v0.9.0 at `eacd543f64d45d8b721e766173af87e6a878152c`
-6. Runtime: Node `v24.20.0`, Playwright `1.62.1`, Vitest `4.1.11`, Windows 11
-
-## 3. Planning authority
-
-1. PR #15 (`docs: plan v0.9.1 PWA hard-gate isolation`) was merged into `master`
-   at 2026-09-21T15:11:04Z as `985d0ce`.
-2. `docs/plans/v0.9.1-implementation-plan.md` is present on `master` and was
-   read in full. It is the frozen authority for this batch.
-3. The planning doc changes in `ROADMAP.md`, `CURRENT_STATE.md`,
-   `DEVELOPMENT.md`, `CI_CD.md`, and `PROJECT_MILESTONES.md`, plus
-   `DOCUMENTATION_PRESERVATION_POLICY.md`, were read.
-4. A first attempt at this prompt stopped with
-   `BLOCKED_V0_9_1_PLANNING_NOT_MERGED` because PR #15 was still open. No changes
-   were made in that attempt.
-
-## 4. Original isolated failure reproduction
-
-After `npm run build` (exit 0), this command ran against the unchanged test:
-
-`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
-
-1. Exit code: 1
-2. Result: 1 failed, 6 skipped
-3. Failure step: `await page.reload()` right after `server.close()`
-4. Failure message: `page.reload: net::ERR_CONNECTION_REFUSED`
-5. Shell reload failed: yes. The page was not served by a service worker.
-6. Evidence-unavailable assertion reached: no. The test failed before it.
-
-A diagnostic outside the repository (scratchpad only, not committed) repeated
-the original steps and recorded service-worker and cache state at the moment the
-original test shut the server down. The result was the same with the historical
-fixed profile and with a fresh temporary profile:
-
-1. Registration present: true
-2. Worker state: `installing` = true, `active` = null
-3. `navigator.serviceWorker.controller`: null
-4. Cache Storage: one `workbox-precache-v2-<origin>/` cache with 5 entries, so
-   the precache was still being filled
-5. Reload after close: `net::ERR_CONNECTION_REFUSED`
-
-So service-worker control and a complete shell cache were both absent at the
-shutdown boundary.
-
-## 5. Root cause
-
-Two faults combined.
-
-1. The wait condition was wrong. The old test waited for
-   `(await navigator.serviceWorker.getRegistration())?.active !== undefined`.
-   `registration.active` is `null`, not `undefined`, while a worker is still
-   installing. The condition was therefore true as soon as any registration
-   existed. It never proved activation, control, or a filled precache.
-2. The test relied on shared state. In normal file order, earlier tests in the
-   same describe had already used the same server origin and the same
-   persistent context. By the time the hard gate ran, the worker was active and
-   controlling that origin, so the weak wait did not matter.
-
-When selected alone, the viewer server starts on a new random port (`port: 0`).
-That is a new origin with no worker. The fixed profile's older registrations
-belong to other origins and do not help. The page was still uncontrolled when
-the server closed, so the reload went to the network and failed.
-
-Classification stays `TEST_DEFECT`. `PRODUCT_CHANGE_REQUIRED = false`.
-
-## 6. Previous shared-state topology
-
-In the first describe block, `beforeAll` created and shared:
-
-1. one evidence root from `mkdtemp`
-2. one viewer server
-3. one persistent Chromium context launched from the fixed profile
-   `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
-
-The hard gate was the fourth `it()` in that block. The three earlier tests
-registered the worker, fetched the manifest, and warmed the cache on the same
-origin. The fixed profile also kept service-worker and cache data between local
-runs. That block's `afterAll` never closed its server. Only the hard gate's
-mid-test `server.close()` shut it down.
-
-## 7. New hard-gate resource ownership
-
-The hard gate now lives in its own describe block:
-`PWA server-down safety - self-contained hard-gate experiment`. It has no
-`beforeAll` and uses no describe-level variables. Inside the test it creates and
-owns:
-
-1. an evidence root:
-   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-evidence-'))`
-2. the fixture, through the existing helpers `writeManyRegionsOneTargetFixture`
-   and `persistAnnotationUnder`. These are now wrapped by a local
-   `writePwaFixture` helper that both describe blocks use. The real annotation
-   is kept so the annotation view and media routes are part of the cache
-   boundary.
-3. a dedicated viewer server from `startViewer` on port 0
-4. a persistent profile:
-   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-profile-'))`
-5. a `BrowserContext` from
-   `chromium.launchPersistentContext(profileRoot, { headless: true })`
-6. a fresh page
-
-The test name is unchanged, so `-t "HARD GATE"` still selects it.
-
-## 8. Fresh-profile design
-
-1. The hard gate uses its own temporary profile and context. It never shares
-   one with any other test.
-2. The first describe block, which keeps the focused registration, manifest,
-   and `/api/` cache tests, now creates its own temporary profile
-   (`my-frontend-observer-pwa-profile-*`) in `beforeAll` and deletes it in
-   `afterAll`.
-3. That `afterAll` now also closes its viewer server, since the hard gate no
-   longer closes it.
-4. The constant for `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile` was
-   removed. No test uses that path any more. The historical directory itself was
-   left on disk untouched.
-5. Profile and evidence removal uses
-   `rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })`,
-   because Chromium can briefly hold profile files after close on Windows.
-
-## 9. Service-worker registration proof
-
-After the first navigation, the test evaluates `navigator.serviceWorker.ready`
-in the real page and requires:
-
-1. `registration.active !== null` is true
-2. `registration.scope` equals `<viewer origin>/`
-
-`ready` only resolves when a worker is active, so there is no fixed sleep.
-
-Observed: `serviceWorkerActive = true`.
-
-## 10. Current-client control proof
-
-Control is checked on its own, apart from activation:
-
-1. The test reads `navigator.serviceWorker.controller !== null`.
-2. If it is null, the page reloads while the server is still live.
-3. The test then waits (bounded at 10 seconds) for
-   `navigator.serviceWorker.controller !== null`.
-4. It requires `controller.scriptURL` to equal `<viewer origin>/sw.js`.
-
-Observed: `controlledOnFirstLoad = true` and `clientControlled = true`. The
-generated worker calls `self.skipWaiting()` and `clientsClaim()`, so once
-activation finishes it takes control of the first page. The reload branch
-stays in place for any platform where control arrives later.
-
-## 11. App-shell cache proof
-
-The test reads every Cache Storage entry from the page before shutdown. It
-requires:
-
-1. at least one cache whose name starts with `workbox-precache`
-2. cached pathnames that include `/index.html`, `/registerSW.js`, and
-   `/manifest.webmanifest`
-3. a cached `/index.html` (matched with `ignoreSearch`, because Workbox adds
-   `__WB_REVISION__`) whose body contains `<div id="root"></div>`
-4. that the module entry script named inside that cached `index.html` matches
-   `/assets/*.js` and is itself in the cache
-
-Why this is stable: the generated `sw.js` precaches `index.html`,
-`registerSW.js`, and `manifest.webmanifest` under fixed names, and serves
-navigations with `createHandlerBoundToURL("index.html")`. Only the Vite asset
-names are hashed. The test never hardcodes a hash. It reads the entry script
-name from the cached shell, so the check stays valid across rebuilds.
-
-Observed: 7 cached entries (index, registerSW, manifest, two icons, one JS
-bundle, one CSS bundle).
-
-## 12. API cache-exclusion proof
-
-From the controlled page, the hard gate first fetches `/api/index`, the
-annotation view route, and the annotation overlay media route. It requires each
-to return `200` with `cache-control: no-store`. It then counts cached requests
-whose pathname starts with `/api/` across every cache.
-
-Observed: `apiCacheEntryCount = 0`.
-
-The separate focused test `never caches /api/ responses at the service-worker
-cache-storage layer` was kept. The hard gate does not depend on it.
-
-## 13. Live evidence proof
-
-Before shutdown the test:
-
-1. waits for the first `.evidence-list__item`
-2. requires it to be visible
-3. requires the `.evidence-list` text to contain the fixture candidate id
-   `many-regions-candidate` (read from the fixture helper's return value, not
-   hardcoded)
-4. makes a direct Node-side `fetch` to `/api/index` (5 second timeout) and
-   requires HTTP 200 with a body that contains the same candidate id
-
-## 14. Server-down proof
-
-After `await server.close()` the test makes a direct Node-side `fetch` to the
-same `/api/index` URL with a 5 second timeout. A Node request cannot be
-intercepted by the page's service worker, so this tests the origin server alone.
-The test requires the request to fail. If it gets any HTTP response, the test
-fails with that status in the message.
-
-The page was not navigated away. The controlled page and worker stayed in place.
-
-## 15. Offline reload proof
-
-Only after the checks in sections 9 to 14 pass does the test call
-`page.reload()`. It then requires:
-
-1. `h1, header` to render within 10 seconds, so the shell was served from the
-   precache
-2. `navigator.serviceWorker.controller !== null` after the reload
-
-## 16. Stale-evidence safety proof
-
-After the offline reload the test requires:
-
-1. `.evidence-list__error` to appear
-2. body text to contain `Evidence index unavailable`
-3. body text not to contain the previously visible candidate id
-4. zero `.evidence-list__item` elements
-
-These assertions are unchanged from the original or stricter. None were
-weakened.
-
-## 17. Cleanup proof
-
-Cleanup runs in `finally` in a fixed order: close the context, close the server
-unless it was already closed on purpose, remove the evidence root, remove the
-profile. Each step runs even if an earlier step fails. Errors are collected.
-
-1. If the experiment failed, cleanup errors are logged with `console.error` and
-   the original assertion error is what the test reports.
-2. If the experiment passed but cleanup failed, the test fails with every
-   cleanup error listed.
-3. After cleanup, the test requires that neither the evidence root nor the
-   profile directory exists.
-
-A leak audit counted `my-frontend-observer-pwa-*` and
-`my-frontend-observer-b8-pwa*` directories under the OS temp directory before
-and after each run. All counts were 0. That covers the hard gate's profile and
-evidence root and the first describe block's temporary profile and evidence
-root.
-
-Not executed: the failure-path cleanup (steps 1 and 2 above) was not triggered
-on purpose. It is supported by code inspection only.
-
-## 18. Isolated run #1
-
-`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
-
-PASS. 1 passed, 6 skipped. Exit 0. The run came right after a fresh
-`npm run build`.
-
-## 19. Isolated run #2
-
-The same command was run again right away. PASS. 1 passed, 6 skipped. Exit 0.
-
-The isolated command was run five times in total over the edits. The final two
-runs, on the committed test content, both passed. One of them used
-`--reporter=verbose` and printed the boundary line:
-
-`HARD GATE pre-shutdown boundary {"serviceWorkerActive":true,"controlledOnFirstLoad":true,"clientControlled":true,"shellEntryScriptCached":true,"precacheEntryCount":7,"apiCacheEntryCount":0,"liveEvidenceVisible":true}`
-
-That line was produced by the test itself after its assertions passed.
-
-## 20. Full PWA file result
-
-`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts`
-
-PASS. 7 passed. Exit 0.
-
-## 21. Typecheck/lint
-
-1. `npm run typecheck`: PASS (exit 0).
-2. `npm run lint`: PASS (exit 0). The first lint run failed with
-   `no-unsafe-finally` because the cleanup error was thrown inside `finally`.
-   The throw was moved after the `try/finally` block, then isolated runs 1 and 2,
-   the full file, typecheck, and lint were all run again and passed.
-
-## 22. Production-code audit
-
-`git diff --name-only` lists only `tests/browser/pwaHardening.test.ts` plus this
-report. No file under `src/` or `viewer/` changed. `viewer/vite.config.ts`,
-the service-worker caching policy, `package.json`, `package-lock.json`,
-`.github/workflows/`, and `CHANGELOG.md` were not touched. `git diff --check`
-passed.
-
-## 23. Product-defect decision
-
-1. `PRODUCT_DEFECT_DISCOVERED = false`
-2. `PRODUCT_CHANGE_REQUIRED = false`
-
-With every precondition proven, the released v0.9.0 viewer shell loads offline
-from the precache. The evidence surface shows its explicit unavailable state.
-Previously fetched evidence is not shown as current. The original failure came
-only from the test's weak wait and its reliance on shared state.
-
-## 24. Changed files
-
-1. `tests/browser/pwaHardening.test.ts`
-2. `docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md`
-
-Generated paths (all removed by the tests or kept outside the repository):
-
-1. `%TEMP%\my-frontend-observer-pwa-hard-gate-evidence-*` (removed)
-2. `%TEMP%\my-frontend-observer-pwa-hard-gate-profile-*` (removed)
-3. `%TEMP%\my-frontend-observer-pwa-profile-*` and
-   `%TEMP%\my-frontend-observer-b8-pwa-*` (removed)
-4. The diagnostic script and config in the Claude Code session scratchpad
-   (outside the repository, not committed)
-5. `dist/` from `npm run build` (ignored build output)
-
-These small temporary directories sit under the OS temp directory on `C:\`, as
-the task's `mkdtemp(tmpdir())` design specifies. They are deleted at the end of
-every passing run.
-
-## 25. Batch 2 handoff
-
-Batch 2 still owns:
-
-1. the permanent `test:pwa-hard-gate` package script
-2. wiring that command into the security or pre-release readiness path
-3. moving `CURRENT_STATE.md`, `ROADMAP.md`, `DEVELOPMENT.md`, `CI_CD.md`, and
-   `CHANGELOG.md` from planned to implemented wording
-4. the full unit, browser, security, build, docs, and pack validation
-
-Notes for Batch 2:
-
-1. The focused test `never caches /api/ responses` still uses the same weak
-   `?.active !== undefined` wait that the old hard gate used. It stays correct
-   in file order, because it runs after the registration test on the same
-   origin. If it is ever meant to stand alone, it should wait on
-   `navigator.serviceWorker.ready` instead. It was not changed here to keep
-   Batch 1 narrow.
-2. The standalone display-mode test still writes a log to
-   `.my-dev-kit-workflow/v0.8/batch-08/logs`. That is a log file, not a browser
-   profile, and was not changed.
-3. The historical directory `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
-   still exists on disk. No test needs it now. It was not deleted.
+# v0.9.1 Batch 1 report: PWA hard-gate isolation
+
+## 1. VERDICT
+
+`PASS_V0_9_1_BATCH1_PWA_HARD_GATE_ISOLATED`
+
+The PWA server-down hard gate is now a self-contained experiment. It passes when
+selected alone and when the whole PWA file runs. No production file changed. No
+product defect was found.
+
+This report covers Batch 1 only. v0.9.1 is not released. Full repository
+regression and cross-platform release readiness are not complete. Batch 2 owns
+them.
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Package: `@dailephd/my-frontend-observer`, version `0.9.0` (unchanged)
+3. Branch: `feature/v0.9.1-pwa-hard-gate-isolation`, created from `master`
+4. Starting HEAD: `985d0ce47a070fd9f84eae478f4098df00d57bd8` (merge of PR #15)
+5. Released baseline: v0.9.0 at `eacd543f64d45d8b721e766173af87e6a878152c`
+6. Runtime: Node `v24.20.0`, Playwright `1.62.1`, Vitest `4.1.11`, Windows 11
+
+## 3. Planning authority
+
+1. PR #15 (`docs: plan v0.9.1 PWA hard-gate isolation`) was merged into `master`
+   at 2026-09-21T15:11:04Z as `985d0ce`.
+2. `docs/plans/v0.9.1-implementation-plan.md` is present on `master` and was
+   read in full. It is the frozen authority for this batch.
+3. The planning doc changes in `ROADMAP.md`, `CURRENT_STATE.md`,
+   `DEVELOPMENT.md`, `CI_CD.md`, and `PROJECT_MILESTONES.md`, plus
+   `DOCUMENTATION_PRESERVATION_POLICY.md`, were read.
+4. A first attempt at this prompt stopped with
+   `BLOCKED_V0_9_1_PLANNING_NOT_MERGED` because PR #15 was still open. No changes
+   were made in that attempt.
+
+## 4. Original isolated failure reproduction
+
+After `npm run build` (exit 0), this command ran against the unchanged test:
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
+
+1. Exit code: 1
+2. Result: 1 failed, 6 skipped
+3. Failure step: `await page.reload()` right after `server.close()`
+4. Failure message: `page.reload: net::ERR_CONNECTION_REFUSED`
+5. Shell reload failed: yes. The page was not served by a service worker.
+6. Evidence-unavailable assertion reached: no. The test failed before it.
+
+A diagnostic outside the repository (scratchpad only, not committed) repeated
+the original steps and recorded service-worker and cache state at the moment the
+original test shut the server down. The result was the same with the historical
+fixed profile and with a fresh temporary profile:
+
+1. Registration present: true
+2. Worker state: `installing` = true, `active` = null
+3. `navigator.serviceWorker.controller`: null
+4. Cache Storage: one `workbox-precache-v2-<origin>/` cache with 5 entries, so
+   the precache was still being filled
+5. Reload after close: `net::ERR_CONNECTION_REFUSED`
+
+So service-worker control and a complete shell cache were both absent at the
+shutdown boundary.
+
+## 5. Root cause
+
+Two faults combined.
+
+1. The wait condition was wrong. The old test waited for
+   `(await navigator.serviceWorker.getRegistration())?.active !== undefined`.
+   `registration.active` is `null`, not `undefined`, while a worker is still
+   installing. The condition was therefore true as soon as any registration
+   existed. It never proved activation, control, or a filled precache.
+2. The test relied on shared state. In normal file order, earlier tests in the
+   same describe had already used the same server origin and the same
+   persistent context. By the time the hard gate ran, the worker was active and
+   controlling that origin, so the weak wait did not matter.
+
+When selected alone, the viewer server starts on a new random port (`port: 0`).
+That is a new origin with no worker. The fixed profile's older registrations
+belong to other origins and do not help. The page was still uncontrolled when
+the server closed, so the reload went to the network and failed.
+
+Classification stays `TEST_DEFECT`. `PRODUCT_CHANGE_REQUIRED = false`.
+
+## 6. Previous shared-state topology
+
+In the first describe block, `beforeAll` created and shared:
+
+1. one evidence root from `mkdtemp`
+2. one viewer server
+3. one persistent Chromium context launched from the fixed profile
+   `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
+
+The hard gate was the fourth `it()` in that block. The three earlier tests
+registered the worker, fetched the manifest, and warmed the cache on the same
+origin. The fixed profile also kept service-worker and cache data between local
+runs. That block's `afterAll` never closed its server. Only the hard gate's
+mid-test `server.close()` shut it down.
+
+## 7. New hard-gate resource ownership
+
+The hard gate now lives in its own describe block:
+`PWA server-down safety - self-contained hard-gate experiment`. It has no
+`beforeAll` and uses no describe-level variables. Inside the test it creates and
+owns:
+
+1. an evidence root:
+   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-evidence-'))`
+2. the fixture, through the existing helpers `writeManyRegionsOneTargetFixture`
+   and `persistAnnotationUnder`. These are now wrapped by a local
+   `writePwaFixture` helper that both describe blocks use. The real annotation
+   is kept so the annotation view and media routes are part of the cache
+   boundary.
+3. a dedicated viewer server from `startViewer` on port 0
+4. a persistent profile:
+   `mkdtemp(path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-profile-'))`
+5. a `BrowserContext` from
+   `chromium.launchPersistentContext(profileRoot, { headless: true })`
+6. a fresh page
+
+The test name is unchanged, so `-t "HARD GATE"` still selects it.
+
+## 8. Fresh-profile design
+
+1. The hard gate uses its own temporary profile and context. It never shares
+   one with any other test.
+2. The first describe block, which keeps the focused registration, manifest,
+   and `/api/` cache tests, now creates its own temporary profile
+   (`my-frontend-observer-pwa-profile-*`) in `beforeAll` and deletes it in
+   `afterAll`.
+3. That `afterAll` now also closes its viewer server, since the hard gate no
+   longer closes it.
+4. The constant for `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile` was
+   removed. No test uses that path any more. The historical directory itself was
+   left on disk untouched.
+5. Profile and evidence removal uses
+   `rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 })`,
+   because Chromium can briefly hold profile files after close on Windows.
+
+## 9. Service-worker registration proof
+
+After the first navigation, the test evaluates `navigator.serviceWorker.ready`
+in the real page and requires:
+
+1. `registration.active !== null` is true
+2. `registration.scope` equals `<viewer origin>/`
+
+`ready` only resolves when a worker is active, so there is no fixed sleep.
+
+Observed: `serviceWorkerActive = true`.
+
+## 10. Current-client control proof
+
+Control is checked on its own, apart from activation:
+
+1. The test reads `navigator.serviceWorker.controller !== null`.
+2. If it is null, the page reloads while the server is still live.
+3. The test then waits (bounded at 10 seconds) for
+   `navigator.serviceWorker.controller !== null`.
+4. It requires `controller.scriptURL` to equal `<viewer origin>/sw.js`.
+
+Observed: `controlledOnFirstLoad = true` and `clientControlled = true`. The
+generated worker calls `self.skipWaiting()` and `clientsClaim()`, so once
+activation finishes it takes control of the first page. The reload branch
+stays in place for any platform where control arrives later.
+
+## 11. App-shell cache proof
+
+The test reads every Cache Storage entry from the page before shutdown. It
+requires:
+
+1. at least one cache whose name starts with `workbox-precache`
+2. cached pathnames that include `/index.html`, `/registerSW.js`, and
+   `/manifest.webmanifest`
+3. a cached `/index.html` (matched with `ignoreSearch`, because Workbox adds
+   `__WB_REVISION__`) whose body contains `<div id="root"></div>`
+4. that the module entry script named inside that cached `index.html` matches
+   `/assets/*.js` and is itself in the cache
+
+Why this is stable: the generated `sw.js` precaches `index.html`,
+`registerSW.js`, and `manifest.webmanifest` under fixed names, and serves
+navigations with `createHandlerBoundToURL("index.html")`. Only the Vite asset
+names are hashed. The test never hardcodes a hash. It reads the entry script
+name from the cached shell, so the check stays valid across rebuilds.
+
+Observed: 7 cached entries (index, registerSW, manifest, two icons, one JS
+bundle, one CSS bundle).
+
+## 12. API cache-exclusion proof
+
+From the controlled page, the hard gate first fetches `/api/index`, the
+annotation view route, and the annotation overlay media route. It requires each
+to return `200` with `cache-control: no-store`. It then counts cached requests
+whose pathname starts with `/api/` across every cache.
+
+Observed: `apiCacheEntryCount = 0`.
+
+The separate focused test `never caches /api/ responses at the service-worker
+cache-storage layer` was kept. The hard gate does not depend on it.
+
+## 13. Live evidence proof
+
+Before shutdown the test:
+
+1. waits for the first `.evidence-list__item`
+2. requires it to be visible
+3. requires the `.evidence-list` text to contain the fixture candidate id
+   `many-regions-candidate` (read from the fixture helper's return value, not
+   hardcoded)
+4. makes a direct Node-side `fetch` to `/api/index` (5 second timeout) and
+   requires HTTP 200 with a body that contains the same candidate id
+
+## 14. Server-down proof
+
+After `await server.close()` the test makes a direct Node-side `fetch` to the
+same `/api/index` URL with a 5 second timeout. A Node request cannot be
+intercepted by the page's service worker, so this tests the origin server alone.
+The test requires the request to fail. If it gets any HTTP response, the test
+fails with that status in the message.
+
+The page was not navigated away. The controlled page and worker stayed in place.
+
+## 15. Offline reload proof
+
+Only after the checks in sections 9 to 14 pass does the test call
+`page.reload()`. It then requires:
+
+1. `h1, header` to render within 10 seconds, so the shell was served from the
+   precache
+2. `navigator.serviceWorker.controller !== null` after the reload
+
+## 16. Stale-evidence safety proof
+
+After the offline reload the test requires:
+
+1. `.evidence-list__error` to appear
+2. body text to contain `Evidence index unavailable`
+3. body text not to contain the previously visible candidate id
+4. zero `.evidence-list__item` elements
+
+These assertions are unchanged from the original or stricter. None were
+weakened.
+
+## 17. Cleanup proof
+
+Cleanup runs in `finally` in a fixed order: close the context, close the server
+unless it was already closed on purpose, remove the evidence root, remove the
+profile. Each step runs even if an earlier step fails. Errors are collected.
+
+1. If the experiment failed, cleanup errors are logged with `console.error` and
+   the original assertion error is what the test reports.
+2. If the experiment passed but cleanup failed, the test fails with every
+   cleanup error listed.
+3. After cleanup, the test requires that neither the evidence root nor the
+   profile directory exists.
+
+A leak audit counted `my-frontend-observer-pwa-*` and
+`my-frontend-observer-b8-pwa*` directories under the OS temp directory before
+and after each run. All counts were 0. That covers the hard gate's profile and
+evidence root and the first describe block's temporary profile and evidence
+root.
+
+Not executed: the failure-path cleanup (steps 1 and 2 above) was not triggered
+on purpose. It is supported by code inspection only.
+
+## 18. Isolated run #1
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t "HARD GATE"`
+
+PASS. 1 passed, 6 skipped. Exit 0. The run came right after a fresh
+`npm run build`.
+
+## 19. Isolated run #2
+
+The same command was run again right away. PASS. 1 passed, 6 skipped. Exit 0.
+
+The isolated command was run five times in total over the edits. The final two
+runs, on the committed test content, both passed. One of them used
+`--reporter=verbose` and printed the boundary line:
+
+`HARD GATE pre-shutdown boundary {"serviceWorkerActive":true,"controlledOnFirstLoad":true,"clientControlled":true,"shellEntryScriptCached":true,"precacheEntryCount":7,"apiCacheEntryCount":0,"liveEvidenceVisible":true}`
+
+That line was produced by the test itself after its assertions passed.
+
+## 20. Full PWA file result
+
+`npx vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts`
+
+PASS. 7 passed. Exit 0.
+
+## 21. Typecheck/lint
+
+1. `npm run typecheck`: PASS (exit 0).
+2. `npm run lint`: PASS (exit 0). The first lint run failed with
+   `no-unsafe-finally` because the cleanup error was thrown inside `finally`.
+   The throw was moved after the `try/finally` block, then isolated runs 1 and 2,
+   the full file, typecheck, and lint were all run again and passed.
+
+## 22. Production-code audit
+
+`git diff --name-only` lists only `tests/browser/pwaHardening.test.ts` plus this
+report. No file under `src/` or `viewer/` changed. `viewer/vite.config.ts`,
+the service-worker caching policy, `package.json`, `package-lock.json`,
+`.github/workflows/`, and `CHANGELOG.md` were not touched. `git diff --check`
+passed.
+
+## 23. Product-defect decision
+
+1. `PRODUCT_DEFECT_DISCOVERED = false`
+2. `PRODUCT_CHANGE_REQUIRED = false`
+
+With every precondition proven, the released v0.9.0 viewer shell loads offline
+from the precache. The evidence surface shows its explicit unavailable state.
+Previously fetched evidence is not shown as current. The original failure came
+only from the test's weak wait and its reliance on shared state.
+
+## 24. Changed files
+
+1. `tests/browser/pwaHardening.test.ts`
+2. `docs/reports/v0.9.1-batch1-pwa-hard-gate-isolation.md`
+
+Generated paths (all removed by the tests or kept outside the repository):
+
+1. `%TEMP%\my-frontend-observer-pwa-hard-gate-evidence-*` (removed)
+2. `%TEMP%\my-frontend-observer-pwa-hard-gate-profile-*` (removed)
+3. `%TEMP%\my-frontend-observer-pwa-profile-*` and
+   `%TEMP%\my-frontend-observer-b8-pwa-*` (removed)
+4. The diagnostic script and config in the Claude Code session scratchpad
+   (outside the repository, not committed)
+5. `dist/` from `npm run build` (ignored build output)
+
+These small temporary directories sit under the OS temp directory on `C:\`, as
+the task's `mkdtemp(tmpdir())` design specifies. They are deleted at the end of
+every passing run.
+
+## 25. Batch 2 handoff
+
+Batch 2 still owns:
+
+1. the permanent `test:pwa-hard-gate` package script
+2. wiring that command into the security or pre-release readiness path
+3. moving `CURRENT_STATE.md`, `ROADMAP.md`, `DEVELOPMENT.md`, `CI_CD.md`, and
+   `CHANGELOG.md` from planned to implemented wording
+4. the full unit, browser, security, build, docs, and pack validation
+
+Notes for Batch 2:
+
+1. The focused test `never caches /api/ responses` still uses the same weak
+   `?.active !== undefined` wait that the old hard gate used. It stays correct
+   in file order, because it runs after the registration test on the same
+   origin. If it is ever meant to stand alone, it should wait on
+   `navigator.serviceWorker.ready` instead. It was not changed here to keep
+   Batch 1 narrow.
+2. The standalone display-mode test still writes a log to
+   `.my-dev-kit-workflow/v0.8/batch-08/logs`. That is a log file, not a browser
+   profile, and was not changed.
+3. The historical directory `.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`
+   still exists on disk. No test needs it now. It was not deleted.