# Sequencer Editor Guide

The sequencer editor helpers provide renderer-neutral view models and editing
operations for timeline authoring tools. They are designed to sit between UI
widgets and the sequencer core runtime.

## Editor State

Use `createSequencerEditorState` to start an editing session from a
`SequencerSequence`. The state tracks the current playhead, timeline zoom,
scroll position, selected keyframes, clipboard contents, expanded tracks,
mute/solo overrides, undo history, and collaboration locks.

`createSequencerTimelineViewModel` turns editor state into timeline rows with
visible bounds, lane heights, keyframe ticks, clip ranges, mute/solo state, and
active lock ownership. Pass the current collaboration tick when the UI needs to
show whether a track is locked by another author.

## Track Editing

Track operations are immutable and return a new editor state:

- `addSequencerEditorTrack` adds a property, animation, audio, event, camera, or
  sub-sequence track and extends the sequence duration when needed.
- `removeSequencerEditorTrack` removes a track by id.
- `reorderSequencerEditorTrack` moves a track to a new row position.
- `setSequencerTrackExpanded` changes track row density.
- `setSequencerTrackMuteSolo` applies editor-level mute and solo overrides.

## Keyframes and Curves

Property keyframes can be selected, added, deleted, moved, copied, and pasted
with `selectSequencerKeyframes`, `addSequencerKeyframe`,
`deleteSequencerKeyframes`, `moveSequencerKeyframes`, `copySequencerKeyframes`,
and `pasteSequencerKeyframes`.

`createSequencerCurveEditorModel` samples a numeric property track across the
sequence duration and returns the active interpolation mode plus selected
keyframe times, tangent handles, and preset curves. Use
`updateSequencerKeyframeCurve` to change interpolation and tangent handles on a
keyframe. Use `createSequencerCurvePresets` to populate common hold, linear,
ease-in, and ease-out choices. Curve tools should use this model for scalar
graph editing and keep non-numeric tracks on the timeline.

## Preview and Recording

`createSequencerViewportPreview` evaluates the sequence at the current playhead
and returns property values, active animation clips, active audio cues, and the
active camera. `createSequencerCameraPreview` returns the picture-in-picture
camera state and a short label for the active cut.

`recordSequencerPropertySample` supports recording mode by creating or updating
a property track from sampled viewport transforms or material values. Repeated
samples for the same binding and property path append linear keyframes to the
same recording track.

## History and Hotkeys

All sequence-changing editor operations push undo history and clear redo
history. Use `undoSequencerEdit` and `redoSequencerEdit` for timeline command
handling. `createSequencerHotkeys` returns the default editing shortcuts, and
`matchSequencerHotkey` resolves UI keyboard events to command ids.

## Templates and Render Planning

`createSequencerTemplateLibrary` returns starting points for common cinematic
sequences, including dialogue, impact events, and camera fly-throughs.
`createSequencerRenderPlan` converts a sequence and export settings into a
frame-counted render job for MP4, MOV, or image sequence output.
`createSequencerThumbnailPreview` evaluates the sequence at a representative
time for browser thumbnails.

## Collaboration and Profiling

`lockSequencerTrack` records a temporary track lock for a user and tick range.
`mergeSequencerCollaborationChange` accepts incoming sequence changes only when
the changed tracks are not locked by another author.

`profileSequencerPerformance` estimates per-track editing cost from keyframe,
clip, cue, event, camera, and sub-sequence density. Use the recommendations to
flag dense tracks before realtime preview becomes expensive.
