app: annotation page — annotator embedded, job asset loading, save via API, next/previous navigation, skip marking, progress

[JArmandoAnaya]

Context

The integration moment: M4's engine meets M3's API, on the job contract ("next N pending
assets").

Deliverables

• Page loads a job → fetches next pending assets + blob URLs + schema → feeds the
  annotator by props → persists annotation changes via bulk submit → marks per-asset
  progress (annotated/skipped) → next/previous navigation with prefetch of the next
  asset's image.
• Save strategy: explicit save + save-on-navigate (decide autosave debounce policy,
  document it); unsaved-changes guard.
• Job progress header (n of m, states) live-updated.

Acceptance criteria

• Annotations created in the browser appear via the SDK/API in a test
• Skip flow marks the asset and advances
• Accept marks the asset accepted via the existing progress endpoint and the
  counter updates
• Navigation never loses unsaved work (guard tested)

Design reference (2026-07-30 audit — see the design comment on #51)

The page's composition is fixed by the reference design:

• Top bar, left to right: back to the batch · project name · asset navigator
  (‹ filename n/m › over the job's assets) · grid button jumping to the gallery (ui-core: asset gallery with thumbnails + batch table with states + job partitioning on approval #55) ·
  the reserved versioning controls, rendered disabled in the beta (annotation versioning — the design's "main" dropdown, branch-create, and Merge #127) · Save
  (the page's one primary button) · Accept · the n / m annotated counter · zoom
  − percent + · fullscreen · help.
• Save is the explicit-save button of the existing deliverable; save-on-navigate and
  the unsaved-changes guard stand unchanged.
• Accept is in scope here (pulled forward from exercise the AI-assist substrate — ModelProvider pre-annotation, review loop in the UI, importers #81): a single per-asset action
  calling the existing progress endpoint with accepted — kernel state since kernel: JobService — states pending→in_progress→completed, per-asset progress (unannotated|annotated|skipped|review_pending|accepted), schema version pinned per batch #9, API
  since server: batch/job endpoints — approve, partition, "next N pending assets", annotation submission, progress (the third-party-app contract) #29 — enabled only when the asset's progress table allows the move. The full
  review loop (filter by state, reject, provenance/confidence display) stays exercise the AI-assist substrate — ModelProvider pre-annotation, review loop in the UI, importers #81.
• Zoom controls: the −/+/percent readout and fullscreen drive the adapter's own
  zoom (annotator: React adapter — SVG render, zoom/pan, asset image, annotation layer #47: the zoom is the adapter's; mod+0 is intercepted) — the buttons are a
  second spelling of the same state, never a parallel one.
• Floating tool palette on the canvas's left edge: select, then one tool per
  geometry the schema's classes actually allow (a polygon-only project shows exactly
  select + polygon), help at the bottom. Tool state is the store's — the palette
  dispatches and reflects, it does not own.
• The right-hand Objects/Labels panel is ui-core: annotator side panel — Objects and Labels tabs (object list, visibility, selection sync, class palette) #126, composed by this page.
• The design's free-text label field maps to a schema class selector — classes are
  schema-declared (kernel: SchemaService — monotonic immutable versioning, additive/destructive change classification, LabelClass/Attribute/allowed_geometries validation #6), never free text.

[JArmandoAnaya]

Verified against v1's AnnotationToolHeader/AnnotationToolStrip (2026-07-30 second audit pass): the concrete measurements and states for this page — 44px header row with 32px controls, save-state indicator (~3s "Saved" with the green-check exception), zoom floor 30%, active tool = primary variant, tooltip shortcuts — are now in the repo-root DESIGN.md under "The annotation workspace". Build against that, not the screenshot.