Editing rules

How tracks, links, locks, targeting and the trim tools behave, for people and agents alike.

• Rendering order: V1 is drawn first, then V2, V3, … on top. SVG/image/text clips go on any V track (higher V lanes are handy overlay lanes). Add lanes with the timeline +V / +A buttons (or by listing them in tracks); up to 16 per kind. Right-click an empty track header → Remove track (disabled if the lane has clips or is the last video/audio track).
• Audio tracks A1–An hold both standalone audio files and linked companions for imported video. Dropping a video creates the picture on a V track (props.volume: 0 so it isn't doubled) plus one kind:"audio" clip per source channel on consecutive A-tracks that share a linkGroup (and the same mediaId / timing). Each stem is mono-isolated then placed with pan (defaults preserve stereo: L −1, R +1). Standalone music/SFX also live on A-tracks. Linked partners move/trim/split together - edit timing on any member of the group; do not treat A-tracks as music-only.
• Three track switches (Premiere-style), all in the track header and all persisted on project.json:
  • Enable (eye / speaker) → disabledTracks. Output only: a disabled lane is left out of preview, audio and export. It does not affect editing.
  • Target (click the track name - lit = targeted) → untargetedTracks. Decides which lanes an edit touches when nothing is selected: split at playhead (S), insert ripple (,), replace punches (.), ripple-delete shifting (⇧Del), close gap (⇧G), next gap (G), split / trim at IN/OUT (T / ⇧T) and jump to cut (↑ / ↓). Source placement follows targeting too: the picture lands on V1 if it is targeted, else the lowest targeted video lane (none → the edit lands audio-only); stems land on the first two targeted audio lanes. A selection is always edited wherever it sits.
  • Lock (padlock) → lockedTracks. Nothing on a locked lane can be moved, trimmed, split, deleted or edited in the inspector, and ripples leave it where it is while the other lanes shift. A locked lane is never an edit target. Typical use: lock the music bed, then ripple the picture freely.
• Clip lock / enable - right-click a clip, or use the toggles at the top of the inspector. locked: true pins one clip the same way a locked lane does. disabled: true (⇧E) keeps the clip on the timeline but drops it from preview, audio and export - like a disabled lane, for a single clip. Both apply to the clip's whole linked group.
• Locks and linked groups - a linked A/V group with any locked member (its own flag or its lane) counts as locked as a whole, so sync is never broken by a partial move.
• Sync lock - edits that shift clips move the targeted lanes; linked AV partners always ride along, even on an untargeted lane, and locked groups stay put. On reload relinkClips rebuilds linkGroup from matching mediaId / start / in / duration.
• Unlink / link (Ctrl/Cmd+L) - unlinking a group removes its linkGroup and stamps unlinked: true on each member, so the reload-time relink leaves them apart; picture and audio then move, trim and delete separately. Link (select one video clip plus its audio, Ctrl/Cmd+L) only joins clips of the same file that line up exactly - same start, in and duration - because a link here means identical timing.
• Agents and locks - fablecut_patch_project refuses updateClip / removeClip on locked material (own flag, locked lane, or a linked partner of one) and addClip onto a locked lane. Treat locked clips as the user's finished work: leave them alone. Only when the user asks you to change one, pass force: true on that op, or unlock first with updateClip set:{locked:null} (always allowed). fablecut_set_project, REST PUT and direct file edits are not guarded - respect locks there too.
• Media is fit-ted to the canvas (default "contain"), then crop → scale/x/y/ rotation → flips apply.
• props keys are all optional - missing keys get the defaults above.
• Video/audio clips must satisfy in + duration×speed ≤ media.duration.
• Keyframes fully override the static prop value while present; they are clip-local and are re-based automatically when clips are split or trimmed.
• Transitions modulate the evaluated props (fade also fades audio); they render on top of keyframes, so both can coexist.
• Same-track overlap IS the crossfade idiom: overlap A and B by ~1 s and give B transitionIn: {type:"fade"}.
• A cut/split is just two clips: first with duration: t, second with start: +t, in: +t×speed, duration: rest.
• Edit tools (timeline toolbar picker, or V / B / R / Y / U) change what a clip drag does. They are editor gestures - agents get the same results by patching start / in / duration directly, keeping linked partners equal.
  • Selection (V) - move and trim, as always.
  • Ripple edit (B) - drag a clip edge; everything after it on the targeted tracks (and the clip's own lanes) moves with it, so no gap opens or closes. Dragging a head keeps the clip's start and trims its source In.
  • Rolling edit (R) - drag a cut; the clip on one side lengthens by what the other loses, nothing else moves.
  • Slip (Y) - drag a clip to change its source In only (dragging left shows later source); position and length stay. Video / audio clips only.
  • Slide (U) - drag a clip along its track; the clip before it trims its tail and the clip after it its head, so the sequence length stays. All four are clamped to the available source media, MIN_DUR and the free room on the track, take linked partners with them, and refuse on locked clips; a readout by the pointer shows the offset while dragging.
• Lift (;) / Extract (') - remove IN→OUT on the targeted tracks. Lift leaves the gap; Extract closes it. Linked partners are cut too, locked clips stay whole, and IN / OUT clear afterwards.
• Jump to cut - ↑ / ↓ move the playhead to the previous / next clip In or Out. Selection first (that clip’s start then end); no selection walks targeted-track cuts. Source monitor: 0 / In / Out / duration. Does not change project.json.
• bgRemove and chromaKey can combine with all filters; heavy pixel work is automatic (only runs when those props are set).