feat(annotator): interactive suggest tool with ephemeral preview (#424 slice 3b)

[JArmandoAnaya]

The user-facing half of click-to-suggest (#424, slice 3b), on top of the route and
adapter slice 3a landed in #448. Click the thing you want, get a shape, refine it,
accept it — or find out in the editor why you cannot.

No server changes. The route, the wire models, openapi.json and the generated
client are all exactly as #448 left them, which is why the generated gate reports
no drift.

What ships

The engine (@visionset/annotator)

core/interaction/suggestion.ts is the session as a pure state machine beside the
pointer's, not a variant inside it. InteractionState is what the pointer is in
the middle of and machine.ts types its table as total over that union — every
state owes a row and every row answers a pointer event synchronously. A suggestion
outlives the press that asked for it, is resolved by a server rather than by a
pointer-up, and survives pointer-cancel, blur and a hundred pointer-moves. A row
there would have had to answer eight events it has no opinion about, and the one
event it does care about is not a pointer event at all.

D4's ephemerality is structural rather than a rule. The module produces no
Effect, holds no store and mints no id, so there is no mechanism by which a
preview could reach AnnotatorStore. acceptedAnnotation is the single door into
the document, and it builds on draftAnnotation so a suggestion inherits the
class's attribute defaults, the asset and the provisional schema_version exactly
as a hand-drawn shape does — overriding only provenance, model_ref and
confidence. draftAnnotation's own provenance: "human" is untouched and its
docstring stays true: acceptance is the human act the provenance records.

Refine clicks send the accumulated points every time, never a diff, because the
route is stateless. Each ask stamps a serial and a late answer is dropped whole
(returned by identity), so a slow first answer cannot overwrite a fast second one —
the failure mode a click-to-refine gesture has by construction.

s joins DEFAULT_BINDINGS as a host row. enter and escape stay exactly what
they were: accepting and discarding are adapter substitutions over those two
rows, the same mechanism #383 introduced for the flow verb, so every cancel row in
machine.ts reads as written and a second enter binding cannot shadow the ring
close. The text-entry guard now reads the resolved action rather than the
substituted one, so Escape still blurs a field whatever it was substituted into.

The adapter

An armed session is the second occupant of a contract that already existed.
state.ts states it for panning: "while panning or pinching, the adapter does not
forward pointer events to the machine; if a gesture was in flight when the pan
began, it sends pointer-cancel first." Arming does exactly that, and afterwards a
primary press becomes a prompt point instead of a pointer-down. That is what stops
a click meant for the model from drawing a box.

Suggest is deliberately not a Tool. tool.ts derives the tool from the active
class and stores nothing, and it is emphatic about why (v1 held both and spent two
mechanisms keeping them from disagreeing). There is no class that means "ask a
model", so a fifth variant would be a stored mode wearing a derived one's name with
nothing for toolFor to derive it from. It is a mode held beside the class it
borrows.

paint.ts decides the treatment and TransientLayer draws it: reduced opacity plus
a dashed outline, never colour alone — the shape draws in its class's own
colour, so hue cannot be what distinguishes it. The class and the model's confidence
render with it, and the prompt points stay on screen through an in-flight ask so a
refine click does not look dropped.

The product (@visionset/ui-core)

• inferenceQueries.ts — the connection list, fetched only once the tool is
  armed (a job nobody suggests on makes no inference request at all), and the
  suggest call itself. usableConnection answers with a connection or with one of
  three blockers, checking among them, so a click landing in the loading window is
  told something rather than vanishing.
• SuggestPanel.tsx — D6's in-editor panel, and the tool's one voice for all five
  things it can be saying. Not a toast, not a redirect, not a modal: principle 10 is
  immovable and no exit may lose work. A server refusal is quoted verbatim,
  because LOCAL_INFERENCE_UNAVAILABLE is expose_message=True precisely so the
  install command reaches a person and a sentence written in the client would throw
  it away.
• ToolPalette gains the sparkles button, hidden rather than disabled on a
  schema no class of which can hold the answer (D3's third case) — the same rule
  that keeps a classification_tag off the strip. A disabled control has to be
  explicable in principle 9's terms, and "no class in this project could accept the
  answer" is a fact about the schema, not a capability that is coming.
• AnnotationPage holds the session in Workspace rather than in JobScreen,
  which is the opposite call from activeClass and clipboard — and the
  difference is what those two exist for. They sit one level up so they survive the
  per-asset remount; a suggestion must not, and D2's "switching assets discards" is
  therefore enforced by key={asset.id} rather than by an effect somebody has to
  remember. Switching tools is one effect on activeClass, which every door — the
  strip, the panel list, a digit hotkey — already ends at.

Which D-positions ship here

	Where
D2 the gesture	ships in full: sparkles tool, S, left-click positive, alt-click negative, ↵ accepts, Esc discards, tool/asset switch discards
D3 geometry follows the schema	ships: the class's own kinds go up as allowed_geometries, and the tool is not offered where neither is holdable
D4 ephemeral preview, acceptance enters history	ships in full, including the annotated entry ratified 2026-08-07
D6 the no-connection panel	ships; its action destination is an optional callback and the app leaves it unwired, per the dispatch
D1 SAM 2 serving	shipped in #448 (slice 3a)
D5 server-side inference through the connection	shipped in #448 (slice 3a)

alt-click is the negative point and right-click is not. D2 offers both; a
secondary press on this canvas is a pan, and #380's contextmenu note sets out what
taking it back would cost. Alt is the spelling that costs no existing gesture.

Mutation verification

Four mutations, each applied to the committed tree, each asserted present before and
after, each reverted by git apply -R on its recorded patch with a clean tree
confirmed afterwards.

Mutation	Tests that turned red
the preview enters the undo stack — onSuccess executes the annotation as soon as the answer lands	5, led by suggestFlow.test.tsx › leaves undo untouched while a suggestion is only showing
acceptance drops the three overrides — acceptedAnnotation returns draftAnnotation's output	3, led by suggestFlow.test.tsx › writes it through the ordinary create path, carrying where it came from
the D6 panel renders its action without a destination	2: renders the explanation and no control when the host wires no destination
the press is no longer diverted from the interaction machine	1: does not draw a shape — the press never reaches the interaction machine

The two the dispatch asked to be named are the first two rows.

Test plan

Boundary gates first, because the design was checked against them rather than the
other way round: pnpm --filter @visionset/annotator lint runs all three (ESLint
no-restricted-imports, no-restricted-globals, and the DOM-free
tsconfig.core.json pass) and all three are green. Nothing in src/core/ gained a
React import, a DOM global or a DOM type in a signature.

• core/interaction/suggestion.test.ts — 27 tests: which classes the tool is
  offered for, the preview lifecycle, staleness by serial, Escape as the preview's
  undo, acceptance, and a whole click→answer→refine→answer session driven against a
  real AnnotatorStore proving document is unchanged by reference and
  canUndo never moved.
• suggestFlow.test.tsx — 16 tests through AnnotationPage with a stubbed route
  table, so what is asserted is the request that actually leaves.
• suggestPanel.test.tsx — 16 tests: the three blocked readings, the
  callback-absent rule, and the five session readings.
• toolPalette.test.tsx — 6 new: offered, hidden on a tag-only schema, lit from the
  mode rather than the derived tool, and the focus rule.
• bindings.test.ts — s and mod+s are different chords and neither shadows the
  other.
• paint.test.ts — 7 new: two distinguishing signals, the confidence label at both
  ends, and null for every status but shown.

Gate

bash scripts/check.sh run in stages — the harness kills a command at ~10
minutes and the full run is well past that — with pytest split by the directories
ls tests/ reported at run time. Every exit code verbatim, from the run after
the rebase described below.

Stage	Exit
pytest tests/architecture	0
pytest tests/cli	0
pytest tests/examples	0
pytest tests/formats	0
pytest tests/inference	0
pytest tests/jobs	0
pytest tests/kernel	0
pytest tests/mcp	0
pytest tests/packaging	0
pytest tests/server	0
pytest tests/test_versioning.py	0
ruff check .	0
ruff format --check .	0
mypy src/visionset	0
lint-imports (4 contracts kept, 0 broken)	0
check.sh frontend (build, tests, lint)	0
check.sh generated (openapi, client, mcp reference, version sync)	0
annotator + app e2e (chromium)	0
browser cycle, real server (chromium)	0

tests/scripts is not a pytest target — it holds the node --test gates, which the
frontend and generated groups run — so it is absent above rather than reported
as exit 5.

Frontend totals: annotator 904 passed (34 files), ui-core 780 passed (44 files).
E2e: 230 passed, 1 flaky. The flaky one is e2e/gallery.spec.ts › tiles never
overlap, at any density, which passed on retry; this diff touches no gallery code
and no layout, and the same run before the rebase reported 231/231 green.

Rebased onto #449

The gate first ran at base 714d18f, where pytest tests/kernel exited 1 on the
two truncated-clip tests tracked as #444. 8785740 (#449) landed mid-run and fixes
exactly those, so this branch was rebased onto it and the whole gate re-run
rather than the delta — the rule about a rebase bringing in commits you did not
write. tests/kernel is green above on its own merits and no baseline-proof
exception was used or needed.

Information architecture

No route, tab, screen, nav entry or entry point moves, so the sitemap is unchanged.
D6's action is an optional callback and frontend/app deliberately leaves it
unwired: the Inference surface waits on #421's open rail question, and ui-core
renders no dead control when a callback is absent.

Found, not fixed

Nothing.

What remains on #424

• D1's "suggested default" — pre-filling the local-connection form with SAM 2
  and its download size. That form is Inference section — user-configured model connections #421's surface and does not exist yet.
• D6's destination — the panel's action is wired to a callback prop; the app
  passes none until there is an Inference screen to send somebody to.

cf. #424, #417, #418, #421, #425, #448