@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.8-integrated-viewer-acceptance-batch8.md

@@ -0,0 +1,128 @@
+# v0.8 Batch 8 — Integrated Viewer Acceptance, PWA Hardening, and Packaged Proof
+
+## 1. Identity and scope
+
+This is the eighth and final implementation batch of the v0.8 "Interactive Local Observation Viewer" feature. It is explicitly **not** a feature-redesign batch: its job is to integrate, harden, test, fix defects, close three named coverage gaps carried forward from Batches 6 and 7, and prove the packaged (`npm pack`) candidate actually works end-to-end in a real browser. Predecessor: Batch 7, commit `e30ba3f`. Package version remains `0.7.0` throughout — no bump, no publish, no tag, no push.
+
+## 2. Workflow-path resolution (recurring contradiction, resolved identically to every prior batch)
+
+The task text states a required sibling workflow root while its own literal `Join-Path`-based construction algorithm resolves to a path inside the repository. Per the precedent established in Batches 4–7, the literal, self-verifying algorithm was followed: `$WORKFLOW_ROOT = .my-dev-kit-workflow/v0.8/batch-08` (inside-repo, gitignored via `.gitignore`'s `.my-dev-kit-workflow/` pattern). All generated state (`tmp/`, `cache/`, `logs/`, `fixtures/`, `smoke/`, `pack/`, `candidate/`, `consumer/`, `my-dev-kit-index/`, `pwa-profile/`) lives exclusively under this path. The sibling location was audited and confirmed to still contain only `batch-01`–`batch-03` from earlier sessions — no cross-contamination.
+
+## 3. No-second-engine audit (task §12)
+
+Re-confirmed via targeted `grep -rn` across `src/viewerServer` and `viewer/src` for every canonical engine function. Findings unchanged from the Batch 8 pre-work audit:
+
+- `compareObservations`, `evaluateFrontendContract`, `projectBoundedAgentContext`, `deriveRuntimeStaticCorrelations`, `attachRuntimeStaticCorrelations`: **zero** occurrences in viewer runtime code (never recomputed at view time).
+- `deriveLayoutRelationships`: exactly one call site, `src/viewerServer/evidence/observationView.ts:49` (Batch 3's sanctioned server-side derivation).
+- `deriveReferenceRegionRelationships`, `deriveReferenceRequirementAdequacy`, `evaluateReferenceCandidateCompatibility`, `evaluateReferenceRuntimeBindings`, `evaluateReferenceCandidateFidelity`, `deriveCoordinateScale`: each exactly one call site, all inside `src/viewerServer/evidence/referenceView.ts`.
+- No `my-dev-kit` or `child_process` invocation exists in shipped viewer code; the only `child_process` import (`src/viewerServer/openBrowser.ts`) is the pre-existing Batch 1 best-effort default-browser launcher, unrelated to my-dev-kit.
+
+**Finding: no duplicate evidence engine exists.** No architectural correction was required.
+
+## 4. Write-method audit (task §31)
+
+`src/viewerServer/httpServer.ts:91` — `if (method !== 'GET' && method !== 'HEAD') { … 405 … }` sits at the top of the single request-dispatch function and applies uniformly to every route, including the newer `/api/context` route. Confirmed structurally (one check point, cannot be bypassed by a route added later without also bypassing this guard) rather than by enumerating each route individually.
+
+## 5. Gap-closing fixtures (new, added to `tests/support/evidenceFixtures.ts`)
+
+Two new canonical fixture writers were added, each built entirely from real canonical writer/service calls (no hand-edited verdicts), and each verified against its actual derived output via a throwaway unit test before any real-browser assertion was written against it — following the exact discipline that caught real fixture bugs in Batches 6 and 7.
+
+- **`writeManyRegionsOneTargetFixture`** — an approved reference with two distinct regions (`region-a`, `region-b`) and a candidate observation with one runtime target (`workspace`). Verified: with explicit bindings mapping both regions to `workspace`, `evaluateReferenceRuntimeBindings` returns `bound` for both, against the same target.
+- **`writeFidelityFailContractPassFixture`** — a before/after observation pair, a real contract evaluation (`evaluateAndPersistFromArtifactRoots`) that genuinely returns `overallVerdict: 'PASS'` (a requested `property-decreases` clause and a protected `property-unchanged-within-tolerance` clause, both genuinely satisfied), and a real `evaluateReferenceCandidateFidelity` call against an approved reference whose `sidebar.width` requirement the same candidate genuinely violates (`state: 'fail'`). One fixture-construction bug was caught and fixed during verification: an initial version left the sidebar's y-position different between before/after, which the contract engine correctly flagged as an unaccounted-for `unexpectedChange`, forcing `overallVerdict` to `FAIL` — fixed by holding sidebar geometry fully identical between before/after so only the header-height clause differs.
+
+Scenario N (bounded-context sources sharing a target id) required **no new fixture**: Batch 7's existing `writeBoundedContextEvidenceFixture` already builds `ctx-before`/`ctx-after` as two source observations that both configure `header`/`sidebar`, and `baseContext.sources.observationIds` already includes both. Only a new real-browser test was needed.
+
+## 6. Real-browser proof of the three named gap closures (task §69 items L, M, N)
+
+New file `tests/browser/viewerIntegratedAcceptance.test.ts`, 3 tests, all passing against the actual built React shell through the actual loopback viewer server:
+
+- **Item L**: selecting the candidate's single `workspace` target rect highlights *both* `region-a` and `region-b` reference rects (`target-overlay-svg__rect--highlighted` class on both), closing the Batch 6 gap where only one-direction (region→target) cross-highlight had been proven for a single relationship.
+- **Item M**: with the fidelity-fail-contract-pass fixture, selecting the matching evaluation shows `.overall-verdict--PASS`, and running on-demand fidelity evaluation shows `.reference-fidelity-state--fail` — both visible simultaneously, with the pre-existing independence note (`ReferenceWorkspace.tsx:361-366`, unchanged, already verdict-agnostic) confirming neither is presented as overriding the other. This closes the Batch 6 asymmetric gap (only PASS+FAIL, never FAIL+PASS, had real-browser proof).
+- **Item N**: with `baseContext` supplied as the session context, selecting the `header` bounded target in Context mode lists exactly 2 items in `.context-target-source-list` — `observation:ctx-before` and `observation:ctx-after` — proving `SourceObservationTargetCheck` genuinely enumerates every matching source observation rather than picking one. Closes the Batch 7 gap.
+
+## 7. Accessibility hardening (task §27) — one real defect found and fixed
+
+Auditing the cross-highlight mechanism (`TargetOverlaySvg.tsx`, `ReferenceRegionOverlaySvg.tsx`) confirmed a real, previously-flagged gap: a cross-highlighted-but-not-selected rect (`isHighlighted && !isSelected`) exposed no accessible state distinguishing it from a plain unselected rect — `aria-pressed` correctly stayed `false` (it is not the primary selection), but nothing else communicated the highlight to assistive technology; it was visual-only.
+
+**Fix**: both components now add `data-highlighted="true"` (a stable, testable hook) and append `" (highlighted: related to current selection)"` to the element's `aria-label` when highlighted-and-not-selected, leaving `aria-pressed` semantics (primary single-select state) untouched. Verified via the new Scenario L test (`data-highlighted` and `aria-label` assertions) and confirmed the full pre-existing browser suite (178/178) still passes with this markup change — no existing test depended on the old `aria-label` text.
+
+Other audited areas (region/target selection buttons, lock toggle, evaluation/candidate `<select>` elements, install affordance) already exposed semantic controls (`role="button"`, keyboard activation via Enter/Space, `aria-pressed` where applicable, real `<button>`/`<select>` elements elsewhere) from prior batches; no further defects were found there.
+
+## 8. Honest-status-language and provenance audits (task §28-29)
+
+Spot-audited the terms the task calls out as never-conflatable (supported/complete/PASS/adequate/compatible/bound/correlated vs. unsupported/partial/unavailable/ambiguous/incomparable/not-evaluated/conflict/FAIL) against `ContextWorkspace.tsx`, `ReferenceWorkspace.tsx`, and `EvidenceList.tsx`. No generic "Everything OK" aggregate state exists anywhere in the viewer; every status surface renders the specific canonical status word. Provenance: every rendered value in Context mode and Reference mode traces to a field read directly off a persisted/supplied artifact or a single designated canonical-engine call site (§3 above) — no independently-invented provenance labels were found.
+
+## 9. PWA live hardening (task §32-38, §53, §56-65) — genuinely new work, no prior coverage existed
+
+Confirmed via `grep -rln "serviceWorker\|beforeinstallprompt" tests/` that **no test anywhere previously exercised live service-worker or install-prompt behavior** — all prior PWA verification was static `sw.js`/`workbox` regex inspection. New file `tests/browser/pwaHardening.test.ts`, 7 tests, all passing, using a dedicated persistent Chromium profile under `$WORKFLOW_ROOT\pwa-profile` (never the user's real profile):
+
+- **Live service-worker registration**: `navigator.serviceWorker.ready` resolves with a non-null `active` registration for the actual built shell, scoped to the actual server origin.
+- **Manifest**: fetched (not just parsed from source), confirmed `display: "standalone"` and non-empty `icons`.
+- **No API caching**: enumerated every Cache Storage entry across all caches after normal use — zero entries with a `/api/` pathname, confirming the `navigateFallbackDenylist` boundary holds live, not just in the built `sw.js` regex.
+- **HARD GATE — server-down shell behavior** (task §61, "must not be waived"): loaded the app, confirmed evidence was visible, waited for SW activation, called `server.close()`, reloaded the **same page**. Result: the app shell still renders (precache working as intended), but the evidence-dependent surface shows the explicit `.evidence-list__error` "Evidence index unavailable" state — the previously-visible evidence item text (`many-regions-candidate`) is asserted **absent** from the reloaded page. **Gate holds: no stale evidence was presented as current.**
+- **Install-control, synthetic branch**: confirmed the honest default ("Install prompt not offered by this browser yet") and confirmed dispatching a synthetic `beforeinstallprompt` event flips the UI to a genuine `Install viewer` button — this is explicitly a **UI-logic proof**, not a genuine platform install signal.
+- **Standalone-mode**: attempted CDP `Emulation.setEmulatedMedia` with a `display-mode: standalone` feature. The command was accepted without error, but `window.matchMedia('(display-mode: standalone)').matches` still reported `false` afterward (recorded verbatim in `$WORKFLOW_ROOT\logs\pwa-standalone-proof.txt`). **Honest finding: this Chromium/Playwright combination did not demonstrably honor the emulated display-mode feature.** No standalone-mode behavioral proof beyond command-acceptance was achieved.
+
+### GENUINE_BROWSER_INSTALL_PROMPT
+`NOT_AVAILABLE_TO_AUTOMATION` — no real `beforeinstallprompt` event was observed to fire natively during automated testing; only the synthetic-dispatch UI-logic path was exercised.
+
+### ACTUAL_OS_PWA_INSTALLATION_VERIFIED
+`NO` — never attempted or claimed. Standalone-mode proof did not even reach the CDP-emulation behavioral tier described in the task as tier B; it is recorded here as a below-tier-B finding rather than overstated.
+
+## 10. Full validation chain
+
+All run against the working tree with the new fixtures/tests/accessibility fix in place:
+
+| Command | Result |
+|---|---|
+| `npx tsc --noEmit` | clean |
+| `npm run lint` | clean |
+| `npm test` (unit) | 1156/1156 passed, 63 files |
+| `npm run build` | clean (tsc + vite build + PWA precache generation) |
+| `npm run check:docs` | passed (17 required files) |
+| `npm run test:browser` | 178/178 passed, 19 files (first run: 1 failure, reproduced in isolation → passed cleanly; full clean rerun → 178/178) |
+| `git diff --check` | clean (only benign LF→CRLF autocrlf warnings, no real whitespace errors) |
+
+### Flake documentation (task §67)
+One browser test (`Case F - incompatible pair` in the pre-existing `referenceBindingFidelityWorkspace.test.ts`, untouched by Batch 8) failed once during a full-suite run with body text showing an in-flight "Evaluating compatibility…" state instead of the settled result — a timing/resource-contention symptom, not a functional regression. Per the discipline established in Batch 7: reproduced the exact failing test in isolation (passed cleanly), then reran the entire suite from a clean state (178/178 passed). Diagnosed as environmental flake, not dismissed without reproduction.
+
+## 11. Packaging and packaged-candidate proof (task §46-55)
+
+- **Build proof**: `npm run build` output confirmed sufficient to run standalone from `dist/` alone (proven directly by the installed-package proof below, which never touches `src/` or `viewer/` source).
+- **Tarball**: `npm pack --pack-destination ".my-dev-kit-workflow/v0.8/batch-08/pack"` → `my-frontend-observer-0.7.0.tgz`, 723.4 kB packed / 2.9 MB unpacked, 283 files.
+  - SHA-256: `9c6c899590cca6577ab403fc1fe130a1166b3f4103123537d8bbd441b6220ad7`
+- **Content-safety audit**: tarball top level is exactly `CHANGELOG.md`, `README.md`, `dist/`, `docs/`, `package.json` — no `src/`, no `viewer/` source, no `tests/`, no `node_modules/`, no workflow/cache/log/tarball-in-tarball/git-metadata pollution (confirmed via a `grep -iE` pass over the full file listing).
+- **Consumer install**: clean `npm install <exact tarball path>` into `$WORKFLOW_ROOT\consumer` with `npm_config_cache`/`TEMP`/`TMP` redirected under the workflow root — never the global npm cache or repo root. `node_modules/my-frontend-observer/package.json` version confirmed `0.7.0`, installed from `file:../pack/my-frontend-observer-0.7.0.tgz`.
+- **Installed CLI proof**: `--version` → `0.7.0`; `--help` lists all 9 commands (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`, `view`) — via the actually-installed `.bin` executable, not repo `dist/cli.js`.
+- **Installed viewer launch**: the installed CLI's `view --root <integrated-evidence-corpus> --port 4319 --no-open` genuinely started, served `/api/index` with real records, and stayed up for the packaged-browser proof below.
+- **Packaged real-browser proof**: real Chromium against `http://127.0.0.1:4319` (the packaged/installed server, not a source-checkout dev server) — 55 evidence records loaded, reference-region overlay rendered after selecting an approved reference, packaged service worker registered and activated, zero page errors.
+- **Read-only evidence-hash proof** (task §59): SHA-256 of every file in the integrated-evidence corpus, taken after the packaged-browser proof session and again after server teardown — **identical**, confirming no mutation.
+- **No-viewer-artifact proof** (task §60): the same hash comparison implies no new files (`viewer.json`, `fidelity.json`, or similar) were created anywhere in the evidence root; the corpus directory listing was not altered by any of the above testing.
+
+## 12. Integrated evidence corpus (task §13)
+
+Built under `$WORKFLOW_ROOT\fixtures\integrated-evidence` via 12 real canonical-fixture-writer calls (no hand-edited verdicts): normal observation, contract PASS + protected-clause FAIL, baseline supersession, reference/candidate pair (compatible + incompatible), reference binding/fidelity (bound/ambiguous/unavailable), reference fidelity+contract independence, bounded context (adequate/correlated/ambiguous/unavailable/omission/truncation/fidelity-mismatch/blocked), many-regions-one-target, fidelity-fail-contract-pass, plus malformed JSON, unsupported schema version, and missing-screenshot negative fixtures. This corpus is what backed the packaged real-browser proof in §11.
+
+## 13. Repository hygiene and commit
+
+- `git status --short` before commit: only `tests/support/evidenceFixtures.ts` (modified), `viewer/src/components/ReferenceRegionOverlaySvg.tsx` (modified), `viewer/src/components/TargetOverlaySvg.tsx` (modified), `tests/browser/viewerIntegratedAcceptance.test.ts` (new), `tests/browser/pwaHardening.test.ts` (new), plus this report (new).
+- All packed/consumer/PWA-profile/corpus/log/cache state remains exclusively under `.my-dev-kit-workflow/` (gitignored) — confirmed nothing outside it was touched.
+- `package.json` version confirmed unchanged at `0.7.0` throughout.
+
+## 14. What this batch does NOT establish
+
+- Not release-ready, not publish-ready, not cross-platform-verified.
+- `VERSION_BUMP: NONE`. `PUBLICATION_ACTIONS: NONE`. Nothing was tagged, pushed, or published.
+- Standalone/installed-PWA behavioral proof did not exceed CDP command-acceptance (matchMedia did not reflect it) — this is a genuine residual gap, not a success to build on without further investigation.
+- The broader hardened-documentation-and-implementation-completeness audit (the stage after this one) was explicitly **not** performed here.
+- Symlink/junction-escape raw-evidence attack cases (task §30) were not re-exercised with new dedicated tests in this batch; the existing raw-evidence-safety mechanism (exact-identity artifact-detail resolution, Batch 2/4/7) was re-confirmed structurally but not stress-tested against new filesystem-escape vectors. Recorded as a residual risk, not closed.
+
+## 15. Remaining risks / residual scope
+
+1. Standalone-mode proof strength is below what the task's tier-B ("behavioral proof via CDP/app-mode") describes — worth a follow-up investigation into why `Emulation.setEmulatedMedia` didn't take effect in this Chromium build.
+2. Symlink/junction raw-evidence-escape cases remain untested by a dedicated new test (§30 residual).
+3. The 20-item acceptance matrix (task §69, items A–T) is satisfied by a mix of this batch's 3 new dedicated tests (L, M, N) plus the already-passing, re-confirmed test suites from Batches 3–7 for the remaining items — this batch did not write a from-scratch dedicated test for every letter independently where an existing one already provides equivalent real-browser proof.
+
+## 16. Verdict
+
+`PASS_V08_BATCH8_INTEGRATED_VIEWER_ACCEPTANCE` — full validation chain green, all three named coverage gaps closed with new real-browser proof, one real accessibility defect found and fixed, PWA live hardening genuinely exercised for the first time with its hard stale-evidence gate holding, and the packaged/installed candidate proven to work end-to-end in a real browser with read-only evidence-root integrity confirmed. `IMPLEMENTATION_BATCHES_STATUS: ALL_8_IMPLEMENTATION_BATCHES_PASS`. `NEXT_STAGE_READINESS`: ready to proceed to the separate hardened-documentation-and-implementation-completeness audit stage — not to release preparation.

package/docs/reports/v0.8-observation-svg-inspection-batch3.md

@@ -0,0 +1,223 @@
+# v0.8 Batch 3 — Runtime Observation Inspection and SVG Overlays — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `be82055e29ca8d12cee61ae933dc85e6af3f2b9f` ("feat: add v0.8 viewer evidence indexing and readers")
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  2` — local is exactly Batch 1 + Batch 2 ahead of origin, no divergence.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. Predecessor reports inspected
+
+Read both local reports in full (not console summaries):
+
+- `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` — confirmed host `127.0.0.1`/port `4319`, `src/viewerServer/httpServer.ts`/`viewerService.ts` ownership, PWA `navigateFallbackDenylist: [/^\/api\//]`.
+- `docs/reports/v0.8-evidence-index-readers-batch2.md` — confirmed exact module/API details reused unchanged this batch: `evidence/index.ts#loadArtifactByHandle`/`buildEvidenceIndexMetadata`, `evidence/handles.ts` (`<family-slug>:<percent-encoded relativeDir>`), `evidence/pathSafety.ts#resolveContainedDir` (including its Batch 2 forward-slash-root bugfix - re-used as-is, not re-litigated), `evidence/classify.ts#ClassifiedRecord`/`ViewerSupportState`, `evidence/projection.ts#EvidenceMetadataRecord`/`EvidenceArtifactDetail`, `GET /api/index`/`GET /api/artifacts/<handle>`/`GET /api/media/<handle>/<role>` exact semantics/status codes, `viewer/src/hooks/useEvidenceIndex.ts`/`useArtifactDetail.ts`, `viewer/src/components/EvidenceList.tsx`/`ArtifactPreview.tsx`. No parallel API was created; every Batch 3 addition is additive to this exact boundary.
+
+## 3. Frozen planning authority inspected
+
+`docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/plans/v0.8-implementation-plan.md` (Batch 3 section + cross-batch invariants §7) — all previously read in full during Batches 1-2, re-confirmed unchanged. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md` (media/schema-version constants, previously read in full), `docs/WORKFLOWS.md`, `docs/COMMANDS.md` (`view` section, then edited), `docs/DEVELOPMENT.md`. New this batch: `src/domain/schema.ts` (full `TargetGeometry`/`TargetEvidenceRecord`/`PageEvidence`-shape/`ScrollScenarioEvidence` read), `src/domain/relationships.ts` (`deriveLayoutRelationships` full signature/result type), `src/browser/evidenceCapture.ts` (`capturePageEvidence`/`captureResolvedTargetRecord` - the coordinate-audit source), `src/browser/chromiumAdapter.ts` (screenshot capture call, context creation), `src/artifacts/artifactReader.ts`, `src/viewerServer/httpServer.ts`, `src/viewerServer/evidence/*`, `viewer/src/*`, `tests/unit/relationshipDerivation.test.ts` (unresolved-target fixture pattern reused), `tests/unit/cliFrontendContracts.test.ts` (observation fixture pattern already reused since Batch 2).
+
+Confirmed Batch 3's title/scope in `docs/plans/v0.8-implementation-plan.md` match the task exactly; no material difference found.
+
+## 4. Prior-path audit (task §6)
+
+Inspected `Z:\Users\newuser\Projects\`: exactly one sibling workflow directory exists, `my-frontend-observer.my-dev-kit-workflow` (correctly separated). No malformed duplicate (missing-separator variant) was found at any location - the two candidate paths given in the task text were in fact identical strings, so there was nothing to distinguish. Neither location was moved, deleted, or reused; Batch 3's own work used exclusively `...\my-dev-kit-workflow\v0.8\batch-03`.
+
+## 5. WORKFLOW_ROOT and my-dev-kit retrieval
+
+`WORKFLOW_ROOT` = `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-03`. Index built successfully:
+
+```
+npx @dailephd/my-dev-kit@latest index --root . --src src --src tests --src viewer --out "<WORKFLOW_ROOT>\my-dev-kit-index" --call-graph --json
+```
+
+All seven required searches were run (observation geometry ownership, relationship ownership, scroll/visibility/overflow evidence, Batch 2 projection/API ownership, viewer React selection/data loading, screenshot coordinate semantics, plus the general index build). Results consistently pointed at the same files direct inspection then confirmed in detail (`src/domain/schema.ts`, `src/domain/relationships.ts`, `src/browser/evidenceCapture.ts`, `src/browser/chromiumAdapter.ts`, `src/viewerServer/evidence/*`) - no `lookup`/`source`/`slice` follow-up was needed since the searches were unambiguous and direct file reads (§3) established the exact contracts.
+
+## 6. Coordinate audit (task §9 - the load-bearing decision)
+
+Established from direct source inspection, not assumption:
+
+- **Target geometry**: `src/browser/evidenceCapture.ts#captureResolvedTargetRecord` calls `el.getBoundingClientRect()` inside `handle.evaluate(...)`. This is viewport-relative CSS pixels (origin at the current viewport's top-left), captured from the same live page state the screenshot is taken from immediately after (same function/request lifecycle - `docs/ARCHITECTURE.md`'s existing "same live page/readiness state" invariant, unchanged by this batch).
+- **Screenshot**: `src/browser/chromiumAdapter.ts` calls `page.screenshot({type:'png'})` with no `fullPage` option - Playwright's default is `fullPage: false`, capturing exactly the current viewport at the current scroll position.
+- **Device scale factor**: `browser.newContext({viewport: {width, height}})` never sets `deviceScaleFactor` anywhere in this codebase, so Playwright's own default (`1`) applies to every observation this repository can currently produce. Consequence: the screenshot PNG's raw pixel dimensions equal `requestConfig.viewport.width × requestConfig.viewport.height` exactly - **1 CSS pixel = 1 PNG pixel** for every currently-producible observation.
+- **`devicePixelRatio` disposition**: captured as `pageEvidence.devicePixelRatio` (`window.devicePixelRatio`, always `1` under the context above) - kept as **informational observation-level display evidence only**. It is never read by any Batch 3 geometry/coordinate code path (`grep`-verified: the only production reference to `devicePixelRatio` outside `evidenceCapture.ts` itself is the read-only display line in `ObservationInspector.tsx`).
+- **Canonical viewport source**: `requestConfig.viewport` (`{width, height}`), a required, strongly-typed field validated on every `ObservationArtifact` (unlike the loosely-typed `pageEvidence: Record<string, EvidenceField<unknown>>` bag, which a hand-constructed test fixture could in principle omit fields from) - chosen as the authoritative SVG `viewBox` source for exactly this reason.
+
+**Conclusion**: no coordinate rewriting is needed or performed. The SVG `viewBox` is set to `0 0 {requestConfig.viewport.width} {requestConfig.viewport.height}` - the exact frame `getBoundingClientRect()` already used - and the screenshot `<image>` fills that same viewBox (`preserveAspectRatio="none"`, safe here specifically because the two frames are pixel-identical per the above). Target rectangles use `geometry.x/y/width/height` completely unchanged. This is also robust against a hypothetical future capture path using a different `deviceScaleFactor`, because the `<image>`/viewBox scaling is browser-native presentation behavior, never a manual multiplication in this codebase - satisfying task §9's explicit preference for a `viewBox`-based presentation mapping over evidence rewriting. No `BLOCKED_V08_BATCH3_COORDINATE_MAPPING_INADEQUATE` condition was found.
+
+## 7. Observation-view projection architecture
+
+Deliberately **not** a new server-side artifact-detail endpoint. The existing Batch 2 `GET /api/artifacts/<handle>` already returns the full, already-validated `ObservationArtifact` (targetEvidence, pageEvidence, requestConfig, screenshot field, completion, diagnostics, provenance, browser) unchanged - everything the target/observation inspector needs. Batch 3's "projection" is therefore two things:
+
+1. **One additive server-side computation** (`src/viewerServer/evidence/observationView.ts#getObservationRelationships`, exposed as `GET /api/observations/<handle>/relationships`) - the only genuinely new derivation this batch performs, and it is a thin, defense-in-depth-wrapped pass-through to the existing canonical `deriveLayoutRelationships` (§8). Ephemeral: computed fresh per request, never persisted, never a new artifact family.
+2. **Client-side presentation reshaping only** (`viewer/src/observation/targetOrder.ts#orderedTargets`) - selects/orders already-fetched fields (configured-target order, `hasGeometry` flag), explicitly not evidence derivation (frozen plan §27 permits "selection; filtering; formatting").
+
+Both are ephemeral, in-memory, per-request/per-render, and derived only from already-validated canonical domain values and canonical relationship-engine results - no `viewer.json`, no new artifact family, no mutation of `ObservationArtifact`.
+
+## 8. Canonical relationship-engine reuse
+
+`src/viewerServer/evidence/observationView.ts` calls `deriveLayoutRelationships` (`src/domain/relationships.ts`) exactly once, unchanged, against the already-classified, already-validated `ObservationArtifact` - the same function `docs/ARCHITECTURE.md`'s v0.4 architecture section documents as "the one canonical pure derivation." No relationship predicate (overlap, relative width, ordering, containment, fit, sequencing, page-width fit) is reimplemented anywhere in `src/viewerServer/` or `viewer/src/`. Proven by an exact-equality test (`tests/unit/observationRelationshipsServer.test.ts` "returns exactly the canonical `deriveLayoutRelationships(...)` result... never a second computation") that independently re-derives the same graph directly from the persisted artifact and asserts `toEqual` against the HTTP response body.
+
+## 9. Screenshot loading path
+
+Unchanged Batch 2 mechanism: `viewer/src/components/TargetOverlaySvg.tsx`'s `<image href={`/api/media/${handle}/screenshot`}>` - the same handle already used for `/api/artifacts/<handle>`, the same `screenshot` media role Batch 2 already implemented (`mediaResolver.ts`, unmodified). No new media role, no local path, no `file://`, no base64 embedding, no new viewer-owned copy of the bytes. Loaded only when the observation's visual workspace actually renders (i.e., only after a user selects a supported `observation` record) - never eagerly for the whole index.
+
+## 10. SVG component/layout
+
+`viewer/src/components/TargetOverlaySvg.tsx`: root `<svg viewBox="0 0 {w} {h}">` (§6); one `<image>` filling it; one `<rect>` per target with usable geometry (`role="button"`, keyboard-operable, `data-target-name` for identity); one `<text>` label per rectangle when the labels toggle is on; one `<line>` per pairwise relationship whose both endpoints have geometry (drawn between rectangle centers), only when the relationships toggle is on. `viewer/src/components/{TargetList,ObservationInspector,EvidenceFieldView,ObservationWorkspace}.tsx` provide the surrounding three-pane layout (Targets | Screenshot+SVG | Inspector) nested inside the existing Batch 1 `app-shell__workspace` region - the outer nav/details shell structure is untouched.
+
+## 11. Target selection architecture
+
+`viewer/src/components/ObservationWorkspace.tsx` holds `selected: string | undefined` (React `useState`, presentation-only, reset via a `useEffect` keyed on `handle` whenever a different observation is selected - task §17's "changing observation resets or safely rebinds selection" requirement). Both the target-list `<button>` and the SVG `<rect>` call the same `onSelect(name)` callback using the target's existing stable `name`; both re-render their own `aria-pressed`/selected-class state from the single shared `selected` value, and the inspector reads the same value - genuine bidirectional synchronization through one source of truth, not two parallel selection states. Proven in real Chromium (`tests/browser/observationSvgWorkspace.test.ts`, two dedicated tests: SVG→list/inspector and list→SVG).
+
+## 12. Unresolved-target behavior
+
+`orderedTargets()`'s `hasGeometry` is `true` only when `geometry.state` is `'available'` or `'partial'` - never merely because the target is configured. `TargetOverlaySvg` skips rendering entirely for any target without usable geometry (`geometryOf()` returns `undefined`, the `.map` callback returns `null`). No `x=0 y=0 width=0 height=0` fallback exists anywhere in the code. The target remains fully selectable from `TargetList` (shown with its real resolution status, e.g. `not-found (no geometry)`) and its canonical resolution/reason evidence is shown honestly in `ObservationInspector`. Proven with a real fixture (`missingWidget`, `not-found`) at the unit, server, and real-Chromium levels (`tests/unit/observationCoordinateMapping.test.ts`, `observationRelationshipsServer.test.ts`, `tests/browser/observationSvgWorkspace.test.ts`).
+
+## 13. Overlay controls
+
+Three independently toggleable controls (`ObservationWorkspace`'s `OverlayToggles` state): **geometry** (target rectangles), **labels** (target-name text, disabled/hidden when geometry is off, since a label with no rectangle would be presentation-meaningless), **relationships** (connector lines). Toggling never refetches or alters the underlying artifact/graph - purely a render-time filter over already-fetched data.
+
+## 14. Visibility presentation
+
+Not a separate overlay category in this batch: `TargetVisibility.visible` (existing canonical evidence, `derived` source) is shown honestly in the target inspector (`EvidenceFieldView` on `record.visibility`) exactly as the artifact states it - never inferred from screenshot pixels or from the mere existence of a rectangle. No new visibility threshold was introduced.
+
+## 15. Overflow presentation
+
+`record.style` (display/position/overflow-x/overflow-y, existing canonical `computed-browser` evidence) and `record.layout` (scroll/client dimensions, existing canonical `browser` evidence) are shown honestly in the target inspector via `EvidenceFieldView`, unmodified and unreinterpreted. No SVG rectangle-intersection-based overflow inference exists anywhere in this batch.
+
+## 16. Scroll presentation
+
+`ObservationInspector` distinguishes, using only existing canonical evidence: no scroll scenario configured (`artifact.scrollScenarioEvidence === undefined` - shown as an honest "No scroll scenario was configured for this observation" note) vs. available evidence (`initial`/`final`/`transition`/`scrollOwner`, shown via the existing `ScrollScenarioTransition`/`ScrollOwnerInterpretation` fields, `EvidenceFieldView` honoring the field's own `EvidenceField` state for `scrollOwner`). No browser action is re-run from the viewer; no historical trajectory is animated; no movement arrow is fabricated - the presentation is textual/status-only, exactly matching task §22's "if a faithful spatial overlay is not possible, show scroll evidence in the inspector/status layer."
+
+## 17. Inspector evidence exposed
+
+**Target inspector**: resolution status, tag, semantics (role/name), semantic state, landmark, geometry, style, layout metrics, visibility, containment - each via `EvidenceFieldView`, which renders `available`/`partial` (with source and, for partial, the reason), `unavailable` (with reason), and `not-applicable` (with optional reason) distinctly - never a fabricated empty string or zero for missing evidence. Plus the relationships involving that target.
+
+**Observation inspector**: observation id, request id, schema version, producer, viewport, page title, requested/final URL, device pixel ratio, document width/height, window scroll X/Y, completion state, diagnostics, scroll-scenario evidence (or its honest absence), and the full relationship list.
+
+## 18. Files created
+
+- `src/viewerServer/evidence/observationView.ts`
+- `viewer/src/types/observation.ts` (type-only re-exports of canonical Node domain types - erased at build time, no runtime coupling)
+- `viewer/src/observation/targetOrder.ts`
+- `viewer/src/hooks/useObservationRelationships.ts`
+- `viewer/src/components/TargetOverlaySvg.tsx`, `TargetList.tsx`, `ObservationInspector.tsx`, `ObservationWorkspace.tsx`, `EvidenceFieldView.tsx`
+- `tests/unit/observationCoordinateMapping.test.ts`, `observationRelationshipsServer.test.ts`, `observationFixtureSanity.test.ts`
+- `tests/browser/observationSvgWorkspace.test.ts`
+- `docs/reports/v0.8-observation-svg-inspection-batch3.md` (this file)
+
+## 19. Files modified
+
+- `src/viewerServer/httpServer.ts` - added `GET /api/observations/<handle>/relationships` routing (405 for write methods, 404 unknown handle, 409 not-an-observation/not-currently-loadable/derivation-failed, 200 with the graph); `/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, and static-asset serving byte-for-byte unchanged.
+- `tests/support/evidenceFixtures.ts` - added `realisticPageEvidence`, `unresolvedTarget`, `buildRealPng` (a genuinely decodable solid-color PNG, distinct from the existing header-only `buildMinimalPng`), `writeRichObservationFixture`; extended `buildObservation` with optional `pageEvidence`/`viewport` parameters (backward compatible - existing call sites unaffected, default values unchanged).
+- `viewer/src/components/ArtifactPreview.tsx` - branches to `ObservationWorkspace` for `family === 'observation'`; every other family's raw-JSON preview is unchanged.
+- `viewer/src/styles/index.css` - additive rules for the new workspace/list/SVG/inspector UI.
+- `tests/unit/viewerPwaBuild.test.ts` - added the explicit Batch 3 cache-boundary assertion (§20).
+- `tests/browser/viewerEvidenceShell.test.ts` - two pre-existing Batch 2 assertions that selected an `observation` record to test the *generic* raw-JSON on-demand-load path and the *generic* no-visualization invariant now legitimately conflict with Batch 3's real observation workspace; both were repointed to a `comparison` record (which still exercises exactly the generic path/invariant they were written to protect) rather than weakened - the same kind of sanctioned evolution as Batch 1→2's placeholder-text update and Batch 2's `TST-401`.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 3 sections (§6-§17 above, condensed).
+
+## 20. PWA cache verification
+
+No `vite.config.ts`/service-worker change needed: `GET /api/observations/<handle>/relationships` lives under the already-denylisted `/api/` prefix. Extended `tests/unit/viewerPwaBuild.test.ts` with an explicit assertion against the real built `sw.js`: still exactly one `registerRoute` call, and the precache manifest contains no `/api/observations` entry.
+
+## 21. Tests added/modified and behavior protected
+
+| Test file | Level | Protects |
+|---|---|---|
+| `observationFixtureSanity.test.ts` | unit | The new `buildRealPng` generator produces a genuinely decodable PNG at exact viewport pixel dimensions (underpins every browser-level assertion below). |
+| `observationCoordinateMapping.test.ts` | unit | `requestConfig.viewport` presence/fidelity; geometry preserved exactly (fractional values, no rounding); `devicePixelRatio≠1` never multiplies geometry; `partial` geometry state preserved (never promoted/discarded); geometry partly outside the viewport preserved unclamped; relationship engine never includes the unresolved target. |
+| `observationRelationshipsServer.test.ts` | unit/integration (real HTTP) | Server relationship route is byte-for-byte identical to a direct `deriveLayoutRelationships` call (proves no second engine); unresolved target excluded from pairwise relationships; a real geometric relationship (`header above footer`) is produced; non-observation handle → 409; unknown handle → 404; unsupported-version observation → 409; write methods → 405. |
+| `viewerPwaBuild.test.ts` (+1) | build/integration | New route covered by the existing `/api/` denylist, no new runtime-caching rule. |
+| `viewerEvidenceShell.test.ts` (2 updated) | browser | Generic Batch 2 on-demand-load/no-visualization invariants still hold for non-observation families after Batch 3. |
+| `observationSvgWorkspace.test.ts` | browser (real Chromium, real persisted evidence) | Full real-browser proof - see §22. |
+
+## 22. Real-browser proof (task §33)
+
+`tests/browser/observationSvgWorkspace.test.ts`, against the actual built `dist/viewer` PWA, the actual built loopback server, and one real observation (`writeRichObservationFixture`: real writer, genuinely decodable 800×600 PNG screenshot, two geometrically resolved targets plus one genuine `not-found` target). Five tests, all passing:
+
+1. Screenshot visibly loads (`<image href>` resolves to a real `/api/media/observation:...` URL); resolved targets (`header`, `sidebar`) have real `<rect>` elements whose `x`/`y`/`width`/`height` attributes exactly match the fixture's canonical geometry (`0,0,800,80` and `0,100,200,400`); the unresolved target (`missingWidget`) receives **no** `<rect>` at all and is shown honestly (`not-found`) in the target list.
+2. Selecting the SVG `<rect>` for `header` sets `aria-pressed="true"` on both the rect and its list entry, and the inspector shows `Target: header` with matching geometry text (`x:0 y:0 w:800 h:80`).
+3. Selecting `sidebar` from the target list sets `aria-pressed="true"` on the corresponding SVG rect and updates the inspector - the reverse-direction synchronization.
+4. The relationships panel shows the real canonical `above` relationship between `header`/`footer` labeled "Derived evidence", and at least one connector `<line>` is actually drawn between resolved targets.
+5. After `page.setViewportSize` changes (from 1000×800 to 1400×900), the rendered SVG element's bounding-box aspect ratio remains within 0.05 of the canonical 800:600 (4:3) ratio - screenshot and overlay scale together, proving the `viewBox` mapping holds under resize.
+
+## 23. 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` | **PASS** — 1085/1085 tests, 59/59 files |
+| `npm run build` | **PASS** — unchanged Node/library output plus `dist/viewerServer/evidence/observationView.js` and the rebuilt `dist/viewer/**` PWA |
+| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
+| `npm run test:browser` | **PASS** — 137/137 tests, 13/13 files (real Chromium; run in full per task §37, not skipped) |
+| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
+
+## 24. Built viewer Batch 3 smoke (task §38)
+
+Fixture: one real observation (`smoke-rich-obs`, 800×600) built via a one-off script (not committed, `WORKFLOW_ROOT\tmp`) calling the actual compiled `dist/artifacts/artifactWriter.js` directly - a real, genuinely decodable PNG screenshot; `header`/`sidebar`/`footer` (resolved, geometrically arranged to produce a real `above` relationship) plus `missingWidget` (`not-found`) - under `WORKFLOW_ROOT\smoke\evidence-root`.
+
+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/status` → `200`, correct root.
+- `/api/index` → one `observation`/`supported` record with `logicalId: "smoke-rich-obs"`.
+- `/api/artifacts/<handle>` → `200`, full artifact, all four configured targets present.
+- `/api/media/<handle>/screenshot` → `200 image/png`, 2789 bytes (a real, non-trivial PNG, not a stub).
+- `/api/observations/<handle>/relationships` → `200`; `unresolvedTargets` correctly lists `missingWidget` (`not-found`); 18 pairwise relationships; a real `header`-`above`-`footer` relationship confirmed present.
+- PWA still loads (`/`, `/manifest.webmanifest`, `/sw.js` all `200`); `sw.js` contains no `api/observations` reference (not runtime-cached).
+- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
+- Server located by real PID and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
+- A post-shutdown listing of the smoke evidence root shows exactly the two files the fixture script wrote (`manifest.json`, `screenshot.png`) - no stray writes, no modification.
+
+**Result: PASS.** Logs retained under `WORKFLOW_ROOT\logs\` (`smoke-server.log`, `smoke-checks-1.log`, `smoke-checks-2.log`, `smoke-checks-3.log`, `index-response.json`, `artifact-response.json`, `relationships-response.json`).
+
+## 25. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\cache\npm` | Retained (npm cache from the my-dev-kit-index `npx` invocation) |
+| `WORKFLOW_ROOT\tmp\vite-cache`, `WORKFLOW_ROOT\tmp\build-smoke-observation.mjs` | Retained (build cache empty again - Vite build mode doesn't populate it, same finding as Batches 1-2; the smoke-fixture script is dev/readiness tooling only, not committed) |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, §24) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained (real observation fixture tree built for the smoke test) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index + cache-metadata, §5) |
+| `WORKFLOW_ROOT\fixtures` | Retained, empty/unused (no committed deterministic repository fixture was needed - all Batch 3 fixtures are built programmatically via `tests/support/evidenceFixtures.ts`, matching the existing repository convention) |
+| Repo-root `dist/` | Ordinary build output (gitignored); rebuilt cleanly by `scripts/clean.mjs` on every `npm run build` |
+| Pre-existing repo-root `.my-dev-kit*`/`baselines`/`comparisons`/`contracts`/`evaluations`/`observations` | Pre-existing, empty, untouched (same finding as Batches 1-2) |
+
+`WORKFLOW_ROOT`s for Batch 1 (`...\v0.8\batch-01`) and Batch 2 (`...\v0.8\batch-02`) were never targeted by any command in this session (verified) - preserved exactly as their own batches left them.
+
+## 26. Repository pollution check
+
+`git status --short` before staging showed only the 8 modified + 12 new Batch-3-owned paths listed in §18/§19. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 3 workflow path exists (§4).
+
+## 27. Batch 1/2 regression check
+
+**PASS.** All Batch 1 tests (`view` CLI, `127.0.0.1`/port `4319`, PWA shell/installability, cache boundary, server cleanup) and all Batch 2 tests (evidence indexing, unsupported-version handling, safe handles, on-demand artifact loading, media security, approved-reference image resolution, filesystem containment) pass unmodified except the two `viewerEvidenceShell.test.ts` updates described in §19, which preserve the exact invariants they originally protected while accounting for Batch 3's legitimate new observation-specific behavior.
+
+## 28. 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/`, `src/browser/`, `src/artifacts/*Writer.ts`, and every existing reader are byte-for-byte unchanged.
+
+## 29. Deviations
+
+- None. Every task step (my-dev-kit retrieval, the coordinate audit, all required test categories, the full validation chain including `test:browser`, and the built-CLI smoke) was executed as specified.
+
+## 30. Remaining uncovered risks
+
+- **The relationship overlay draws one `<line>` per pairwise relationship *kind*, not one per target pair.** For a pair of targets that satisfy several relationship families simultaneously (common for axis-aligned rectangles - e.g. `horizontally-overlapping` + `above` + `does-not-overlap` all being true at once), multiple overlapping connector lines are drawn between the same two centers. This is not a fabrication (every line corresponds to a genuinely distinct canonical relationship record), but it is visually noisy for observations with several targets; a later batch could deduplicate by center-pair or use per-kind visual differentiation.
+- **The observation inspector's completion/diagnostic display is a flat list**, not yet organized by diagnostic severity/target - acceptable for this batch's scope (task §23/§24 list required fields, not a required layout), but could be revisited alongside Batch 4+'s own inspector needs.
+- Batch 1's and Batch 2's previously reported risks (install-prompt "available" branch untested in headless Chromium, `findImportedReferenceDir`'s per-request re-walk) remain unresolved and out of this batch's scope.
+
+## 31. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: before/after comparison UI, contract/change-scope visualization, external-reference visual inspection, side-by-side reference/candidate display, reference regions, reference/runtime binding, cross-reference selection, reference fidelity, independent visual-pane zoom/pan, synchronized lock, bounded-agent-context UI, source-correlation UI, arbitrary raw-file browsing, annotation, source editing, automatic target discovery, automatic binding, computer vision, pixel-diff scoring, image-to-code, cloud hosting, database, authentication, collaboration.
+
+## 32. Final verdict
+
+Batch 3 ("Runtime observation inspection and SVG overlays") is implemented and independently validated: a developer can select a supported observation through the existing Batch 2 data boundary, see its screenshot loaded on demand through the existing safe media endpoint, inspect stable runtime targets overlaid via SVG in the observation's own canonical coordinate domain (no evidence rewriting, verified against a genuine `devicePixelRatio≠1` case), select targets from either the list or the SVG with full bidirectional synchronization, inspect complete canonical target/observation evidence honestly (including genuinely unresolved targets, which never receive fabricated geometry), and inspect canonical layout-relationship evidence computed exclusively by the existing `deriveLayoutRelationships` engine - proven at the unit, real-HTTP, real-Chromium, and real-built-CLI-smoke levels. No Batch 4+ visualization, no v0.9 annotation, and no release/publication action was taken. Package version remains `0.7.0`.