arthur/docs/lane-nesting-notes.md

Lane nesting interaction notes

Status: design note, 2026-10-01. This records the interaction before more lane UI is implemented.

The capability that must not be lost

A lane owns temporal placement, but a symbol instance is still a doorway into another symbol. A drawing accidentally authored at the root must be movable into an instance in any lane, including another lane, without changing its visible position or timing.

That operation already exists as nest/move-node. It resolves the source and destination at the current root frame, transplants the node, and re-expresses its transform and time under the new parent. The lane UI must expose a target path for it; it must not replace it with a weaker :parent assignment.

There are therefore two different drag intentions:

1. Temporal move: drag a clip body onto lane space. It remains a clip in a lane, moves in time, and claims the destination interval by trimming/removing incumbents.
2. Structural move: drag from the clip's grab affordance onto another symbol instance. The dragged node is transplanted into the target instance's source symbol with nest/move-node, preserving its world transform and root timing.

These cannot be inferred from overlap alone. Dropping clip A onto time occupied by clip B already means “A claims that time and trims B.” Structural nesting therefore needs an explicit grab affordance/mode. Its cursor is grab and grabbing; trim edges keep their resize cursors and the ordinary body keeps its timeline-move behavior.

Both visible clip blocks and an expanded symbol header are structural drop targets. This permits moving a root drawing directly into symbol-3 even when its lane is collapsed.

Compact expansion: one selected-clip portal

Expanding a lane must not restore row-per-clip vertical growth. Instead, an expanded lane reveals exactly one clip portal: the currently selected clip in that lane.

▾ foreground lane          [symbol-1][symbol-2][symbol-3]
    ▾ symbol-3             instance/source header and drop target
        ▸ body lane        nested rows, mapped to the root ruler
        ▸ face lane
        position           nested keyframes mapped to root time

• Selecting another block in the same lane swaps the portal in place.
• With no selected clip in that lane, expansion shows a compact “select a clip to inspect” row. It must not follow the playhead during playback; that would make the timeline restructure itself while playing.
• The portal header represents the selected instance and is the structural drop target for moving root or sibling content into its source symbol.
• Sub-expanding the portal uses the existing recursive symbol-row walk. Nested lanes and channels are mapped through the instance clock into the open/root ruler, as ordinary expanded instances already are.
• The lane's own transform/channel rows remain available separately. They affect every clip in the lane and are not properties of the selected portal.

This keeps the cost of inspection constant: an expanded lane adds one selected symbol branch, not one branch for every temporal clip it contains.

Keyframe visibility

Two levels should be visible without changing editors:

• The selected clip's instance-level keys (transform, visibility, corrections) appear as ticks inside that clip block on the lane row.
• Expanding the lane opens the selected clip portal, where source-symbol and recursively nested keys appear on their own rows, mapped to root time.

Thus the collapsed lane answers “where does this clip change?” and the expanded portal answers “which property inside this symbol changes?” The second view is still the root timeline; entering the symbol is not required merely to see or edit its keys.

Drag targets and feedback

• Grab onto lane background: move/adopt the instance into that lane.
• Grab onto a symbol clip: structurally transplant into that clip's source symbol.
• Grab onto the expanded portal header: the same structural transplant, with a larger and less ambiguous target.
• Grab onto itself or one of its descendants: refuse before drop to prevent a symbol cycle.
• A structural target receives an inset highlight and the preview stays in that target. A lane-time target receives the dashed temporal clip preview.
• Successful structural drops expand the target lane and select the moved node beneath the target portal, so the result is immediately visible.

Data model consequence

No lane-as-symbol type is required. The hierarchy remains:

symbol -> sequence lane -> instance clip -> source symbol -> its lanes/nodes

Lane membership owns time partitioning. Symbol instances own composition nesting. The UI may present the selected instance below its lane, but that is a derived portal, not another ownership edge and not a duplicated node.

Implementation order

1. Render instance-level key ticks within lane clips.
2. Add selected-clip portal expansion to timeline/rows using the existing recursive walk and root-time mapping.
3. Add the explicit structural grab affordance and clip/portal drop targets.
4. Route structural drops through nest/move-node; add browser coverage for a root drawing moved into a clip in another lane without a visual jump.
5. After the transplant, expand the destination portal and reveal/select the moved row.