@dailephd/my-frontend-observer 0.8.1

package/docs/plans/v0.8-implementation-plan.md

@@ -0,0 +1,655 @@
+# v0.8 Implementation Plan — Interactive Local Observation Viewer
+
+## 1. Status and authority
+
+This document is the frozen concrete implementation plan for
+`my-frontend-observer` v0.8.
+
+It was created during v0.8 version-start planning after reviewing the current
+v0.7 repository state and the v0.8 roadmap/milestone requirements. It governs
+implementation scope, architecture decisions, batch order, batch gates, and
+validation expectations unless the user explicitly revises it.
+
+This document is planning authority only. It does not prove that any v0.8 batch
+has been implemented. Actual implementation/release state remains owned by
+repository evidence and `docs/CURRENT_STATE.md`.
+
+The package remains `0.7.0` until the separate release-preparation workflow
+explicitly bumps it after implementation and pre-release readiness pass.
+
+## 2. Version objective
+
+Build an interactive local graphical viewer over the existing v0.1-v0.7
+Observer evidence system so a developer can understand runtime observations,
+before/after comparisons, frontend contracts, external references,
+reference/candidate fidelity, runtime/reference bindings, bounded agent context,
+and runtime/static correlation without manually opening raw artifacts.
+
+The viewer is a presentation and inspection layer over existing Observer-owned
+evidence. It must not become a second implementation of any existing evidence
+engine.
+
+## 3. Frozen planning decisions
+
+The following version-start decisions are frozen for v0.8.
+
+1. UI technology: React + TypeScript + Vite.
+2. Application boundary: normal browser + Node-backed local server + installable
+   Progressive Web App (PWA), using the same React application in browser and
+   installed modes.
+3. Reader architecture: existing canonical readers -> ephemeral viewer adapter
+   -> viewer protocol/UI projection. The projection is not persisted evidence.
+4. Reference/candidate display: side-by-side by default, with independently
+   toggleable structured overlays.
+5. Geometry rendering: SVG using each source artifact/image's original
+   coordinate domain.
+6. Interaction: explicit-binding cross-selection + independent zoom/pan +
+   conditional synchronized/locked viewing only when existing compatibility
+   evidence permits it.
+7. Loading: metadata/index first + on-demand artifact and image loading.
+
+No paid, premium-only, proprietary hosted, or cloud dependency is required for
+this plan. The viewer remains local-first.
+
+## 4. Derived architecture decisions
+
+The frozen decisions above imply the following implementation boundaries.
+
+### 4.1 Public viewer entry point
+
+Add one thin public CLI entry point for launching the viewer:
+
+```text
+my-frontend-observer view --root <evidence-root>
+```
+
+The command starts the local viewer server and exposes the same React viewer to
+a normal browser or an installed PWA. Exact optional operational flags may be
+added only when needed for deterministic testing or local operation, but they
+must not create a second evidence workflow.
+
+The CLI remains a parsing/dispatch/presentation boundary. It must not contain
+artifact semantics, comparison logic, contract logic, fidelity logic, binding
+logic, or browser observation logic.
+
+### 4.2 Stable local PWA origin
+
+The default viewer server must bind only to loopback and use one stable default
+origin so an installed PWA has a stable identity. The implementation batch must
+select and document one fixed default loopback port after checking current repo
+and test-fixture conflicts.
+
+Do not silently fall back to a random port when the default port is occupied.
+Return an actionable error. An explicit alternate port may be supported for
+advanced/testing use, with the consequence that it is a different web origin.
+
+### 4.3 Read-only server boundary
+
+The v0.8 viewer server is read-only with respect to target applications and
+persisted Observer evidence.
+
+Permitted responsibilities include:
+
+```text
+serve viewer application assets
+index supported evidence under the explicitly allowed evidence root
+read and validate existing artifacts through canonical readers
+produce ephemeral viewer projections
+serve referenced screenshots/reference images safely
+run existing pure/in-memory evaluation functions when the required explicit
+inputs are supplied and the result is intentionally non-persisted in v0.7
+```
+
+The viewer server must not add approval, supersession, source editing, capture,
+contract mutation, annotation authoring, automatic binding, or workflow-control
+endpoints.
+
+Opening or inspecting evidence never changes it.
+
+### 4.4 Filesystem boundary
+
+`--root` is an explicit local filesystem trust boundary.
+
+The server may expose only recognized files and media reachable through
+validated Observer evidence under that allowed root. Path traversal, arbitrary
+absolute-path reads, and unrelated filesystem browsing must fail closed.
+
+### 4.5 Existing readers and ephemeral viewer adapter
+
+Existing artifact readers and validators remain the only artifact semantic
+readers. The viewer may add narrow missing reader wrappers only when a current
+artifact family lacks one, and such a reader must call that artifact family's
+existing structural validator rather than introduce a second validator.
+
+The viewer adapter converts already-validated domain values into UI-friendly
+in-memory projections. These projections are not new evidence contracts and are
+not persisted.
+
+Do not create `viewer.json`, a viewer manifest artifact, a viewer cache artifact,
+or another durable evidence family in v0.8.
+
+### 4.6 PWA caching boundary
+
+The PWA/service worker may cache the application shell and immutable built
+assets required for the viewer UI.
+
+It must not make screenshots, external reference images, observation manifests,
+comparison artifacts, contract/evaluation evidence, bounded-agent-context data,
+or source-correlation evidence available as stale cached truth after the local
+server/evidence source changes.
+
+Evidence remains server-backed and current to the selected local root.
+
+If the installed PWA is opened while the local Observer viewer server is not
+running, show an actionable local-server-not-running state rather than a blank
+or misleading stale evidence screen.
+
+### 4.7 SVG coordinate rule
+
+Runtime screenshot overlays use the runtime screenshot/artifact coordinate
+space. External-reference overlays use the external reference image coordinate
+space. The viewer uses SVG `viewBox`/display transforms to scale for presentation
+without rewriting the underlying evidence coordinates.
+
+Reference-image pixels and runtime/CSS coordinates remain distinct domains.
+Existing v0.7 applicability/fidelity mapping remains the only authority for
+cross-domain measurement interpretation.
+
+### 4.8 Interaction rule
+
+Cross-highlighting between a reference region and runtime target is driven only
+by existing explicit binding results/declarations. Name similarity, spatial
+proximity, rectangle overlap, or UI heuristics must never create a binding.
+
+Independent zoom/pan is always available. Locked/synchronized viewing is enabled
+only when existing applicability/compatibility evidence makes coordinated
+viewing meaningful. If it is not safe, the UI must show why lock is unavailable.
+
+### 4.9 Loading rule
+
+Initial viewer navigation loads bounded metadata only. Full artifact payloads,
+screenshots, and reference images are fetched on demand for the selected view.
+
+Do not add virtualization, workers, databases, or complex caching unless
+measured v0.8 performance evidence demonstrates a need. The architecture should
+leave room for later optimization without making it part of this version by
+default.
+
+## 5. Planned viewer structure
+
+The expected responsibility flow is:
+
+```text
+my-frontend-observer view --root <evidence-root>
+                     |
+                     v
+           Node local viewer server
+                loopback only
+                     |
+          +----------+----------+
+          |                     |
+          v                     v
+ canonical readers        safe media serving
+          |
+          v
+ ephemeral viewer adapters
+          |
+          v
+ viewer protocol/API
+          |
+          v
+ React + TypeScript + Vite PWA
+          |
+   +------+------+----------------+----------------+
+   |             |                |                |
+   v             v                v                v
+Observation   Comparison       Reference        Context/
+inspection    + contracts      /candidate       provenance
+                              inspection
+          |
+          v
+SVG overlays + explicit-binding interaction
+```
+
+The PWA contains presentation logic. It does not contain replacement Observer
+engines.
+
+## 6. Implementation batches
+
+v0.8 is implemented in eight ordered batches. Each batch is part of the same
+version. Later batches assume earlier batches are implemented and merged. A
+coding-agent prompt must not redesign the version or pull later-version features
+forward.
+
+### Batch 1 — Viewer runtime and PWA foundation
+
+#### Goal
+
+Establish the build/runtime shell for a local browser viewer and installable PWA
+without yet implementing evidence interpretation.
+
+#### In scope
+
+- Add React + TypeScript + Vite viewer build configuration.
+- Add PWA manifest/service-worker infrastructure and installability support.
+- Add a Node local viewer server bound to loopback only.
+- Select and freeze one stable default loopback port after checking current
+  repo/test fixture conflicts.
+- Add the thin `view --root <evidence-root>` CLI dispatch path.
+- Serve built viewer assets from the npm package.
+- Establish viewer protocol/version identity if needed for safe client/server
+  compatibility.
+- Establish a basic three-area viewer shell suitable for evidence navigation,
+  visual inspection, and details/diagnostics.
+- Integrate viewer build output into package build/packing without splitting the
+  project into another npm package.
+
+#### Out of scope
+
+- artifact interpretation beyond minimal server health/root identity;
+- screenshot geometry overlays;
+- comparison/contract/reference/fidelity inspection;
+- source editing;
+- approval/supersession;
+- annotation;
+- automatic binding;
+- cloud hosting.
+
+#### Gate
+
+A built/packed candidate can start `my-frontend-observer view --root <fixture>`
+and serve the same working React shell to a normal browser and PWA-capable
+browser from the fixed loopback origin. Existing CLI/library behavior remains
+unchanged.
+
+### Batch 2 — Evidence indexing, canonical readers, and lazy data boundary
+
+#### Goal
+
+Create the safe read-only data boundary from local Observer evidence into the
+viewer while preserving existing validators and artifact semantics.
+
+#### In scope
+
+- Bounded recognition/indexing of supported Observer evidence under the allowed
+  root.
+- Reuse existing canonical readers for observation, comparison, external
+  reference, frontend contract, and frontend contract evaluation artifacts.
+- Add only narrow missing reader wrappers required for currently persisted
+  artifact/context families, delegating to existing validators.
+- Add ephemeral viewer adapter/projection types for UI consumption.
+- Add metadata-first index responses.
+- Add on-demand full-artifact and media retrieval.
+- Represent supported, unsupported-version, malformed, missing, partial, and
+  unavailable states explicitly.
+- Enforce safe evidence-root/media-path resolution.
+
+#### Out of scope
+
+- new persistent viewer artifacts;
+- schema migration/upgrading;
+- silently accepting unsupported future schema versions;
+- full-directory arbitrary file browsing;
+- presentation-specific reimplementation of validators.
+
+#### Gate
+
+The viewer can enumerate recognized fixture evidence from metadata, load one
+selected artifact on demand through its existing validation boundary, load its
+owned/referenced media safely, and visibly distinguish malformed/unsupported/
+missing evidence rather than silently dropping it.
+
+### Batch 3 — Runtime observation inspection and SVG overlays
+
+#### Goal
+
+Make one current `ObservationArtifact` understandable graphically.
+
+#### In scope
+
+- Display the observation screenshot on demand.
+- Render stable target geometry through SVG in the original source coordinate
+  domain.
+- Add selectable runtime-target overlays and labels.
+- Add independently toggleable runtime overlays for evidence already present,
+  such as relationships, visibility, overflow, and scroll behavior where
+  meaningful.
+- Show stable target identity, resolution status, semantics, geometry,
+  visibility, overflow, scrolling, containment, relationships, diagnostics,
+  evidence source/provenance, and completion state in the inspector.
+- Preserve unavailable/not-found/ambiguous/partial states without fabricated
+  zero rectangles.
+
+#### Out of scope
+
+- before/after comparison UI;
+- contracts;
+- external references;
+- reference/runtime binding;
+- new browser queries or target resolution from the viewer.
+
+#### Gate
+
+A real existing observation fixture renders screenshot and target overlays whose
+positions are traceable to the artifact's existing geometry. Unresolved targets
+produce honest non-geometric states, not invented boxes.
+
+### Batch 4 — Before/after comparison and contract/change-scope inspection
+
+#### Goal
+
+Expose the existing v0.4 comparison and v0.5 contract/evaluation results through
+the viewer without recomputing alternate semantics.
+
+#### In scope
+
+- Before/after visual mode using the source observations referenced by an
+  existing comparison.
+- Display existing appeared/disappeared/moved/resized, visibility, clipping,
+  overflow, relationship, page-size, scroll-owner, and comparability evidence
+  as available.
+- Display baseline and per-change contract/evaluation results.
+- Display requested, expected-dependent, protected, preserved, and unexpected
+  classifications.
+- Cross-highlight relevant runtime targets only where existing target identity
+  supports it.
+- Make overall failures visually clear when a requested/local change passes but
+  a protected/preserved condition fails.
+
+#### Out of scope
+
+- a second before/after comparison engine;
+- a second contract evaluator;
+- reference/candidate fidelity;
+- editing contracts or approving baselines.
+
+#### Gate
+
+Controlled fixtures prove the viewer can explain both an all-pass change and the
+required safety case where a requested change passes but an active protected or
+preserved requirement fails overall.
+
+### Batch 5 — External reference and reference/candidate inspection
+
+#### Goal
+
+Expose the existing v0.7 external-reference model beside a browser-rendered
+candidate using the frozen side-by-side and toggleable-overlay design.
+
+#### In scope
+
+- Load imported/approved external-reference artifacts through canonical readers.
+- Resolve approved-reference image ownership/source references safely.
+- Side-by-side reference and candidate panels as the default layout.
+- Reference-side SVG region overlays in original reference-image coordinates.
+- Candidate-side runtime-target overlays in original runtime coordinates.
+- Independent overlay toggles for regions/labels/relationships/requirement
+  status on the reference side and targets/labels/relationships/contract status
+  on the candidate side.
+- Display reference lifecycle, provenance, image metadata, regions,
+  relationships, selected requirements, tolerances, adequacy, applicability,
+  supersession, diagnostics, and approval information.
+- Display existing reference/candidate compatibility and fidelity state/results
+  when supplied/computable through the existing v0.7 engines.
+
+#### Out of scope
+
+- pixel-difference scoring as a success mechanism;
+- automatic computer-vision region discovery;
+- automatic binding;
+- changing/importing/approving/superseding references through the viewer;
+- graphical region authoring.
+
+#### Gate
+
+A reference/candidate fixture can be inspected side by side with source-domain
+SVG overlays and existing structured reference/fidelity evidence. Imported and
+approved lifecycle states and image ownership remain distinguishable.
+
+### Batch 6 — Explicit-binding interaction, zoom/pan, and conditional lock
+
+#### Goal
+
+Add the synchronized inspection behavior required for useful reference/candidate
+analysis while preserving explicit identity and compatibility rules.
+
+#### In scope
+
+- Explicit-binding-driven cross-selection in both directions.
+- Visible `bound`, `ambiguous`, and `unavailable` binding states.
+- Independent zoom, pan, reset, and fit controls for both visual panes.
+- Conditional view lock/synchronization only when existing applicability and
+  compatibility evidence permits it.
+- Clear explanation when synchronization is unavailable.
+- On-demand use of the existing v0.7 in-memory reference-fidelity evaluator
+  where its required reference/candidate/binding inputs are available.
+- No persistence of a new fidelity artifact when the existing v0.7 contract is
+  intentionally in-memory.
+
+#### Out of scope
+
+- name-based or geometry-based inferred binding;
+- unconditional zoom synchronization;
+- a viewer-only fidelity evaluator;
+- automatic correction or source mutation.
+
+#### Gate
+
+Selecting a bound reference region highlights exactly its declared runtime
+target and vice versa. Ambiguous/unavailable bindings never auto-select a target.
+Independent zoom/pan always works, and locked viewing is enabled only for a
+compatible case and visibly blocked for an incompatible case.
+
+### Batch 7 — Bounded agent context, correlation, provenance, and raw evidence navigation
+
+#### Goal
+
+Complete the nonvisual evidence inspection needed to understand why the coding
+agent received a particular bounded context and how runtime targets relate to
+static/source candidates.
+
+#### In scope
+
+- Display bounded-agent-context identity/profile and supported version.
+- Display adequacy, omissions, truncations, required-evidence loss, and
+  reference-fidelity projection where present.
+- Display runtime/static correlation status, competing candidates, evidence
+  references, and uncertainty without asserting false ownership.
+- Display provenance/source references relevant to the selected evidence.
+- Provide safe navigation to relevant raw structured evidence within the allowed
+  evidence root.
+- Preserve correlated/ambiguous/unavailable and adequate/partial/inadequate
+  distinctions exactly as existing domain evidence represents them.
+
+#### Out of scope
+
+- running `my-dev-kit` from the viewer;
+- inventing static/source ownership;
+- rebuilding bounded-agent-context;
+- arbitrary filesystem browsing;
+- editing raw evidence.
+
+#### Gate
+
+A developer can trace a selected runtime/reference problem through the bounded
+context and existing source-correlation evidence, including ambiguity,
+omissions, and truncation, and can inspect the associated raw evidence without
+leaving the allowed evidence root.
+
+### Batch 8 — Integrated viewer acceptance, PWA hardening, and packaged proof
+
+#### Goal
+
+Prove the complete v0.8 viewer works as one packaged, local-first product while
+preserving all earlier CLI/programmatic workflows and architectural boundaries.
+
+#### Required integrated proof set
+
+Use deterministic evidence covering, as applicable:
+
+```text
+baseline observation
+candidate observation
+comparison
+persistent baseline contract
+per-change contract
+contract evaluation
+imported external reference
+approved external reference/reference image ownership
+reference regions and requirements
+reference applicability
+explicit reference/runtime bindings
+reference/candidate fidelity
+bounded agent context
+runtime/static correlation, including ambiguity
+```
+
+#### Required acceptance scenarios
+
+1. Normal observation: screenshot -> target -> geometry/semantics/behavior/
+   relationships.
+2. Successful requested change: before -> after -> comparison -> contract pass.
+3. Protected/preserved regression: requested change passes locally while an
+   active protected/preserved condition fails overall.
+4. Reference mismatch: approved reference -> explicit binding -> structured
+   fidelity failure.
+5. Reference fidelity passes while an active contract fails, producing overall
+   failure rather than apparent success.
+6. Reference/candidate incompatibility produces an explicit blocked/
+   incomparable state rather than fabricated visual failures.
+7. Ambiguous/unavailable binding remains visible and produces no automatic
+   candidate selection.
+8. Missing/malformed/unsupported evidence remains visible and actionable.
+9. Normal browser mode works against the packaged candidate.
+10. PWA manifest/service worker/installability behavior works in a supported
+    PWA-capable browser.
+11. Installed/standalone viewer mode connects to the same local server and same
+    canonical evidence boundary.
+12. PWA shell caching never makes stale evidence appear available when the local
+    server/evidence source is unavailable.
+13. Existing observation, comparison, contract, external-reference, and
+    programmatic workflows still pass their current validation.
+
+#### Gate
+
+The packaged candidate satisfies the v0.8 roadmap/milestone acceptance criteria
+through a real local viewer, while all pre-v0.8 CLI/programmatic paths remain
+independently functional and no second evidence engine has been introduced.
+
+## 7. Cross-batch invariants
+
+Every implementation prompt must preserve these invariants.
+
+- Assume all earlier prompts in this milestone are already implemented and
+  merged in the current repo state. Do not re-create their architecture.
+- Inspect current implementation before editing.
+- Reuse current Observer artifact/domain/application ownership boundaries.
+- Do not move v0.9 annotation authoring into v0.8.
+- Do not add source editing or automatic design generation.
+- Do not add a second browser observer, relationship engine, comparison engine,
+  contract engine, reference model, reference evaluator, binding engine,
+  correlation implementation, or bounded-context builder.
+- Runtime target identity, reference-region identity, static/source identity,
+  and filesystem identity remain distinct.
+- Viewer state is presentation state, not evidence state.
+- Unsupported, partial, unavailable, derived, ambiguous, and incomparable states
+  remain honest and visible.
+- Reference-fidelity success cannot override an active contract failure.
+- Existing approved references/baselines are never implicitly approved,
+  superseded, or mutated by viewing.
+- Heavy images are referenced/served on demand rather than embedded into every
+  data response.
+- The local viewer remains optional. CLI/programmatic workflows must continue to
+  work without it.
+
+## 8. Version-wide validation expectations
+
+Implementation batches should add focused tests as they introduce each layer.
+The completed implementation must ultimately pass the repository's applicable
+validation, including:
+
+```text
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run build
+npm run check:docs
+```
+
+v0.8 must additionally include viewer-specific tests for:
+
+- loopback-only server behavior and filesystem-root safety;
+- viewer protocol/readers/adapters;
+- unsupported/malformed/missing evidence states;
+- metadata-first/on-demand loading;
+- SVG coordinate/display transforms;
+- target/region selection;
+- explicit-binding cross-selection;
+- independent zoom/pan and conditional lock;
+- PWA manifest/service-worker/installability behavior;
+- packaged viewer asset presence and launch;
+- complete deterministic integrated viewer flows.
+
+Cross-platform pre-release validation must exercise the packed candidate on
+Windows, Linux, and macOS where the existing release workflow requires it.
+Browser/PWA behavior that cannot be proven identically on all three runners must
+be reported precisely rather than overstated.
+
+## 9. Explicit v0.8 exclusions
+
+The following are not part of v0.8:
+
+```text
+visual annotation authoring
+drawing, moving, or resizing reference regions
+interactive requirement authoring
+source editing
+automatic frontend correction
+automatic region/target binding
+computer-vision target discovery
+image-to-code or raster-to-HTML/CSS/SVG generation
+pixel-diff-only acceptance
+a second workflow engine
+cloud hosting
+accounts/authentication for the viewer
+collaboration/comments
+a database
+mandatory viewer use for observation or coding-agent review
+```
+
+These exclusions must not be pulled into a batch merely because the new UI makes
+them technically convenient.
+
+## 10. Post-implementation workflow
+
+After all eight implementation batches pass, follow the existing fixed version
+workflow rather than treating Batch 8 as release authorization:
+
+```text
+8 implementation batches
+        ->
+hardened documentation update + implementation-completeness audit
+        ->
+pre-release readiness + cross-platform/security validation
+        ->
+release preparation/version bump/package hygiene
+        ->
+user-approved publication
+```
+
+The implementation batches must not bump package version to `0.8.0`, publish to
+npm, create the release tag, or create the GitHub release. Those actions belong
+to the later release workflow.
+
+## 11. Plan change control
+
+If implementation evidence proves that this plan cannot be executed safely or
+that one of its frozen assumptions is wrong, stop the affected batch and report
+the concrete evidence. Do not silently reorder batches, replace the selected
+viewer architecture, pull in future-version scope, or redefine an existing
+Observer engine.
+
+A material change becomes authoritative only after the user explicitly accepts
+it and this file is revised to record the new plan before subsequent batches are
+executed against that revision.