ARCADIA-Studio/harness/release-state-gesture-design.md

Direct state editing — bounded design, 2026-09-05

Originally a read-only proposal. Implemented in the isolated state-integration checkout through e0b2210; current verification and outstanding acceptance are in STATE.md. The old file/line seams below describe the pre-implementation baseline. State layouts now use the typed context and commands proposed here; full scenario and process direct editing remain separate release work.

Decision and first task

Reuse Diagram/NodePlacement and existing atomic commands. Prefer a typed ProjectionKind::StateMachine { machine: Id } over desktop-only coordinates or a second persisted behavior-layout store. Existing projection strings remain valid. Use the existing constructor syntax: projection { StateMachine { machine @operating_modes; }; };. The context references a same-layer machine and scopes placements to its machine, regions and vertices. Explicit creation initializes existing contents in one transaction; rendering must not dirty a model. Missing placements remain legal and discoverable through an elements-not-shown action.

Retain active behavior diagram identity independently of semantic selection; selecting a root Event must not switch machines. Diagram context/layout are model content; active tool, pointer and zoom remain editor state. Context participates in reference remapping/deletion, language reference controls and OpenAPI.

The first native task is: create a region and Initial/State; drag a child and a composite; draw a transition; reconnect its endpoint; edit its guard; undo/redo; save/reopen and inspect the equivalent source/API records. This is the minimum vertical slice, not acceptance of all behavior editing.

Existing seams and implementation contract

• behavior.rs:56,118,494: selection-derived context, selection-only canvas.
• behavior/state_scene.rs:24,163: computed vertical geometry; retain its state symbols, internal-transition rows and typed routing, but consume persisted shared node geometry. Generic projection drops equal-anchored/self edges and includes relationships unsuitable for a state diagram.
• behavior/states.rs:73,191: reuse existing typed transition controls and candidate validation. Reconnection edits a clone of the original relation.
• model.rs:1235,1247, projection.rs:104,184, session.rs:562: reuse placement identity, semantic nesting/folding and grouped movement.

Events carry diagram identity explicitly: CreateAt(diagram, parent, kind, position), Move(diagram, node, position), Connect(diagram, source, target), Reconnect(diagram, relation, endpoint, vertex), EditTransition(diagram, relation). They lower to existing CreateElement+CreateNode Batch, MoveNode, CreateRelation/EditRelation commands. No alternate mutation API is required. Gesture state is Idle/Move/Connect/Reconnect with transient preview and a captured revision. Release commits once; Escape, stale revision or context change cancels. Allocate creation IDs once per accepted plan. Drawing/hit testing/preview consume one scene. Extend app.rs:864's draft guard to every mutation gesture.

Required invariants

Creation targets the explicitly highlighted semantic Region. Region creation targets a machine or stable State/Mode. Dragging never reparents. Moving a container moves all descendant placements once, including folded descendants, only in that diagram. Child movement preserves ownership and siblings. Resize constraints preserve child/header space and movement cannot misleadingly suggest ownership by another region. Entry/Exit remain region-owned boundary symbols.

Reconnect preserves relation UUID, alias, name, prose, triggers/effects and artifact references; validate the full replacement so the old relation is not double-counted for cardinality. Do not silently change transition kind or erase incompatible data. Internal remains a row/self contract; External self-loops and Local edges remain distinct. Cross-immediate-region transitions can be valid; cross-machine endpoints reject. Existing history, boundary and orthogonal rules in state_validation.rs remain authoritative.

Reject invalid drafts without losing them. New tools must not discard unfinished behavior drafts. Preserve semantic selection after movement and same-card reselection. Context references remap with UUID changes; machine deletion removes its dedicated views without deleting cross-layer counterparts. Source-created unplaced elements remain discoverable; cross-machine reparenting must also handle incompatible placements atomically or reject with an actionable diagnostic.

Partition and evidence gates

Core/context owns model.rs, projection.rs, references.rs, validation.rs and focused tests. After type freeze, representation owns language.rs, source-project reference handling, reST/OpenAPI and round-trip/API tests. Desktop gestures own new behavior/state_canvas.rs and state_scene.rs. Lead integrates behavior.rs, states.rs, app.rs and diagram context controls. Avoid a general graph framework.

Test pointer events at non-100% zoom, one history entry per gesture, exact identities, grouped movement limited to one view, atomic rejection, context lifecycle and source/JSON/REST equality. Native trial at 1440x900 and 1100x700 uses two regions, a nested composite and guarded transitions. Try invalid edges into Initial, invalid history reconnection, Escape mid-drag, a folded composite, root-Event selection and save/reopen. Record task completion, discoverability, ownership clarity and recoverability; no such native result is claimed here.

Current-interface review (2026-09-06)

Independent core and desktop maps confirm the payload projection remains the smallest persisted boundary. Preserve unit-variant JSON strings; the new value is {"StateMachine":{"machine":"UUID"}}. A machine context is required for empty and partial views; inferring it from placements cannot represent an empty diagram, while an optional unrelated Diagram context adds invalid combinations. Use one narrow state-view membership predicate and preserve existing projections' legal hidden placements. Dedicated views disappear with their machine; moving elements across machines must repair incompatible views/routes in the same Batch or reject atomically.

The shared router now owns route pins, label placement and grouped translation. An executed probe found that merely retaining an External self-transition yields an 18 px out-and-back stub. Add genuine self-loop and state-symbol endpoint geometry in the shared routing/projection path; Entry/Exit snapping must precede draw/hit testing. Internal transitions remain rows, and folded descendants must not create false visible self-transitions. Probe: D:/CodexBuilds/Capella2-source-document-contract/examples/state_projection_boundary_probe.rs.

Before adding gestures, close existing behavior draft gaps: Start/Edit must not overwrite an unresolved form, Submit must retain it until Document source/model commit succeeds, and Save/Close/navigation must account for behavior drafts. Canvas events carry the existing document/diagram/revision/epoch context and recheck it before acceptance. Generic MoveNode message delivery selects the current active diagram and is insufficient for delayed behavior gestures.

Keep Select, State/symbol, Region, Transition and Fit in a compact toolbar. Create inside an explicitly highlighted eligible owner, place missing ancestry in the same command batch, and expose unplaced semantic elements. Retain the behavior view independently of selection, including root Events. Reconnect clones the relation and changes one endpoint; preserve all other data and reject invalid cardinalities. Keep form editing in a bounded panel so the canvas remains usable at 1100×700. These are decision-ready interfaces; no implementation or native gesture acceptance is claimed by this design record. The implemented contract and subsequent acceptance evidence are in release-state-editing.md; production316dc55 closes the direct state slice, while scenario/process work remains.