@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-batch3-runtime-screenshot-annotation-authoring.md

@@ -0,0 +1,412 @@
+# v0.9 Batch 3 Report: Runtime Screenshot Annotation Authoring
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH3_RUNTIME_SCREENSHOT_ANNOTATION_AUTHORING
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Starting HEAD: `3776c356d1c7c8848c633d0a3c0fab46501b9a04`
+4. Ending HEAD before the final commit: `3776c356d1c7c8848c633d0a3c0fab46501b9a04`
+5. Package version: `0.8.1` (unchanged in `package.json` and `package-lock.json`)
+
+## 3. Prompt 2 entry gate
+
+1. Prompt 2 verdict: `PASS_V0_9_BATCH2_VIEWER_ANNOTATION_AUTHORING_BOUNDARY`
+2. Prompt 2 commit: `3776c356d1c7c8848c633d0a3c0fab46501b9a04`
+3. Viewer protocol: `1.1.0`
+4. Annotation save route: `POST /api/annotations`
+5. Project-aware authoring: enabled
+6. Standalone viewer: read-only
+7. Preflight found a clean tracked worktree on `master` at the required HEAD.
+8. `git ls-files -v docs/reports/v0.9-architecture-retrieval.md` printed `S`
+   at entry and again before commit. The `skip-worktree` state was preserved.
+   The file was not restored, overwritten, or committed. No pull, rebase,
+   reset, or clean was run.
+9. No Prompt 2 API defect was found. The UI uses the Prompt 2 API unchanged.
+
+## 4. Authoring-session consumption
+
+1. `viewer/src/hooks/useAuthoringSession.ts` fetches
+   `GET /api/authoring/session` with `cache: 'no-store'` when the observation
+   workspace mounts.
+2. States: `loading`, `read-only`, `available` (with the token), and `error`.
+3. The token lives only in React state. It is never written to localStorage,
+   sessionStorage, IndexedDB, a URL, a log, a service-worker message, or the
+   visible UI. The only place it leaves memory is the save request header.
+   A source search of the new viewer files found no storage APIs and no
+   `console` calls.
+4. A read-only viewer is a normal state:
+   1. The toolbar shows only Select and Pan plus a "Read-only viewer" notice.
+   2. The panel can still list and display saved annotations for inspection.
+   3. No drawing, editing, or save controls are shown.
+
+## 5. Runtime annotation discovery
+
+`viewer/src/hooks/useRuntimeAnnotations.ts` uses only existing APIs.
+
+1. `GET /api/index` gives the candidates: `family === 'visual-annotation'`,
+   `supportState === 'supported'`, and
+   `relatedIds.sourceObservationId === observationId`. At most 100 candidates
+   are checked, and truncation is reported.
+2. `GET /api/annotations/:handle/view` confirms each candidate. The pure
+   helper `annotationViewBelongsToObservation` requires `source.status`
+   `available`, `source.family` `observation`, and `source.handle` equal to
+   the selected observation handle.
+3. Aliases, relative directories, and labels are never used to join an
+   annotation to an observation.
+
+The panel's saved list shows, for each annotation:
+
+1. `annotationId`
+2. item count
+3. confirmed item count
+4. whether it is a revision
+
+No paths are shown. Selecting a saved annotation copies its items into the
+in-memory draft. It sets that annotation as the parent handle and keeps every
+`annotationItemId`. The persisted artifact is never mutated.
+
+## 6. Shared SVG source-coordinate transform
+
+1. New `viewer/src/svg/sourceCoordinates.ts` provides
+   `screenPointToSvgSource(svg, clientX, clientY)`. It uses
+   `getScreenCTM()`, `createSVGPoint()`, `ctm.inverse()`, and
+   `matrixTransform()`.
+2. `viewer/src/hooks/useZoomPan.ts` now calls this helper. Its private
+   duplicate was removed.
+3. Annotation drawing and moving (`useAnnotationPointerInteraction.ts`) call
+   the same helper.
+4. A search of `viewer/src` finds exactly one `getScreenCTM()` or
+   `matrixTransform` implementation. No bounding-rectangle ratios,
+   devicePixelRatio, CSS ratios, or manual aspect-ratio math are used.
+5. The source frame is `artifact.requestConfig.viewport` (runtime CSS pixels).
+   Coordinates are never rounded, clamped, or scaled. A pointer position
+   outside `0..width` by `0..height` is ignored. A gesture keeps its last
+   valid in-frame position.
+
+## 7. Interaction modes
+
+1. `AnnotationInteractionMode` is the closed set `select`, `pan`, `point`,
+   `rectangle`, `line`, `arrow`, `note`. It is defined in the new pure module
+   `viewer/src/annotation/annotationGeometry.ts`.
+2. `useAnnotationPointerInteraction` attaches exactly one handler set to the
+   SVG at a time:
+   1. `pan`: the existing `useZoomPan` pointer handlers only. Target and mark
+      pointer input is disabled.
+   2. Drawing modes: drawing handlers only. Target rectangles get
+      `pointer-events: none`, and marks are not selectable, so drawing over a
+      target never selects it and never moves marks.
+   3. `select`: target selection, mark selection, and mark drag-to-move. The
+      background neither pans nor draws.
+3. A drag therefore can never mean both pan and draw.
+
+## 8. Annotation layer
+
+1. New `viewer/src/components/AnnotationLayer.tsx` renders one `<g>` inside the
+   existing `TargetOverlaySvg`. It comes after the screenshot, relationships,
+   and targets, so annotations render on top. There is no second SVG, no
+   canvas, and no positioned DOM layer.
+2. It receives only items, the selected item id, a selectable flag, callbacks,
+   and an optional preview mark. It knows nothing about artifacts, paths,
+   tokens, the API, or aliases, so Prompt 4 can reuse it.
+3. It renders the five mark kinds with fixed classes. Note text is plain React
+   text: no `dangerouslySetInnerHTML` and no authored SVG.
+4. Each mark has `data-annotation-item-id`, `data-annotation-kind`, and a
+   bounded `aria-label`.
+5. `TargetOverlaySvg` gains three optional props: `annotationLayer`,
+   `targetsInteractive` (default `true`), and `interactionClassName`.
+   Screenshot, targets, labels, relationship connectors, target selection, and
+   viewBox behavior are otherwise unchanged. Comparison and reference
+   workspaces pass none of the new props.
+
+## 9. Draft lifecycle
+
+`viewer/src/hooks/useRuntimeAnnotationDraft.ts` owns the draft.
+
+1. New annotation: no items, no parent, nothing selected, not dirty.
+2. Drawing:
+   1. Point and note are created on pointer release at the pointer-down
+      source point.
+   2. Rectangle, line, and arrow show a dashed preview while dragging and are
+      created on release.
+   3. Rectangles are direction-normalized. A zero-width or zero-height
+      rectangle is not created.
+   4. Local choice: a zero-length line or arrow is not created either.
+   5. A note is created only when the toolbar note text is 1 to 2000
+      characters.
+3. New item: `annotation-item-${crypto.randomUUID()}`, no association,
+   `interpretation: { state: 'uninterpreted' }`. It is selected on creation
+   and marks the draft dirty.
+4. Move (select mode): drag a mark past a 3-pixel threshold. It translates
+   rigidly by the source delta through the shared transform. A translation
+   that would leave the frame is not applied. The id, association, and
+   interpretation are unchanged. There are no resize handles.
+5. Note edit: a controlled textarea for the selected note changes only
+   `mark.text`, bounded at 2000 characters. Saving is disabled while any note
+   is empty.
+6. Delete draft item removes the item from memory only. No HTTP DELETE is
+   sent.
+7. Cancel changes restores the loaded persisted items, or an empty draft for a
+   new annotation. It also clears transient drawing and any save error.
+8. Loaded items keep their persisted interpretation. No interpretation UI
+   exists in this batch.
+
+## 10. Target association
+
+1. Drawing never associates anything.
+2. With a draft item selected and a runtime target selected (from the target
+   list or SVG), the explicit "Associate target <name>" button sets
+   `{ kind: 'runtime-target', target }`.
+3. "Clear association" removes it.
+4. Annotation selection and target selection are separate state.
+5. The display reads "Target association: <name>" or "No association". This
+   wording is deliberately different from the inspector's "Target: <name>".
+
+## 11. Relationship association
+
+1. Options come only from the server graph already fetched from
+   `/api/observations/:handle/relationships`.
+   1. Pairwise options keep `relationshipKind`, `subjectTarget`, and
+      `relatedTarget`.
+   2. Page-level options keep `relationshipKind` only.
+2. The user must choose an option and press "Associate relationship". Lines
+   and arrows never imply a relationship.
+3. The display reads "Relationship association: <kind> (<subject> →
+   <related>)".
+
+## 12. Zoom/pan behavior
+
+1. The observation workspace now uses
+   `useZoomPan(viewport.width, viewport.height)` with the existing
+   `ZoomControls`: Zoom in, Zoom out, Fit, and Reset. Reset equals Fit.
+2. Bounds are unchanged (`ZOOM_MIN = 1`, `ZOOM_MAX = 8`, `ZOOM_STEP = 1.25`).
+3. Zoom and pan change only the SVG viewBox. Target and annotation geometry
+   and the screenshot frame are unchanged. Zoom state is never persisted.
+
+## 13. Save/reload behavior
+
+1. Save runs only when the session is `available`. It POSTs
+   `{ sourceHandle, parentAnnotationHandle?, items }` with `content-type` and
+   the token header. The browser supplies Origin.
+2. On 201, the UI:
+   1. Reads the returned handle.
+   2. Re-reads the canonical view.
+   3. Replaces the draft items with the persisted items.
+   4. Sets the parent to the new handle.
+   5. Clears dirty.
+   6. Shows "Saved annotation <id>".
+   7. Refreshes the saved list.
+3. On failure (403, 404, 409, 413, 422, 500, or network), the UI shows a
+   concise message, keeps the draft, and does not retry. It never falls back
+   to a new root annotation.
+4. After a browser reload the token is re-acquired and the saved list rebuilt.
+   No draft is recovered, because none is stored in the browser.
+
+## 14. Revision behavior
+
+1. After a save, or after selecting a saved annotation, further edits save as
+   a child. The new artifact has a fresh `annotationId` and
+   `supersedesAnnotationId` pointing to the parent. It then becomes the loaded
+   parent.
+2. The parent's manifest bytes are unchanged (browser-verified).
+3. A stale parent gets 409. The UI shows "Save conflict", keeps the draft,
+   sends no second POST, and writes nothing.
+
+## 15. Alias identity behavior
+
+The browser test:
+
+1. Aliases `current` to observation A.
+2. Saves annotation X on A.
+3. Moves `current` to observation B with the canonical `writeAliasCatalog`.
+4. Restarts the viewer from `loadProjectViewerState`.
+
+Result: B (shown as `current`) lists no saved annotations. A, selected by its
+canonical id, still lists X, and X's persisted source still names A.
+
+## 16. Source-unavailable behavior
+
+With a draft mark present, the test moves the source observation directory
+away before Save. The POST returns 404 and the UI shows "…no longer exists".
+The draft and its rendered mark remain, no success message appears, and no
+artifact is written. The directory is restored afterwards.
+
+## 17. Accessibility
+
+1. Toolbar mode buttons are native buttons with "<Mode> mode" labels and
+   `aria-pressed`.
+2. The note input and the selected-note textarea have labels.
+3. In select mode, marks are `role="button"`, `tabIndex=0`, `aria-pressed`,
+   with bounded labels such as "Rectangle annotation" or "Note annotation:
+   <up to 60 chars>".
+4. Enter and Space select a mark, mirroring target selection.
+5. Save status uses `role="status"`, and failures use `role="alert"`.
+6. Browser-verified: Tab from the last target reaches the first mark, and
+   Enter or Space selects it. Target keyboard selection still works and does
+   not clear the annotation selection.
+
+## 18. Browser tests
+
+New `tests/browser/runtimeAnnotationAuthoring.test.ts` (15 real-Chromium
+tests). It reuses the Prompt 2 fixtures in `tests/support/annotationAuthoringFixtures.ts`.
+
+1. Availability: the project-aware toolbar has all seven modes and Save. The
+   standalone viewer has no drawing or save controls, target inspection still
+   works, and no non-GET request is sent.
+2. All five mark kinds are drawn with real pointer input. The persisted kinds,
+   coordinates, `uninterpreted` state, id format, and canonical source are
+   checked. A note without text is not created.
+3. Exact rectangle: a reverse drag from 250,220 to 100,120 persists 100, 120,
+   150, 100. A zero-area drag creates nothing.
+4. Zoomed drawing: after three zoom-ins, a rectangle keeps its source
+   coordinates. Fit restores `0 0 800 600`, and target geometry is unchanged.
+5. Panned drawing and exclusivity: a pan drag changes the viewBox and creates
+   no item. A rectangle drag creates an item, leaves the viewBox unchanged,
+   and persists the intended source coordinates.
+6. DPR: at `deviceScaleFactor: 2` (confirmed `devicePixelRatio === 2`), the
+   rectangle and point persist CSS-pixel source values, not doubled ones.
+7. Explicit target association: a rectangle drawn inside `header` stays
+   unassociated and does not select the target, until "Associate target
+   header". The persisted association is exact.
+8. Explicit relationship association: the relationship is taken from the
+   server graph, the arrow stays unassociated until chosen, and the persisted
+   `relationshipKind`, `subjectTarget`, and `relatedTarget` are exact.
+9. Draft editing:
+   1. Move keeps the id at +40,+30.
+   2. Note edit keeps the anchor and id.
+   3. Save keeps item ids.
+   4. Delete, then Cancel, restores the persisted items.
+   5. Cancel on a new draft empties it.
+   6. No DELETE request is sent.
+10. Keyboard selection of marks and targets.
+11. Save and reload: the same annotation id, item ids, rectangle geometry,
+    association, and source handle come back from canonical evidence.
+12. Revision: a child supersedes the parent, the parent bytes are unchanged,
+    item ids are preserved, and the child becomes the loaded parent.
+13. Stale revision: 409, conflict alert, draft kept, exactly one failed POST,
+    and nothing written.
+14. Alias replacement does not rebind (section 15).
+15. Source disappearance gives a visible failure with the draft kept
+    (section 16).
+
+Unit tests: new `tests/unit/viewerAnnotationDraftModel.test.ts` (12 tests) covers:
+
+1. Mode set
+2. Frame validity
+3. Drawn-mark normalization and refusal
+4. New-item shape
+5. Translation
+6. The shared transform (fake CTM)
+7. Exact-handle membership
+8. Failure messages
+9. Mark and association labels
+
+Stabilization notes (test-only):
+
+1. The stale-revision test waits for the post-save saved-list refresh to
+   finish before persisting a child from outside the page. Otherwise the
+   test's out-of-band writer raced the viewer's own evidence discovery on
+   Windows (see section 21).
+2. The alias test leaves the page before closing the first viewer server, so
+   in-flight requests do not hold its connections open during `close()`.
+3. After these changes the file passed on repeated runs.
+
+## 19. 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 (77 files, 1298 tests)
+4. `npm run build`: PASS
+5. `npm run test:browser`: PASS (22 files, 202 tests, real Chromium)
+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 (344 files, 888.8 kB)
+
+`tests/browser/observationSvgWorkspace.test.ts` passes unchanged. It covers
+canonical target geometry, unresolved-target honesty, list and SVG selection,
+inspector, and relationships. `projectWorkflowViewer`, `pwaHardening`,
+comparison, reference, binding, fidelity, and context browser suites all
+pass.
+
+## 20. Security regression
+
+1. No server file changed. Host, Origin, token, body-size, path, symlink,
+   method, and PWA no-cache tests all pass in `test:security`.
+2. The viewer sends the token only in the `x-frontend-observer-authoring-token`
+   header of same-origin POSTs and stores it nowhere.
+3. The service-worker configuration is unchanged.
+
+## 21. Scope audit
+
+1. external-reference annotation UI changed: false
+2. contract promotion implemented: false
+3. reference materialization implemented: false
+4. ContractPrimitive vocabulary changed: false
+5. annotation artifact schema changed: false
+6. Prompt 2 security policy weakened: false
+7. project config schema changed: false
+8. alias catalog schema changed: false
+9. package version changed: false
+10. dependency changed: false
+
+No file under `src/` changed. `ReferenceWorkspace` and
+`ReferenceRegionOverlaySvg` are untouched. No intent, category, confirmation,
+or contract-primitive UI exists.
+
+Remaining risk (pre-existing, not introduced here, protected files not
+modified):
+
+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. That happens when a
+   separate process or tab refreshes `/api/index` exactly during a save.
+2. Normal single-page use does not trigger it, because the UI refreshes only
+   after a 201.
+3. A future batch that owns the writer or discovery could skip `.tmp-*`
+   directories during discovery.
+
+## 22. Changed files
+
+### 22.1 Added
+
+1. `viewer/src/types/visualAnnotation.ts`
+2. `viewer/src/svg/sourceCoordinates.ts`
+3. `viewer/src/annotation/annotationGeometry.ts` (pure draft geometry and
+   mode model, split out so unit tests can reach it)
+4. `viewer/src/components/AnnotationLayer.tsx`
+5. `viewer/src/components/AnnotationToolbar.tsx`
+6. `viewer/src/components/RuntimeAnnotationPanel.tsx`
+7. `viewer/src/hooks/useAuthoringSession.ts`
+8. `viewer/src/hooks/useRuntimeAnnotations.ts`
+9. `viewer/src/hooks/useRuntimeAnnotationDraft.ts`
+10. `viewer/src/hooks/useAnnotationPointerInteraction.ts` (frame-agnostic
+    exclusive pointer binding, reusable by Prompt 4)
+11. `tests/browser/runtimeAnnotationAuthoring.test.ts`
+12. `tests/unit/viewerAnnotationDraftModel.test.ts`
+13. `docs/reports/v0.9-batch3-runtime-screenshot-annotation-authoring.md`
+
+### 22.2 Modified
+
+1. `viewer/src/components/ObservationWorkspace.tsx`
+2. `viewer/src/components/TargetOverlaySvg.tsx`
+3. `viewer/src/hooks/useZoomPan.ts`
+4. `viewer/src/styles/index.css`
+5. `tests/support/evidenceFixtures.ts`: `writeRichObservationFixture` gains an
+   optional `requestId`, because alias catalogs require 64-hex request ids.
+   Existing callers are unaffected.
+
+### 22.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.
+
+## 23. Remaining next step
+
+v0.9 Prompt 4 — External-reference annotation and reference-region authoring