@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-batch4-external-reference-annotation-authoring.md

@@ -0,0 +1,452 @@
+# v0.9 Batch 4 Report: External-Reference Annotation Authoring
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH4_EXTERNAL_REFERENCE_ANNOTATION_AUTHORING
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Starting HEAD: `9d8169b653b087a581ef38a04f97bfab5a252aae`
+4. Ending HEAD before the final commit: `9d8169b653b087a581ef38a04f97bfab5a252aae`
+5. Package version: `0.8.1` (unchanged in `package.json` and `package-lock.json`)
+
+## 3. Prompt 3 entry gate
+
+1. Prompt 3 verdict: `PASS_V0_9_BATCH3_RUNTIME_SCREENSHOT_ANNOTATION_AUTHORING`
+2. Prompt 3 commit: `9d8169b653b087a581ef38a04f97bfab5a252aae`
+3. Runtime annotation UI: implemented
+4. Prompt 2 save API: unchanged
+5. Viewer protocol: `1.1.0`
+6. Preflight found a clean tracked worktree on `master` at the required HEAD.
+7. `git ls-files -v docs/reports/v0.9-architecture-retrieval.md` printed `S`
+   at entry and before commit. The `skip-worktree` state was preserved and the
+   file was not restored, overwritten, or committed. No pull, rebase, reset,
+   or clean was run.
+8. No Prompt 1 to 3 API conflict and no domain contract defect were found.
+   No file under `src/` changed.
+
+## 4. Imported/approved reference source handling
+
+1. The source frame is `image.width`/`image.height` for an imported
+   reference and `sourceReference.image.width`/`height` for an approved one.
+   These are the same values the reference SVG already uses for its viewBox.
+2. The browser sends only `{ sourceHandle, parentAnnotationHandle?, items }`.
+   The Prompt 2 server builds `referenceId`, `referenceRequestId`,
+   `lifecycle`, `imageOwnerReferenceId`, and `imageSha256`.
+3. The annotation is tied to whichever reference the user opened.
+   Browser-verified:
+   1. An imported annotation has `lifecycle: imported`, the imported
+      `referenceId`, and the image owner equal to itself.
+   2. An approved annotation has `lifecycle: approved`, the approved
+      `referenceId`, and `imageOwnerReferenceId` equal to the imported
+      `sourceReference.referenceId`.
+   3. Neither is redirected to the other.
+
+## 5. Reference annotation discovery
+
+1. The Prompt 3 discovery hook was generalized into `useSourceAnnotations`
+   (in `useRuntimeAnnotations.ts`). `useRuntimeAnnotations` is now a thin
+   wrapper with unchanged behavior.
+2. New `viewer/src/hooks/useReferenceAnnotations.ts` finds candidates through
+   `/api/index` by `relatedIds.sourceReferenceId`. It keeps a candidate only
+   when `/api/annotations/:handle/view` reports `source.status === available`,
+   `source.family` equal to the current reference family, and `source.handle`
+   equal to the current reference handle. That check is
+   `annotationViewBelongsToSource`.
+3. Labels, image dimensions, `referenceRequestId` alone, region ids, and image
+   hashes are never used to attach an annotation.
+
+## 6. Shared annotation infrastructure reuse
+
+Reused unchanged:
+
+1. `AnnotationLayer`
+2. `useAnnotationPointerInteraction`
+3. `sourceCoordinates.screenPointToSvgSource`
+4. `annotationGeometry`
+5. `useAuthoringSession`
+6. `useZoomPan`, in the reference pane's existing controlled mode
+
+Small generic refactors, with runtime behavior preserved and all Prompt 3
+tests still passing:
+
+1. `useRuntimeAnnotationDraft.ts` now exports `useAnnotationDraft(sourceHandle)`.
+   `useRuntimeAnnotationDraft` is an alias of it.
+2. The 404 save message says "source evidence" instead of "source
+   observation". The existing tests check "no longer exists", which is
+   unchanged.
+3. `AnnotationToolbar` makes its zoom controls optional through `zoom?` and
+   `zoomLabel`, because the reference pane already renders its own
+   `ZoomControls`.
+4. New `AnnotationPanelSections.tsx` holds the session notice, saved list, and
+   draft lifecycle. It was extracted from `RuntimeAnnotationPanel` with
+   identical markup and used by both panels.
+
+No reference-specific layer, coordinate helper, pointer interaction, or
+toolbar was created.
+
+## 7. Reference-image coordinate behavior
+
+1. All drawing and moving uses the shared CTM transform in the reference SVG's
+   own viewBox, which is reference-image pixels.
+2. The candidate viewport, CSS pixels, devicePixelRatio, the reference/candidate
+   coordinate scale, and bindings are never used for persisted geometry.
+3. Browser-verified at exact reference-image coordinates:
+   1. A rectangle drawn in reverse from 250,200 to 50,80 persists as
+      50, 80, 200, 120.
+   2. Zoomed and panned drawings persist their intended coordinates.
+   3. A drawing made while the view is locked persists reference pixels, not
+      values mapped through the 0.25 lock scale.
+
+## 8. Interaction modes
+
+1. The same closed set is used: `select`, `pan`, `point`, `rectangle`,
+   `line`, `arrow`, `note`. No region, requirement, or asset mode exists.
+   Those are interpretations of a selected mark.
+2. `ReferenceRegionOverlaySvg` gains three optional props: `annotationLayer`,
+   `regionsInteractive` (default `true`), and `interactionClassName`. Callers
+   that pass none of them are unchanged.
+3. Per mode:
+   1. Select: region selection plus mark selection and move.
+   2. Pan: `useZoomPan` handlers only.
+   3. Drawing modes: drawing only. Region pointer selection is off, but region
+      keyboard selection stays available.
+4. Behavior change, recorded deliberately: the reference pane now pans only
+   in Pan mode. Before this batch a zoomed reference pane also panned on a
+   drag in its default state. This matches the Prompt 3 rule that a select
+   drag never pans. The candidate pane is unchanged.
+5. Layout fix found by the browser tests. The reference workspace is a
+   fixed-height scrolling flex column, so its panes row could shrink, and the
+   details section, now taller with the annotation panel, was painted over the
+   lower part of the reference image. The fix is
+   `.reference-workspace > * { flex-shrink: 0; }`.
+
+## 9. Reference region association
+
+1. Drawing over a region never associates it.
+2. With a draft item selected and a region selected (pointer in Select mode,
+   or keyboard), "Associate region <id>" sets
+   `{ kind: 'reference-region', regionId }`. "Clear association" removes it.
+3. Selecting a region never associates automatically.
+
+## 10. Reference relationship association
+
+1. Options come only from `referenceView.regionRelationships.pairwiseRelationships`,
+   the canonical server derivation.
+2. "Associate relationship" sets
+   `{ kind: 'reference-relationship', subjectRegion, relatedRegion, relationship }`.
+3. Lines and arrows never imply a relationship. Nothing is derived in React.
+
+## 11. Region create candidate
+
+1. Available only for a selected rectangle, with a "Proposed region ID" input
+   (`maxLength=64`) and a hint about the allowed characters.
+2. The id is never rewritten, lowercased, or replaced.
+3. Blocked when:
+   1. the id is empty or does not match `^[A-Za-z0-9_-]{1,64}$`;
+   2. it duplicates a source region (case-insensitive);
+   3. it duplicates another draft create (case-insensitive);
+   4. source regions plus other distinct draft creates already reach 20
+      (`MAX_REFERENCE_REGIONS`, mirrored).
+4. The candidate is
+   `{ kind: 'reference-region', mode: 'create', region: { id, rectangle } }`,
+   using the exact mark geometry.
+5. The preview renders a dashed candidate rectangle labeled
+   "candidate new <id> (<state>)".
+
+## 12. Region refine candidate
+
+1. Requires a selected rectangle and a selected existing region. The user
+   clicks "Refine selected region <id>".
+2. The candidate is `mode: 'refine'` with the same region id and the mark
+   geometry. The item is also explicitly associated with that region.
+3. The preview shows the original source rectangle and the candidate
+   replacement, each with its own distinct class. The source region keeps
+   rendering with its original geometry.
+4. A summary line reads "Existing source regions: N · Candidate creates: N ·
+   Candidate refinements: N" and is marked as not the final region set.
+
+## 13. Informational and asset-sensitive intent
+
+1. "Mark informational" gives `candidate { kind: 'inspect' }`.
+2. "Mark asset-sensitive" gives `{ kind: 'asset-sensitive' }`.
+3. "Mark asset-sensitive for region <id>" requires an explicitly selected
+   region and gives `{ kind: 'asset-sensitive', regionId }`.
+4. None of these create a requirement, a PASS/FAIL result, or a contract
+   clause.
+
+## 14. Candidate reference requirements
+
+1. Categories are exactly `requested`, `expected-dependent`, `protected`, and
+   `preserved`. `expected-dependent` requires `required` or `permitted`. For
+   other categories the mode is absent, even if one was chosen earlier.
+2. Subjects:
+   1. `region-property` takes an existing or draft-proposed region and one of
+      the 8 canonical properties. A tolerance is required.
+   2. `region-relationship` takes only a canonical server relationship,
+      selected by index. No tolerance is allowed. Candidate-created regions
+      never appear, because they have no derived relationships.
+   3. `region-measurement` takes two distinct known regions and one of the 6
+      canonical measurements. A tolerance is required. No measured value is
+      ever computed or stored.
+3. Tolerance kinds are `exact`, `absolute-reference-px` (labeled
+   "reference-image pixels"), and `percent`. Amounts must be finite and
+   between 0 and 100.
+4. "Set candidate requirement" is disabled with a visible reason until the
+   form is complete. It sets
+   `candidate { kind: 'reference-requirement', requirement }` with the
+   canonical `RawReferenceRequirement` shape.
+5. The panel lists "Candidate annotation region proposals" and "Candidate
+   annotation requirements" separately from the source regions and
+   requirements shown by the unchanged reference inspector.
+
+## 15. Confirmation workflow
+
+1. "Confirm reference intent" is enabled only for a candidate. It sets
+   `{ state: 'confirmed', intent, confirmedAt: new Date().toISOString() }`.
+2. Saving never confirms. Browser-verified: a candidate stays a candidate
+   after save.
+3. The selected item always shows its interpretation state as text and the
+   exact intent structure as JSON before and after confirmation.
+4. Confirmation was proven in the browser for all four families:
+   `reference-region`, `reference-requirement`, `inspect`, and
+   `asset-sensitive`.
+
+## 16. Confirmation invalidation
+
+1. Every reference draft edit passes through `applyReferenceItemEdit`. A
+   rectangle's region intent is first synchronized to the rectangle geometry.
+2. If the item was confirmed and its meaning changed, it becomes a candidate
+   without `confirmedAt`. Meaning covers the mark, the association, and the
+   intent.
+3. Setting a new intent (region id or mode, requirement fields, tolerance,
+   asset region) always produces a candidate.
+4. Browser-verified:
+   1. Moving a confirmed candidate region synchronizes its rectangle, drops it
+      to candidate, and a later reconfirmation gets a new `confirmedAt`.
+   2. Changing a confirmed requirement's tolerance requires reconfirmation.
+   3. Changing a confirmed item's association requires reconfirmation.
+5. Unit-verified: note text edits and asset-region changes also invalidate,
+   and a no-op edit keeps confirmation.
+
+## 17. Save/reload/revision
+
+1. Saving uses the unchanged Prompt 2 `POST /api/annotations`. On 201 the
+   canonical view is reloaded, the draft is replaced, the parent is set,
+   dirty is cleared, and the saved list is refreshed.
+2. Failures use the shared bounded messages, keep the draft, and are never
+   retried.
+3. Browser-verified reload: an approved-reference annotation containing a
+   plain mark, a region candidate, a confirmed requirement, and an
+   asset-sensitive candidate comes back with the same annotation id, item ids,
+   marks, and interpretations. The view equals the persisted artifact, and
+   the source handle is exactly the approved reference with media role
+   `source-image`.
+4. Browser-verified revision: B supersedes A, item ids are kept, A's manifest
+   bytes are unchanged, and B has a fresh id.
+5. After a reload the token is re-acquired and no draft is recovered.
+
+## 18. Source immutability
+
+1. Browser tests snapshot every file in the imported and approved reference
+   directories, meaning the manifests and the image.
+2. The snapshots are compared after drawing, candidate create, candidate
+   refine, requirement authoring, confirmation, save, and revision. They were
+   byte-identical in each test.
+3. Reference-family artifact count is unchanged, no manifest contains
+   `supersedesReferenceId`, and only visual-annotation artifacts are added.
+4. No import, approval, materialization, or reference-write call exists in
+   the viewer.
+
+## 19. Binding/view-lock regression
+
+1. View lock (browser):
+   1. With a compatible candidate locked, zooming the reference pane still
+      moves the candidate view.
+   2. Drawing on the reference then leaves the candidate viewBox unchanged and
+      puts no annotation marks in the candidate pane.
+   3. The bound `header → header` binding row is unchanged.
+   4. The persisted rectangle is in reference pixels with no association.
+2. Equal names (browser): the reference region `header` and the runtime
+   target `header`, with no declaration, never cross-highlight. The explicit
+   association is `reference-region header`, and no `runtime-target` appears
+   anywhere in the artifact.
+3. Explicit binding cross-highlight (browser): reference `header` highlights
+   the candidate `header`, and candidate `sidebar` highlights reference
+   `sidebar`. Associating an annotation with `header` leaves both highlights
+   unchanged, and the association persists separately.
+4. The existing `referenceCandidateWorkspace`, `referenceBindingFidelityWorkspace`,
+   and `referenceCorrectionWorkflow` browser suites pass unchanged.
+
+## 20. Browser tests
+
+New `tests/browser/referenceAnnotationAuthoring.test.ts` has 19 real-Chromium
+tests, using the existing reference fixtures and the Prompt 2/3
+`TestResources`/`readManifest` helpers.
+
+1. Availability: the project-aware toolbar and Save are present. The
+   standalone viewer is read-only, region selection still works, and no
+   non-GET request is sent.
+2. Imported reference: rectangle plus note, exact coordinates, imported source
+   identity, and dimensions.
+3. Approved reference: all five mark kinds, approved identity, and the
+   imported image owner.
+4. Zoom and pan coordinates, with pan and draw exclusive.
+5. View lock regression.
+6. No equal-name binding, plus explicit region association (keyboard region
+   selection).
+7. Explicit relationship association.
+8. Binding cross-highlight separate from association.
+9. Region create candidate: duplicate id refused, preview, confirm, move
+   invalidates and syncs geometry, reconfirm, source byte-identical.
+10. Region refine candidate: original and candidate preview, source region
+    unchanged, association set, source byte-identical.
+11. Informational and asset-sensitive intent (with and without a region), plus
+    confirmation.
+12. Region-property requirement (protected, `header` width,
+    absolute-reference-px 4), confirmed, source requirements unchanged.
+13. Expected-dependent mode required, and omitted for other categories.
+14. Region-relationship requirement from a canonical relationship, no
+    tolerance, and no candidate-region relationship offered.
+15. Region-measurement requirement (vertical-gap, percent), with an
+    out-of-range amount refused, and invalidation on tolerance and
+    association change.
+16. No auto requirement from drawn geometry, and save never confirms.
+17. Save and reload.
+18. Revision, no materialization, source byte-identical.
+19. Keyboard selection of marks and regions, and keyboard-operated intent and
+    confirm controls.
+
+Test-harness notes:
+
+1. The reference SVG is inside scrolling containers. Gestures first scroll the
+   SVG into view and then compute both client points from the SVG CTM. This
+   is how the flex-shrink overlap was found.
+2. No test performs an out-of-band canonical write while the page refreshes
+   evidence.
+3. The file passed on repeated runs.
+
+## 21. Unit tests
+
+New `tests/unit/viewerReferenceAnnotationModel.test.ts` (18 tests) covers:
+
+1. Create and refine construction, including rejection for non-rectangles.
+2. Case-insensitive and pattern id blocking, the region maximum, and an item
+   re-creating its own id.
+3. Geometry synchronization.
+4. Region summary and requirement region choices.
+5. Confirmation.
+6. Invalidation by move, association, note text, and asset region, and no
+   invalidation on a no-op edit.
+7. Informational and asset-sensitive shapes.
+8. Region-property, relationship, and measurement requirement construction.
+9. Expected-dependent mode rules and tolerance bounds.
+10. Exact-family membership and association labels.
+
+Several built items are also checked against the canonical
+`isValidVisualAnnotationContent`, which proves the viewer's structures are
+accepted by the domain validator.
+
+## 22. Regression validation
+
+Every command below was run on Windows in the repository root.
+
+1. `npm run typecheck`: PASS
+2. `npm run lint`: PASS
+3. `npm test`: PASS (78 files, 1316 tests)
+4. `npm run build`: PASS
+5. `npm run test:browser`: PASS (23 files, 221 tests, real Chromium). This
+   includes `runtimeAnnotationAuthoring`, `referenceCandidateWorkspace`,
+   `referenceBindingFidelityWorkspace`, `referenceCorrectionWorkflow`,
+   `pwaHardening`, and `observationSvgWorkspace`.
+6. `npm run test:security`: PASS (unit: 13 files, 143 tests. Browser: 3 files,
+   77 tests)
+7. `npm run check:docs`: PASS
+8. `npm pack --dry-run`: PASS (345 files, 900.7 kB)
+
+## 23. Security regression
+
+1. No server, domain, artifact, or application file changed.
+2. Host, Origin, token, body-size, path, symlink, method, and PWA no-cache
+   tests pass.
+3. The reference UI keeps the token in React memory only.
+4. A source search of the new reference viewer files found no storage API,
+   `console` call, `dangerouslySetInnerHTML`, or reference import, approval,
+   or materialization call.
+
+## 24. Known deferred writer/discovery race
+
+This risk is carried forward unchanged from Prompt 3. It is not fixed and
+Prompt 4 does not own it.
+
+1. On Windows, the canonical artifact writers' atomic directory rename can
+   fail with `EPERM` if viewer evidence discovery is reading inside the
+   writer's `.tmp-<id>` directory at that moment.
+2. It needs a concurrent evidence refresh during a save.
+3. `src/artifacts/*` and `src/viewerServer/evidence/discovery.ts` were not
+   modified.
+4. Prompt 4 tests perform no out-of-band canonical write while the page
+   refreshes evidence.
+
+## 25. Scope audit
+
+1. server authoring API changed: false
+2. annotation artifact schema changed: false
+3. external-reference artifact schema changed: false
+4. source reference mutated: false
+5. reference materialization implemented: false
+6. reference approval implemented: false
+7. runtime contract promotion implemented: false
+8. runtime intent confirmation implemented: false
+9. ContractPrimitive vocabulary changed: false
+10. project config schema changed: false
+11. alias catalog schema changed: false
+12. package version changed: false
+13. dependency changed: false
+
+Runtime annotation semantics are unchanged: new runtime items stay
+`uninterpreted`, and the runtime panel has no intent or confirmation
+controls.
+
+## 26. Changed files
+
+### 26.1 Added
+
+1. `viewer/src/annotation/referenceIntent.ts`
+2. `viewer/src/components/ReferenceAnnotationPanel.tsx`
+3. `viewer/src/components/CandidateRegionPreviewLayer.tsx` (display-only
+   candidate region preview inside the reference SVG)
+4. `viewer/src/components/AnnotationPanelSections.tsx` (shared panel
+   sections extracted from the runtime panel)
+5. `viewer/src/hooks/useReferenceAnnotations.ts`
+6. `viewer/src/hooks/useReferenceAnnotationDraft.ts`
+7. `tests/browser/referenceAnnotationAuthoring.test.ts`
+8. `tests/unit/viewerReferenceAnnotationModel.test.ts`
+9. `docs/reports/v0.9-batch4-external-reference-annotation-authoring.md`
+
+### 26.2 Modified
+
+1. `viewer/src/components/ReferenceWorkspace.tsx`
+2. `viewer/src/components/ReferenceRegionOverlaySvg.tsx`
+3. `viewer/src/components/AnnotationToolbar.tsx` (optional zoom controls)
+4. `viewer/src/components/RuntimeAnnotationPanel.tsx` (uses the shared
+   sections, with identical markup)
+5. `viewer/src/hooks/useRuntimeAnnotationDraft.ts` (generic
+   `useAnnotationDraft`)
+6. `viewer/src/hooks/useRuntimeAnnotations.ts` (generic
+   `useSourceAnnotations`)
+7. `viewer/src/styles/index.css`
+8. `viewer/src/types/reference.ts` (type-only `RawReferenceRequirement`
+   re-export)
+
+### 26.3 Generated paths
+
+1. `dist/` was rebuilt. It is ignored.
+2. Tests create and remove temporary directories under the OS temp directory.
+3. Validation logs went to the session scratchpad.
+
+## 27. Remaining next step
+
+v0.9 Prompt 5 — Intent interpretation, confirmation, and canonical change-contract promotion