@dailephd/my-frontend-observer 0.8.1 → 0.9.1

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

@@ -0,0 +1,1529 @@
+# v0.9 Implementation Plan — Human Visual Annotation and Design-Intent Capture
+
+## 1. Status and authority
+
+This document is the frozen concrete implementation plan for
+`my-frontend-observer` v0.9.
+
+It was created during v0.9 version-start planning after reviewing the current
+v0.8.1 documentation, `docs/ROADMAP.md`, `docs/PROJECT_MILESTONES.md`, the
+frozen v0.8 and v0.8.1 plans, and the current v0.8.1 source architecture.
+The source inspection is preserved in
+`docs/reports/v0.9-architecture-retrieval.md`.
+
+The architecture retrieval inspected source commit
+`473713d240af09e752eeb8e00735738c4927b16d`. Current `master` later advanced
+to `f57737585734ca72f173986b7ba0dd35c5734cea`; the intervening commit changed
+documentation only, so no production source, viewer source, test, package, or
+artifact-schema ownership used by this plan changed.
+
+This document governs v0.9 implementation scope, architecture, public and
+internal contracts, batch order, and validation expectations unless the user
+explicitly revises it.
+
+This is planning authority only. It does not prove that any v0.9 batch has been
+implemented. Actual implementation and release state remains owned by repository
+evidence and `docs/CURRENT_STATE.md`.
+
+The package remains `0.8.1` until a separate release-preparation workflow
+explicitly changes it after implementation and pre-release validation.
+
+## 2. Version objective
+
+Add structured visual human intent to the existing Observer system through the
+local viewer.
+
+A user must be able to annotate either:
+
+1. an existing runtime observation screenshot, or
+2. an existing external visual reference.
+
+Those annotations must survive save/reload while preserving the exact canonical
+source identity and source coordinate system.
+
+The annotation workflow must support explicit interpretation and confirmation
+before visual marks become strong design requirements.
+
+Confirmed annotation intent must feed the existing canonical contract and
+external-reference systems rather than introduce a second change-semantics,
+reference, or PASS/FAIL system.
+
+v0.9 does not edit application source, generate code from images, or complete
+the full coding-agent correction loop planned for v0.10.
+
+## 3. Frozen version-start decisions
+
+### 3.1 New persisted annotation evidence family
+
+v0.9 introduces one new persisted artifact family:
+
+```text
+VisualAnnotationArtifact
+artifactKind: my-frontend-observer/visual-annotation
+schemaVersion: 1.0.0
+```
+
+Annotations must not be added as mutable fields to `ObservationArtifact`,
+`ExternalReferenceArtifact`, `ComparisonArtifact`, frontend contracts, or
+contract evaluation artifacts.
+
+Observations and external references remain immutable evidence. Every explicit
+annotation save creates a new immutable annotation artifact instance.
+
+### 3.2 Source contexts remain separate
+
+A visual annotation has exactly one source context:
+
+```text
+runtime-observation
+```
+
+or:
+
+```text
+external-reference
+```
+
+Runtime observation coordinates are viewport CSS pixels.
+External-reference coordinates are reference-image pixels.
+
+The two coordinate and identity domains must never be collapsed.
+A reference-region ID must never be treated as a runtime-target name.
+A mutable project alias such as `baseline` or `current` must never become
+persisted annotation provenance.
+
+### 3.3 First persisted drawing set
+
+The v0.9 persisted mark vocabulary is exactly:
+
+```text
+point
+rectangle
+line
+arrow
+note
+```
+
+`select` and `pan` are interaction modes, not persisted annotation evidence.
+
+Do not add freehand drawing, polygons, Bezier paths, paint strokes, masks, OCR,
+computer-vision segmentation, or arbitrary SVG markup in v0.9.
+
+### 3.4 First human intent set
+
+The first human-facing intent operations are:
+
+```text
+inspect
+move
+resize
+remove
+preserve
+```
+
+External-reference annotation additionally supports:
+
+```text
+reference-region
+reference-requirement
+asset-sensitive
+```
+
+These labels describe human intent. They do not create a second evaluator.
+
+Where an operation can be represented through the current canonical contract or
+reference vocabulary, a confirmed interpretation stores that canonical
+proposal. Where the current vocabulary cannot express the operation, the
+annotation may still preserve the confirmed human intent, but promotion must
+remain visibly unsupported.
+
+v0.9 must not add a new frontend-contract primitive solely to make every drawing
+evaluable.
+
+### 3.5 Current canonical contract vocabulary remains authoritative
+
+Runtime annotation may promote only into the current `ContractPrimitive`
+vocabulary.
+
+Relevant current primitives include:
+
+```text
+property-increases
+property-decreases
+property-unchanged-within-tolerance
+relationship-unchanged
+target-width-within-bound
+target-visible
+target-not-clipped
+targets-do-not-overlap
+target-wider-than
+target-follows-vertically
+target-fits-inside
+```
+
+The current runtime geometry properties available for increase/decrease or
+preservation are:
+
+```text
+x
+y
+width
+height
+```
+
+Examples:
+
+```text
+move right
+→ property-increases(target, x)
+
+move up
+→ property-decreases(target, y)
+
+resize wider
+→ property-increases(target, width)
+
+preserve height
+→ property-unchanged-within-tolerance(target, height, tolerance)
+
+preserve an existing relationship
+→ relationship-unchanged(...)
+```
+
+A `remove` annotation is representable human intent in v0.9, but the current
+contract vocabulary has no `target-absent` primitive. Therefore:
+
+```text
+remove
+→ may be saved
+→ may be explicitly confirmed
+→ must report "not promotable by current canonical contract vocabulary"
+→ must not fabricate an equivalent contract clause
+```
+
+### 3.6 Existing authored categories remain authoritative
+
+When annotation is promoted to design intent, reuse exactly:
+
+```text
+requested
+expected-dependent
+protected
+preserved
+```
+
+`unexpected` remains evaluator output and cannot be authored through annotation.
+For `expected-dependent`, the existing `required` / `permitted` mode remains
+mandatory.
+
+No annotation-specific requested/protected/preserved vocabulary may be created.
+
+### 3.7 External-reference requirements reuse the current reference model
+
+Confirmed external-reference design requirements must use the existing
+`RawReferenceRequirement` and `ReferenceRequirementSubject` models.
+
+Current subject kinds remain:
+
+```text
+region-property
+region-relationship
+region-measurement
+```
+
+Current reference coordinates remain reference-image pixels. Current reference
+tolerances remain:
+
+```text
+exact
+absolute-reference-px
+percent
+```
+
+They must never be silently reinterpreted as CSS pixels.
+
+### 3.8 Save is explicit and immutable
+
+v0.9 does not autosave canonical annotation evidence.
+
+The editing workflow is:
+
+```text
+load source
+→ edit in-memory draft
+→ explicit Save
+→ new immutable VisualAnnotationArtifact
+```
+
+Editing a previously saved annotation creates another artifact:
+
+```text
+old annotation artifact
+→ explicit revision
+→ new annotation artifact with supersedesAnnotationId
+```
+
+The previous artifact remains unchanged.
+
+### 3.9 Confirmation is explicit
+
+A drawing is not automatically a requirement.
+
+Each annotation item carries one of:
+
+```text
+uninterpreted
+candidate
+confirmed
+```
+
+Only `confirmed` interpretations may be selected for canonical promotion.
+Geometry may be used to present a candidate interpretation, but a suggestion
+does not become confirmed intent automatically.
+
+Freeform overlap with a target or region does not create a binding.
+
+### 3.10 Authoring entry point
+
+Normal v0.9 authoring uses the existing project-aware viewer:
+
+```text
+my-frontend-observer view
+```
+
+The advanced form remains supported:
+
+```text
+my-frontend-observer view --root <evidence-root>
+```
+
+but arbitrary-root viewer use remains read-only unless it is operating through
+the normal initialized-project context.
+
+Do not add a new top-level `annotate` workflow command.
+
+### 3.11 Narrow viewer write boundary
+
+v0.8 is GET/HEAD-only. v0.9 introduces POST only for the bounded
+annotation-authoring operations defined by this plan.
+
+Do not add PUT, PATCH, DELETE, arbitrary filesystem write, source-file write, or
+artifact replacement endpoints.
+
+Existing evidence remains immutable.
+
+### 3.12 Annotated-image derivation
+
+The structured manifest is the annotation authority.
+
+Each saved annotation artifact also owns one deterministic derived overlay:
+
+```text
+annotation-overlay.svg
+```
+
+The overlay:
+
+- uses the same source-native coordinate frame recorded by the artifact;
+- contains only system-generated SVG from validated annotation marks;
+- does not contain arbitrary user SVG or HTML;
+- does not copy the source screenshot/reference image;
+- is not an independent interpretation or evidence engine.
+
+The manifest stores its relative reference and SHA-256 digest.
+
+The viewer reconstructs annotated imagery as:
+
+```text
+canonical source image
++
+annotation-overlay.svg
+```
+
+The structured annotation data remains authoritative if the overlay disagrees.
+
+## 4. Frozen domain contract
+
+Exact helper names may follow repository conventions, but the ownership and
+semantics below are frozen.
+
+### 4.1 Constants
+
+```ts
+export const VISUAL_ANNOTATION_ARTIFACT_KIND =
+  'my-frontend-observer/visual-annotation' as const;
+
+export const VISUAL_ANNOTATION_SCHEMA_VERSION = '1.0.0' as const;
+
+export const MAX_VISUAL_ANNOTATION_ITEMS = 100;
+export const MAX_VISUAL_ANNOTATION_NOTE_LENGTH = 2000;
+```
+
+### 4.2 Source identity
+
+Conceptual source contract:
+
+```ts
+type VisualAnnotationSource =
+  | {
+      kind: 'runtime-observation';
+      observationId: string;
+      requestId: string;
+      observationSchemaVersion: string;
+      screenshot: { path: string };
+      coordinateSpace: {
+        kind: 'runtime-css-px';
+        width: number;
+        height: number;
+      };
+    }
+  | {
+      kind: 'external-reference';
+      referenceId: string;
+      referenceRequestId: string;
+      referenceSchemaVersion: string;
+      lifecycle: 'imported' | 'approved';
+      imageOwnerReferenceId: string;
+      imageSha256: string;
+      coordinateSpace: {
+        kind: 'reference-image-px';
+        width: number;
+        height: number;
+      };
+    };
+```
+
+Reuse existing canonical source-reference types where that preserves exactly the
+same semantics.
+
+Do not persist mutable aliases, absolute artifact paths, browser evidence
+handles, viewer URLs, or viewer ports as source identity.
+
+### 4.3 Mark geometry
+
+```ts
+type VisualAnnotationMark =
+  | { kind: 'point'; x: number; y: number }
+  | { kind: 'rectangle'; x: number; y: number; width: number; height: number }
+  | {
+      kind: 'line';
+      start: { x: number; y: number };
+      end: { x: number; y: number };
+    }
+  | {
+      kind: 'arrow';
+      start: { x: number; y: number };
+      end: { x: number; y: number };
+    }
+  | {
+      kind: 'note';
+      anchor: { x: number; y: number };
+      text: string;
+    };
+```
+
+Coordinates must be finite. Rectangle width and height must be positive.
+Saved annotation geometry must lie within its source frame because v0.9
+annotation describes visible source-image evidence.
+
+This rule does not change existing runtime target evidence, which may
+legitimately extend outside the captured viewport.
+
+### 4.4 Explicit source-domain associations
+
+Runtime associations:
+
+```ts
+type RuntimeAnnotationAssociation =
+  | { kind: 'runtime-target'; target: string }
+  | {
+      kind: 'runtime-relationship';
+      relationshipKind: PairwiseRelationshipKind | PageLevelRelationshipKind;
+      subjectTarget?: string;
+      relatedTarget?: string;
+    };
+```
+
+Reference associations:
+
+```ts
+type ReferenceAnnotationAssociation =
+  | { kind: 'reference-region'; regionId: string }
+  | {
+      kind: 'reference-relationship';
+      subjectRegion: string;
+      relatedRegion: string;
+      relationship: PairwiseRelationshipKind;
+    };
+```
+
+Associations come from explicit user selection of known structured evidence.
+
+Do not infer association from name similarity, rectangle overlap, nearest
+element, visual proximity, or drawing containment.
+
+A free drawing without explicit structured association remains unbound.
+
+### 4.5 Interpretation state
+
+```ts
+type VisualAnnotationInterpretation =
+  | { state: 'uninterpreted' }
+  | { state: 'candidate'; intent: VisualAnnotationIntent }
+  | {
+      state: 'confirmed';
+      intent: VisualAnnotationIntent;
+      confirmedAt: string;
+    };
+```
+
+### 4.6 Intent
+
+Conceptually:
+
+```ts
+type VisualAnnotationIntent =
+  | { kind: 'inspect' }
+  | {
+      kind: 'change';
+      operation: 'move' | 'resize' | 'remove' | 'preserve';
+      category: AuthoredChangeScopeCategory;
+      expectedDependentMode?: ExpectedDependentMode;
+      contractPrimitive?: ContractPrimitive;
+    }
+  | {
+      kind: 'reference-region';
+      mode: 'create' | 'refine';
+      region: ReferenceRegion;
+    }
+  | {
+      kind: 'reference-requirement';
+      requirement: RawReferenceRequirement;
+    }
+  | {
+      kind: 'asset-sensitive';
+      regionId?: string;
+    };
+```
+
+Rules:
+
+- `inspect` is informational and never becomes a contract clause.
+- `asset-sensitive` is informational metadata in v0.9 and never becomes a
+  hidden acceptance criterion.
+- confirmed `move`, `resize`, or `preserve` requires an existing valid
+  `ContractPrimitive` before contract promotion.
+- confirmed `remove` must not fabricate a contract primitive.
+- `reference-region`, `reference-requirement`, and `asset-sensitive` are valid
+  only for external-reference source context.
+- runtime contract proposals are valid only for runtime-observation source
+  context.
+- every contract primitive, authored category, expected-dependent mode,
+  `ReferenceRegion`, and `RawReferenceRequirement` must be validated through
+  its existing canonical validator.
+
+### 4.7 Annotation item
+
+```ts
+interface VisualAnnotationItem {
+  annotationItemId: string;
+  mark: VisualAnnotationMark;
+  association?: RuntimeAnnotationAssociation | ReferenceAnnotationAssociation;
+  interpretation: VisualAnnotationInterpretation;
+}
+```
+
+`annotationItemId` is generated by Observer when an item is first created and
+remains stable when that logical item is carried into a later annotation
+revision. It is not derived from geometry.
+
+### 4.8 Artifact
+
+Conceptually:
+
+```ts
+interface VisualAnnotationArtifact {
+  artifactKind: typeof VISUAL_ANNOTATION_ARTIFACT_KIND;
+  schemaVersion: typeof VISUAL_ANNOTATION_SCHEMA_VERSION;
+
+  annotationRequestId: string;
+  annotationId: string;
+  supersedesAnnotationId?: string;
+
+  producer: {
+    name: string;
+    version: string;
+  };
+
+  source: VisualAnnotationSource;
+  items: VisualAnnotationItem[];
+
+  overlay: {
+    path: 'annotation-overlay.svg';
+    format: 'svg';
+    width: number;
+    height: number;
+    sha256: string;
+  };
+
+  provenance: {
+    createdAt: string;
+    origin: 'viewer';
+  };
+}
+```
+
+## 5. Identity and revision rules
+
+### 5.1 Request identity
+
+`annotationRequestId` is deterministic and includes canonical semantic content:
+
+```text
+source canonical identity
+source coordinate domain and dimensions
+items
+associations
+interpretations
+supersedesAnnotationId when present
+```
+
+It excludes:
+
+```text
+createdAt
+output directory
+project root
+mutable alias
+viewer port
+HTTP evidence handle
+temporary path
+```
+
+### 5.2 Instance identity
+
+`annotationId` is fresh for every persisted instance.
+
+Saving identical semantic annotation content twice may produce the same
+`annotationRequestId` but different `annotationId` values.
+
+### 5.3 Revision lineage
+
+A revision contains `supersedesAnnotationId` pointing from the new artifact to
+the previous artifact. The previous artifact is never changed.
+
+### 5.4 Revision conflicts
+
+The authoring API must reject stale revision attempts rather than silently
+overwrite newer work.
+
+Saving a revision sends the canonical parent annotation ID. If that parent
+already has a later accepted child in the same active lineage, return an
+explicit conflict response.
+
+Do not choose a winner by timestamp. If malformed historical evidence has
+multiple heads, expose the branch conflict and require explicit user choice.
+
+## 6. Persistence architecture
+
+Add the established repository pattern:
+
+```text
+src/domain/visualAnnotation.ts
+src/domain/visualAnnotationIdentity.ts
+src/artifacts/visualAnnotationArtifactWriter.ts
+src/artifacts/visualAnnotationArtifactReader.ts
+src/application/visualAnnotationPersistenceService.ts
+```
+
+The writer must:
+
+1. validate the domain artifact;
+2. derive the final immutable directory from `annotationId`;
+3. refuse an existing final directory;
+4. write through a sibling temporary directory;
+5. deterministically generate `annotation-overlay.svg`;
+6. compute/store its SHA-256;
+7. write `manifest.json`;
+8. atomically rename the temporary directory;
+9. remove temporary output on failure.
+
+The reader must parse the manifest, use the one canonical annotation validator,
+reject unsupported schema versions, verify required owned overlay media, and
+fail closed on unsafe media references.
+
+The annotation writer must not read or modify the source observation/reference.
+
+## 7. Managed project layout
+
+Extend project-managed evidence with:
+
+```text
+.frontend-observer/
+  catalog.json
+  evidence/
+    observations/
+    annotations/
+    contracts/
+    references/
+```
+
+Existing evidence paths remain valid. Do not migrate or relocate historical
+evidence simply to create these directories.
+
+New annotation artifacts use:
+
+```text
+.frontend-observer/evidence/annotations/<annotationId>/
+```
+
+New annotation-promoted change contracts use:
+
+```text
+.frontend-observer/evidence/contracts/<contractId>/
+```
+
+New annotation-authored external-reference revisions use:
+
+```text
+.frontend-observer/evidence/references/<referenceId>/
+```
+
+All paths remain project-relative and portable.
+No annotation alias catalog is introduced in v0.9.
+
+## 8. Viewer discovery and read model
+
+Extend current evidence discovery/classification explicitly for
+`my-frontend-observer/visual-annotation`.
+
+Add the canonical reader branch and metadata projection.
+
+Bounded annotation metadata may include:
+
+```text
+annotationId
+annotationRequestId
+source kind
+source canonical ID
+supersedesAnnotationId
+item count
+confirmation summary
+```
+
+Full annotation items remain on-demand.
+
+Add an annotation view projection that resolves:
+
+```text
+annotation artifact
+→ canonical source evidence
+→ source media
+→ existing structured target/relationship/region evidence
+```
+
+The viewer server may project these values. It must not reinterpret confirmed
+intent or implement a second annotation semantic engine.
+
+## 9. Viewer authoring security boundary
+
+Authoring changes the v0.8 read-only boundary, so v0.9 adds a deliberately small
+write surface.
+
+### 9.1 Authoring capability
+
+`startViewer` exposes annotation authoring only when started from a valid
+initialized project with a known project root and managed evidence root.
+Standalone arbitrary-root viewing remains read-only.
+
+### 9.2 Session capability token
+
+At viewer startup, generate one cryptographically random in-memory authoring
+token.
+
+The token:
+
+- is not persisted;
+- is not stored in a cookie;
+- is not embedded in service-worker cache;
+- expires when the viewer server exits.
+
+The live viewer obtains it only through the current local server boundary.
+Every authoring POST requires it in a dedicated header.
+
+### 9.3 Same-origin enforcement
+
+Every authoring POST additionally requires:
+
+- exact expected loopback `Origin`;
+- expected `Host`;
+- JSON content type;
+- bounded request body size;
+- valid session token.
+
+Do not enable permissive CORS.
+
+### 9.4 Method surface
+
+Existing GET/HEAD routes remain unchanged.
+POST is accepted only for explicit authoring endpoints.
+PUT, PATCH, and DELETE remain unsupported.
+
+## 10. Authoring API
+
+Use a small responsibility-based API surface, conceptually:
+
+```text
+POST /api/annotations
+POST /api/annotations/:handle/promote-contract
+POST /api/annotations/:handle/materialize-reference
+```
+
+Exact route names may follow current viewer-server conventions, but do not
+expand the public surface beyond these responsibilities.
+
+### 10.1 Save annotation
+
+The request supplies a source evidence handle, optional parent annotation
+handle, and bounded annotation items.
+
+The server resolves handles to canonical artifacts. The client never supplies
+an arbitrary filesystem path.
+
+The application service constructs canonical source references and identities
+and persists one immutable artifact.
+
+### 10.2 Promote runtime intent
+
+Contract promotion takes one saved annotation artifact and explicit selected
+confirmed annotation item IDs.
+
+Reject:
+
+```text
+unconfirmed item
+unsupported item
+wrong source context
+invalid existing primitive
+missing configured baseline requirements
+```
+
+Build one normal `PerChangeContract` using existing authored categories,
+expected-dependent modes, `ContractPrimitive`, contract identity, and contract
+persistence owners.
+
+Supporting evidence should point back to the relevant persisted annotation
+item/source evidence through the existing `EvidenceReference` mechanism.
+
+The annotation system must not evaluate the contract itself.
+
+### 10.3 Activate promoted contract for project check
+
+When project configuration already contains the required contract acceptance
+configuration and baseline artifact, explicit promotion may atomically update
+only:
+
+```text
+acceptance.contract.changeArtifact
+```
+
+to the newly persisted project-relative change-contract path.
+
+Do not change the configured baseline. Do not add a baseline automatically. Do
+not silently enable contract acceptance when the project did not configure one.
+
+If required project configuration is absent, persist the change contract but
+report that it is not active for `check` until project acceptance configuration
+is explicitly supplied.
+
+### 10.4 Materialize external-reference intent
+
+External-reference promotion takes one saved external-reference annotation
+artifact and selected confirmed `reference-region` and/or
+`reference-requirement` items.
+
+Read the canonical source external reference and its canonical image bytes.
+Construct a new imported `ExternalReferenceArtifact` using the existing
+external-reference import/persistence service.
+
+The new revision:
+
+- reuses the original image content;
+- carries forward unchanged regions/requirements/applicability unless explicitly
+  replaced through confirmed annotation intent;
+- adds confirmed regions;
+- replaces an existing region only when the user explicitly confirmed
+  `mode: refine` for that region ID;
+- adds selected requirements through existing `RawReferenceRequirement`
+  construction;
+- sets `supersedesReferenceId` to the selected source reference;
+- receives new canonical reference request/instance identities.
+
+It does not mutate the old reference, automatically approve the new reference,
+or update configured approved-reference acceptance.
+
+The UI must expose the existing explicit approval workflow as the next step.
+
+## 11. Reference-region authoring rules
+
+### Create
+
+A rectangle becomes a reference region only through explicit interpretation.
+The user supplies or accepts a valid region ID. Because the rectangle is already
+in reference-image pixels, no coordinate conversion occurs.
+
+### Refine
+
+The user explicitly selects an existing region. The new reference revision
+retains the same region ID and replaces that region's rectangle with the
+confirmed rectangle. Only the new external-reference artifact contains the
+revised geometry.
+
+### Relationship requirements
+
+Relationships remain derived by the existing canonical
+`deriveReferenceRegionRelationships` function.
+
+The annotation UI may let the user select one supported derived relationship
+and turn it into a candidate `RawReferenceRequirement`. The annotation layer
+must not create a second relationship engine.
+
+## 12. Rendering and coordinate rules
+
+### 12.1 Runtime observations
+
+Annotations render inside the same runtime screenshot SVG coordinate frame
+already used by `TargetOverlaySvg`.
+
+Do not create another runtime coordinate transform.
+Runtime annotations remain viewport CSS pixels with no device-pixel-ratio
+multiplication.
+
+### 12.2 External references
+
+Annotations render inside the same reference-image SVG coordinate frame already
+used by `ReferenceRegionOverlaySvg`.
+
+Reference annotations remain reference-image pixels.
+
+### 12.3 Shared annotation layer
+
+Add one reusable presentation layer such as:
+
+```text
+viewer/src/components/AnnotationLayer.tsx
+```
+
+It should render a `<g>` layer inside the existing source SVG rather than create
+an independently transformed screenshot/reference canvas.
+
+The existing workspace owns the viewBox and zoom/pan state. The annotation layer
+receives source-native coordinates.
+
+### 12.4 Pointer conversion
+
+Extract/reuse one helper for screen-pointer to SVG-source-coordinate conversion
+from current `useZoomPan` `getScreenCTM().inverse()` behavior.
+
+Do not create one coordinate implementation for panning and another for drawing.
+
+### 12.5 Navigation versus drawing
+
+The toolbar has explicit interaction modes:
+
+```text
+select
+pan
+point
+rectangle
+line
+arrow
+note
+```
+
+Drawing modes consume drawing pointer gestures. Pan mode consumes drag-to-pan
+gestures. The same drag must never be interpreted simultaneously as both.
+
+## 13. Interpretation and confirmation workflow
+
+For each mark:
+
+```text
+draw/select
+→ optional explicit structured association
+→ choose intent
+→ show candidate canonical interpretation
+→ explicit Confirm
+→ save immutable annotation revision
+```
+
+For runtime move/resize/preserve proposals, show the exact candidate
+`ContractPrimitive` before confirmation.
+
+Example:
+
+```text
+Move workspace right
+
+Candidate:
+category: requested
+primitive:
+  kind: property-increases
+  target: workspace
+  property: x
+```
+
+The user confirms that structured meaning. The arrow itself is not the
+contract.
+
+For reference requirements, show the exact category, subject, and tolerance
+before confirmation.
+
+An annotation with no reliable association remains useful visual/narrative
+evidence but cannot be promoted into a canonical requirement requiring a
+structured subject.
+
+## 14. Conflict policy
+
+v0.9 does not introduce a new semantic conflict engine.
+
+### Revision conflict
+
+Handled by annotation revision lineage. Stale edits fail explicitly.
+
+### Contract conflict
+
+Promotion builds an ordinary per-change contract. Existing contract validation
+and evaluation remains authoritative for clause conflicts.
+
+### Reference requirement conflict
+
+Existing reference requirement validation and adequacy derivation remains
+authoritative.
+
+### Unsupported interpretation
+
+A confirmed human intent that has no current canonical mapping is not a conflict
+and is not a pass. Report it as:
+
+```text
+confirmed but not canonically promotable
+```
+
+with a bounded reason. `remove` is the initial required example.
+
+## 15. Implementation sequence
+
+Implement v0.9 in exactly seven ordered implementation prompts. Each prompt
+assumes earlier prompts are implemented and merged.
+
+### Batch 1 — Visual annotation domain, identity, persistence, and overlay derivation
+
+#### Goal
+
+Implement the canonical annotation evidence family independently of viewer
+authoring UI.
+
+#### Production scope
+
+Add:
+
+```text
+src/domain/visualAnnotation.ts
+src/domain/visualAnnotationIdentity.ts
+src/artifacts/visualAnnotationArtifactWriter.ts
+src/artifacts/visualAnnotationArtifactReader.ts
+src/application/visualAnnotationPersistenceService.ts
+```
+
+Implement artifact/schema constants, the runtime/reference source union, five
+mark kinds, association types, interpretation state, frozen intent vocabulary,
+source-domain validation, bounded counts/text, coordinate validation,
+deterministic request identity, fresh instance identity, forward-only
+supersession, deterministic overlay SVG, immutable atomic persistence, reader
+validation, and public `src/index.ts` exports.
+
+#### Mandatory tests
+
+Cover:
+
+- valid runtime artifact;
+- valid reference artifact;
+- invalid cross-domain association;
+- invalid/out-of-frame annotation geometry;
+- note length/count bounds;
+- candidate versus confirmed interpretation;
+- invalid authored `unexpected`;
+- deterministic request identity;
+- timestamp/output-path exclusion from request identity;
+- fresh instance identity;
+- writer/reader round trip;
+- no overwrite;
+- temporary-directory cleanup;
+- overlay determinism and SHA-256;
+- malicious text escaping in generated SVG;
+- supersession preservation.
+
+#### Gate
+
+A structured runtime or reference annotation can be constructed, validated,
+persisted immutably, read back, and rendered as the same deterministic overlay
+without any viewer mutation route.
+
+### Batch 2 — Viewer discovery, project authoring boundary, and secure POST API
+
+#### Goal
+
+Make annotation evidence visible and establish the secure local write boundary.
+
+#### Production scope
+
+Extend evidence classification, metadata projection, on-demand annotation
+loading, media resolution for `annotation-overlay.svg`, annotation/source view
+projection, and project-aware viewer startup.
+
+Implement:
+
+- authoring enabled only in initialized project mode;
+- in-memory session capability token;
+- strict same-origin/Host checks;
+- JSON-only bounded request bodies;
+- annotation save POST;
+- source-handle to canonical-source resolution;
+- optional parent annotation revision;
+- stale revision conflict response;
+- no arbitrary client-supplied write path;
+- standalone `view --root` remains read-only.
+
+#### Mandatory tests
+
+Cover annotation family classification, unsupported/malformed annotation,
+source resolution, missing source, overlay media serving, traversal/symlink
+containment, project-mode authoring, standalone read-only behavior, missing or
+incorrect token, wrong Origin, unsupported methods, oversized/invalid request,
+valid save, stale revision conflict, and unchanged prior artifact.
+
+#### Gate
+
+A project-aware viewer can save and reload an immutable annotation artifact
+through a secured local POST boundary while previous GET/HEAD inspection
+behavior remains unchanged.
+
+### Batch 3 — Runtime screenshot annotation authoring
+
+#### Goal
+
+Allow a human to create, edit, save, and reload annotations directly on a
+runtime observation.
+
+#### Production scope
+
+Add the annotation toolbar and shared annotation layer.
+
+Support interaction modes:
+
+```text
+select
+pan
+point
+rectangle
+line
+arrow
+note
+```
+
+Integrate with `ObservationWorkspace`, `TargetOverlaySvg`, target selection,
+relationship views, and current zoom/pan.
+
+Implement explicit runtime associations through existing target/relationship
+selection only.
+
+Implement in-memory draft editing:
+
+```text
+create
+select
+move annotation mark
+edit note
+delete unsaved draft mark
+cancel
+save
+```
+
+Deleting a draft mark does not delete historical persisted evidence.
+
+#### Mandatory browser tests
+
+Prove exact runtime CSS-pixel geometry, zoom/pan pointer mapping, no DPR
+conversion, explicit target association, no overlap auto-binding, save/reload,
+alias-to-canonical source resolution, alias replacement not rebinding saved
+annotation, source-unavailable behavior, and keyboard/pointer usability.
+
+#### Gate
+
+A user can annotate an observation, save it, reload, and see the same marks
+associated with the same canonical observation and explicit runtime
+associations.
+
+### Batch 4 — External-reference annotation and reference-region authoring
+
+#### Goal
+
+Provide the same structured authoring flow in reference-image coordinates and
+add explicit region creation/refinement.
+
+#### Production scope
+
+Integrate the annotation layer into `ReferenceWorkspace`,
+`ReferenceRegionOverlaySvg`, existing reference-region selection, relationship
+projection, and zoom/pan/view-lock behavior.
+
+Support reference point/rectangle/line/arrow/note marks, explicit
+region/relationship association, candidate region creation, candidate region
+refinement, `asset-sensitive` informational intent, and informational versus
+candidate-requirement distinction.
+
+Do not materialize a new reference artifact yet. That belongs to Batch 6.
+
+#### Mandatory browser tests
+
+Prove exact reference-image coordinates, zoom/pan coordinate correctness,
+reference-region/runtime-target identity separation, no equal-name auto-binding,
+region create/refine preview, unchanged source artifact, binding
+cross-highlighting remaining separate from annotation association, and
+save/reload preserving canonical reference source identity.
+
+#### Gate
+
+A user can annotate an imported or approved reference, create/refine candidate
+regions, save/reload, and retain the exact selected canonical reference source
+without mutating it.
+
+### Batch 5 — Intent interpretation, confirmation, and canonical change-contract promotion
+
+#### Goal
+
+Turn explicitly confirmed runtime visual intent into the existing per-change
+contract model.
+
+#### Production scope
+
+Add interpretation UI for:
+
+```text
+inspect
+move
+resize
+remove
+preserve
+```
+
+Add category selection for the four existing authored categories and show the
+exact canonical proposal before confirmation.
+
+Implement supported mappings through existing `ContractPrimitive` values.
+Implement an annotation-to-contract application service and persist through the
+existing frontend contract persistence owner.
+
+Promote only explicitly selected confirmed annotations.
+
+Support explicit activation through existing project acceptance configuration
+when a baseline contract is already configured.
+
+`remove` is confirmed annotation intent but is not canonically promotable in
+v0.9. Do not extend the primitive vocabulary merely to make it promotable.
+
+#### Mandatory tests
+
+Cover at least:
+
+- move right -> `property-increases x`;
+- move left -> `property-decreases x`;
+- move down -> `property-increases y`;
+- resize wider -> `property-increases width`;
+- preserve property -> `property-unchanged-within-tolerance`;
+- preserve relationship -> `relationship-unchanged`;
+- expected-dependent requires its existing mode;
+- `unexpected` cannot be authored;
+- inspect is not promotable;
+- remove reports unsupported canonical mapping;
+- unconfirmed candidate cannot promote;
+- unbound mark cannot fabricate a target;
+- only selected confirmed items enter the contract;
+- contract persists through the canonical service;
+- active baseline IDs come from explicit configured evidence;
+- configured baseline is never replaced;
+- existing evaluator remains authoritative.
+
+#### Gate
+
+At least one move/resize case and one preserve case can travel:
+
+```text
+visual mark
+→ explicit association
+→ candidate structured interpretation
+→ explicit confirmation
+→ normal PerChangeContract
+```
+
+with no annotation-specific contract evaluator.
+
+### Batch 6 — Canonical external-reference region/requirement materialization
+
+#### Goal
+
+Turn explicitly confirmed reference annotation into a new immutable external
+reference revision through the existing reference model.
+
+#### Production scope
+
+Implement reference materialization for selected confirmed:
+
+```text
+reference-region create
+reference-region refine
+reference-requirement
+```
+
+Reuse `RawReferenceRequirement`, `ReferenceRequirementSubject`,
+`AuthoredChangeScopeCategory`, and `ReferenceRequirementTolerance`.
+
+Use existing region relationship derivation for selectable relationship
+subjects.
+
+Read original image bytes from the canonical image owner through the existing
+safe reference/media boundary. Persist a new imported external reference through
+the canonical reference persistence service. Set explicit supersession.
+
+Never auto-approve or alter project configured approved-reference acceptance.
+
+#### Mandatory tests
+
+Prove region creation, region refinement, preservation of unchanged regions and
+requirements, selected requirement addition, no auto-requirements from visible
+geometry, applicability preservation, image byte/hash preservation, old
+artifact immutability, fresh new reference identity, explicit supersession,
+resulting imported lifecycle, normal existing adequacy/relationship behavior,
+and no approval side effect.
+
+#### Gate
+
+A user can turn selected confirmed reference annotations into a normal new
+imported external-reference revision that can subsequently use the existing
+approval and fidelity workflow.
+
+### Batch 7 — Integrated acceptance, packaging, documentation, and regression
+
+#### Goal
+
+Prove v0.9 as one packaged feature without pulling v0.10 source editing or
+correction orchestration forward.
+
+#### Required integrated scenarios
+
+1. Runtime observation annotation: select observation -> draw/note -> save ->
+   reload.
+2. Canonical identity: annotate alias `current` -> replace alias -> saved
+   annotation still points to the original observation.
+3. Move intent: arrow + target -> move candidate -> explicit confirmation ->
+   canonical per-change clause.
+4. Preserve intent -> confirmed canonical preserved clause.
+5. Unsupported remove saves/reloads but cannot fabricate a contract.
+6. Ambiguous/free drawing remains visual evidence and cannot silently become a
+   strong requirement.
+7. External-reference annotation -> save -> reload in reference-image
+   coordinates.
+8. Confirmed reference-region creation -> new imported reference revision.
+9. Region refinement -> new revision while old reference remains unchanged.
+10. Confirmed selected property/relationship/measurement requirement becomes a
+    normal external-reference requirement.
+11. Informational inspect/note/asset-sensitive annotation stays non-contractual.
+12. Stale annotation revision is rejected rather than overwriting newer
+    evidence.
+13. Unrelated browser origin cannot POST annotation writes.
+14. Missing source is reported honestly while annotation evidence remains
+    inspectable.
+15. Existing v0.8 viewer inspection remains functional.
+16. Existing `init`, `capture`, `check`, and project-aware `view` remain
+    functional.
+17. Annotation create/reload and promoted-contract inspection work from a clean
+    installed npm package.
+
+#### Documentation reconciliation
+
+Update implementation-facing documentation as appropriate after implementation:
+
+```text
+README.md
+CHANGELOG.md
+docs/ARCHITECTURE.md
+docs/COMMANDS.md
+docs/CONTRACTS.md
+docs/CURRENT_STATE.md
+docs/PROJECT_MILESTONES.md
+docs/PROJECT_OVERVIEW.md
+docs/QUICKSTART.md
+docs/ROADMAP.md
+docs/SECURITY.md
+docs/WORKFLOWS.md
+```
+
+Do not mark v0.9 released during implementation. Release-state changes belong
+to the later release-preparation workflow.
+
+#### Gate
+
+A packed candidate demonstrates both annotation source contexts, persistence,
+explicit confirmation, runtime contract promotion, reference region/requirement
+materialization, source immutability, security boundaries, and backward
+compatibility.
+
+## 16. Cross-batch invariants
+
+Every implementation prompt must preserve these rules.
+
+1. Observations remain immutable.
+2. External references remain immutable.
+3. Annotation save creates new immutable evidence.
+4. Mutable aliases never become annotation identity.
+5. Runtime CSS pixels remain distinct from reference-image pixels.
+6. Annotation geometry never silently establishes runtime/reference binding.
+7. Viewer geometry overlap never silently establishes target/region ownership.
+8. Drawing alone never becomes a contract.
+9. Confirmation is required before promotion.
+10. `unexpected` remains derived, never authored.
+11. Existing contract primitives remain authoritative.
+12. Existing reference requirement vocabulary remains authoritative.
+13. Existing relationship derivation remains authoritative.
+14. Existing contract evaluation remains authoritative.
+15. Existing reference adequacy/compatibility/fidelity engines remain
+    authoritative.
+16. Reference-fidelity PASS cannot override an active contract failure.
+17. Original source evidence is not rewritten during annotation.
+18. New external-reference revisions are not automatically approved.
+19. Annotation is optional for ordinary `capture`, `check`, and coding-agent
+    workflows.
+20. Observer never edits application source.
+21. Observer does not generate HTML/CSS/application code from images.
+22. Viewer POST may write only canonical Observer/project evidence explicitly
+    authorized by this plan.
+23. Browser/PWA caching must not make stale annotation/evidence API responses
+    authoritative.
+24. Historical annotation revisions remain available.
+25. Unsupported intent is shown honestly rather than approximated into a
+    different requirement.
+
+## 17. Version-wide validation
+
+Every batch runs the focused tests it introduces.
+
+Before declaring implementation complete, run at minimum:
+
+```text
+npm run typecheck
+npm run lint
+npm test
+npm run test:browser
+npm run build
+npm run check:docs
+```
+
+Also run all existing security/package checks used by the current pre-release
+workflow.
+
+The final packed-candidate proof must verify that the package includes annotation
+domain/application/artifact compiled output, updated public exports, viewer
+server authoring code, annotation viewer assets, generated viewer bundle, and
+packed viewer smoke coverage.
+
+Cross-platform validation must continue on the same supported Windows, Linux,
+and macOS surfaces used by the current release workflow.
+
+## 18. Explicit v0.9 exclusions
+
+The following do not belong in v0.9:
+
+```text
+application source editing
+automatic coding-agent execution
+full correction-loop orchestration
+image-to-code
+raster-to-HTML
+raster-to-CSS
+automatic target discovery
+automatic reference/runtime binding
+automatic region detection
+OCR-driven requirements
+computer-vision segmentation
+freehand drawing
+arbitrary SVG input
+annotation collaboration
+accounts
+cloud synchronization
+database storage
+comment threads
+automatic reference approval
+automatic baseline approval
+automatic baseline replacement
+automatic approved-reference replacement
+new PASS/FAIL semantics
+annotation-only contract categories
+annotation-only reference requirement categories
+silent mapping of unsupported intent
+```
+
+The full human-to-coding-agent correction workflow remains v0.10.
+
+## 19. Prompt count and implementation order
+
+The frozen implementation sequence is exactly seven prompts:
+
+```text
+Prompt 1
+Visual annotation domain, identity, persistence, overlay derivation
+
+Prompt 2
+Viewer discovery, secure authoring boundary, annotation save API
+
+Prompt 3
+Runtime screenshot annotation authoring
+
+Prompt 4
+External-reference annotation and reference-region authoring
+
+Prompt 5
+Interpretation, confirmation, canonical change-contract promotion
+
+Prompt 6
+Canonical external-reference region/requirement materialization
+
+Prompt 7
+Integrated acceptance, packaging, documentation, regression
+```
+
+Do not combine later prompts into an earlier batch merely because files are
+nearby.
+
+Do not start Prompt 2 until Prompt 1 passes its gate.
+
+Do not start contract/reference promotion until the persisted annotation
+contract and both coordinate-domain authoring flows are independently proven.
+
+The dependency progression is:
+
+```text
+canonical annotation evidence
+        ↓
+secure persistence through viewer
+        ↓
+runtime visual authoring
+        ↓
+reference visual authoring
+        ↓
+confirmed canonical change intent
+        ↓
+confirmed canonical reference intent
+        ↓
+integrated packaged v0.9
+```