Video Timeline Engine

This is the engine, not a styled UI

You bring the rendering. What takes weeks to converge is the coordinate math and the edit semantics underneath — not the divs.

What goes wrong without it

A timeline looks like `x = (t - scroll) * pxPerSec`. That line is correct, and it is also the source of nearly every timeline bug, because the hard part is what must stay true *while* it changes.

Zoom is anchored, not absolute. Zooming has to hold a chosen time still under a chosen pixel — the mouse, or the playhead. Scaling `pxPerSec` alone is the obvious move, and it throws your work off-screen on every wheel tick.

Frames are integers, and seconds drift. Video has no time between frames. Every time reaching a cut, trim, or playhead is quantized — and quantization *rounds* rather than floors, because flooring biases every edit backwards into a systematic one-frame drift. Frame index is the source of truth; at 29.97 the naive `t += 1/fps` accumulation diverges visibly within an hour. Round-tripping is tested across a 24-minute 23.976 timeline, frame by frame.

Snapping is measured in pixels, not seconds. A 0.1s snap radius is enormous zoomed out and unusable zoomed in. The threshold lives in screen space so snapping feels identical at every zoom level — there is a test asserting the same 50ms offset snaps when zoomed out and refuses to when zoomed in. Ties break toward the earlier target, deterministically; a snap that depends on array order is maddening precisely because it is almost always right.

Pan is clamped — but not to `duration - visible`. The right-edge stop lets the last frame reach the *middle* of the screen. Pinning it to the right edge is where it is awkward to edit, and people feel that immediately without being able to name it.

**Ripple moves downstream clips by the delta that was *applied*, never the one that was *requested*.** This is the expensive one. A trim clamped by the end of its source shifts everything after it by the full requested amount, silently opening a gap — which nobody notices until the export has a frozen frame in it. Every clamp reports what bit, so the caller can never assume it got what it asked for.

Splits keep the source offset honest. The second half's source offset advances by exactly the frames the first half consumed. Fumbling it produces a visible jump cut.

Trims cannot invert or exceed the source. Dragging the out-point past the in-point stops at one frame, instead of producing a negative-length clip that crashes three steps later.

Gaps and overlaps are explicit. They are reported by functions that report, and closed by a function whose name says it closes them. A timeline that "mostly" prevents them produces corrupt output.

Verified by mutation, not by passing

Every rule above had its guard removed one at a time and the suite was confirmed to fail each time — 10 for 10, including both flagged as expensive: ripple-by-requested-delta, and the split that forgets to advance the source offset. A test that has never been seen to fail is a decoration.

48 tests passing · typecheck clean · 10/10 mutations caught.

Built for

AI-generated video assembly, where shots arrive at fixed lengths and the work is trimming, reordering, and butting them together. There is nothing generator-specific in it.

Delivery

Private repository invite within 24 hours. Single-product commercial license: use and modify in one shipped product; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function endFrame(c: Clip): number;
  export function trimHead(clip: Clip, deltaFrames: number):;
  export function trimTail(clip: Clip, deltaFrames: number):;
  export function rippleTrimTail(clips: Clip[], id: string, deltaFrames: number): TrimResult;
  export function compact(clips: Clip[], startFrame = 0): Clip[];
  export function findGaps(clips: Clip[], startFrame = 0): Gap[];
  export function findOverlaps(clips: Clip[]): Overlap[];
  export function splitAt(clip: Clip, frame: number): [Clip, Clip] | null;
  export function shotBoundaries(clips: Clip[], fps: number): Array<;
  export function timeToFrame(sec: number, fps: number): number;
  export function frameToTime(frame: number, fps: number): number;
  export function quantize(sec: number, fps: number): number;