ARCADIA-Studio/harness/multiselect-contract-20260923.md

# Multiple selection and group actions: implementation contract

User requirement: [issue 29](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/29)
asks for Shift+click selection of several functions, moving them together, and
related useful group actions. This contract derives from that request and the
existing graphical/textual equivalence requirement. It is a development decision,
not a claim that the feature is implemented or accepted. Inspected source is
`b8685416f56e53e30bd11ecf93a54cea10ac8458`; integration with later peer branches
requires inspection of their actual changes.

## Selection and operation identity

Selection is transient and scoped to one document and rendered surface. It has
an ordered set of exact visual targets and one primary target for the inspector.
A semantic UUID alone cannot identify a placed node, a port on a particular
placement, or a repeated occurrence in an expanded reusable Process. Navigation
highlights are not edit targets. Changing surface clears the set; accepted model
changes reconcile surviving exact targets without mapping a missing occurrence
to another occurrence of its semantic definition.

Shift+click toggles the hit target. Plain click on an unselected target replaces
the set. Pressing a selected member retains the set for a possible group drag;
a stationary release that never crossed the drag threshold selects that member
alone. A threshold-crossing drag keeps the group, including cancellation, refusal,
snap-to-zero or returning to the original pointer position. Defer any primary
inspector/layout change until the gesture outcome. The interaction must use
captured pointer order and original gesture
geometry even if the inspector changes layout. Modifiers must be available on
the first canvas press after focus comes from another editor; passive modifier
tracking must not grant keyboard command focus. Escape cancels a live gesture
before clearing selection. Contextual Add/Remove from selection provides an
explicit alternative to the modifier gesture. Opening a context menu captures
its exact target without replacing the selection; Add/Remove operates on that
captured target. Dismissing the menu preserves the set. A visible count and appropriate
group actions distinguish group selection from the primary inspector target.

Property edits continue to address the primary object. No implicit bulk property
editing is introduced. Group actions explicitly address the captured set and
must reject stale document, revision, surface or target identity before any
selection, source, history or allocation state changes.

## Movement depends on the diagram's meaning

Saved Architecture and State views store placement geometry. Translate the
union of selected placements and their visual descendants by one displacement;
each placement moves once, including when both parent and child are selected.
Derive all affected routes from the original diagram and the complete movement
map. Both moved endpoint owners translate internal pins; an unmoved endpoint
keeps world pins fixed. Existing State boundary rules still apply. Labels and
manual attachment fractions remain relative. Other views, semantic ownership,
contracts, IDs and unrelated records remain exact.

Movement admission evaluates the complete typed selection. Unsupported mixtures
of placements, ports, edges, rows or read-only occurrences are refused with a
reason; adapters must not silently omit members or promote ports to owner nodes.

Rejected approach: sequential `MoveNode` commands. Each command sees only its
own root/descendants, so routes between separate selected roots do not receive
the simultaneous translation required by `docs/language.rst`. A pure planner
can emit the existing atomic `Batch(EditNode..., SetEdgeRoute...)`; a new wire
command or source schema is unnecessary. Preview and commit must consume the
same plan; tests independently construct expected geometry rather than merely
comparing those two uses of the implementation.

Process and Scenario layouts are derived from semantic order, not free XY node
placements. Their group drag must reorder a stable block while retaining its
internal order and applicable owner/column/operand boundaries. Existing topology
and temporal/lifecycle validation remains authoritative. Qualified reused
Process content must not silently edit the reusable definition. These adapters
are required work for the issue, not waived because ordinary diagrams are easier.

In Allocation views, multiple selection must not silently change work-body drag
from assignment to arrangement. Work-only groups use one frozen common performer
destination and one all-or-nothing allocation plan. Normalize semantic work
ancestry, deduplicate leaves and placements, and apply existing role/coherence
rules to every constituent. Different valid initial performers on independent
roots are not automatically an ambiguous destination. Any invalid constituent
refuses the whole action. Mixed selections cannot partially assign only eligible
members; explain the refusal and offer the existing Arrange-only operation.
Explicit Arrange-only always preserves every allocation record. Destination
feedback and hit geometry remain stable throughout the gesture.

The [explicit Arrange amendment](allocation-arrange-amendment-20260923.md) defines
the bounded one-or-more work/performer footprint and diagnostic collision domain.
Its [pure planner evidence](allocation-arrange-planner-20260923.md) and the
[ordinary assignment foundation](allocation-assignment-planner-20260923.md)
establish bounded source/planner behavior. App/native group input acceptance
remains pending.

## Related group actions

Move/reorder and removal are the initial useful operation families. Saved-view
Hide removes selected placements rather than the underlying engineering objects.
Delete-from-model uses one aggregate impact review and transaction; preserve
opposite-layer counterparts under the established deletion contract. Process
and Scenario removal identifies local occurrences/messages/operands, not the
reused definitions. A mixed set that cannot express one clear removal operation
is refused with an explanation. Never act on only the primary object while the
interface depicts a group. Alignment, distribution and duplication are separate
capabilities to assess after this foundation; no speculative semantics are adopted.

## Acceptance and dependencies

1. Prove simultaneous geometry planning with unrelated roots/internal routes,
   nested and folded selections, one-ended routes, typed ports and State
   boundaries. Whole-model comparison, JSON/source round trips, atomic refusal,
   one Undo/Redo and zero-motion history behavior are required.
2. Implement exact selection/primary state and focus-aware input. Exercise
   Shift held before canvas focus, toggle/removal, stationary click versus drag,
   captured event batches, hidden/stale targets and navigation invalidation.
3. Connect ordinary/State previews and commits to the geometry planner, then
   implement group Allocation and Process/Scenario order adapters with their
   independent semantic evaluators. Preserve current route/attachment cancel,
   pan, read-only and pending-source/property behavior.
4. Implement aggregate removal admission, feedback and history. Destructive
   semantics remain explicit; raw drafts must not be silently discarded.
5. Build and exercise realistic native workflows, including multi-function
   selection/movement, nested selection, cancellation, source inspection,
   save/reopen and one-step history. Review interaction and saved-model evidence
   independently. Integrate with the release owner's actual combined source.

The [Architecture critique](multiselect-architecture-review-20260923.md) and
[Behavior investigation](multiselect-behavior-design-20260923.md) contain source
references and additional falsifiers. Live ownership, implementation sequencing
and blockers belong to issue 29. Linux verification remains user-deferred.