arthur/docs/lane-handoff.md

# Lane and cel handoff

Status (2026-09-30): the lane model is implemented through its commands, its
first two views, and correction authoring. Cels are ordinary nodes with their
own playback clock; the timeline draws them as one row and the cel sheet draws
frames down and lanes across. Both views issue the same commands. Rotation and
position corrections can be authored as Constant, Ramp, or Return motion on a
lane or cel, survive regeneration, and expose conflicts for removal or retry.

The commits beginning at `3d3c1bb` are the argument for the model and are worth
reading before touching what they did — they are the design record, more than
this file is.

    3d3c1bb  An occurrence is a node, with a clock of its own
    9446829  Reuse, duplicate and make unique: deciding what is shared
    26517af  A position is an argument, not another command
    94c0a21  A correction is a layer, and a layer's values are a channel
    72b57e3  Regenerate the base, keep the hand work, and say when you cannot
    76106d3  The shot is as long as somebody said it was
    598c186  One word for one thing: it is a cel

## Read first, in this order

1. [The Lane Model](lane-model.md) — the design, and the status note under
   *Proof obligations* says what is built. It supersedes `animation-model.md`,
   `timing-model.md` and `architecture.md` wherever they overlap.
2. `frontend/src/arthur/domain/lane.cljs` — every command, and the reasoning in
   its docstrings.
3. `frontend/test/arthur/domain/lane_test.cljs` — what the model is asserted to
   do. It is the fastest way to see the shapes.
4. `frontend/src/arthur/domain/channel.cljs`, the correction-layer section.

## Vocabulary — one word for one thing

Renamed in `598c186`, after four words had accumulated for one object. Use these
and do not reintroduce the others.

| word | means |
| --- | --- |
| instance | the `:kind`. The general thing, anywhere in a document |
| cel | an instance in a lane. One drawing, held for some duration |
| lane | a group with `:layout :sequence` |
| drawing | the content a cel names — an ordinary symbol |
| placement | ONLY where a node sits: `nest/placement`, and the transform that puts a face on the stage. Never the node itself |

`occurrence` and `exposure` are not words for a cel. **`exposure` means something
else and still does**: `:time :expose` is how many frames each step of a subtree
lasts, which is what shooting on twos is — `node/expose`, `clock/exposed-frame`,
`subs/render ::exposure`. Keeping these apart is why the block is called a cel.

`:layout :sequence` stays as the field, and is the one place two words are kept
on purpose: the layout names the RULE — children follow one another and may not
overlap — and a group carrying it is called a lane. `node/lane?` is where they
meet.

The second view is the CEL SHEET, not the exposure sheet.

## Decisions already made — do not re-litigate

These were each argued out and are load-bearing. Changing one is a design
decision, not a cleanup.

- **The shot length is authored.** `:frames` is the symbol's window; the
  occupied extent of its lanes is a different fact derived from the cels. A
  command grows the window only when the caller passes `:extent :grow-symbol`,
  and never shrinks it. Blanking the end of a shot leaves empty frames at the
  end, because deriving the window from the extent would make deleting the last
  drawing silently shorten the film. `lane/finish`.
- **Placing ripples; overwrite is `blank` then non-rippling placement.**
  `lane/overwrite-drawing` composes those pieces as one transaction. Insertion
  retains its ripple rule; overwrite does not move any surviving cel.
- **A position inside a cel refuses and names `split`.** One command must not
  quietly perform two. The UI offers the retry.
- **A correction has no time space of its own.** Its `:support` and its values'
  keys are in the frames the base channel's keys are in — the node's. A
  correction on a lane is in lane frames and reaches across the drawings under
  it; one on a cel travels with that cel. Ownership already answered it.
- **A layer's values are a channel.** Constant, ramp and return motion are one
  mechanism. Do not add a second way to say what a value is over time.
- **A conflict is not a `problem`.** A document whose topology outgrew a
  correction loads, evaluates and saves; `clip/conflicts` lists the decisions
  waiting for a person. `problems` means the document will not load.
- **Refuse rather than guess.** Every command returns `{:clip :selection}` or
  `{:refused why}`, never a half-applied edit. Where the model needs a choice
  nobody has made, refusing and saying why is the behaviour, not a placeholder.
- **A cel is not a row.** Rows, expansion and selection are editor state. The
  document has never known about rows and must not learn.

## Next steps, in order

The cel sheet now supports rectangular selection by pointer drag, Shift-click,
and Shift-arrow, plus an editor-local clipboard (Cmd/Ctrl C/X/V). Paste
overwrites the destination rectangle, including copied gaps, and reuses drawing
symbols. Partial cels retain their local clocks, playback and corrections.
Delete clears frames without closing time. Each cut, paste or clear is one
history transaction. The clipboard belongs to the mounted sheet and current
document; it is not a system clipboard interchange format.

A selected held cel has a bottom-right resize handle. Dragging previews its new
extent and commits one ripple edit on release; Escape cancels. Overflow uses
the existing explicit shot-extension retry. Rectangle edits currently require
lanes on the sheet's clock and paste must fit within the shot and available
columns. Insert-paste, moving rectangles, and repeating multi-cel patterns with
the handle remain future work.

The implemented correction slice and its remaining UI limits are recorded in
[Correction authoring](correction-authoring-plan.md).

1. **Slip source and retime.** Both have real design questions open and the doc
   says to refuse rather than approximate: retime needs a defined warp and
   interpolation behaviour, and is not moving keys whose numbers happen to fall
   inside a selection.
2. **Deleting reused content.** Reference discovery exists (`node/sources`,
   `clip/places`, `clip/contains-symbol?`); the policy does not.
3. **Displayed-range correction gestures.** The first correction panel asks for
   explicit owner frames. Dragging a range in a retimed/nested view still needs
   a proved mapping; do not make it snap through floors or loops.
4. **Collaboration.** `lane-model.md` is explicit that one leaf per channel does
   NOT solve two people editing different keys of the same channel. No conflict
   policy exists for that.

## Mechanisms to reuse — these keep paying out

- **`:span` is in the node's OWN frames** and `:time` says where they land in
  the lane. Moving an edge of a cel is therefore one write to `:span`, with
  `:time` and `:playback` untouched. This is why split costs nothing, why the
  two halves of a split go on meaning what the one cel meant, why trimming the
  front of a playing insert starts it later into its animation instead of
  restarting it, and why extending a hold leaves lane keys alone. `lane/local`
  and `lane/edged` are the whole geometry; trim, split and blank are all it.
- **`lane/finish`** is the one commit path: it validates, applies the shot-length
  policy, and returns the refusal. New commands go through it.
- **`:required-frames` plus the retry event** is the pattern for "this needs a
  decision you have not made": the domain reports what it would need, the UI
  offers one button. `events/ui/lane-retry`.
- **`lane/lane-frame`** converts a symbol frame to a lane frame, or returns nil
  through a stepped or looping lane where there is no single answer. Nil refuses;
  it never snaps.
- **`channel/conflict-with`** is the rule for whether one offset fits a base,
  used by `conflicts` and regeneration. Validation additionally follows prior
  replacement layers, so it cannot approve a stack that throws when read.
- **Generated sampling applies to the base, not the hand correction.** Picture
  rate and pose selection may choose an earlier generated frame; correction
  support and values still read the node's current authored frame.
- **Correction commands live in `domain/correction.cljs`.** IDs come from the
  event caller; the pure command materializes default transform channels,
  appends one layer, and validates the complete document. The inspector authors
  rotation and position offsets in explicit owner frames. One Apply is one undo
  step. `channel/reconcile` is the shared ordered-stack compatibility rule used
  by validation, conflict reporting, and regeneration.
- **Two test patterns worth copying.** `the-cursor-agrees-with-the-specification-in-any-frame-order`
  holds the optimized cursor to `value-at` in forward, backward and random order
  — add a case to it for any new channel shape. And `drawn` in `lane_test`
  samples every frame before and after an edit, which is how split and trim are
  proved to change nothing: state a claim as "the same picture" rather than as
  numbers computed by hand.

## Known gaps and traps

- **Audio lanes do not work.** `symbol/lane-problems` requires `:instance`
  children, so an audio node in a lane is rejected outright. `lane-model.md`
  says a lane may hold visual OR audio cels and should reject only a mixture.
- **`:z` is required on cels and means nothing there.** A lane never has two
  cels on one frame, so draw order between them cannot matter. `node/problems`
  requires `:z` on every node uniformly, which is its own kind of simplicity —
  but the field is noise on a cel.
- **`channel/offset-onto` throws** on a shape mismatch that no regeneration has
  recorded as a conflict. That is deliberate — a correction that silently does
  not take is the failure the design exists to prevent, and `channel/problems`
  catches the authored case — but it is a throw in the read path, so any new
  producer of layers must not create a mismatched one.
- **`docs/timing-handoff.md` is a separate, unreconciled thread.** Performance-
  pose selection and plate drawings/tracing, instance-specific picture-rate
  requests, `pose/put-cut` addressing only `:main`. It predates the lane model
  and nobody has squared the two.
- **The button row in the timeline pane is a test harness, not a design.** It is
  how the commands were made reachable and provable. `lane-model.md` describes
  the real cel action strip, the breadcrumb and the location bar; none exist.
- **`shadow-cljs release app` clobbers the dev bundle.** Both builds write
  `../static/arthur/js`, which Django serves, and the optimized build does not
  export the `arthur` global — so after a release the browser tests fail with
  `ReferenceError: arthur is not defined`. Run `npx shadow-cljs compile app` to
  restore it. A running `watch app` does not notice; it rebuilds on the next
  source change.

## Running it

From `frontend/`:

    npx shadow-cljs compile test && node out/node-tests.js     # 437 tests, 5,804 assertions
    npx shadow-cljs compile app                                # the bundle Django serves
    npx shadow-cljs release app                                # then `compile app` again — see above

The browser tests need the Django dev server up (`mise exec -- python manage.py
runserver 8778` from the repo root) and a compiled dev bundle:

    node --experimental-websocket test/browser/lane.mjs                  # the lane/cel flow
    CHROME=/usr/bin/chromium node --experimental-websocket test/browser/take.mjs

`take.mjs` defaults to a macOS Chrome path, hence `CHROME=`. It writes a real
project to the local server by design; `lane.mjs` never writes to the server.

From the repo root: `mise exec -- python manage.py test clips` — 56 tests.

Documents are schema 3. A version 2 document is not read and nothing converts
one; there is no backward compatibility to preserve anywhere in this work.