Deliberate multi-object suggestions, with selection before write

[JArmandoAnaya]

Re-scoped 2026-08-16 per the decision recorded in the comments: this issue is now the
deliberate multi-object suggestion capability, with no schedule. The removed fragments
mechanism is history, not a prerequisite to rebuild.

What this is

A way for one gesture to propose several objects deliberately — a row of parked cars, a
scatter of road markings — and for the annotator to choose among the proposals before anything
is written.

This is not the old fragments behaviour. Splitting one point-prompted mask into its
connected pieces was removed by the corrections pass (cf. #557 §E), and the decision below
ratifies that removal as final for point prompts: a click points at one object, and when its
mask arrives in pieces that is nearly always one object seen around an occlusion — one box per
fragment annotates it twice. Whatever produces plural here must produce it on purpose, from
a mechanism that means "several objects" (for example a future prompt kind, or a batch
proposal), never by re-fragmenting a single mask.

What already exists to build on

• The wire is ready. SuggestionOut.regions is a list, and shapes_from
  (src/visionset/inference/masks.py) keeps its list return type naming this issue as the
  reason. No wire change is needed for a plural answer to travel; what is missing is anything
  that produces one.
• The acceptance rules from the original filing still apply once plural exists:
  • a way to say which of the proposed shapes are wanted, on the canvas or on the panel or
    both, before anything is written;
  • one gesture, one undo entry — a partial acceptance carries the chosen subset in one write
    rather than repeating a write per shape;
  • a resting state for the shapes that were not chosen, which is the question that decides
    whether this is a selection or a filter.

Out of scope

• Rebuilding fragments or any per-mask splitting for point prompts — settled by the decision.
• Any schedule. This is a future capability, recorded so its design constraints survive.

History: description as it stood after the 2026-08-16 audit (which itself preserves the original 2026-08-12 filing)

Audited 2026-08-16 at f31653d: description updated to match HEAD. The premise this was
filed on — that a suggestion already comes back plural — is no longer true. The wanted
behaviour survives; its prerequisite has to be rebuilt first, and there is a recorded
argument against part of it.

The premise moved

This issue was filed against a fragments parameter — Every separate piece — that the
post-processing work (cf. #547) shipped. That parameter was removed by the corrections pass
(cf. #557, section E), together with fill_holes, on the grounds that both only did anything to
a mask that was already unusual and so read as controls wired to nothing.

At HEAD:

• SuggestRequest (src/visionset/server/models.py:1962) declares detail and nothing else.
  AppliedParameters carries detail alone.

• shapes_from (src/visionset/inference/masks.py:739-787) returns at most one shape, on
  every path. Its own docstring says so, and names this issue as the reason the return type is
  still a list:

  **A list, though today it holds at most one.** The plural shape is kept
  because accepting part of a plural proposal is tracked work (#548) and
  because an empty list is how "nothing to propose" is already said.
  

• suggestPanel.test.tsx:471-479 pins the removal: suggest-fragments and suggest-fill-holes
  are asserted absent.

So "the preview already renders plural and the parameters already produce plural" is false in
both halves. Nothing in the product can currently propose more than one shape from one click.

What this issue is now

Two pieces of work, in order, and the first is not optional:

1. Produce plural at all. Some mechanism has to put more than one shape on screen from one
   gesture. shapes_from already computes the connected components (pieces) and then discards
   all but one — for a polygon it traces pieces[0], for a box it unions every surviving piece
   into one extent — so the information is present and thrown away, not absent.
2. Choose among them before anything is written, which is what the original body describes
   and what still stands: a way to point at the wanted shapes, a rule that keeps the whole
   acceptance as one undo entry, and a resting state for the ones not chosen.

The counter-argument that has to be answered

#557's section E did not only remove a control; it recorded a reason that bears directly on
item 1:

A prompt points at one object; when its mask arrives in pieces that is nearly always one
object seen around an occlusion. Proposing only the largest piece cuts the object; proposing
one box per piece annotates it twice.

That argument is about a box class and about pieces of one mask. This issue's motivating
cases — a row of parked cars, a scatter of road markings — are the case where the pieces really
are separate objects. Any design here has to say how the two are told apart, or the plural
proposal reintroduces the double-annotation #557 removed.

Original description, as filed 2026-08-12

The suggestion post-processing pipeline (#547) gives the suggest tool a fragments parameter.
Set to keep every connected blob above a minimum area, one click on a mask holding several
islands proposes several shapes at once — a row of parked cars, a scatter of road markings, a
plant whose leaves the segmenter separates.

Acceptance of a plural proposal is all-or-nothing there, and that is a deliberate limit rather
than an oversight: it is one write, one entry in the undo history, and one press of undo takes
back exactly what one press of accept created. Refusing half of what is on screen means keeping
the rest, which needs a selection model the preview does not have.

What is missing is the ordinary case where the proposal is mostly right. Three of five blobs are
the object and two are a reflection of it in a window, and today the only moves are to accept all
five and delete two, or to discard everything and click again with a negative point. The first
writes annotations somebody immediately removes; the second throws away an answer that was
almost entirely correct.

What this needs

• A way to say which of the proposed shapes are wanted, on the canvas or on the panel or both,
  before anything is written.
• A rule for what the undo entry then covers. The all-or-nothing case gets one entry because one
  gesture produced it; a partial acceptance is still one gesture and should still be one entry,
  which means the write has to carry the chosen subset rather than being repeated per shape.
• A resting state for the shapes that were not chosen. Whether declining two of five leaves the
  other three on screen for a second pass, or ends the proposal entirely, is the question that
  decides whether this is a selection or a filter.

None of this touches the pipeline or the parameters, which is why it was separated from them.
The preview already renders plural and the parameters already produce plural; what is absent is
a way to point at one of them.

[JArmandoAnaya]

Decision (Armando, 2026-08-16): The occlusion argument recorded in #557 §E stands for point prompts — a click points at one object, and one box per mask fragment annotates it twice. Plural suggestions are a legitimate future capability (e.g. a row of parked cars) but require a mechanism that produces plural deliberately, not fragments of one mask. The plural return type stays on the wire as-is. This issue is re-scoped to that future capability, with no schedule. — supersedes any prior direction.