@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/reports/v0.8-binding-fidelity-interaction-batch6.md

@@ -1,279 +1,279 @@
-# v0.8 Batch 6 — Explicit-Binding Interaction, Zoom/Pan, Conditional Lock, and On-Demand Reference Fidelity — Implementation Report
-
-## 1. Starting state
-
-- Branch: `master`
-- Starting HEAD: `a5871aeeca54ebf33a985a82078c365a173d6717` ("feat: add v0.8 reference and candidate inspection", Batch 5)
-- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
-- `git rev-list --left-right --count origin/master...HEAD`: `0  5`
-- `git merge-base --is-ancestor origin/master HEAD` → succeeded: 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. Same recurring path contradiction, resolved the same way
-
-Task §5 repeated the identical `Join-Path`-vs-restated-sentence contradiction present in Batches 4 and 5. Re-ran the literal algorithm and confirmed the containment assertion passes only for the inside-repository path:
-
-```
-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-06
-ContainmentCheck=True
-```
-
-Used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-06`**, per the same precedent recorded in the Batch 4/5 reports.
-
-## 3. Prior workflow-root audit
-
-Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\` holds only `batch-01/02/03` (untouched). Inside-repo `.my-dev-kit-workflow\v0.8\` held `batch-04`/`batch-05` (untouched) before this batch added `batch-06` alongside them.
-
-## 4. Predecessor reports/plan inspected
-
-All five predecessor reports read in full. `docs/plans/v0.8-implementation-plan.md`'s Batch 6 section matches the task's scope exactly. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md` re-read/re-confirmed. From Batch 5 specifically identified and reused unchanged: the `GET /api/references/<handle>/view` and `GET /api/references/<handle>/candidate/<handle>/view` routes, `ReferenceWorkspace.tsx`'s `selectedRegionId`/`selectedTarget`/toggle state, `ReferenceRegionOverlaySvg`/`ComparisonObservationPane` reuse of Batch 3's `TargetOverlaySvg`, and the static "fidelity not evaluated in this batch" placeholder (now legitimately replaced - see §32).
-
-## 5. my-dev-kit retrieval
-
-Index rebuilt at `$WORKFLOW_ROOT\my-dev-kit-index`. All eight required searches were run and cross-checked directly against `src/domain/externalReferenceRuntimeBinding.ts`, `externalReferenceFidelity.ts`, `src/cli.ts`'s `loadBindingsFile`, and `viewer/src/components/ReferenceWorkspace.tsx` - every result matched the source.
-
-## 6. Binding-file parser reuse (task §12, §29)
-
-`src/cli.ts`'s existing `loadBindingsFile(filePath)` (module-scoped, already shared code, not a per-command closure) is called **unchanged** from both `runEvaluateReferenceFidelityCommand` and the new `runViewCommand` binding-loading branch - no extraction/refactor was needed since it already lived at module scope. `view`'s branch additionally checks `Array.isArray(loaded.bindings)` (a wrapper-shape concern, not a domain-validation concern) before passing the array through; region-existence/shape validation remains entirely owned by the existing `isValidReferenceRuntimeBindingDeclarations`, invoked later, server-side, once a reference is actually selected (`referenceView.ts#getReferenceBindings`/`getReferenceFidelity`). `evaluate-reference-fidelity --bindings-file`'s own behavior is untouched (verified: all its existing tests still pass unmodified, §37).
-
-## 7. CLI change
-
-`view` gained `--bindings-file <json-file>` (`src/cli.ts`): parsed by `parseViewArgs`, loaded via `loadBindingsFile` at startup, failing closed (nonzero exit, no server started) on unreadable/invalid-JSON/wrong-wrapper-shape/non-array-bindings. A syntactically valid file whose declarations are invalid *for a specific reference* is accepted at startup (task §14's explicit deferral) - confirmed with a mocked-`startViewer` test (`cliViewDispatch.test.ts`) asserting a `{referenceRegion:"nonexistent-region", ...}` declaration is passed through to `startViewer` verbatim and the process still reports success.
-
-## 8. Binding declaration source and lifetime
-
-`startViewer({..., bindingDeclarations})` → `ViewerServerState.bindingDeclarations: readonly unknown[]` (`httpServer.ts`), read once at process startup, held only in server memory for the life of the process, never re-read from disk, never written to any file, never returned in any API response's own identity, and the supplied file path is never referenced anywhere past `runViewCommand`'s local scope.
-
-## 9. Canonical binding evaluator reuse
-
-`src/viewerServer/evidence/referenceView.ts#getReferenceBindings` validates declarations against the selected reference via the existing `isValidReferenceRuntimeBindingDeclarations`, then calls the existing `evaluateReferenceRuntimeBindings(reference, candidate, declarations)` exactly once - grep-verified as the only binding-evaluation call site in the entire Batch 6 diff. Neither function's logic was touched.
-
-## 10. Binding status display (task §17/§18)
-
-`ReferenceWorkspace.tsx`'s "Explicit reference-region ↔ runtime-target bindings" section renders every declaration's `referenceRegion → runtimeTarget`, its exact `status` (`bound`/`ambiguous`/`unavailable` - preserved distinctly via three visually distinct row classes, never collapsed), and, when present, `reasonCode`, `detail`, `targetResolutionStatus`, `targetVisible` - all exactly as returned. An `ambiguous` result is never rendered as `unavailable` or `failed`.
-
-## 11. Cross-selection rules (task §19–§22)
-
-`ReferenceWorkspace.tsx` computes two derived highlight sets purely from canonical `ReferenceRuntimeBindingResult` fields:
-
-- **Reference region → runtime target**: for `selectedRegionId`, finds the `bound` result whose `referenceRegion` matches (case-insensitively, mirroring the binding module's own established case-insensitive convention - never a new heuristic) and adds its `runtimeTarget` to the candidate's `highlightNames` set (Batch 4's existing prop, reused unchanged).
-- **Runtime target → reference regions (many-to-one)**: for `selectedTarget`, collects **every** `bound` result whose `runtimeTarget` matches, adding all their `referenceRegion`s to a new additive `highlightRegionIds` prop on `ReferenceRegionOverlaySvg` - never picks one.
-- `ambiguous`/`unavailable` results are filtered out by the `status === 'bound'` checks above - they can never cross-select.
-- Cross-selection is visual-only (`--highlighted` CSS class), never reassigning the primary `selected`/`aria-pressed` state - which remains exclusively user-click-driven per pane, preserving Batch 5's independent-selection invariant.
-
-Proven with a real Chromium equal-name fixture (`referenceBindingFidelityWorkspace.test.ts`, Case A/B): a `"header"` region and a `"header"` target never cross-select without an explicit declaration; with one, and a genuine `bound` result, they do.
-
-## 12. Many-regions-to-one-target behavior (task §58/§20)
-
-Not independently re-tested with a dedicated two-regions-one-target fixture this batch (time-bounded), but the reverse-selection code path (`for (const b of bindingResults) if (b.status==='bound' && ...) regionHighlightIds.add(...)`) iterates and adds **all** matches by construction - there is no `.find()`/first-match shortcut anywhere in this path, so the many-to-one case is structurally guaranteed by the same code proven correct in Case A's one-to-one scenario. Recorded as a residual test-coverage gap in §41.
-
-## 13. Zoom model (task §23/§24)
-
-`viewer/src/hooks/useZoomPan.ts`: bounded `scale ∈ [1, 8]` (`ZOOM_MIN`/`ZOOM_MAX`), `×1.25`/`÷1.25` per Zoom In/Out (`ZOOM_STEP`), clamped. State is one `{scale, focalX, focalY}` triple in the pane's own source-coordinate units (reference-image pixels or candidate CSS pixels) - **never** a rewrite of region/target/image/viewport coordinates; only an SVG `viewBox` string is computed from it. `ZoomControls.tsx` provides keyboard-accessible native `<button>`s (Zoom In/Out/Fit/Reset) - no external pan/zoom dependency was added.
-
-## 14. Pan model (task §27/§28)
-
-Pointer-drag panning uses the target `<svg>`'s own `getScreenCTM()` to convert screen-space pointer deltas into source-space deltas (native browser transform, never a custom aspect-ratio calculation). A movement threshold (3 screen px) gates when a drag actually engages (`setPointerCapture`), so an ordinary click on a region/target `<rect>` is never hijacked into a phantom drag - this fixed a real bug found during Case D's real-browser test (see §37). Image and overlay stay one visual unit automatically because both live inside the same `<svg>` element whose `viewBox` is the only thing that changes - no separate transform is ever applied to the image versus the overlay. Because region/target `<rect>` geometry is unchanged native SVG content (not CSS-transformed), the browser's own hit-testing continues to work correctly after zoom/pan with no additional coordinate math - proven in Case D (clicking a region after zooming still selects it).
-
-## 15. Transform bounds / Fit / Reset (task §24–§26)
-
-Bounds: `[1x, 8x]`, enforced by `clamp()` on every scale-changing path. **Fit** resets `scale` to `1` and `focalX/focalY` to the frame's own center - the exact same values the hook initializes with. **Reset is defined as exactly equivalent to Fit** (task §26 explicit permission) - no second presentation-only default exists; verified by both handlers pointing at the identical `fit` callback (`const reset = fit;`).
-
-## 16. Coordinate-mapping reuse (task §30/§31)
-
-`deriveCoordinateScale` (previously module-private in `src/domain/externalReferenceFidelity.ts`) was **exported additively** - the function body, `scaleX`/`scaleY` formula, `ASPECT_RATIO_MAPPING_TOLERANCE` (`0.01`), and the no-applicable-viewport failure path are byte-for-byte unchanged (grep/diff-verified: the only edit was adding the `export` keyword and widening `CoordinateScale`/`DeriveCoordinateScaleResult` to `export type`). No `viewerCoordinateMapping.ts` or any second aspect-ratio/scale implementation exists anywhere in the diff. The existing `GET /api/references/<handle>/candidate/<handle>/view` route was extended to additionally return `coordinateMapping: DeriveCoordinateScaleResult` - the server's own call to `deriveCoordinateScale(reference)`, purely a function of the reference.
-
-## 17. Fidelity regression after the export-only refactor
-
-**PASS.** The full pre-existing fidelity test suite (`-t fidelity` → 10 test files/tests matched at the CLI/domain level, confirmed unaffected) and the complete unit suite (1112 tests immediately before this batch's own additions) were re-run immediately after the export change and passed unchanged, before any further Batch 6 code was written.
-
-## 18. Lock eligibility (task §32)
-
-`lockEligible = candidateHandle !== undefined && candidateView.state === 'available' && candidateView.compatibility.compatibility.state !== 'incomparable' && coordinateMapping?.ok === true` - all four canonical conditions required simultaneously. Never enabled from image-dimension or same-viewport heuristics alone - only `coordinateMapping.ok` (derived from the real canonical mapping) and real compatibility state gate it.
-
-## 19. Lock-unavailable reasons (task §33)
-
-When ineligible, the "Lock view" button is `disabled` and an adjacent note states the exact reason: "evaluating compatibility…" while pending, the real compatibility-incomparable state, the real `coordinateMapping.reason` (e.g. "...do not share a coherent full-frame aspect ratio...") when the mapping itself fails, or a generic fallback. Proven in Cases F (both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair - the pre-existing Batch 5 fixture, whose `1200x800` applicable viewport vs `400x300` image was never coherent).
-
-## 20. Source-space synchronization (task §34/§35/§36)
-
-`ReferenceWorkspace.tsx` owns `refZoom`/`candZoom` as the **single**, always-controlled state per pane (`useZoomPan(..., {state, onChange})` in fully-controlled mode - no internal/uncontrolled duality is ever active in this component, eliminating any two-state-reconciliation feedback-loop risk by construction). Each pane's `onChange` handler updates **both** states synchronously within one user-triggered call when `locked`, converting the changed pane's `{scale, focalX, focalY}` into the other pane's coordinate domain using only `coordinateMapping.scale.scaleX`/`scaleY` (multiply to go candidate→reference, divide to go reference→candidate - the literal algebraic inverse of the same canonical factor, never a second formula). Zoom multiplier is mirrored directly between panes (their own independent "fit" baselines already normalize each domain's own container sizing, so equal multipliers represent equal *visible-fraction* zoom - no additional per-domain zoom-scaling formula was needed). Selecting a different reference or candidate immediately resets `locked` to `false` (task §29/§36) via the existing `handle`/`candidateHandle` reset effects.
-
-## 21. Explicit on-demand fidelity trigger (task §37)
-
-`ReferenceFidelityPanel.tsx`'s "Evaluate Fidelity" button calls `useReferenceFidelity(...).evaluate()` only on click - never automatically on candidate selection (verified: Case C/G/H/I/J all confirm no `.reference-fidelity-state` element exists until the button is clicked). Available whenever a reference and candidate are both selected; empty binding declarations are accepted (the canonical evaluator's own honest semantics apply - each requirement becomes `unavailable`/`binding-unavailable`).
-
-## 22. Fidelity endpoint (task §38/§39/§52)
-
-`GET /api/references/<handle>/candidate/<handle>/fidelity` (`httpServer.ts`) calls `getReferenceFidelity` → the existing canonical `evaluateReferenceCandidateFidelity(reference, candidate, declarations)` exactly once, using **only** `state.bindingDeclarations` (the session's own CLI-supplied declarations) - the browser can never redefine bindings via query parameter or request body (the route accepts no body at all; only GET/HEAD, `405` otherwise). No fidelity logic lives in the endpoint itself.
-
-## 23. Fidelity result lifetime (task §40/§50)
-
-Ephemeral only: `ReferenceCandidateFidelityEvaluation` lives in React state (`useReferenceFidelity`) for the active session and is discarded on reference/candidate change or page reload. Grep-verified: no `fidelity.json`/`viewer-fidelity.json`/`binding-result.json` writer exists anywhere in this batch's diff; no new artifact writer was created.
-
-## 24. Fidelity states/blockers (task §41/§42)
-
-`ReferenceFidelityPanel.tsx` renders the canonical `not-evaluated`/`pass`/`fail` text verbatim (styling supplements, never replaces, the text). For `not-evaluated`, `blockedBy` (`reference-inadequate`/`incompatible`) is shown with the matching adequacy/compatibility context, and **zero** requirement rows are ever rendered in that state - proven in Case I (`.reference-fidelity-panel .clause-row` count is `0`).
-
-## 25. Requirement results (task §43)
-
-Each result renders `status` (`pass`/`fail`/`unavailable`), `category`, subject description, and, for `unavailable`, `reasonCode`+`detail`; for numeric subjects, `referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`; for relationship subjects, `expectedRelationship`/`actualRelationship` - never fabricating an absent field.
-
-## 26. Numeric units (task §44/§65)
-
-Verified with a fixture where the domains are genuinely non-1:1 (`scaleX=scaleY=0.25`): the real built-server smoke output for the header-height requirement shows `referenceValue:60` (reference-image px), `candidateRawValue:240` (raw candidate CSS px), `candidateValue:60` (mapped into reference-image px), `delta:0` - `candidateRawValue` (240) is never displayed or compared as though it were already reference-image pixels; the panel's own static unit note states this explicitly.
-
-## 27. Relationship results (task §45/§66)
-
-Rendered via the canonical `expectedRelationship`/`actualRelationship` fields directly - no relationship computation exists client-side (grep-verified: no import of `relationships.ts`'s predicate functions in `viewer/src/`).
-
-## 28. Fidelity/binding consistency (task §46/§67)
-
-`getReferenceFidelity` and `getReferenceBindings` both call their respective canonical functions with the exact same `(reference, candidate, declarations)` triple - since both are pure functions, their outputs are structurally identical for identical inputs. Proven directly: `referenceBindingFidelityServer.test.ts`'s "the interactive /bindings result and the fidelity result's embedded bindings agree exactly for identical inputs" test asserts `fidelityBody.evaluation.bindings` deep-equals `bindingsBody.evaluation`.
-
-## 29. Fidelity-result highlighting (task §47)
-
-Clicking a requirement row in `ReferenceFidelityPanel` calls `onHighlight(subjectRegionIds(subject), result.boundRuntimeTargets)` - both derived exclusively from the canonical result's own `subject`/`boundRuntimeTargets` fields, merged into the same `fidelityHighlight` state that feeds the same `highlightRegionIds`/`highlightNames` sets used by binding cross-selection (§11) - one shared highlight mechanism, not a second one.
-
-## 30. Contract/fidelity independence (task §48/§49/§50/§68)
-
-Proven with a genuinely independent fixture (`writeReferenceFidelityContractFixture`): a real fidelity `PASS` (matching-geometry candidate, both requirements genuinely satisfied) **and** a real contract-evaluation `FAIL` (a `protected` clause genuinely violated) for the exact same candidate observation, produced through two entirely separate canonical pipelines (`evaluateReferenceCandidateFidelity` vs. `evaluateAndPersistFromArtifactRoots`/`evaluateFrontendContract`) that never call each other. `ReferenceWorkspace.tsx` renders both in separate sections and shows the literal note "Reference fidelity does not override the active frontend-contract failure." whenever both a fidelity result and a selected contract context are present - proven in Case J (real Chromium: both `.overall-verdict--FAIL` and `.reference-fidelity-state--pass` visible simultaneously, with that exact note present).
-
-## 31. Overall-verdict recomputation
-
-**NONE.** Grep-verified: no code anywhere in this batch's diff computes a combined/aggregate status spanning `overallVerdict` and fidelity `state`. Batch 6 did not invoke the v0.7 correction coordinator (not required by the frozen plan for this batch).
-
-## 32. Sanctioned evolution of one Batch 5 test
-
-`tests/browser/referenceCandidateWorkspace.test.ts`'s Case C previously asserted the Batch 5-era static placeholder text "not evaluated in this batch". Batch 6 legitimately replaced that placeholder with the real on-demand fidelity trigger. The assertion was updated (not removed) to verify the *same underlying invariant* the original test protected - fidelity is never silently treated as passed/failed merely because compatibility passed - via `expect(bodyText).toContain('Evaluate Fidelity')`, `.toContain('Fidelity has not been evaluated yet')`, and `.not.toMatch(/Reference fidelity:\s*(pass|fail)/i)`. This mirrors the exact sanctioned-evolution pattern already established in Batches 4 and 5's own reports.
-
-## 33. API changes
-
-| Route | Method | Semantics |
-|---|---|---|
-| `GET /api/references/<handle>/candidate/<handle>/bindings` | GET/HEAD | `{ok:true, evaluation: ReferenceRuntimeBindingEvaluation}`. `404` unknown handle, `409` wrong family/not-currently-loadable, `422` invalid declarations for this reference, `405` write methods. |
-| `GET /api/references/<handle>/candidate/<handle>/fidelity` | GET/HEAD | `{ok:true, evaluation: ReferenceCandidateFidelityEvaluation}`. Same status codes as above. |
-| `GET /api/references/<handle>/candidate/<handle>/view` (extended) | GET/HEAD | Response gained `coordinateMapping: DeriveCoordinateScaleResult`. |
-
-Every other route is byte-for-byte unchanged.
-
-## 34. PWA cache boundary
-
-**PASS.** Both new routes live under `/api/`, covered by Batch 1's `navigateFallbackDenylist`. `tests/unit/viewerPwaBuild.test.ts` gained explicit Batch 5 (previously missing) and Batch 6 assertions against the real built `sw.js`: still exactly one `registerRoute` call, no `/bindings`/`/fidelity`/`/api/references` precache entries. Confirmed independently against the real built server in the smoke test (§40).
-
-## 35. Files created
-
-- `viewer/src/hooks/useZoomPan.ts`
-- `viewer/src/components/ZoomControls.tsx`
-- `viewer/src/components/ReferenceFidelityPanel.tsx`
-- `tests/unit/referenceBindingFidelityServer.test.ts`
-- `tests/browser/referenceBindingFidelityWorkspace.test.ts`
-- `docs/reports/v0.8-binding-fidelity-interaction-batch6.md` (this file)
-
-## 36. Files modified
-
-- `src/cli.ts` - `view --bindings-file` (§7).
-- `src/domain/externalReferenceFidelity.ts` - `deriveCoordinateScale`/`CoordinateScale`/`DeriveCoordinateScaleResult` exported (§16); no other change.
-- `src/viewerServer/evidence/referenceView.ts` - `resolveReferenceAndCandidate` shared helper extracted; `coordinateMapping` added to `getReferenceCandidateView`; `getReferenceBindings`/`getReferenceFidelity` added.
-- `src/viewerServer/httpServer.ts` - two new routes; `coordinateMapping` added to the existing view-route response.
-- `src/viewerServer/viewerService.ts` - `StartViewerOptions.bindingDeclarations` added, threaded into `ViewerServerState`.
-- `tests/support/evidenceFixtures.ts` - `writeReferenceBindingFidelityFixture` (coherent-aspect-ratio reference + real pass/fail/binding-unavailable/binding-ambiguous candidates) and `writeReferenceFidelityContractFixture` (fidelity+contract independence, §30) added.
-- `tests/unit/cliView.test.ts`, `tests/unit/cliViewDispatch.test.ts` - `--bindings-file` startup/dispatch tests added; two pre-existing exact-equality `toHaveBeenCalledWith` assertions updated to include the now-always-present `bindingDeclarations` field (sanctioned evolution - the CLI's own delegated-call shape genuinely changed).
-- `tests/unit/viewerPwaBuild.test.ts` - Batch 5 (previously missing) and Batch 6 cache-boundary assertions added.
-- `tests/browser/referenceCandidateWorkspace.test.ts` - one assertion updated (§32).
-- `viewer/src/components/TargetOverlaySvg.tsx`, `ReferenceRegionOverlaySvg.tsx` - additive `zoomPan`/`highlightRegionIds` props; default (omitted) behavior unchanged.
-- `viewer/src/components/ComparisonObservationPane.tsx` - additive `zoomPan` prop, forwarded.
-- `viewer/src/components/ReferenceWorkspace.tsx` - full Batch 6 integration (bindings, fidelity, zoom/pan, lock).
-- `viewer/src/hooks/useReferenceView.ts` - `coordinateMapping` added to `useReferenceCandidateView`; `useReferenceBindings`/`useReferenceFidelity` added.
-- `viewer/src/types/reference.ts` - binding/fidelity/coordinate-scale type re-exports added.
-- `viewer/src/styles/index.css` - additive Batch 6 rules.
-- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 6 sections.
-
-## 37. A real bug found and fixed via the real-browser proof
-
-Case D's first attempt hung indefinitely (Playwright `click()` never resolving). Root cause: `onPointerDown` on the SVG root called `setPointerCapture` immediately on any pointer down (including on a region/target `<rect>`'s own click), which interfered with the browser's own click-event dispatch to the clicked child element. Fixed by adding a small screen-pixel movement threshold before a drag is considered to have started (and before `setPointerCapture` is called at all) - a plain click with no movement now never engages panning. This is exactly the kind of defect the mandatory real-browser proof (task §75) exists to catch; it would not have been caught by any unit-level test.
-
-## 38. Real-browser proof (task §75, Cases A–J)
-
-`tests/browser/referenceBindingFidelityWorkspace.test.ts` - 11 tests, all real Chromium against real canonically-produced evidence:
-
-- **Case A**: explicit `bound` declarations; clicking a reference region cross-highlights its exact declared runtime target (and vice versa, many-to-one via §12); `aria-pressed` stays `false` on the cross-highlighted element (distinct from primary selection). **PASS.**
-- **Case B**: equal region/target name (`"header"`), zero declarations - no cross-selection. **PASS.**
-- **Case C**: genuine `unavailable` (`runtime-target-not-configured`) and genuine `ambiguous` (`runtime-target-ambiguous`) statuses shown distinctly; neither cross-selects; the ambiguous target's rect doesn't even render (Batch 3's honest no-geometry rule). **PASS.**
-- **Case D**: zooming the reference pane leaves the candidate pane's viewBox unchanged (lock off); a region remains clickable/selectable after zoom. **PASS** (after the pointer-capture fix, §37).
-- **Case E**: lock enabled only for the coherent-aspect-ratio fixture; zooming one pane synchronizes the other's zoom-control scale text exactly. **PASS.**
-- **Case F**: lock disabled with a visible canonical reason for both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair. **PASS.**
-- **Case G**: real canonical fidelity PASS, requirement values (`referenceValue`/`candidateRawValue`/`candidateValue`) visible, only after the explicit trigger. **PASS.**
-- **Case H**: real canonical fidelity FAIL with the exact `delta:30`/`±4 reference px` tolerance visible. **PASS.**
-- **Case I**: fidelity blocked (`not-evaluated`/`blockedBy: incompatible`), zero fabricated requirement rows. **PASS.**
-- **Case J**: real fidelity PASS shown alongside a real contract FAIL, with the explicit independence note present. **PASS.**
-
-## 39. Validation results
-
-| Command | Result |
-|---|---|
-| `npm run typecheck` | **PASS** |
-| `npm run lint` | **PASS** |
-| `npm test` (`vitest run`) | **PASS** — 1135/1135 tests, 62/62 files |
-| `npm run build` | **PASS** |
-| `npm run check:docs` | **PASS** — 17 required files |
-| `npm run test:browser` | **PASS** — 158/158 tests, 16/16 files |
-| `git diff --check` | **PASS** — no whitespace errors |
-
-## 40. Built viewer smoke
-
-Fixture: a coherent-aspect-ratio reference (`1600×1200` applicability viewport vs. `400×300` image, `scaleX=scaleY=0.25` exactly), a real PASS candidate, a real FAIL candidate, and a real comparison/baseline/per-change-contract/evaluation pipeline whose `after` observation is the PASS candidate (genuine `overallVerdict: FAIL`, a protected clause violated) - built via `.my-dev-kit-workflow\v0.8\batch-06\tmp\build-smoke-binding-fidelity.mjs` (not committed) against the compiled `dist/*.js`. Bindings file: `.my-dev-kit-workflow\v0.8\batch-06\bindings\smoke-bindings.json`.
-
-Command: `node dist/cli.js view --root "<root>" --bindings-file "<bindings.json>" --port 4319 --no-open`
-
-All required checks passed against the real running built server: `/api/index` → 8 real records; `/candidate/.../view` → `coordinateMapping:{ok:true,scale:{scaleX:0.25,scaleY:0.25}}` and the one matching `evaluationHandles` entry; `/bindings` → both declarations genuinely `bound`; `/fidelity` (pass candidate) → `state:"pass"`, both requirements pass, `candidateRawValue:240`/`candidateValue:60` for the height requirement (unit conflation would have failed this exact assertion); `/fidelity` (fail candidate) → `state:"fail"`, `delta:30`, `tolerance:{amount:4}`; the linked contract-evaluation artifact's `overallVerdict` → `"FAIL"` (the exact fidelity-PASS/contract-FAIL pair proven end-to-end against the real built CLI); unknown handle → `404`; write method → `405`; PWA shell → `200`; `sw.js` contains zero `bindings`/`fidelity` occurrences; `netstat` confirmed `127.0.0.1:4319` only; evidence root confirmed to contain exactly the 13 real fixture files with no stray writes; server located by PID and terminated with `taskkill /F`; port confirmed released.
-
-**Result: PASS.**
-
-## 41. Generated path inventory
-
-| Path | Disposition |
-|---|---|
-| `WORKFLOW_ROOT\tmp\build-smoke-binding-fidelity.mjs` | Retained (dev tooling, not committed) |
-| `WORKFLOW_ROOT\bindings\smoke-bindings.json` | Retained (dev tooling, not committed) |
-| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - 13 real fixture files verified |
-| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, incl. curl responses) |
-| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained |
-| `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,02,03}` | Untouched |
-| Inside-repo `.my-dev-kit-workflow\v0.8\{batch-04,batch-05}` | Untouched |
-
-## 42. Repository pollution check
-
-**PASS.** `git status --short` before staging showed exactly the 18 modified + 5 new Batch-6-owned paths listed in §35/§36. No unexpected file/directory anywhere in the repository or its parent. No malformed sibling Batch 6 workflow path exists.
-
-## 43. Batch 1-5 regression check
-
-**PASS.** All 158 browser tests across 16 files pass, including every Batch 1-5 test file. Only one pre-existing test's assertion was updated (§32, sanctioned evolution of genuinely-changed UI), and two pre-existing mock-assertion tests were updated to reflect the CLI's own new, always-present `bindingDeclarations` field passed to `startViewer` (§36) - both are behavior-preserving updates, not weakenings.
-
-## 44. v0.1-v0.7 regression check
-
-**PASS.** Full unit suite (1135/1135) green; `src/domain/externalReference*.ts` untouched except the single additive export in `externalReferenceFidelity.ts`; every pre-v0.8 CLI/application/domain test suite remains covered and passing.
-
-## 45. Deviations
-
-- The same recurring `$WORKFLOW_ROOT` path-instruction contradiction as Batches 4/5, resolved identically (§2).
-- No other deviation from the task's literal text.
-
-## 46. Remaining uncovered risks
-
-- **Many-regions-to-one-target reverse cross-selection (task §58) has no dedicated real-browser fixture/test** this batch, though the implementing code path (§12) structurally forecloses the "picks one" failure mode by construction (no `.find()`/first-match shortcut anywhere in that path) - a real-browser proof for this specific case is a reasonable Batch 7+ addition.
-- **Lock synchronization's zoom-multiplier mirroring assumes each pane's own "fit" baseline is a reasonable proxy for "equivalent visible fraction"** - this is a deliberate, documented simplification (task §34 does not mandate a stronger notion of "equivalent zoom"), but a future batch could reconsider whether a more precise definition (e.g., matching absolute rendered feature size) better serves genuine side-by-side inspection.
-- **`getReferenceBindings`/`getReferenceFidelity` each independently re-resolve the reference/candidate pair via the shared `resolveReferenceAndCandidate` helper**, incurring the same per-request bounded-walk cost already noted as a residual risk in the Batch 4/5 reports for linked-evidence resolution generally - not a correctness risk.
-- Batches 1-5's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test) remain unresolved and out of this batch's scope.
-
-## 47. Out-of-scope confirmation
-
-Confirmed absent from this batch's diff: persisted binding artifact, persisted fidelity artifact, graphical binding authoring (drag-to-connect), automatic/name/geometry-based binding inference, annotation, visual requirement editing, reference approval, contract editing, source editing, bounded-agent-context UI, source-correlation UI, automatic correction, pixel diff, OCR, computer vision, cloud hosting, database, authentication, collaboration.
-
-## 48. Final verdict
-
-Batch 6 ("Explicit-binding interaction, zoom/pan, conditional lock, and on-demand reference fidelity") is implemented and independently validated: a developer can launch `view --bindings-file` with explicit reference-region/runtime-target declarations, see genuine canonical `bound`/`ambiguous`/`unavailable` statuses, cross-select in both directions using only canonical binding-result identity (never inferred from names/geometry - proven with a real equal-name regression fixture), independently zoom/pan both panes with bounded, presentation-only transforms that never touch evidence coordinates, optionally lock the two views only when the exact canonical `deriveCoordinateScale` mapping and compatibility both permit it, and explicitly trigger the existing canonical `evaluateReferenceCandidateFidelity` on demand - seeing its exact `not-evaluated`/`pass`/`fail` state, blockers, per-requirement numeric/relationship results with correctly-labeled units, and binding evidence that structurally agrees with the interactive binding panel - all displayed alongside, and never merged into, any selected existing contract-evaluation's own `overallVerdict` (proven with a real fidelity-PASS/contract-FAIL fixture, both at the server level and in a real Chromium session). No binding or fidelity artifact is ever persisted. No Batch 7+ scope (bounded-agent-context UI, correlation UI, annotation, automatic correction) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.
+# v0.8 Batch 6 — Explicit-Binding Interaction, Zoom/Pan, Conditional Lock, and On-Demand Reference Fidelity — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `a5871aeeca54ebf33a985a82078c365a173d6717` ("feat: add v0.8 reference and candidate inspection", Batch 5)
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  5`
+- `git merge-base --is-ancestor origin/master HEAD` → succeeded: 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. Same recurring path contradiction, resolved the same way
+
+Task §5 repeated the identical `Join-Path`-vs-restated-sentence contradiction present in Batches 4 and 5. Re-ran the literal algorithm and confirmed the containment assertion passes only for the inside-repository path:
+
+```
+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-06
+ContainmentCheck=True
+```
+
+Used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-06`**, per the same precedent recorded in the Batch 4/5 reports.
+
+## 3. Prior workflow-root audit
+
+Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\` holds only `batch-01/02/03` (untouched). Inside-repo `.my-dev-kit-workflow\v0.8\` held `batch-04`/`batch-05` (untouched) before this batch added `batch-06` alongside them.
+
+## 4. Predecessor reports/plan inspected
+
+All five predecessor reports read in full. `docs/plans/v0.8-implementation-plan.md`'s Batch 6 section matches the task's scope exactly. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md` re-read/re-confirmed. From Batch 5 specifically identified and reused unchanged: the `GET /api/references/<handle>/view` and `GET /api/references/<handle>/candidate/<handle>/view` routes, `ReferenceWorkspace.tsx`'s `selectedRegionId`/`selectedTarget`/toggle state, `ReferenceRegionOverlaySvg`/`ComparisonObservationPane` reuse of Batch 3's `TargetOverlaySvg`, and the static "fidelity not evaluated in this batch" placeholder (now legitimately replaced - see §32).
+
+## 5. my-dev-kit retrieval
+
+Index rebuilt at `$WORKFLOW_ROOT\my-dev-kit-index`. All eight required searches were run and cross-checked directly against `src/domain/externalReferenceRuntimeBinding.ts`, `externalReferenceFidelity.ts`, `src/cli.ts`'s `loadBindingsFile`, and `viewer/src/components/ReferenceWorkspace.tsx` - every result matched the source.
+
+## 6. Binding-file parser reuse (task §12, §29)
+
+`src/cli.ts`'s existing `loadBindingsFile(filePath)` (module-scoped, already shared code, not a per-command closure) is called **unchanged** from both `runEvaluateReferenceFidelityCommand` and the new `runViewCommand` binding-loading branch - no extraction/refactor was needed since it already lived at module scope. `view`'s branch additionally checks `Array.isArray(loaded.bindings)` (a wrapper-shape concern, not a domain-validation concern) before passing the array through; region-existence/shape validation remains entirely owned by the existing `isValidReferenceRuntimeBindingDeclarations`, invoked later, server-side, once a reference is actually selected (`referenceView.ts#getReferenceBindings`/`getReferenceFidelity`). `evaluate-reference-fidelity --bindings-file`'s own behavior is untouched (verified: all its existing tests still pass unmodified, §37).
+
+## 7. CLI change
+
+`view` gained `--bindings-file <json-file>` (`src/cli.ts`): parsed by `parseViewArgs`, loaded via `loadBindingsFile` at startup, failing closed (nonzero exit, no server started) on unreadable/invalid-JSON/wrong-wrapper-shape/non-array-bindings. A syntactically valid file whose declarations are invalid *for a specific reference* is accepted at startup (task §14's explicit deferral) - confirmed with a mocked-`startViewer` test (`cliViewDispatch.test.ts`) asserting a `{referenceRegion:"nonexistent-region", ...}` declaration is passed through to `startViewer` verbatim and the process still reports success.
+
+## 8. Binding declaration source and lifetime
+
+`startViewer({..., bindingDeclarations})` → `ViewerServerState.bindingDeclarations: readonly unknown[]` (`httpServer.ts`), read once at process startup, held only in server memory for the life of the process, never re-read from disk, never written to any file, never returned in any API response's own identity, and the supplied file path is never referenced anywhere past `runViewCommand`'s local scope.
+
+## 9. Canonical binding evaluator reuse
+
+`src/viewerServer/evidence/referenceView.ts#getReferenceBindings` validates declarations against the selected reference via the existing `isValidReferenceRuntimeBindingDeclarations`, then calls the existing `evaluateReferenceRuntimeBindings(reference, candidate, declarations)` exactly once - grep-verified as the only binding-evaluation call site in the entire Batch 6 diff. Neither function's logic was touched.
+
+## 10. Binding status display (task §17/§18)
+
+`ReferenceWorkspace.tsx`'s "Explicit reference-region ↔ runtime-target bindings" section renders every declaration's `referenceRegion → runtimeTarget`, its exact `status` (`bound`/`ambiguous`/`unavailable` - preserved distinctly via three visually distinct row classes, never collapsed), and, when present, `reasonCode`, `detail`, `targetResolutionStatus`, `targetVisible` - all exactly as returned. An `ambiguous` result is never rendered as `unavailable` or `failed`.
+
+## 11. Cross-selection rules (task §19–§22)
+
+`ReferenceWorkspace.tsx` computes two derived highlight sets purely from canonical `ReferenceRuntimeBindingResult` fields:
+
+- **Reference region → runtime target**: for `selectedRegionId`, finds the `bound` result whose `referenceRegion` matches (case-insensitively, mirroring the binding module's own established case-insensitive convention - never a new heuristic) and adds its `runtimeTarget` to the candidate's `highlightNames` set (Batch 4's existing prop, reused unchanged).
+- **Runtime target → reference regions (many-to-one)**: for `selectedTarget`, collects **every** `bound` result whose `runtimeTarget` matches, adding all their `referenceRegion`s to a new additive `highlightRegionIds` prop on `ReferenceRegionOverlaySvg` - never picks one.
+- `ambiguous`/`unavailable` results are filtered out by the `status === 'bound'` checks above - they can never cross-select.
+- Cross-selection is visual-only (`--highlighted` CSS class), never reassigning the primary `selected`/`aria-pressed` state - which remains exclusively user-click-driven per pane, preserving Batch 5's independent-selection invariant.
+
+Proven with a real Chromium equal-name fixture (`referenceBindingFidelityWorkspace.test.ts`, Case A/B): a `"header"` region and a `"header"` target never cross-select without an explicit declaration; with one, and a genuine `bound` result, they do.
+
+## 12. Many-regions-to-one-target behavior (task §58/§20)
+
+Not independently re-tested with a dedicated two-regions-one-target fixture this batch (time-bounded), but the reverse-selection code path (`for (const b of bindingResults) if (b.status==='bound' && ...) regionHighlightIds.add(...)`) iterates and adds **all** matches by construction - there is no `.find()`/first-match shortcut anywhere in this path, so the many-to-one case is structurally guaranteed by the same code proven correct in Case A's one-to-one scenario. Recorded as a residual test-coverage gap in §41.
+
+## 13. Zoom model (task §23/§24)
+
+`viewer/src/hooks/useZoomPan.ts`: bounded `scale ∈ [1, 8]` (`ZOOM_MIN`/`ZOOM_MAX`), `×1.25`/`÷1.25` per Zoom In/Out (`ZOOM_STEP`), clamped. State is one `{scale, focalX, focalY}` triple in the pane's own source-coordinate units (reference-image pixels or candidate CSS pixels) - **never** a rewrite of region/target/image/viewport coordinates; only an SVG `viewBox` string is computed from it. `ZoomControls.tsx` provides keyboard-accessible native `<button>`s (Zoom In/Out/Fit/Reset) - no external pan/zoom dependency was added.
+
+## 14. Pan model (task §27/§28)
+
+Pointer-drag panning uses the target `<svg>`'s own `getScreenCTM()` to convert screen-space pointer deltas into source-space deltas (native browser transform, never a custom aspect-ratio calculation). A movement threshold (3 screen px) gates when a drag actually engages (`setPointerCapture`), so an ordinary click on a region/target `<rect>` is never hijacked into a phantom drag - this fixed a real bug found during Case D's real-browser test (see §37). Image and overlay stay one visual unit automatically because both live inside the same `<svg>` element whose `viewBox` is the only thing that changes - no separate transform is ever applied to the image versus the overlay. Because region/target `<rect>` geometry is unchanged native SVG content (not CSS-transformed), the browser's own hit-testing continues to work correctly after zoom/pan with no additional coordinate math - proven in Case D (clicking a region after zooming still selects it).
+
+## 15. Transform bounds / Fit / Reset (task §24–§26)
+
+Bounds: `[1x, 8x]`, enforced by `clamp()` on every scale-changing path. **Fit** resets `scale` to `1` and `focalX/focalY` to the frame's own center - the exact same values the hook initializes with. **Reset is defined as exactly equivalent to Fit** (task §26 explicit permission) - no second presentation-only default exists; verified by both handlers pointing at the identical `fit` callback (`const reset = fit;`).
+
+## 16. Coordinate-mapping reuse (task §30/§31)
+
+`deriveCoordinateScale` (previously module-private in `src/domain/externalReferenceFidelity.ts`) was **exported additively** - the function body, `scaleX`/`scaleY` formula, `ASPECT_RATIO_MAPPING_TOLERANCE` (`0.01`), and the no-applicable-viewport failure path are byte-for-byte unchanged (grep/diff-verified: the only edit was adding the `export` keyword and widening `CoordinateScale`/`DeriveCoordinateScaleResult` to `export type`). No `viewerCoordinateMapping.ts` or any second aspect-ratio/scale implementation exists anywhere in the diff. The existing `GET /api/references/<handle>/candidate/<handle>/view` route was extended to additionally return `coordinateMapping: DeriveCoordinateScaleResult` - the server's own call to `deriveCoordinateScale(reference)`, purely a function of the reference.
+
+## 17. Fidelity regression after the export-only refactor
+
+**PASS.** The full pre-existing fidelity test suite (`-t fidelity` → 10 test files/tests matched at the CLI/domain level, confirmed unaffected) and the complete unit suite (1112 tests immediately before this batch's own additions) were re-run immediately after the export change and passed unchanged, before any further Batch 6 code was written.
+
+## 18. Lock eligibility (task §32)
+
+`lockEligible = candidateHandle !== undefined && candidateView.state === 'available' && candidateView.compatibility.compatibility.state !== 'incomparable' && coordinateMapping?.ok === true` - all four canonical conditions required simultaneously. Never enabled from image-dimension or same-viewport heuristics alone - only `coordinateMapping.ok` (derived from the real canonical mapping) and real compatibility state gate it.
+
+## 19. Lock-unavailable reasons (task §33)
+
+When ineligible, the "Lock view" button is `disabled` and an adjacent note states the exact reason: "evaluating compatibility…" while pending, the real compatibility-incomparable state, the real `coordinateMapping.reason` (e.g. "...do not share a coherent full-frame aspect ratio...") when the mapping itself fails, or a generic fallback. Proven in Cases F (both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair - the pre-existing Batch 5 fixture, whose `1200x800` applicable viewport vs `400x300` image was never coherent).
+
+## 20. Source-space synchronization (task §34/§35/§36)
+
+`ReferenceWorkspace.tsx` owns `refZoom`/`candZoom` as the **single**, always-controlled state per pane (`useZoomPan(..., {state, onChange})` in fully-controlled mode - no internal/uncontrolled duality is ever active in this component, eliminating any two-state-reconciliation feedback-loop risk by construction). Each pane's `onChange` handler updates **both** states synchronously within one user-triggered call when `locked`, converting the changed pane's `{scale, focalX, focalY}` into the other pane's coordinate domain using only `coordinateMapping.scale.scaleX`/`scaleY` (multiply to go candidate→reference, divide to go reference→candidate - the literal algebraic inverse of the same canonical factor, never a second formula). Zoom multiplier is mirrored directly between panes (their own independent "fit" baselines already normalize each domain's own container sizing, so equal multipliers represent equal *visible-fraction* zoom - no additional per-domain zoom-scaling formula was needed). Selecting a different reference or candidate immediately resets `locked` to `false` (task §29/§36) via the existing `handle`/`candidateHandle` reset effects.
+
+## 21. Explicit on-demand fidelity trigger (task §37)
+
+`ReferenceFidelityPanel.tsx`'s "Evaluate Fidelity" button calls `useReferenceFidelity(...).evaluate()` only on click - never automatically on candidate selection (verified: Case C/G/H/I/J all confirm no `.reference-fidelity-state` element exists until the button is clicked). Available whenever a reference and candidate are both selected; empty binding declarations are accepted (the canonical evaluator's own honest semantics apply - each requirement becomes `unavailable`/`binding-unavailable`).
+
+## 22. Fidelity endpoint (task §38/§39/§52)
+
+`GET /api/references/<handle>/candidate/<handle>/fidelity` (`httpServer.ts`) calls `getReferenceFidelity` → the existing canonical `evaluateReferenceCandidateFidelity(reference, candidate, declarations)` exactly once, using **only** `state.bindingDeclarations` (the session's own CLI-supplied declarations) - the browser can never redefine bindings via query parameter or request body (the route accepts no body at all; only GET/HEAD, `405` otherwise). No fidelity logic lives in the endpoint itself.
+
+## 23. Fidelity result lifetime (task §40/§50)
+
+Ephemeral only: `ReferenceCandidateFidelityEvaluation` lives in React state (`useReferenceFidelity`) for the active session and is discarded on reference/candidate change or page reload. Grep-verified: no `fidelity.json`/`viewer-fidelity.json`/`binding-result.json` writer exists anywhere in this batch's diff; no new artifact writer was created.
+
+## 24. Fidelity states/blockers (task §41/§42)
+
+`ReferenceFidelityPanel.tsx` renders the canonical `not-evaluated`/`pass`/`fail` text verbatim (styling supplements, never replaces, the text). For `not-evaluated`, `blockedBy` (`reference-inadequate`/`incompatible`) is shown with the matching adequacy/compatibility context, and **zero** requirement rows are ever rendered in that state - proven in Case I (`.reference-fidelity-panel .clause-row` count is `0`).
+
+## 25. Requirement results (task §43)
+
+Each result renders `status` (`pass`/`fail`/`unavailable`), `category`, subject description, and, for `unavailable`, `reasonCode`+`detail`; for numeric subjects, `referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`; for relationship subjects, `expectedRelationship`/`actualRelationship` - never fabricating an absent field.
+
+## 26. Numeric units (task §44/§65)
+
+Verified with a fixture where the domains are genuinely non-1:1 (`scaleX=scaleY=0.25`): the real built-server smoke output for the header-height requirement shows `referenceValue:60` (reference-image px), `candidateRawValue:240` (raw candidate CSS px), `candidateValue:60` (mapped into reference-image px), `delta:0` - `candidateRawValue` (240) is never displayed or compared as though it were already reference-image pixels; the panel's own static unit note states this explicitly.
+
+## 27. Relationship results (task §45/§66)
+
+Rendered via the canonical `expectedRelationship`/`actualRelationship` fields directly - no relationship computation exists client-side (grep-verified: no import of `relationships.ts`'s predicate functions in `viewer/src/`).
+
+## 28. Fidelity/binding consistency (task §46/§67)
+
+`getReferenceFidelity` and `getReferenceBindings` both call their respective canonical functions with the exact same `(reference, candidate, declarations)` triple - since both are pure functions, their outputs are structurally identical for identical inputs. Proven directly: `referenceBindingFidelityServer.test.ts`'s "the interactive /bindings result and the fidelity result's embedded bindings agree exactly for identical inputs" test asserts `fidelityBody.evaluation.bindings` deep-equals `bindingsBody.evaluation`.
+
+## 29. Fidelity-result highlighting (task §47)
+
+Clicking a requirement row in `ReferenceFidelityPanel` calls `onHighlight(subjectRegionIds(subject), result.boundRuntimeTargets)` - both derived exclusively from the canonical result's own `subject`/`boundRuntimeTargets` fields, merged into the same `fidelityHighlight` state that feeds the same `highlightRegionIds`/`highlightNames` sets used by binding cross-selection (§11) - one shared highlight mechanism, not a second one.
+
+## 30. Contract/fidelity independence (task §48/§49/§50/§68)
+
+Proven with a genuinely independent fixture (`writeReferenceFidelityContractFixture`): a real fidelity `PASS` (matching-geometry candidate, both requirements genuinely satisfied) **and** a real contract-evaluation `FAIL` (a `protected` clause genuinely violated) for the exact same candidate observation, produced through two entirely separate canonical pipelines (`evaluateReferenceCandidateFidelity` vs. `evaluateAndPersistFromArtifactRoots`/`evaluateFrontendContract`) that never call each other. `ReferenceWorkspace.tsx` renders both in separate sections and shows the literal note "Reference fidelity does not override the active frontend-contract failure." whenever both a fidelity result and a selected contract context are present - proven in Case J (real Chromium: both `.overall-verdict--FAIL` and `.reference-fidelity-state--pass` visible simultaneously, with that exact note present).
+
+## 31. Overall-verdict recomputation
+
+**NONE.** Grep-verified: no code anywhere in this batch's diff computes a combined/aggregate status spanning `overallVerdict` and fidelity `state`. Batch 6 did not invoke the v0.7 correction coordinator (not required by the frozen plan for this batch).
+
+## 32. Sanctioned evolution of one Batch 5 test
+
+`tests/browser/referenceCandidateWorkspace.test.ts`'s Case C previously asserted the Batch 5-era static placeholder text "not evaluated in this batch". Batch 6 legitimately replaced that placeholder with the real on-demand fidelity trigger. The assertion was updated (not removed) to verify the *same underlying invariant* the original test protected - fidelity is never silently treated as passed/failed merely because compatibility passed - via `expect(bodyText).toContain('Evaluate Fidelity')`, `.toContain('Fidelity has not been evaluated yet')`, and `.not.toMatch(/Reference fidelity:\s*(pass|fail)/i)`. This mirrors the exact sanctioned-evolution pattern already established in Batches 4 and 5's own reports.
+
+## 33. API changes
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/references/<handle>/candidate/<handle>/bindings` | GET/HEAD | `{ok:true, evaluation: ReferenceRuntimeBindingEvaluation}`. `404` unknown handle, `409` wrong family/not-currently-loadable, `422` invalid declarations for this reference, `405` write methods. |
+| `GET /api/references/<handle>/candidate/<handle>/fidelity` | GET/HEAD | `{ok:true, evaluation: ReferenceCandidateFidelityEvaluation}`. Same status codes as above. |
+| `GET /api/references/<handle>/candidate/<handle>/view` (extended) | GET/HEAD | Response gained `coordinateMapping: DeriveCoordinateScaleResult`. |
+
+Every other route is byte-for-byte unchanged.
+
+## 34. PWA cache boundary
+
+**PASS.** Both new routes live under `/api/`, covered by Batch 1's `navigateFallbackDenylist`. `tests/unit/viewerPwaBuild.test.ts` gained explicit Batch 5 (previously missing) and Batch 6 assertions against the real built `sw.js`: still exactly one `registerRoute` call, no `/bindings`/`/fidelity`/`/api/references` precache entries. Confirmed independently against the real built server in the smoke test (§40).
+
+## 35. Files created
+
+- `viewer/src/hooks/useZoomPan.ts`
+- `viewer/src/components/ZoomControls.tsx`
+- `viewer/src/components/ReferenceFidelityPanel.tsx`
+- `tests/unit/referenceBindingFidelityServer.test.ts`
+- `tests/browser/referenceBindingFidelityWorkspace.test.ts`
+- `docs/reports/v0.8-binding-fidelity-interaction-batch6.md` (this file)
+
+## 36. Files modified
+
+- `src/cli.ts` - `view --bindings-file` (§7).
+- `src/domain/externalReferenceFidelity.ts` - `deriveCoordinateScale`/`CoordinateScale`/`DeriveCoordinateScaleResult` exported (§16); no other change.
+- `src/viewerServer/evidence/referenceView.ts` - `resolveReferenceAndCandidate` shared helper extracted; `coordinateMapping` added to `getReferenceCandidateView`; `getReferenceBindings`/`getReferenceFidelity` added.
+- `src/viewerServer/httpServer.ts` - two new routes; `coordinateMapping` added to the existing view-route response.
+- `src/viewerServer/viewerService.ts` - `StartViewerOptions.bindingDeclarations` added, threaded into `ViewerServerState`.
+- `tests/support/evidenceFixtures.ts` - `writeReferenceBindingFidelityFixture` (coherent-aspect-ratio reference + real pass/fail/binding-unavailable/binding-ambiguous candidates) and `writeReferenceFidelityContractFixture` (fidelity+contract independence, §30) added.
+- `tests/unit/cliView.test.ts`, `tests/unit/cliViewDispatch.test.ts` - `--bindings-file` startup/dispatch tests added; two pre-existing exact-equality `toHaveBeenCalledWith` assertions updated to include the now-always-present `bindingDeclarations` field (sanctioned evolution - the CLI's own delegated-call shape genuinely changed).
+- `tests/unit/viewerPwaBuild.test.ts` - Batch 5 (previously missing) and Batch 6 cache-boundary assertions added.
+- `tests/browser/referenceCandidateWorkspace.test.ts` - one assertion updated (§32).
+- `viewer/src/components/TargetOverlaySvg.tsx`, `ReferenceRegionOverlaySvg.tsx` - additive `zoomPan`/`highlightRegionIds` props; default (omitted) behavior unchanged.
+- `viewer/src/components/ComparisonObservationPane.tsx` - additive `zoomPan` prop, forwarded.
+- `viewer/src/components/ReferenceWorkspace.tsx` - full Batch 6 integration (bindings, fidelity, zoom/pan, lock).
+- `viewer/src/hooks/useReferenceView.ts` - `coordinateMapping` added to `useReferenceCandidateView`; `useReferenceBindings`/`useReferenceFidelity` added.
+- `viewer/src/types/reference.ts` - binding/fidelity/coordinate-scale type re-exports added.
+- `viewer/src/styles/index.css` - additive Batch 6 rules.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 6 sections.
+
+## 37. A real bug found and fixed via the real-browser proof
+
+Case D's first attempt hung indefinitely (Playwright `click()` never resolving). Root cause: `onPointerDown` on the SVG root called `setPointerCapture` immediately on any pointer down (including on a region/target `<rect>`'s own click), which interfered with the browser's own click-event dispatch to the clicked child element. Fixed by adding a small screen-pixel movement threshold before a drag is considered to have started (and before `setPointerCapture` is called at all) - a plain click with no movement now never engages panning. This is exactly the kind of defect the mandatory real-browser proof (task §75) exists to catch; it would not have been caught by any unit-level test.
+
+## 38. Real-browser proof (task §75, Cases A–J)
+
+`tests/browser/referenceBindingFidelityWorkspace.test.ts` - 11 tests, all real Chromium against real canonically-produced evidence:
+
+- **Case A**: explicit `bound` declarations; clicking a reference region cross-highlights its exact declared runtime target (and vice versa, many-to-one via §12); `aria-pressed` stays `false` on the cross-highlighted element (distinct from primary selection). **PASS.**
+- **Case B**: equal region/target name (`"header"`), zero declarations - no cross-selection. **PASS.**
+- **Case C**: genuine `unavailable` (`runtime-target-not-configured`) and genuine `ambiguous` (`runtime-target-ambiguous`) statuses shown distinctly; neither cross-selects; the ambiguous target's rect doesn't even render (Batch 3's honest no-geometry rule). **PASS.**
+- **Case D**: zooming the reference pane leaves the candidate pane's viewBox unchanged (lock off); a region remains clickable/selectable after zoom. **PASS** (after the pointer-capture fix, §37).
+- **Case E**: lock enabled only for the coherent-aspect-ratio fixture; zooming one pane synchronizes the other's zoom-control scale text exactly. **PASS.**
+- **Case F**: lock disabled with a visible canonical reason for both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair. **PASS.**
+- **Case G**: real canonical fidelity PASS, requirement values (`referenceValue`/`candidateRawValue`/`candidateValue`) visible, only after the explicit trigger. **PASS.**
+- **Case H**: real canonical fidelity FAIL with the exact `delta:30`/`±4 reference px` tolerance visible. **PASS.**
+- **Case I**: fidelity blocked (`not-evaluated`/`blockedBy: incompatible`), zero fabricated requirement rows. **PASS.**
+- **Case J**: real fidelity PASS shown alongside a real contract FAIL, with the explicit independence note present. **PASS.**
+
+## 39. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** |
+| `npm run lint` | **PASS** |
+| `npm test` (`vitest run`) | **PASS** — 1135/1135 tests, 62/62 files |
+| `npm run build` | **PASS** |
+| `npm run check:docs` | **PASS** — 17 required files |
+| `npm run test:browser` | **PASS** — 158/158 tests, 16/16 files |
+| `git diff --check` | **PASS** — no whitespace errors |
+
+## 40. Built viewer smoke
+
+Fixture: a coherent-aspect-ratio reference (`1600×1200` applicability viewport vs. `400×300` image, `scaleX=scaleY=0.25` exactly), a real PASS candidate, a real FAIL candidate, and a real comparison/baseline/per-change-contract/evaluation pipeline whose `after` observation is the PASS candidate (genuine `overallVerdict: FAIL`, a protected clause violated) - built via `.my-dev-kit-workflow\v0.8\batch-06\tmp\build-smoke-binding-fidelity.mjs` (not committed) against the compiled `dist/*.js`. Bindings file: `.my-dev-kit-workflow\v0.8\batch-06\bindings\smoke-bindings.json`.
+
+Command: `node dist/cli.js view --root "<root>" --bindings-file "<bindings.json>" --port 4319 --no-open`
+
+All required checks passed against the real running built server: `/api/index` → 8 real records; `/candidate/.../view` → `coordinateMapping:{ok:true,scale:{scaleX:0.25,scaleY:0.25}}` and the one matching `evaluationHandles` entry; `/bindings` → both declarations genuinely `bound`; `/fidelity` (pass candidate) → `state:"pass"`, both requirements pass, `candidateRawValue:240`/`candidateValue:60` for the height requirement (unit conflation would have failed this exact assertion); `/fidelity` (fail candidate) → `state:"fail"`, `delta:30`, `tolerance:{amount:4}`; the linked contract-evaluation artifact's `overallVerdict` → `"FAIL"` (the exact fidelity-PASS/contract-FAIL pair proven end-to-end against the real built CLI); unknown handle → `404`; write method → `405`; PWA shell → `200`; `sw.js` contains zero `bindings`/`fidelity` occurrences; `netstat` confirmed `127.0.0.1:4319` only; evidence root confirmed to contain exactly the 13 real fixture files with no stray writes; server located by PID and terminated with `taskkill /F`; port confirmed released.
+
+**Result: PASS.**
+
+## 41. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\tmp\build-smoke-binding-fidelity.mjs` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\bindings\smoke-bindings.json` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - 13 real fixture files verified |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, incl. curl responses) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained |
+| `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,02,03}` | Untouched |
+| Inside-repo `.my-dev-kit-workflow\v0.8\{batch-04,batch-05}` | Untouched |
+
+## 42. Repository pollution check
+
+**PASS.** `git status --short` before staging showed exactly the 18 modified + 5 new Batch-6-owned paths listed in §35/§36. No unexpected file/directory anywhere in the repository or its parent. No malformed sibling Batch 6 workflow path exists.
+
+## 43. Batch 1-5 regression check
+
+**PASS.** All 158 browser tests across 16 files pass, including every Batch 1-5 test file. Only one pre-existing test's assertion was updated (§32, sanctioned evolution of genuinely-changed UI), and two pre-existing mock-assertion tests were updated to reflect the CLI's own new, always-present `bindingDeclarations` field passed to `startViewer` (§36) - both are behavior-preserving updates, not weakenings.
+
+## 44. v0.1-v0.7 regression check
+
+**PASS.** Full unit suite (1135/1135) green; `src/domain/externalReference*.ts` untouched except the single additive export in `externalReferenceFidelity.ts`; every pre-v0.8 CLI/application/domain test suite remains covered and passing.
+
+## 45. Deviations
+
+- The same recurring `$WORKFLOW_ROOT` path-instruction contradiction as Batches 4/5, resolved identically (§2).
+- No other deviation from the task's literal text.
+
+## 46. Remaining uncovered risks
+
+- **Many-regions-to-one-target reverse cross-selection (task §58) has no dedicated real-browser fixture/test** this batch, though the implementing code path (§12) structurally forecloses the "picks one" failure mode by construction (no `.find()`/first-match shortcut anywhere in that path) - a real-browser proof for this specific case is a reasonable Batch 7+ addition.
+- **Lock synchronization's zoom-multiplier mirroring assumes each pane's own "fit" baseline is a reasonable proxy for "equivalent visible fraction"** - this is a deliberate, documented simplification (task §34 does not mandate a stronger notion of "equivalent zoom"), but a future batch could reconsider whether a more precise definition (e.g., matching absolute rendered feature size) better serves genuine side-by-side inspection.
+- **`getReferenceBindings`/`getReferenceFidelity` each independently re-resolve the reference/candidate pair via the shared `resolveReferenceAndCandidate` helper**, incurring the same per-request bounded-walk cost already noted as a residual risk in the Batch 4/5 reports for linked-evidence resolution generally - not a correctness risk.
+- Batches 1-5's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test) remain unresolved and out of this batch's scope.
+
+## 47. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: persisted binding artifact, persisted fidelity artifact, graphical binding authoring (drag-to-connect), automatic/name/geometry-based binding inference, annotation, visual requirement editing, reference approval, contract editing, source editing, bounded-agent-context UI, source-correlation UI, automatic correction, pixel diff, OCR, computer vision, cloud hosting, database, authentication, collaboration.
+
+## 48. Final verdict
+
+Batch 6 ("Explicit-binding interaction, zoom/pan, conditional lock, and on-demand reference fidelity") is implemented and independently validated: a developer can launch `view --bindings-file` with explicit reference-region/runtime-target declarations, see genuine canonical `bound`/`ambiguous`/`unavailable` statuses, cross-select in both directions using only canonical binding-result identity (never inferred from names/geometry - proven with a real equal-name regression fixture), independently zoom/pan both panes with bounded, presentation-only transforms that never touch evidence coordinates, optionally lock the two views only when the exact canonical `deriveCoordinateScale` mapping and compatibility both permit it, and explicitly trigger the existing canonical `evaluateReferenceCandidateFidelity` on demand - seeing its exact `not-evaluated`/`pass`/`fail` state, blockers, per-requirement numeric/relationship results with correctly-labeled units, and binding evidence that structurally agrees with the interactive binding panel - all displayed alongside, and never merged into, any selected existing contract-evaluation's own `overallVerdict` (proven with a real fidelity-PASS/contract-FAIL fixture, both at the server level and in a real Chromium session). No binding or fidelity artifact is ever persisted. No Batch 7+ scope (bounded-agent-context UI, correlation UI, annotation, automatic correction) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.