@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.9-architecture-retrieval.md

@@ -281,12 +281,10 @@ Closest server tests are `tests/unit/viewerServer.test.ts`,
   rendering-only subset passed to the SVG leaf.
 
 Closest protection is `tests/browser/observationSvgWorkspace.test.ts`, covering
-  screenshot/media loading, exact rectangles, unresolved targets, selection in
-  both directions, relationship connectors, and aspect-ratio/viewBox alignment.
-  Zoom/pan coverage is in `tests/browser/observationComparison.test.ts`,
-  `referenceCandidateWorkspace.test.ts`, and the focused viewer workspace
-  suites; the hook’s direct unit coverage is in the corresponding viewer hook
-  test locations where present.
+screenshot/media loading, exact rectangles, unresolved targets, selection in
+both directions, relationship connectors, and aspect-ratio/viewBox alignment.
+Zoom/pan coverage is in `tests/browser/observationComparison.test.ts`,
+`referenceCandidateWorkspace.test.ts`, and the focused viewer workspace suites.
 
 ## 7. External-reference coordinate architecture
 
@@ -308,7 +306,7 @@ Closest protection is `tests/browser/observationSvgWorkspace.test.ts`, covering
   `data-region-id` values and are not runtime target names.
 - The reference overlay has separate `requirementRegionIds` and
   `highlightRegionIds` presentation props. A bound cross-selection highlights
-  the other domain without changing that domain’s primary interactive
+  the other domain without changing that domain's primary interactive
   selection.
 - Reference and runtime views share the `useZoomPan` interaction machinery,
   but each supplies its own frame dimensions and SVG coordinate domain.
@@ -400,10 +398,8 @@ zoom/pan/view lock, and server-side canonical derivation.
   observation directory and its `observationId` remain authoritative. Replacement
   creates a fresh observation instance and leaves the prior directory intact;
   the catalog changes which current artifact the alias selects.
-- Viewer startup receives ephemeral
-  `ViewerAliasMetadata`; `buildEvidenceIndexMetadata` attaches an alias only to
-  the matching observation relative directory. Artifact handles and logical IDs
-  remain canonical.
+- Viewer startup receives ephemeral `ViewerAliasMetadata`; artifact handles and
+  logical IDs remain canonical.
 - `view` discovers project evidence when `--root` is omitted. `init`, `capture`,
   and `check` dispatch through `src/cli.ts` to application/project workflow
   owners rather than embedding persistence semantics.
@@ -438,12 +434,9 @@ zoom/pan/view lock, and server-side canonical derivation.
 - A. Structural validation: `tests/unit/schema.test.ts`,
   `comparison.test.ts`, `frontendContracts.test.ts`,
   `externalReference.test.ts`, and `frontendContractEvaluationArtifact.test.ts`.
-  Protect required fields, versions, closed vocabularies, geometry, and
-  lifecycle validation.
 - B. Identity determinism: `tests/unit/identity.test.ts`,
   `comparisonIdentity.test.ts`, `frontendContractIdentity.test.ts`, and
-  `externalReferenceIdentity.test.ts`. Protect semantic hashing, array order,
-  exclusion of paths/timestamps, and fresh instance IDs.
+  `externalReferenceIdentity.test.ts`.
 - C. Writer/reader round trip: `tests/unit/artifactWriter.test.ts`,
   `comparisonPersistence.test.ts`, `frontendContractPersistence.test.ts`,
   `externalReferencePersistence.test.ts`, and
@@ -455,39 +448,23 @@ zoom/pan/view lock, and server-side canonical derivation.
   `cliFrontendContracts.test.ts`, `cliExternalReference.test.ts`,
   `cliEvaluateReferenceFidelity.test.ts`, and `cliProjectWorkflow.test.ts`.
 - F. Viewer discovery/classification: `tests/unit/evidenceDiscovery.test.ts`.
-  Protect deterministic manifest discovery, family classification, honest
-  malformed/unsupported states, metadata-only indexing, and no arbitrary-file
-  inclusion.
 - G. Path containment: `tests/unit/paths.test.ts`,
   `tests/unit/viewerEvidenceServer.test.ts`, and `tests/unit/policy.test.ts`.
-  Protect portable paths, root containment, symlink handling, and method/error
-  boundaries.
 - H. Runtime SVG selection/highlighting: `tests/browser/observationSvgWorkspace.test.ts`.
-  Protect exact geometry, unresolved-target omission, list/SVG selection, and
-  visual highlights.
 - I. Reference SVG selection/highlighting: `tests/browser/referenceCandidateWorkspace.test.ts`
   and `referenceBindingFidelityWorkspace.test.ts`.
 - J. Zoom/pan: `tests/browser/observationComparison.test.ts`,
-  `referenceCandidateWorkspace.test.ts`, and focused workspace scenarios in the
-  browser suite. These protect fit/reset, viewBox, pointer pan, and view lock.
-- K. Explicit binding cross-selection: `tests/browser/referenceBindingFidelityWorkspace.test.ts`
-  (`Case A - explicit bound cross-selection`). It protects declared-only,
-  many-to-one reverse highlighting and keeps primary selection separate.
+  `referenceCandidateWorkspace.test.ts`, and focused workspace scenarios.
+- K. Explicit binding cross-selection: `tests/browser/referenceBindingFidelityWorkspace.test.ts`.
 - L. Real-browser viewer behavior: `tests/browser/viewerIntegratedAcceptance.test.ts`,
   `viewerEvidenceShell.test.ts`, `observationSvgWorkspace.test.ts`,
   `referenceCandidateWorkspace.test.ts`, and
   `referenceBindingFidelityWorkspace.test.ts`.
-- M. PWA/API cache boundary: `tests/browser/pwaHardening.test.ts` protects real
-  service-worker registration, shell precache, no `/api/` cache entries, and
-  explicit unavailable state when the server is down.
+- M. PWA/API cache boundary: `tests/browser/pwaHardening.test.ts`.
 - N. Packed installed-package viewer smoke: `scripts/ci/runPackedViewerSmoke.mjs`.
-  It owns pack/install/launch checks for the shipped viewer boundary; the
-  analogous observation package path is `runPackedObservationSmoke.mjs`.
-- O. Project-aware viewer behavior: `tests/browser/projectWorkflowViewer.test.ts`
-  and `tests/browser/projectCheckWorkflow.test.ts`; unit ownership is
-  `tests/unit/projectWorkflow.test.ts`, `projectCheckService.test.ts`, and
-  `projectCheckResult.test.ts`. These protect init/capture/replace, canonical
-  paths, alias projection, and project check flow.
+- O. Project-aware viewer behavior: `tests/browser/projectWorkflowViewer.test.ts`,
+  `tests/browser/projectCheckWorkflow.test.ts`, `tests/unit/projectWorkflow.test.ts`,
+  `projectCheckService.test.ts`, and `projectCheckResult.test.ts`.
 
 ## 13. Package/release boundary
 

package/docs/reports/v0.9-final-pre-release-readiness.md

@@ -1,209 +1,209 @@
-# v0.9 Final Pre-release Readiness
-
-## 1. VERDICT
-
-`RUN_A` passed the complete final-readiness workflow on one exact
-post-correction commit: the candidate/static job, the exact-candidate package
-smoke on Windows, Linux and macOS, and Observer tutorial readiness on Windows,
-Linux and macOS.
-
-This is final pre-release readiness evidence for v0.9. It is not a release.
-The package version is unchanged at `0.8.1`, v0.9 is unreleased, and `master`
-has not been pushed.
-
-A second complete workflow run is required after this report is committed,
-because `docs/reports/` is inside the npm package and committing this file
-changes the candidate bytes.
-
-## 2. Repository identity
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Branch: `validation/v0.9-final-readiness`
-- Entry HEAD: `116bf5f45513768d4dfc552545cc02e13265f02f`
-- Correction commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
-- Package: `@dailephd/my-frontend-observer`
-- Package version: `0.8.1`
-- `docs/reports/v0.9-architecture-retrieval.md`: `S` skip-worktree preserved
-
-## 3. The failed run this replaces
-
-- Run: `35527166495`
-- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35527166495`
-- Conclusion: failure
-
-That run is retained as history and contributes no passing evidence to the
-final candidate. Rerunning only its failed jobs would have proved nothing,
-because the scenario files, the lab version, the readiness verifier and the
-candidate bytes all changed.
-
-## 4. The three independent root causes
-
-The earlier compressed summary attributed the whole failure to tutorial
-portability. That was incomplete.
-
-1. Candidate/package job: failed in `npm test` because one scenario pause was
-   too short. `02-runtime-intent-contract.json/category-requested` declared
-   `pauseAfterMs` of `10900` where the frozen readability rule required
-   `11900`. The exact candidate tarball was therefore never built, so the
-   package matrix was `NOT_REACHED`.
-2. Windows tutorial job: the readiness verifier crashed with
-   `Cannot read properties of undefined (reading 'contractClass')` because
-   contract-reader success results were extracted through the wrong property.
-3. Ubuntu tutorial job: the same readiness verifier crash.
-4. macOS tutorial job: scenario 2 failed while using native-select keyboard
-   emulation.
-
-This was an Observer tutorial pacing fixture defect, an Observer readiness
-verifier bug, and a generic my-dev-kit-lab native-select portability gap. No
-core Observer product regression was established by that run.
-
-Two further readiness verifier defects, both in the same family as the second
-root cause, were found while proving the correction locally. They were
-unreachable before, because every earlier run died in scenario 2. Both are
-recorded in `docs/reports/v0.9-final-readiness-corrections.md`.
-
-## 5. The v0.4.9 migration
-
-- Lab pinned exactly to `@dailephd/my-dev-kit-lab@0.4.9`
-- Release commit: `3aca0e2f5969b0a8b414bcd361dec20ba70b8dc6`
-- Scenario, target-contract, run-result and manifest schema versions all remain
-  `1.0.0`
-- 85 native-select keyboard workaround steps were collapsed into 37 semantic
-  `select-option` actions
-- Remaining combobox `press` actions: 0
-- Option values were read from the owning viewer source, never inferred from
-  visible labels
-- One canonical scenario set; no OS-conditional steps
-- Lab Playwright remains `1.60.0`; Observer's own `playwright` dependency
-  remains `^1.62.1` and was not changed to match
-
-## 6. The readiness verifier correction
-
-The canonical frontend-contract readers return `contract`, not `artifact`. The
-verifier now reads contracts through a dedicated canonical helper that tries
-`readPersistentBaselineContract` and then `readPerChangeContract`, and fails
-with both validation reasons. No raw JSON is parsed to choose a reader and no
-third contract validator exists.
-
-The reference checks now use the canonical exported type guards
-`isApprovedExternalReferenceArtifact` and `isImportedExternalReferenceArtifact`
-instead of comparing `lifecycle` as a string, and the materialized image digest
-is compared through the artifacts' own identity-bearing `sha256` fields, which
-means that comparison actually executes rather than being silently skipped.
-
-## 7. The pacing correction
-
-The frozen rule is unchanged and was not weakened:
-
-```
-readingMs = max(1200, ceil((narration.length / 15) * 10) * 100)
-```
-
-Every step in all four scenarios was re-paced after the narration edits. All
-210 steps satisfy the rule. The candidate job proved this remotely by getting
-past `npm test`.
-
-## 8. RUN_A identity
-
-- Run id: `35584183782`
-- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35584183782`
-- Head SHA: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
-- Conclusion: success
-- Workflow: Pre-release readiness
-
-All seven required jobs passed:
-
-1. Package exact candidate (Linux, Node 24): success
-2. windows-latest exact-candidate smoke: success
-3. ubuntu-latest exact-candidate smoke: success
-4. macos-latest exact-candidate smoke: success
-5. windows-latest Observer tutorial readiness: success
-6. ubuntu-latest Observer tutorial readiness: success
-7. macos-latest Observer tutorial readiness: success
-
-## 9. RUN_A exact candidate package
-
-One tarball was built by the candidate job and used unchanged by all three
-package smokes. It was not repacked per platform.
-
-- Filename: `dailephd-my-frontend-observer-0.8.1.tgz`
-- SHA-256: `2a14c4ccae1b846a6a7454900c9f3e2b200952d4456f824b2db01c1d3d9b0c35`
-- File count: 366
-- Package version: `0.8.1`
-- Candidate commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
-
-The published artifact was downloaded and independently verified. The
-recomputed SHA-256 matched the value the workflow recorded, and the archive
-contains 0 entries under `examples/v09-demo`, so the demo remains excluded from
-the npm package.
-
-## 10. RUN_A package results
-
-The exact candidate reached and passed the package matrix, which run
-`35527166495` never reached.
-
-- Windows exact-package smoke: PASS
-- Linux exact-package smoke: PASS
-- macOS exact-package smoke: PASS
-
-Each platform ran the packed observation smoke, the packed viewer smoke and the
-packed v0.9 annotation smoke against the installed tarball, not the source
-checkout.
-
-## 11. RUN_A tutorial results
-
-- Windows Observer tutorial readiness: PASS
-- Linux Observer tutorial readiness: PASS
-- macOS Observer tutorial readiness: PASS
-
-Each platform reported identical evidence:
-
-- lab version `0.4.9`
-- `observer-v09-annotation-basics`: `passed`, `cleanupErrors: []`, 2 annotations
-- `observer-v09-runtime-contract`: `passed`, `cleanupErrors: []`, 3 contracts
-- `observer-v09-reference-authoring`: `passed`, `cleanupErrors: []`, 2 references
-- `observer-v09-reference-materialization`: `passed`, `cleanupErrors: []`,
-  3 references
-- all required tutorial artifacts written and non-empty
-- canonical Observer evidence checks passed on every scenario
-- `demoSourceImmutable`: true
-- `repositoryUnchanged`: true
-
-macOS is the significant result. It previously failed in scenario 2 on native
-select keyboard emulation and now produces byte-identical evidence counts to
-Windows and Linux, which is the direct proof that the portability defect is
-closed.
-
-## 12. Native select portability gate
-
-All three platforms ran scenarios that use `select-option` for every native
-`<select>` semantic choice. No OS-specific keyboard navigation was
-reintroduced. `tests/unit/v09TutorialScenarios.test.ts` fails if a scenario
-drives a `combobox` locator with `press`, so the gate is enforced statically in
-the candidate job as well as behaviourally on each platform.
-
-## 13. Local evidence supporting RUN_A
-
-Recorded in full in `docs/reports/v0.9-final-readiness-corrections.md`:
-
-- `npm run typecheck`, `npm run lint`, `npm run build`, `npm run check:docs`:
-  PASS
-- `npm test`: PASS, 1453 tests in 89 files
-- `npm run test:browser`: PASS, 275 tests in 29 files
-- `npm run test:security`: PASS, 167 tests in 16 files plus 77 tests in 3 files
-- Local four-tutorial readiness: all four `passed`, `cleanupErrors: []`,
-  `demoSourceImmutable: true`, `repositoryUnchanged: true`
-- Local packed observation, viewer and v0.9 annotation smokes: PASS
-
-## 14. Release state
-
-- Package version: `0.8.1`, unchanged
-- v0.9: unreleased
-- No version bump, tag, GitHub Release or npm publication was performed
-- `master`: not pushed
-- Validation branch `validation/v0.9-final-readiness`: preserved
-- No Observer product semantics, artifact schema, command surface or dependency
-  was changed
-
-Passing final pre-release readiness does not authorize publication. The next
-stage is v0.9.0 controlled release preparation.
+# v0.9 Final Pre-release Readiness
+
+## 1. VERDICT
+
+`RUN_A` passed the complete final-readiness workflow on one exact
+post-correction commit: the candidate/static job, the exact-candidate package
+smoke on Windows, Linux and macOS, and Observer tutorial readiness on Windows,
+Linux and macOS.
+
+This is final pre-release readiness evidence for v0.9. It is not a release.
+The package version is unchanged at `0.8.1`, v0.9 is unreleased, and `master`
+has not been pushed.
+
+A second complete workflow run is required after this report is committed,
+because `docs/reports/` is inside the npm package and committing this file
+changes the candidate bytes.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `validation/v0.9-final-readiness`
+- Entry HEAD: `116bf5f45513768d4dfc552545cc02e13265f02f`
+- Correction commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1`
+- `docs/reports/v0.9-architecture-retrieval.md`: `S` skip-worktree preserved
+
+## 3. The failed run this replaces
+
+- Run: `35527166495`
+- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35527166495`
+- Conclusion: failure
+
+That run is retained as history and contributes no passing evidence to the
+final candidate. Rerunning only its failed jobs would have proved nothing,
+because the scenario files, the lab version, the readiness verifier and the
+candidate bytes all changed.
+
+## 4. The three independent root causes
+
+The earlier compressed summary attributed the whole failure to tutorial
+portability. That was incomplete.
+
+1. Candidate/package job: failed in `npm test` because one scenario pause was
+   too short. `02-runtime-intent-contract.json/category-requested` declared
+   `pauseAfterMs` of `10900` where the frozen readability rule required
+   `11900`. The exact candidate tarball was therefore never built, so the
+   package matrix was `NOT_REACHED`.
+2. Windows tutorial job: the readiness verifier crashed with
+   `Cannot read properties of undefined (reading 'contractClass')` because
+   contract-reader success results were extracted through the wrong property.
+3. Ubuntu tutorial job: the same readiness verifier crash.
+4. macOS tutorial job: scenario 2 failed while using native-select keyboard
+   emulation.
+
+This was an Observer tutorial pacing fixture defect, an Observer readiness
+verifier bug, and a generic my-dev-kit-lab native-select portability gap. No
+core Observer product regression was established by that run.
+
+Two further readiness verifier defects, both in the same family as the second
+root cause, were found while proving the correction locally. They were
+unreachable before, because every earlier run died in scenario 2. Both are
+recorded in `docs/reports/v0.9-final-readiness-corrections.md`.
+
+## 5. The v0.4.9 migration
+
+- Lab pinned exactly to `@dailephd/my-dev-kit-lab@0.4.9`
+- Release commit: `3aca0e2f5969b0a8b414bcd361dec20ba70b8dc6`
+- Scenario, target-contract, run-result and manifest schema versions all remain
+  `1.0.0`
+- 85 native-select keyboard workaround steps were collapsed into 37 semantic
+  `select-option` actions
+- Remaining combobox `press` actions: 0
+- Option values were read from the owning viewer source, never inferred from
+  visible labels
+- One canonical scenario set; no OS-conditional steps
+- Lab Playwright remains `1.60.0`; Observer's own `playwright` dependency
+  remains `^1.62.1` and was not changed to match
+
+## 6. The readiness verifier correction
+
+The canonical frontend-contract readers return `contract`, not `artifact`. The
+verifier now reads contracts through a dedicated canonical helper that tries
+`readPersistentBaselineContract` and then `readPerChangeContract`, and fails
+with both validation reasons. No raw JSON is parsed to choose a reader and no
+third contract validator exists.
+
+The reference checks now use the canonical exported type guards
+`isApprovedExternalReferenceArtifact` and `isImportedExternalReferenceArtifact`
+instead of comparing `lifecycle` as a string, and the materialized image digest
+is compared through the artifacts' own identity-bearing `sha256` fields, which
+means that comparison actually executes rather than being silently skipped.
+
+## 7. The pacing correction
+
+The frozen rule is unchanged and was not weakened:
+
+```
+readingMs = max(1200, ceil((narration.length / 15) * 10) * 100)
+```
+
+Every step in all four scenarios was re-paced after the narration edits. All
+210 steps satisfy the rule. The candidate job proved this remotely by getting
+past `npm test`.
+
+## 8. RUN_A identity
+
+- Run id: `35584183782`
+- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35584183782`
+- Head SHA: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+- Conclusion: success
+- Workflow: Pre-release readiness
+
+All seven required jobs passed:
+
+1. Package exact candidate (Linux, Node 24): success
+2. windows-latest exact-candidate smoke: success
+3. ubuntu-latest exact-candidate smoke: success
+4. macos-latest exact-candidate smoke: success
+5. windows-latest Observer tutorial readiness: success
+6. ubuntu-latest Observer tutorial readiness: success
+7. macos-latest Observer tutorial readiness: success
+
+## 9. RUN_A exact candidate package
+
+One tarball was built by the candidate job and used unchanged by all three
+package smokes. It was not repacked per platform.
+
+- Filename: `dailephd-my-frontend-observer-0.8.1.tgz`
+- SHA-256: `2a14c4ccae1b846a6a7454900c9f3e2b200952d4456f824b2db01c1d3d9b0c35`
+- File count: 366
+- Package version: `0.8.1`
+- Candidate commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+
+The published artifact was downloaded and independently verified. The
+recomputed SHA-256 matched the value the workflow recorded, and the archive
+contains 0 entries under `examples/v09-demo`, so the demo remains excluded from
+the npm package.
+
+## 10. RUN_A package results
+
+The exact candidate reached and passed the package matrix, which run
+`35527166495` never reached.
+
+- Windows exact-package smoke: PASS
+- Linux exact-package smoke: PASS
+- macOS exact-package smoke: PASS
+
+Each platform ran the packed observation smoke, the packed viewer smoke and the
+packed v0.9 annotation smoke against the installed tarball, not the source
+checkout.
+
+## 11. RUN_A tutorial results
+
+- Windows Observer tutorial readiness: PASS
+- Linux Observer tutorial readiness: PASS
+- macOS Observer tutorial readiness: PASS
+
+Each platform reported identical evidence:
+
+- lab version `0.4.9`
+- `observer-v09-annotation-basics`: `passed`, `cleanupErrors: []`, 2 annotations
+- `observer-v09-runtime-contract`: `passed`, `cleanupErrors: []`, 3 contracts
+- `observer-v09-reference-authoring`: `passed`, `cleanupErrors: []`, 2 references
+- `observer-v09-reference-materialization`: `passed`, `cleanupErrors: []`,
+  3 references
+- all required tutorial artifacts written and non-empty
+- canonical Observer evidence checks passed on every scenario
+- `demoSourceImmutable`: true
+- `repositoryUnchanged`: true
+
+macOS is the significant result. It previously failed in scenario 2 on native
+select keyboard emulation and now produces byte-identical evidence counts to
+Windows and Linux, which is the direct proof that the portability defect is
+closed.
+
+## 12. Native select portability gate
+
+All three platforms ran scenarios that use `select-option` for every native
+`<select>` semantic choice. No OS-specific keyboard navigation was
+reintroduced. `tests/unit/v09TutorialScenarios.test.ts` fails if a scenario
+drives a `combobox` locator with `press`, so the gate is enforced statically in
+the candidate job as well as behaviourally on each platform.
+
+## 13. Local evidence supporting RUN_A
+
+Recorded in full in `docs/reports/v0.9-final-readiness-corrections.md`:
+
+- `npm run typecheck`, `npm run lint`, `npm run build`, `npm run check:docs`:
+  PASS
+- `npm test`: PASS, 1453 tests in 89 files
+- `npm run test:browser`: PASS, 275 tests in 29 files
+- `npm run test:security`: PASS, 167 tests in 16 files plus 77 tests in 3 files
+- Local four-tutorial readiness: all four `passed`, `cleanupErrors: []`,
+  `demoSourceImmutable: true`, `repositoryUnchanged: true`
+- Local packed observation, viewer and v0.9 annotation smokes: PASS
+
+## 14. Release state
+
+- Package version: `0.8.1`, unchanged
+- v0.9: unreleased
+- No version bump, tag, GitHub Release or npm publication was performed
+- `master`: not pushed
+- Validation branch `validation/v0.9-final-readiness`: preserved
+- No Observer product semantics, artifact schema, command surface or dependency
+  was changed
+
+Passing final pre-release readiness does not authorize publication. The next
+stage is v0.9.0 controlled release preparation.