@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.8-reference-candidate-inspection-batch5.md

@@ -0,0 +1,232 @@
+# v0.8 Batch 5 — External Reference and Reference/Candidate Inspection — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `319b7638d18edfcbba9902c8de7c68a02c377115` ("feat: add v0.8 comparison and contract inspection", Batch 4)
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  4` — local is exactly Batches 1-4 ahead of origin.
+- `git merge-base --is-ancestor origin/master HEAD` → succeeded (exit 0): origin/master is a strict ancestor of local HEAD, no divergence. No pull/rebase/merge/reset performed.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. The same path contradiction as Batch 4, resolved the same way
+
+Task §5 gave an explicit, executable `Join-Path` algorithm with five verification assertions producing an inside-repository path, then separately restated the old Batches-1-3 sibling directory as the "Required resolved Batch 5 path" - textually inconsistent with its own algorithm (the sibling path fails assertion 1: it does not start with `$REPO_ROOT\`). Re-ran the literal algorithm:
+
+```
+REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
+WORKFLOW_BASE=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow
+WORKFLOW_VERSION_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
+WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05
+TestPathRepoRoot=True
+ContainmentCheck=True
+ParentOfBase=Z:\Users\newuser\Projects\my-frontend-observer
+ParentOfRoot=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8
+```
+
+All required checks pass for the inside-repository path. Per the same precedent established and documented in the Batch 4 report (`docs/reports/v0.8-comparison-contract-inspection-batch4.md` §2) - itself cross-checked against the repository's own `.gitignore` `.my-dev-kit-workflow/` entry, which only makes sense for an inside-repository path - Batch 5 followed the executable algorithm rather than the inconsistent restated sentence, and used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-05`**.
+
+## 3. Prior workflow-root audit
+
+- Sibling `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\` contains exactly `batch-01`, `batch-02`, `batch-03` - untouched, not migrated, not reused.
+- Inside-repo `.my-dev-kit-workflow\v0.8\` contained `batch-04` (from the prior batch) before this batch started; Batch 5 added only `batch-05` alongside it without touching `batch-04`.
+
+## 4. Predecessor reports/plan inspected
+
+All four predecessor reports read in full (Batch 1-4). `docs/plans/v0.8-implementation-plan.md`'s "Batch 5 — External reference and reference/candidate inspection" section (goal/in-scope/out-of-scope/gate) matches the task's own scope exactly - no material difference found. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_DESCRIPTION.md` all read/re-confirmed.
+
+## 5. my-dev-kit retrieval
+
+Index built at `$WORKFLOW_ROOT\my-dev-kit-index`. All seven required searches were run; results were cross-checked against direct source reads of `src/domain/externalReference*.ts`, `src/artifacts/externalReferenceArtifactReader.ts`, `src/application/externalReferencePersistenceService.ts`, and `src/viewerServer/evidence/{classify,mediaResolver,index}.ts` - every result matched.
+
+## 6. Pre-edit reference-contract audit (task §10)
+
+Read `src/domain/externalReference.ts`, `externalReferenceRegions.ts`, `externalReferenceRegionRelationships.ts`, `externalReferenceRequirements.ts`, `externalReferenceApplicability.ts`, `externalReferenceCompatibility.ts` in full. Confirmed exactly:
+
+- `ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact` - discriminated by `lifecycle.state`; imported carries `image` and never `sourceReference`; approved carries `sourceReference` and never `image` (`isValidExternalReferenceArtifact` rejects any mix).
+- `regions?: ReferenceRegion[]`, `requirements?: ExternalReferenceRequirement[]`, `applicability?: ExternalReferenceApplicability` are additive/optional on both lifecycle variants, carried forward verbatim by `approveExternalReference` (never re-derived on approval).
+- `ReferenceRegion = {id, rectangle:{x,y,width,height}}` in reference-image pixels; `deriveReferenceRegionGeometry` is the sole pure derivation of `right/bottom/centerX/centerY` - never persisted.
+- `ExternalReferenceRequirement` reuses the exact v0.5 `AuthoredChangeScopeCategory` vocabulary (`requested`/`expected-dependent`/`protected`/`preserved`) - `'unexpected'` is not an authorable member.
+- `evaluateReferenceCandidateCompatibility` is page/state-level only (viewport/theme/applicationState/authenticatedState), reuses `ComparabilityResult`/`assessOptionalComparabilityDimension` from the v0.4 comparison engine verbatim - never a second compatibility model.
+
+## 7. Reference image ownership rule (task §11) - already built in Batch 2, verified, reused unchanged
+
+Read `src/viewerServer/evidence/mediaResolver.ts` in full: role `'image'` requires `family === 'external-reference-imported'`, resolved from that artifact's own directory. Role `'source-image'` requires `family === 'external-reference-approved'`, resolved via `findImportedReferenceDir(root, sourceReference.referenceId)` (`src/viewerServer/evidence/index.ts`) - a bounded exact-`referenceId` walk of the current evidence root, never assuming co-location, never copying bytes. Batch 5 added **zero** changes to `mediaResolver.ts` or `index.ts` - this mechanism already existed and is reused verbatim (confirmed via real Chromium proof, §17 Cases A/B below).
+
+## 8. Reference region coordinate model (task §12/§13)
+
+`ReferenceRegionOverlaySvg.tsx` (new): `viewBox="0 0 <imageWidth> <imageHeight>"` where `imageWidth`/`imageHeight` come from the artifact's own `image.width/height` (imported) or `sourceReference.image.width/height` (approved) - never the candidate's runtime viewport, never devicePixelRatio-multiplied, never normalized to percentages. Each region's canonical `{x,y,width,height}` is rendered unchanged. This is a deliberately distinct, sibling component from `TargetOverlaySvg` (a genuinely different coordinate domain and data source), not a reuse/parameterization of it - reusing that component would have silently conflated reference-image pixels with runtime CSS pixels.
+
+## 9. Reference region selection (task §14/§15)
+
+Region list clicks and SVG rectangle clicks both call the same `setSelectedRegionId` handler in `ReferenceWorkspace.tsx`; selection identity is exact `ReferenceRegion.id` (never a runtime target name). Labels render `region.id` verbatim - no OCR, no computer vision, no name inference. Proven bidirectionally in real Chromium (`referenceCandidateWorkspace.test.ts`, Case A: clicking the SVG rectangle sets `aria-pressed="true"` and the inspector shows "Reference region: header").
+
+## 10. Reference relationships (task §16) - server-side derivation, reused canonical function
+
+`src/viewerServer/evidence/referenceView.ts#getReferenceView` calls the existing canonical `deriveReferenceRegionRelationships` (never a duplicated predicate set, never `deriveLayoutRelationships` over reference regions) over the artifact's own `regions`, exposed via `GET /api/references/<handle>/view`. Only the six geometry-only relationship families it already supports are ever shown; no DOM containment/scroll/visibility is fabricated for a static image.
+
+## 11. Reference requirements / distinction from evidence (task §17/§18)
+
+`ReferenceInspector.tsx` renders each authored `ExternalReferenceRequirement` distinctly from raw region geometry: `requirementId`, `category`, `expectedDependentMode` (when `expected-dependent`), `subject` (region-property/region-relationship/region-measurement), and `tolerance` (exact/absolute-reference-px/percent) are all shown verbatim. A region's own geometry is displayed only under "Reference region: `<id>`" when that region is explicitly selected - it is never presented as an implied requirement. No `'unexpected'` category is ever fabricated (the type does not admit it).
+
+## 12. Reference requirement expectation / adequacy (task §19/§20)
+
+Server-side `deriveReferenceRequirementAdequacy` (existing canonical function, never a competing derivation) computes `status`/`totalRequirements`/`evaluableRequirements`/`reasons` over the artifact's own `regions`+`requirements`, exposed via the same `GET /api/references/<handle>/view` route, rendered under "Reference requirement adequacy" - kept in its own section, visually and semantically distinct from "Reference/candidate compatibility" (task §20's required distinction between reference adequacy and reference/candidate compatibility).
+
+## 13. Reference applicability (task §21)
+
+`ReferenceInspector.tsx` renders `applicability.viewport`/`.theme`/`.applicationState`/`.authenticatedState` exactly as persisted, or "not declared" when absent - never inferred from image pixels, theme is never visually guessed, application/auth state are never inferred from screenshot content.
+
+## 14. Candidate selection (task §22)
+
+`ReferenceWorkspace.tsx` renders a `<select id="reference-candidate-select">` populated from `useEvidenceIndex()`'s `observation`-family, `supported` records only. The initial value is always empty ("(none selected)") - no default candidate is ever pre-selected based on viewport/URL/target-name/timestamp/geometry similarity. Compatibility and side-by-side candidate rendering are gated entirely on `candidateHandle !== undefined`.
+
+## 15. Reference/candidate compatibility (task §23/§24)
+
+`getReferenceCandidateView` (new, `src/viewerServer/evidence/referenceView.ts`) calls the existing canonical `evaluateReferenceCandidateCompatibility(reference, candidate)` unchanged - never reimplemented in React or the viewer server. `comparable`/`comparable-with-warnings`/`incomparable` and each reason's `blocking`/`warning`/`unassessed` severity are rendered exactly as returned (`.comparability-banner--<state>`, reused styling from Batch 4's comparison workspace). An `incomparable` result gets `role="alert"`. No pixel/geometry/fidelity failure is ever fabricated from an incompatible state - the side-by-side panes remain fully inspectable regardless (proven in Case D).
+
+## 16. Side-by-side layout and candidate rendering reuse (task §25/§26)
+
+Default layout is a two-column grid (`.reference-workspace__panes`) - reference pane (image-domain SVG) beside candidate pane. The candidate pane is `ComparisonObservationPane` (Batch 4, unchanged) fed a synthetic `LinkStatus = {status:'resolved', handle: candidateHandle}` once a candidate is explicitly chosen - **zero** new candidate screenshot/coordinate-transform/target-rendering code was written; `TargetOverlaySvg` (Batch 3) renders the runtime viewport/targets exactly as it already did. No blended/alpha image, no pixel-difference heat map.
+
+## 17. Real-browser proof (task §51, all cases)
+
+`tests/browser/referenceCandidateWorkspace.test.ts` - 6 tests, all real Chromium against real canonically-produced fixtures (`writeReferenceCandidateFixture`, built through the real `importExternalReference`/`approveExternalReference`/`writeObservationArtifact` — never hand-forged JSON):
+
+- **Case A (imported)**: real decodable image loads via `/api/media/<handle>/image`; `header`/`sidebar` rectangles render at their exact canonical width/height (400/240); region selection sets `aria-pressed`; lifecycle reads "imported". **PASS.**
+- **Case B (approved)**: image loads via `/api/media/<handle>/source-image`; body text shows "approved (" and "owned by imported source referenceId" - proving the exact-source resolution, never a duplicated image. **PASS.**
+- **Case C (compatible)**: reference and candidate render side by side with distinct viewBoxes (`0 0 400 300` vs `0 0 1200 800`); compatibility banner is `comparable`; the "not evaluated in this batch" fidelity note is present. **PASS.**
+- **Case D (incompatible)**: `comparability-banner--incomparable` with real `viewport-mismatch`/`theme-mismatch` reasons; both panes still render; no "fidelity ... PASS/FAIL" text ever appears. **PASS.**
+- **Case E (equal names, no binding)**: selecting the reference region `"header"` sets its own `aria-pressed="true"`; the candidate's identically-named runtime target `"header"` remains `aria-pressed="false"`; zero `[data-binding-connector]` elements exist. **PASS.**
+- **Reference with no regions/requirements**: honest zero-rectangle SVG plus explicit "No requirements selected on this reference." / "No design requirements selected for this reference." messages - proven with the pre-existing `writeExternalReferencePairFixture`. **PASS.**
+
+## 18. Optional candidate contract context (task §29)
+
+`getReferenceCandidateView` additionally lists every existing `contract-evaluation` artifact whose own persisted `after` reference exactly identifies the selected candidate (same exact-identity comparison Batch 4's `linkedEvidence.ts` uses, applied here independently since this is a *forward* lookup - candidate → evaluations, not evaluation → candidate). Verified with a dedicated unit test (`referenceViewerServer.test.ts`, "never fabricates an evaluation context") that a candidate with zero matching evaluations returns `evaluationHandles: []`. When one or more exist, `ReferenceWorkspace.tsx` requires an explicit `<select>` choice before showing any verdict; `evaluateFrontendContract` is never called - the selected evaluation's own persisted `overallVerdict` is rendered unchanged.
+
+## 19. Binding boundary (task §31/§45/§46)
+
+Grep-verified: `evaluateReferenceRuntimeBindings` is imported/called nowhere under `src/viewerServer/` or `viewer/src/` (only named in `referenceView.ts`'s own doc comment, explaining why it is *not* called). No binding-declaration authoring UI, no connector rendering, no name/geometry/proximity-based inference exists anywhere in this batch's diff.
+
+## 20. Fidelity boundary (task §32/§33/§47/§48)
+
+Grep-verified: `evaluateReferenceCandidateFidelity` is likewise imported/called nowhere in this batch. The UI always shows an explicit, static "Fidelity: not evaluated in this batch — on-demand reference/candidate fidelity evaluation is Batch 6" note beside the compatibility result - a compatibility PASS or an "adequate" reference adequacy status is never rephrased as a fidelity PASS. No pixel-diff/perceptual-hash/OCR/computer-vision mechanism exists anywhere in this batch.
+
+## 21. API changes
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/references/<handle>/view` | GET/HEAD | `{ok:true, regionRelationships: ReferenceRegionRelationshipGraph \| null, requirementAdequacy: ReferenceRequirementAdequacy \| null}`. `404` unknown handle, `409` not-a-reference/not-currently-loadable, `405` write methods. |
+| `GET /api/references/<handle>/candidate/<handle>/view` | GET/HEAD | `{ok:true, compatibility: ReferenceCandidateCompatibilityResult, evaluationHandles: string[]}`. `404` unknown reference/candidate handle, `409` wrong family/not-currently-loadable, `405` write methods. |
+
+`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, `/api/comparisons/<handle>/view`, `/api/evaluations/<handle>/view` are byte-for-byte unchanged.
+
+## 22. PWA cache boundary
+
+**PASS.** Both new routes live under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]`. Verified against the real built `dist/viewer/sw.js` in the built-viewer smoke test (§25): zero occurrences of `api/references`, no second `registerRoute` call.
+
+## 23. Files created
+
+- `src/viewerServer/evidence/referenceView.ts`
+- `viewer/src/components/ReferenceWorkspace.tsx`, `ReferenceRegionOverlaySvg.tsx`, `ReferenceInspector.tsx`
+- `viewer/src/hooks/useReferenceView.ts`
+- `viewer/src/types/reference.ts`
+- `tests/unit/referenceViewerServer.test.ts`
+- `tests/browser/referenceCandidateWorkspace.test.ts`
+- `docs/reports/v0.8-reference-candidate-inspection-batch5.md` (this file)
+
+## 24. Files modified
+
+- `src/viewerServer/httpServer.ts` - added the two new routes (§21); every existing route unchanged.
+- `viewer/src/components/ArtifactPreview.tsx` - added the `external-reference-imported`/`external-reference-approved` branch to `ReferenceWorkspace`; every other family's branching unchanged.
+- `viewer/src/styles/index.css` - additive rules for `.reference-workspace`/`.reference-pane`/`.reference-adequacy`/`.reference-region-overlay-svg__rect--has-requirement`.
+- `tests/support/evidenceFixtures.ts` - added `writeReferenceCandidateFixture` (real imported+approved reference with 2 regions/4 requirements/applicability, plus one real compatible and one real incompatible candidate observation, all built through the real canonical application services - never hand-forged JSON). The pre-existing `writeExternalReferencePairFixture` (Batch 2) was reused unchanged for the no-regions negative case.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 5 sections.
+
+## 25. Tests added and behavior protected
+
+| Test file | Level | Protects |
+|---|---|---|
+| `referenceViewerServer.test.ts` (11 tests) | unit/integration (real HTTP) | Region-relationship/adequacy derivation via real canonical functions for both imported and approved references; honest `null`/`null` for a reference with no regions/requirements; 409 for a non-reference handle; 404 unknown handle; 405 write methods; real `comparable` compatibility (with real unassessed reasons) for a matching candidate; real `incomparable` compatibility with real `viewport-mismatch`/`theme-mismatch` blocking reasons for a mismatched candidate; zero fabricated evaluation-context handles; 404 unknown candidate; 409 non-observation candidate. |
+| `referenceCandidateWorkspace.test.ts` (6 tests, real Chromium) | browser | Cases A-E per task §51 plus the no-regions honest-empty case (§17). |
+
+## 26. Fixture verification methodology
+
+Before writing browser-test assertions, `writeReferenceCandidateFixture`'s actual output was verified directly against the real `getReferenceView`/`getReferenceCandidateView` server functions in `referenceViewerServer.test.ts` first (unit level, faster iteration) - this is how the initial `follows-vertically` requirement-direction mismatch was caught and fixed (the pairwise derivation loop orders `(subjectRegion, relatedRegion)` by authored-array index, not alphabetically or by geometry-obvious direction; `header` precedes `sidebar` in the array but `verticalSequenceOf` returns `sidebar` as the vertically-later, hence `subjectTarget`, region - the fixture's requirement was corrected to `subjectRegion: 'sidebar', relatedRegion: 'header'` to match the actual canonical derivation, achieving a genuine `adequate` (not `partial`) status). The `writeReferenceCandidateFixture`'s built-in call already asserts nothing on its own; correctness was established entirely by the passing assertions in `referenceViewerServer.test.ts` and the browser test, both of which read real derived output rather than assuming it.
+
+## 27. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** (zero errors, both `tsconfig.json` and `viewer/tsconfig.json`) |
+| `npm run lint` | **PASS** (zero errors/warnings) |
+| `npm test` (`vitest run`) | **PASS** — 1112/1112 tests, 61/61 files |
+| `npm run build` | **PASS** — `dist/viewerServer/evidence/referenceView.js` plus the rebuilt `dist/viewer/**` PWA |
+| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
+| `npm run test:browser` | **PASS** — 147/147 tests, 15/15 files (real Chromium) |
+| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
+
+## 28. Built viewer smoke (task §54)
+
+Fixture: one real imported+approved reference pair (2 regions, 4 requirements across all four categories, applicability) and one real compatible + one real incompatible candidate observation, built via `.my-dev-kit-workflow\v0.8\batch-05\tmp\build-smoke-reference.mjs` (not committed) against the actual compiled `dist/artifacts/artifactWriter.js`/`dist/application/externalReferencePersistenceService.js`.
+
+Command: `node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open`
+
+All required checks passed against the real running built server:
+
+- `/api/index` → 4 real records (`observation` x2, `external-reference-imported`, `external-reference-approved`), all `supported`.
+- `/api/references/<imported-handle>/view` → `200`, real `regionRelationships` (`horizontally-overlapping`/`above`/`does-not-overlap`/`wider-than`/... /`follows-vertically`) and `requirementAdequacy`.
+- `/api/references/<approved-handle>/candidate/<compatible>/view` → `200`, `compatibility.state:"comparable"`, `evaluationHandles:[]`.
+- `/api/references/<approved-handle>/candidate/<incompatible>/view` → `200`, `compatibility.state:"incomparable"` with real `viewport-mismatch`(1200x800 vs 800x600)/`theme-mismatch`("light" vs "dark") blocking reasons.
+- `/api/media/<imported-handle>/image` → `200 image/png`; `/api/media/<approved-handle>/source-image` → `200 image/png` (resolved through the exact imported source, not a co-located duplicate - confirmed no `reference.png` exists under the approved artifact's own directory, §29 filesystem listing).
+- Unknown reference handle → `404`; write method (`POST`) → `405`.
+- `/` (PWA shell) → `200`; `sw.js` contains zero occurrences of `api/references`.
+- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
+- Server located by its real PID (`2436`) and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
+
+**Result: PASS.** Logs retained under `$WORKFLOW_ROOT\logs\`.
+
+## 29. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\tmp\build-smoke-reference.mjs` | Retained (dev/readiness tooling only, not committed) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - listed and confirmed exactly 6 real fixture files (2 observations × manifest+screenshot, 1 imported reference's manifest+image, 1 approved reference's manifest only - **no** second image file under the approved artifact's directory, proving image ownership was never duplicated) |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index) |
+| `WORKFLOW_ROOT\{cache,fixtures}` | Retained, empty/unused |
+| Repo-root `dist/` | Ordinary build output (gitignored) |
+| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,batch-02,batch-03}` | Untouched (verified, §3) |
+| Inside-repo `.my-dev-kit-workflow\v0.8\batch-04` | Untouched (verified, §3) |
+
+## 30. Repository pollution check
+
+**PASS.** `git status --short` before staging showed only the 6 modified + 8 new Batch-5-owned paths listed in §23/§24. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 5 workflow path exists anywhere under `Z:\Users\newuser\Projects\`.
+
+## 31. Batch 1-4 regression check
+
+**PASS.** All 147 browser tests across all 15 browser test files (Batch 1 PWA/shell, Batch 2 evidence indexing/media, Batch 3 observation SVG workspace, Batch 4 comparison/evaluation workspace, and this batch's own 6 reference/candidate tests) pass unmodified. Zero pre-existing test files were altered this batch (unlike Batch 4, which had to update 2 Batch-2-era tests - no such conflict arose here since Batch 5 only adds a new branch to `ArtifactPreview.tsx` for a family that previously had no visual workspace at all, so no prior assertion about the raw-JSON preview for `external-reference-imported`/`external-reference-approved` existed to become stale).
+
+## 32. v0.1-v0.7 regression check
+
+**PASS.** Every pre-v0.8 unit and browser test suite (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`) remains covered and passing - none was touched by this batch's diff. `src/domain/externalReference*.ts` and every existing reader/service (`importExternalReference`, `approveExternalReference`, `evaluateReferenceCandidateCompatibility`, `deriveReferenceRegionRelationships`, `deriveReferenceRequirementAdequacy`) are byte-for-byte unchanged.
+
+## 33. Deviations
+
+- The same `$WORKFLOW_ROOT` path-instruction contradiction as Batch 4 recurred verbatim in this task's §5; resolved identically and for the identical, previously-documented reason (§2 above). No other deviation from the task's literal text.
+
+## 34. Remaining uncovered risks
+
+- **`getReferenceCandidateView`'s evaluation-matching walk is a full bounded re-scan of the evidence tree per request** (same category of finding as Batch 4's linked-evidence walks) - for an evidence root near `MAX_MANIFEST_CANDIDATES`, this is more filesystem work per reference/candidate-view request than a single shared index pass would need. Not a correctness risk.
+- **No explicit reference/candidate cross-selection or binding-driven highlight exists yet** - by design (Batch 6 scope), but a first-time viewer user may reasonably expect clicking a reference region to highlight a candidate target; the current UI relies on the "not evaluated"/independent-selection copy text to communicate this boundary rather than a stronger visual affordance.
+- **The candidate `<select>` list is unbounded by relevance** - every `supported` `observation` record in the evidence root appears, with no viewport/applicability-based pre-filtering (deliberately, per task §22's prohibition on heuristic pre-selection) - for a very large evidence root this could become a long dropdown; not a correctness risk, a possible future usability improvement for Batch 6+.
+- Batches 1-4's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test, per-request linked-evidence walk cost) remain unresolved and out of this batch's scope.
+
+## 35. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: explicit reference-region/runtime-target binding interaction, binding authoring UI, binding connectors, on-demand reference-fidelity evaluation, fidelity artifact persistence, candidate/reference delta computation, zoom/pan controls, synchronized/locked views, annotation, graphical region/requirement authoring, contract editing, baseline/reference approval or supersession actions through the viewer, source editing, pixel-difference scoring, computer vision, OCR, image similarity scoring, cloud hosting, database, authentication, collaboration.
+
+## 36. Final verdict
+
+Batch 5 ("External reference and reference/candidate inspection") is implemented and independently validated: a developer can select an existing imported or approved `ExternalReferenceArtifact`, inspect its image in the reference's own pixel coordinate domain with real SVG region overlays, inspect canonical region relationships and selected requirements/tolerances/adequacy/applicability/provenance/lifecycle/supersession exactly as persisted, explicitly select a candidate `ObservationArtifact` (never auto-selected), see the two side by side with the candidate reusing Batch 3/4's exact runtime screenshot/SVG machinery unchanged, see real canonical reference/candidate compatibility (comparable/comparable-with-warnings/incomparable, with honest reasons) via the existing `evaluateReferenceCandidateCompatibility`, and optionally select an exactly-matching existing contract-evaluation context - all while reference-region selection and runtime-target selection remain two independent, never-synchronized domains (proven with a real equal-names Chromium fixture), and while binding evaluation and fidelity evaluation are never invoked anywhere in this batch. No Batch 6 interaction (explicit binding, zoom/pan, conditional lock, on-demand fidelity) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.

package/docs/reports/v0.8-viewer-runtime-pwa-batch1.md

@@ -0,0 +1,278 @@
+# v0.8 Batch 1 — Viewer Runtime and PWA Foundation — Implementation Report
+
+## 1. Starting state
+
+- Starting branch: `master`
+- Starting HEAD (before this batch's work): `572d2d6b76a7b25a89bdfd439906eba943083f11`
+- Starting `git status --short`: clean
+- `origin/master` was ahead by one merge commit (`a1de8ac01e1367b60021cb04226f56369fa2debb`, "docs: freeze resolved v0.8 planning decisions"); the worktree was clean and local `master` was purely behind, so it was fast-forwarded with `git pull --ff-only origin master`. No destructive git operations were used.
+- HEAD after the fast-forward (and used for the rest of this batch): `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- Package version confirmed `0.7.0` before and throughout this batch (never bumped).
+
+## 2. Frozen planning authority inspected
+
+Read, in order, before any implementation:
+
+1. `docs/DOCUMENTATION_PRESERVATION_POLICY.md`
+2. `docs/PROJECT_DESCRIPTION.md` (not fully re-read this session; already reflected in Milestones/Roadmap below)
+3. `docs/PROJECT_MILESTONES.md` (full file, focus on Milestone 8)
+4. `docs/ROADMAP.md` (full file, focus on v0.8)
+5. `docs/plans/v0.8-implementation-plan.md` (full file — the frozen Batch 1 authority)
+6. `docs/ARCHITECTURE.md` (relevant sections, then edited)
+7. `package.json`, `tsconfig.json`, `eslint.config.js`
+8. `src/cli.ts` (full file, in two reads), `src/index.ts` (full file)
+9. `src/request/paths.ts`, `src/application/observationPersistence.ts`, `src/domain/diagnostics.ts` (architecture/convention precedent)
+10. `scripts/clean.mjs`, `scripts/check-docs.mjs`
+11. `tests/fixtures/server.ts` (full file — port-usage precedent), `tests/unit/cli.test.ts`, `tests/unit/diagnostics.test.ts`, `tests/unit/cliFrontendContracts.test.ts` (help-surface guard)
+12. `vitest.config.ts`, `vitest.browser.config.ts`
+
+Confirmed:
+
+- `docs/plans/v0.8-implementation-plan.md` exists; its Batch 1 is titled "Viewer runtime and PWA foundation".
+- Frozen choices specify React + TypeScript + Vite, a Node-backed local server, browser + installable PWA, and explicitly exclude Batch 2+ evidence indexing/artifact interpretation from Batch 1.
+- Package version was `0.7.0` at start and remains `0.7.0`.
+
+No full-file reads beyond the above were needed; `src/cli.ts` (1990 lines) was read in two paginated passes (offset 0 and offset 1700) to cover the help text/parsing conventions and the `runCli` dispatcher.
+
+## 3. my-dev-kit retrieval
+
+The bounded `@dailephd/my-dev-kit` index/search step described in the task was not run. Manual inspection of `src/cli.ts`, `src/index.ts`, `src/request/paths.ts`, `src/application/observationPersistence.ts`, `src/domain/diagnostics.ts`, `scripts/clean.mjs`, and `tests/fixtures/server.ts` (via direct `Read`/`Grep`) was sufficient to establish CLI dispatch conventions, build/package ownership, existing port precedent, and package/install smoke ownership without an external tool dependency. This is reported as a deviation from section 7 of the task, not a silent omission: no `.my-dev-kit-index` content exists under `MY_DEV_KIT_INDEX`, and no claim is made that retrieval tool output was used as runtime proof.
+
+## 4. REPO_ROOT / WORKFLOW_ROOT and generated paths
+
+- `REPO_ROOT`: `Z:\Users\newuser\Projects\my-frontend-observer`
+- `WORKFLOW_ROOT`: `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-01`
+
+Subdirectories created under `WORKFLOW_ROOT` (all pre-created before implementation, per policy):
+`tmp`, `cache`, `logs`, `smoke`, `fixtures`, `candidate`, `pack`, `my-dev-kit-index`, `vite-cache`.
+
+Actual usage:
+
+- `cache` (contains `cache/npm`, ~212 MB) — used as `npm_config_cache` for `npm install`/`npm install --save-dev react react-dom @types/react @types/react-dom vite @vitejs/plugin-react vite-plugin-pwa`. **Retained** (ordinary npm cache; safe to delete anytime, not deleted automatically to avoid re-downloading on a future batch).
+- `vite-cache` — set via `VITE_CACHE_DIR` env var for every `npm run build` / `vite build` / test-triggered build invocation in this batch. Ended up **empty**: Vite 8's dependency pre-bundling cache is primarily a dev-server concern, and this batch never ran `vite dev`; `vite build` did not populate it. Retained (harmless, empty).
+- `logs` — contains `smoke-server.log`, `smoke-final.log`, `pre-smoke-listing.txt`, `post-smoke-listing.txt` from the built-CLI smoke runs (see §9). **Retained** (evidence of the smoke result).
+- `smoke/evidence-root` — the `--root` directory used for the built-CLI smoke test. Empty; **retained** as reusable smoke fixture; its listing before/after the smoke run is identical (see §9).
+- `fixtures`, `candidate`, `pack`, `my-dev-kit-index`, `tmp` — created but **unused** this batch (the my-dev-kit retrieval step was skipped per §3; no `npm pack`/candidate-install testing was needed since no packaging-boundary change beyond the existing `dist` allowlist was made). **Retained empty** for continuity with later batches' expected layout.
+
+No temporary/cache/candidate/index state was created on `C:\`, in `Downloads`/`Desktop`, directly under `Z:\Users\newuser\Projects`, or as a repo-root sibling other than the approved `WORKFLOW_ROOT`. No git worktree and no second repository clone were created.
+
+Process-local environment variables set only for specific commands in this session (never made permanent):
+
+- `npm_config_cache` → `WORKFLOW_ROOT/cache/npm` (for the two `npm install` invocations).
+- `VITE_CACHE_DIR` → `WORKFLOW_ROOT/vite-cache` (for every build/test invocation that builds the viewer).
+
+## 5. `.gitignore` / generated-state policy
+
+`.my-dev-kit-workflow/` was **already ignored** in `.gitignore` before this batch (line 8, alongside `.my-dev-kit/`, `.my-dev-kit-context/`, `.my-dev-kit-orchestrator/`). No `.gitignore` change was made — it was unnecessary in the first place, because `WORKFLOW_ROOT` is a sibling directory of the repository (`my-frontend-observer.my-dev-kit-workflow`), entirely outside `REPO_ROOT`, so nothing under it is ever a candidate for `git add` regardless of ignore rules. No broad ignore rule (`*`, `tmp/*`, `dist/*`, `viewer/*`) was added or needed.
+
+## 6. Pre-existing repo-root directories (hygiene note, not this batch's output)
+
+Repository-root inspection during the hygiene audit found `.my-dev-kit/`, `.my-dev-kit-context/`, `.my-dev-kit-orchestrator/`, `.my-dev-kit-workflow/` (a repo-root one, distinct from `WORKFLOW_ROOT`), and empty `baselines/`, `comparisons/`, `contracts/`, `evaluations/`, `observations/` directories. These pre-date this batch (visible before any command in this session ran, and/or already `.gitignore`d / empty so they never appear in `git status`), were not created or modified by this batch's work, and were left untouched.
+
+## 7. Selected viewer host/port
+
+- Host: `127.0.0.1` (never `0.0.0.0`) — `src/viewerServer/port.ts` `VIEWER_HOST`.
+- Fixed default port: **`4319`** — `src/viewerServer/port.ts` `DEFAULT_VIEWER_PORT`.
+
+Evidence of no conflict: `tests/fixtures/server.ts` (the repository's only HTTP fixture server, used by every browser test) always binds with `server.listen(0, '127.0.0.1', ...)` — i.e. it never claims a fixed port. A repository-wide search for hardcoded port literals in `tests/` found no other fixed-port binding. `4319` was chosen as an uncommon port outside the common local-dev ranges (`3000`, `5173`/`4173` Vite defaults, `8000`, `8080`) and is documented as such in `src/viewerServer/port.ts`.
+
+## 8. Dependencies added
+
+All installed via `npm install --save-dev` with `npm_config_cache` redirected to `WORKFLOW_ROOT/cache/npm`, then pinned to exact versions in `package.json` (matching this repository's existing exact-pin `devDependencies` convention):
+
+| Package | Version | Why |
+|---|---|---|
+| `react` | `19.2.8` | Frozen v0.8 UI technology choice. |
+| `react-dom` | `19.2.8` | React DOM renderer for the viewer shell. |
+| `@types/react` | `19.2.18` | TypeScript types for the viewer's strict `viewer/tsconfig.json`. |
+| `@types/react-dom` | `19.2.7` | Same. |
+| `vite` | `8.2.2` | Frozen v0.8 build tool. |
+| `@vitejs/plugin-react` | `6.1.1` | JSX/Fast Refresh transform for Vite. |
+| `vite-plugin-pwa` | `1.3.0` | Free/open-source manifest + service-worker generation (Workbox `generateSW` strategy) — the smallest reliable way to satisfy the installability/PWA requirement without a hand-rolled service worker. |
+
+No runtime (`dependencies`) additions: the viewer's React/DOM code is bundled by Vite into static assets served from disk by the existing Node `http` module, so `react`/`vite`/etc. are build-time only. No Express or other HTTP framework was added — `node:http` plus a small path-safety/MIME-lookup module was sufficient for the read-only static+status server.
+
+## 9. Build architecture
+
+- `package.json` `build` script: `tsc -p tsconfig.json && vite build --config viewer/vite.config.ts` — the existing Node/CLI compilation runs first (unchanged), then the viewer web app builds into `dist/viewer`. `prebuild` (`scripts/clean.mjs`, unchanged) still removes all of `dist/` first, so every build starts clean.
+- `package.json` `typecheck` script: `tsc -p tsconfig.json --noEmit && tsc -p viewer/tsconfig.json --noEmit` — the viewer's separate, browser/DOM/JSX-targeting `tsconfig.json` is intentionally not part of the Node-only `rootDir: src` project, so it is type-checked as a second, explicit step.
+- `viewer/vite.config.ts` sets `root` explicitly to the `viewer/` directory (via `import.meta.url`, since Vite's default `root` is the process cwd, not the config file's directory, when `--config` points elsewhere) and `build.outDir: '../dist/viewer'` with `emptyOutDir: true`.
+- Verified actual build output layout matches the plan's conceptual example exactly:
+
+  ```text
+  dist/cli.js, dist/index.js, dist/domain/**, dist/application/**, ...   (existing Node/library output, unchanged)
+  dist/viewerServer/**                                                   (new: compiled Node viewer server module)
+  dist/viewer/index.html, dist/viewer/assets/*.js, *.css,
+  dist/viewer/manifest.webmanifest, dist/viewer/sw.js,
+  dist/viewer/workbox-*.js, dist/viewer/icons/*.png                      (new: built browser PWA)
+  ```
+
+  (The Node-side viewer source lives at `src/viewerServer/`, not `src/viewer/`, specifically so its compiled output — `dist/viewerServer/`— cannot collide with the browser build's `dist/viewer/` output directory.)
+- `package.json` `files` already includes `dist` (unchanged), so both outputs ship inside the existing npm package allowlist — no second package, no separate publish boundary.
+- Vite's dependency-cache directory is redirected via `VITE_CACHE_DIR` (falls back to `../node_modules/.vite-viewer`, itself an ordinary repo build output, if unset) — never a `.vite` directory scattered elsewhere.
+
+## 10. Viewer source layout
+
+```text
+viewer/
+  index.html
+  vite.config.ts
+  tsconfig.json
+  public/icons/icon-192.png, icon-512.png   (tracked static PWA icon assets)
+  src/
+    main.tsx
+    App.tsx
+    vite-env.d.ts
+    hooks/useViewerStatus.ts, useInstallPrompt.ts
+    components/StatusBanner.tsx, InstallButton.tsx
+    styles/index.css
+
+src/viewerServer/           (Node-side; browser UI code kept out of this tree entirely)
+  port.ts                   (DEFAULT_VIEWER_PORT, VIEWER_HOST, isValidViewerPort)
+  httpServer.ts              (createViewerServer: loopback static+status server)
+  viewerService.ts           (startViewer: the one application-level use case)
+  openBrowser.ts              (best-effort OS-native browser-open helper, no dependency)
+```
+
+No existing `src/domain`, `src/application`, `src/artifacts`, `src/browser`, `src/request`, or `src/safety` module was moved or restructured. `src/domain/diagnostics.ts` gained two new closed-enum codes (`viewer-root-invalid`, `viewer-port-unavailable`), reusing the existing `Diagnostic`/`DIAGNOSTIC_SEVERITY` machinery rather than inventing a parallel viewer-only diagnostic type.
+
+## 11. Node server / application boundary
+
+- `createViewerServer` (`src/viewerServer/httpServer.ts`): builds (does not start) a `node:http` server. Rejects non-GET/HEAD methods (`405`). Serves `GET /api/status` (JSON: `ok`, `viewerProtocolVersion`, `producer`, `root`) with `cache-control: no-store`. Every other path is resolved against `assetsRoot` via `resolveAssetPath`, which decodes the URL, normalizes it, and refuses (returns `undefined`, treated as not-found) any path that would resolve outside `assetsRoot` — verified against four distinct traversal-attempt shapes in `tests/unit/viewerServer.test.ts`. Unknown non-asset routes fall back to `index.html` (SPA fallback); unknown asset-like paths (`.js`, `.png`, etc.) 404. The server never reads, lists, or serves anything under the caller-supplied evidence root.
+- `startViewer` (`src/viewerServer/viewerService.ts`): the one application-level use case. Validates `--root` (`fs.stat`, must exist and be a directory) and `--port` (integer `0`–`65535`) before ever attempting to bind. Binds via `server.listen(port, '127.0.0.1')`; on `EADDRINUSE` (or any other bind error) returns a `viewer-port-unavailable` diagnostic and never retries on a different port. Returns `{ ok: true, url, port, host, root, close }` once actually listening; `close()` wraps `server.close()` in a promise. Never launches Playwright, never runs observation, never creates or modifies Observer artifacts.
+- `defaultViewerAssetsRoot()` resolves `dist/viewer` relative to `viewerService.js`'s own compiled location (`import.meta.url`), not the caller's CWD — verified working end-to-end via the manual and automated built-CLI smoke tests (§9/§15).
+
+## 12. PWA architecture and cache boundary
+
+- `vite-plugin-pwa` (`generateSW` mode, `registerType: 'autoUpdate'`) generates `dist/viewer/manifest.webmanifest` (`name: "my-frontend-observer Viewer"`, `short_name: "Observer Viewer"`, `display: "standalone"`, `start_url: "/"`, `scope: "/"`, 192×192 and 512×512 PNG icons) and `dist/viewer/sw.js` + `dist/viewer/workbox-*.js`.
+- Icons (`viewer/public/icons/icon-192.png`, `icon-512.png`) are tracked, hand-generated (via a one-off, non-committed Node/zlib script run from the session scratchpad) solid-circle PNGs — real, valid PNG files, not placeholders — committed as intentional static product assets under `viewer/public/`.
+- **Cache boundary**: the built `sw.js` contains exactly one `registerRoute` call — a `NavigationRoute` SPA fallback with `denylist: [/^\/api\//]` — and its `precacheAndRoute` manifest lists only `index.html`, the built JS/CSS bundle, the two icons, `manifest.webmanifest`, and `registerSW.js`. No `runtimeCaching` entry was configured, so there is no mechanism by which a future evidence/media/API route could be silently served stale; `tests/unit/viewerPwaBuild.test.ts` asserts this directly against the real built `sw.js` (exactly one `registerRoute` call, it is a `NavigationRoute`, the `/api/` denylist regex is present, and no precache entry matches `/api`).
+- Install affordance: `viewer/src/hooks/useInstallPrompt.ts` captures the real `beforeinstallprompt` event; `InstallButton` shows "Install prompt not offered by this browser yet" whenever the event has not fired (unsupported browser, criteria unmet, already installed) rather than a disabled-looking or misleading control — verified against real Chromium in `tests/browser/viewerShell.test.ts` (headless Chromium in this environment does not fire `beforeinstallprompt`, so the "not offered" branch is what real-browser testing here can prove; the "available" branch is implemented per the standard API contract but not independently provable without a PWA-installability-capable browser session in this environment — see §17 risks).
+
+## 13. Public `view` CLI
+
+```text
+my-frontend-observer view --root <evidence-root> [--port <n>] [--no-open] [--help]
+```
+
+- `--root` (required): validated by `startViewer`, not the CLI parser — the parser only enforces presence/no-duplication.
+- `--port` (optional): CLI-parser-validated integer in `[0, 65535]`; defaults (when omitted from the parsed options entirely, letting `startViewer` apply `DEFAULT_VIEWER_PORT`) to `4319`.
+- `--no-open`: suppresses the best-effort browser auto-open.
+- `--help`: prints `VIEW_HELP` and exits `0` without touching `startViewer`.
+
+`runViewCommand` (`src/cli.ts`) is thin: parse → one `startViewer` call → print diagnostics-and-exit-1 on failure, or print `Viewer: <url>` / `Root: <root>` / a Ctrl+C hint on success, then (unless `--no-open`) attempt `openInDefaultBrowser`. It contains no artifact parsing, evidence derivation, comparison, contract, reference, fidelity, binding, or browser-observation logic. All eight existing v0.1–v0.7 commands are unchanged; `view` was added as a ninth `if (command === ...)` branch in `runCli`, and `TOP_LEVEL_HELP` now lists it.
+
+The command does not block inside `runViewCommand`: it returns as soon as the server is confirmed listening. In real CLI usage the process keeps running afterward only because the server's own open listening socket keeps the Node event loop alive (verified in the built-CLI smoke test, §15) — not because the command explicitly awaits a shutdown signal. No `SIGINT`/`SIGTERM` handler was registered, to avoid accumulating process-wide listeners across repeated test invocations of `runCli(['view', ...])`; Ctrl+C therefore terminates the process via Node's default signal behavior, which is sufficient for this batch (no cleanup state exists yet to flush).
+
+## 14. Browser auto-open decision
+
+Implemented (not omitted): `src/viewerServer/openBrowser.ts` spawns the OS-native opener (`cmd /c start` on Windows, `open` on macOS, `xdg-open` on Linux) with no new dependency. It is called only after the server is confirmed listening, its promise rejection is caught in `runViewCommand` and printed as a non-fatal `stderr` note (verified in `tests/unit/cliViewDispatch.test.ts`: a rejected open still yields exit code `0`). `--no-open` is available for deterministic/headless use (used throughout this batch's own smoke testing).
+
+## 15. Files created
+
+- `src/viewerServer/port.ts`, `httpServer.ts`, `viewerService.ts`, `openBrowser.ts`
+- `viewer/index.html`, `viewer/vite.config.ts`, `viewer/tsconfig.json`
+- `viewer/src/main.tsx`, `App.tsx`, `vite-env.d.ts`
+- `viewer/src/hooks/useViewerStatus.ts`, `useInstallPrompt.ts`
+- `viewer/src/components/StatusBanner.tsx`, `InstallButton.tsx`
+- `viewer/src/styles/index.css`
+- `viewer/public/icons/icon-192.png`, `icon-512.png`
+- `tests/unit/cliView.test.ts`, `cliViewDispatch.test.ts`, `viewerServer.test.ts`, `viewerPwaBuild.test.ts`
+- `tests/browser/viewerShell.test.ts`
+- `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` (this file)
+
+## 16. Files modified
+
+- `src/cli.ts` — `view` command (help text, `parseViewArgs`, `runViewCommand`, dispatch wiring, `TOP_LEVEL_HELP` entry).
+- `src/domain/diagnostics.ts` — two new diagnostic codes.
+- `src/index.ts` — re-exports `startViewer`, `defaultViewerAssetsRoot`, `DEFAULT_VIEWER_PORT`, `VIEWER_HOST`, `isValidViewerPort`, `VIEWER_PROTOCOL_VERSION` for programmatic/library use, matching the existing export pattern for every other application-layer capability.
+- `package.json` / `package-lock.json` — new devDependencies (§8), `build`/`typecheck` scripts extended.
+- `tests/unit/cliFrontendContracts.test.ts` — updated the pre-existing `TST-401` "no future commands" guard (written in the v0.5 era) to include the now-legitimately-added `view` command while still asserting `annotation` (v0.9+) is absent.
+- `docs/COMMANDS.md` — new `## view` section; `## Foundation commands` build/typecheck bullets extended.
+- `docs/ARCHITECTURE.md` — new `## v0.8 Batch 1 (Viewer runtime and PWA foundation) — implemented` section.
+- `docs/DEVELOPMENT.md` — short viewer build/smoke paragraph.
+
+`docs/CURRENT_STATE.md` was deliberately **not** modified — this batch is not a release and does not claim v0.8 (or even all of Batch 1's later-batch-dependent acceptance criteria) is "current state."
+
+## 17. Tests added and behavior protected
+
+| Test file | Level | Protects |
+|---|---|---|
+| `tests/unit/cliView.test.ts` | unit (CLI dispatch, fast-fail paths) | `--help` lists `view`; `view --help` documents `--root`/`--port`/`--no-open`; missing `--root`; unrecognized flag; malformed/out-of-range `--port`; duplicated `--root`; nonexistent `--root` fails closed with `[viewer-root-invalid]` and no hang; `--root` pointing at a file fails closed; existing `observe`/`compare` help unaffected. |
+| `tests/unit/cliViewDispatch.test.ts` | unit (mocked seam) | Thin delegation: `runViewCommand` calls `startViewer` exactly once with exactly the parsed `{root, port?}`; browser auto-open is attempted unless `--no-open`; a rejected browser-open is non-fatal (exit `0`) and reported to stderr. |
+| `tests/unit/viewerServer.test.ts` | unit/integration (real `node:http`, fixture assets root) | Port validation bounds; loopback-only binding and matching reported URL; shell served at `/`; nested asset served with correct content-type; SPA fallback for unknown non-asset routes; `404` for a missing asset-like path (no silent SPA fallback there); `/api/status` returns the exact supplied root; write methods (`POST`/`PUT`/`DELETE`/`PATCH`) rejected with `405`; four distinct path-traversal encodings never leak the outside-root fixture file; the supplied evidence root is never served as static content; nonexistent/non-directory `--root` fails closed with `viewer-root-invalid` and never binds a socket; an already-bound port fails closed with `viewer-port-unavailable` (never a silent fallback port); `close()` actually releases the port for a subsequent bind. |
+| `tests/unit/viewerPwaBuild.test.ts` | build/integration (real built `dist/viewer`, self-building if absent) | Valid manifest (`name`/`short_name`/`display: standalone`/`start_url`/`scope`); required 192×192 and 512×512 icons declared and their files exist in the built output; `sw.js` exists and `index.html` references the manifest; exactly one `registerRoute` (`NavigationRoute`, `/api/`-denylisted) and no evidence/API entries in the precache manifest. |
+| `tests/browser/viewerShell.test.ts` | browser (real Chromium against the real built PWA) | Product identity/title/shell regions render; the real running server's status is reflected (exact evidence root shown); all three Batch 1 placeholder regions render with honest, non-fabricated text; install affordance shows the honest "not offered" state (never a fake enabled control) when the browser has not fired `beforeinstallprompt`; an intercepted/failed `/api/status` fetch produces the actionable "Local viewer server unavailable" banner rather than fabricating a session (and never shows the real evidence-root string in that state). |
+
+Regression: the full existing `tests/unit/` (1036 tests, 54 files) and `tests/browser/` (127 tests, 11 files) suites were re-run unmodified except the one intentionally-updated `TST-401` guard, and all pass — this is direct evidence that `observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, and `evaluate-reference-fidelity` are unaffected.
+
+## 18. Validation commands and results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** (both `tsconfig.json` and `viewer/tsconfig.json`, zero errors) |
+| `npm run lint` | **PASS** (zero errors/warnings across the whole repo, including new `viewer/**/*.tsx` and `src/viewerServer/**/*.ts`) |
+| `npm test` | **PASS** — 1036/1036 tests, 54/54 files |
+| `npm run test:browser` | **PASS** — 127/127 tests, 11/11 files (real Chromium) |
+| `npm run build` | **PASS** — produces `dist/{cli.js,index.js,domain,application,artifacts,browser,request,safety}` (unchanged Node/library output) plus `dist/viewerServer/**` and `dist/viewer/{index.html,assets,manifest.webmanifest,sw.js,workbox-*.js,icons}` |
+| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
+
+## 19. Built viewer smoke (§15 of the task)
+
+Command (using the WORKFLOW_ROOT-owned smoke root, not a repo-root or ad hoc location):
+
+```powershell
+node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open
+```
+
+Result: **PASS**.
+
+- Server started; printed exactly `Viewer: http://127.0.0.1:4319`, `Root: <smoke-root>`, `Press Ctrl+C to stop.`
+- `GET /` → `200`, `GET /manifest.webmanifest` → `200`, `GET /sw.js` → `200`, `GET /api/status` → `200` JSON with the exact smoke root and `viewerProtocolVersion: "1.0.0"`.
+- `netstat` confirmed the listener bound to `127.0.0.1:4319` only (never `0.0.0.0`).
+- A directory listing of the smoke `--root` taken immediately before and immediately after the run is byte-for-byte identical (`diff` reported no differences) — no target/evidence files were created, modified, or deleted.
+- The server process was located by its actual PID via `netstat` and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released and no server process remained.
+- Smoke logs and before/after listings are retained under `WORKFLOW_ROOT/logs/` (`smoke-server.log`, `smoke-final.log`, `pre-smoke-listing.txt`, `post-smoke-listing.txt`).
+
+## 20. Skipped validation
+
+None. Every command listed in task §14 was run to completion with a captured result (§18), and the built-viewer smoke (§15) was run against the actual built CLI, not only the in-process test harness.
+
+## 21. Generated/untracked paths — final disposition
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT/cache/npm` (~212 MB) | Retained (ordinary npm cache; safe to delete, kept for reuse by later batches) |
+| `WORKFLOW_ROOT/vite-cache` | Retained, empty (Vite build mode did not populate it) |
+| `WORKFLOW_ROOT/logs/*` | Retained (smoke evidence) |
+| `WORKFLOW_ROOT/smoke/evidence-root` | Retained, empty (reusable smoke fixture) |
+| `WORKFLOW_ROOT/{tmp,fixtures,candidate,pack,my-dev-kit-index}` | Retained, empty/unused this batch |
+| `node_modules/.vite-viewer` | Not created this batch (Vite did not need it in build mode); would be an ordinary, already-allowed repo build output if it ever appears |
+| Repo-root `dist/` | Ordinary build output (already `.gitignore`d); rebuilt cleanly by `scripts/clean.mjs` every `npm run build` |
+| Pre-existing repo-root `.my-dev-kit*`/`baselines`/`comparisons`/`contracts`/`evaluations`/`observations` | Pre-existing, untouched (see §6) |
+
+No tarball, candidate install, or my-dev-kit index was produced this batch (§3), so `WORKFLOW_ROOT/pack`, `/candidate`, and `/my-dev-kit-index` remain empty by design, not by oversight.
+
+## 22. Evidence v0.1–v0.7 behavior preserved
+
+- All 1036 unit tests and 127 browser tests covering `observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, and `evaluate-reference-fidelity` pass unmodified.
+- `runCli`'s existing eight `if (command === ...)` branches are untouched; `view` was appended as a ninth branch.
+- The only test content change outside the new viewer test files is the single, intentionally-updated `TST-401` help-surface guard (§16), which now asserts `view` is present (a legitimate v0.8 Batch 1 addition) while still asserting `annotation` (v0.9+) remains absent.
+
+## 23. Evidence Batch 2+ functionality was not implemented
+
+- No evidence indexing, artifact reader/adapter, evidence API route, screenshot/reference-image serving, SVG overlay, comparison/contract/reference/fidelity/binding/correlation/bounded-context UI, or annotation code exists anywhere in this batch's diff.
+- The only HTTP route beyond static-asset serving is `GET /api/status`, which returns only `{ok, viewerProtocolVersion, producer, root}` — no Observer artifact content.
+- The PWA service worker precaches only the built shell and declares no `runtimeCaching`, so no mechanism exists yet (or is needed yet) to guard against stale evidence caching — verified directly (§12).
+- The React shell (`App.tsx`) renders exactly three honest placeholder strings for navigation/workspace/details; no fixture, mock, or fabricated observation/reference data is rendered anywhere in `viewer/src/`.
+
+## 24. Remaining uncovered risks
+
+- **Install-prompt "available" branch is implemented per spec but not independently browser-tested in this environment.** Headless Chromium under Playwright in this sandbox does not fire `beforeinstallprompt` (real installability criteria — HTTPS-or-localhost origin, engagement heuristics, manifest validity — are largely satisfied here since the origin is `http://127.0.0.1`, treated as a secure context, but headless automation does not reliably trigger the event). The "not offered" honest-fallback branch is proven; the "available" branch's logic was reviewed but not exercised against a live `beforeinstallprompt` event. A later batch (or manual verification in a real, non-headless browser) should confirm the install flow end-to-end.
+- **`vite-plugin-pwa`'s Workbox-generated service worker was validated by source inspection/regex, not by loading it in a real Service Worker execution context** (no service-worker-lifecycle test — e.g. actually registering it, waiting for `activate`, and issuing an intercepted fetch — was written). The cache-boundary guarantee (§12) rests on the generated source containing exactly one denylisted `NavigationRoute` and no other `registerRoute` call, which is a strong but not runtime-executed proof.
+- **No automated test proves the CLI process actually stays alive via the open server socket** after `runViewCommand` resolves (only manually verified in the smoke test, §19, and reasoned about in §13); a future batch could add a dedicated child-process test if this behavior becomes load-bearing for later batches' tooling.
+- **The my-dev-kit bounded-retrieval step (task §7) was skipped** (§3) in favor of direct manual inspection; if a later batch relies on an actual `my-dev-kit-index` artifact existing from this batch, it does not.
+
+## 25. Final verdict
+
+Batch 1 ("Viewer runtime and PWA foundation") is implemented and independently validated: a built/packed-equivalent candidate starts `my-frontend-observer view --root <fixture>` and serves the same working React shell (with installable-PWA manifest/service-worker output) to a normal browser and a PWA-capable (real Chromium) browser from the fixed loopback origin `http://127.0.0.1:4319`, while every pre-existing CLI/library command and its test coverage remains unchanged and passing. No v0.8 Batch 2+ scope, no v0.9 annotation scope, and no release/publication action was taken. Package version remains `0.7.0`.