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.

**47 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.