arthur/docs/one-grid-plan.md

The editing grid is the symbol's own frames

What was wrong

Every number a person authors — a span, a :time :at, a key, a cut — is in the frame space of the symbol it lives in (docs/time.md, and that part is right). The timeline, though, drew its ruler in OUTPUT frames: clip/output-frames, the transport's length. In a 12fps project holding 30fps symbols those two spaces sit at a ratio of 2.5, so:

• a clip at symbol frame 31 was drawn at ruler frame 12.4 — no clip edge landed on a frame mark, because almost none of them can;
• a gesture measured in ruler frames had to be multiplied into the symbol's frames and rounded (nest/dragged), so dragging one ruler frame moved the clip 2 or 3 symbol frames — 0.8 or 1.2 ruler frames, never the 1 the pointer said. That is the jumpiness;
• the preview drew the gesture's own number of ruler frames while the commit wrote the rounded one, so the ghost sat somewhere the settled clip did not;
• before the rounding was added, the fraction went into the document and every later edge edit on that clip was refused for ever (span/* refuses a fractional edge, as it should).

One cause, four symptoms. None of them is an edge case to patch.

The model

1. A symbol's own frames are the only coordinate anything authored lives in. Unchanged.
2. The editor edits in the open symbol's frames. The ruler, the marks, the playhead's position on it, every pointer→frame answer, every drop frame and every drag delta are the open symbol's frames. No multiplication anywhere in the gesture path, so no rounding and nothing fractional to refuse.
3. The output grid is playback's alone — the clock, the audio mix, export, and the frame the stage draws. Exactly two pure functions cross between them and nothing else does:
   • clip/shown-frame clip sid f — which of sid's frames output frame f shows (cadence/frame: the latest at or before it).
   • clip/first-output-frame clip sid n — the output frame that first shows symbol frame n; the inverse, for seeking from the ruler.
4. nest/inside, nest/placement, nest/spans and the gestures take the subject symbol's OWN frame. They used to take an output frame and multiply it secretly, which is what made every caller's units a guess. A caller holding the playhead converts with clip/shown-frame, at its own edge, visibly.

The gestures

5. One pointer→frame function for the whole timeline, frame-under. A drag's delta is the difference of two of its answers, never a pixel ratio rounded separately — so the preview and the commit are the same number by construction.
6. The junction between two clips is one handle with one meaning: roll. It moves the end of the left clip and the start of the right one together, which is span/roll, which is already nothing but resize-out then resize-in. The three 4px-wide zones it used to pick between — trim-left, roll, trim-right, inside twelve pixels — were the "it just picks one" the handle was accused of. An edge that is not shared still has its own in/out handles.

Audio goes with the picture it belongs to

A take's sound lived inside the take symbol, so placing the take brought it and placing the FACE the take is made of brought nothing. A symbol now says what it sounds like — :audio, a sound source — and placing one places a linked audio node beside the clip. Detection sets it on the face it extracts, which is the automatic link; ::ui/link-audio sets or clears it by hand, which is the manual one. :linked-to on the audio node already existed and already follows a moved picture.