Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { useSyncExternalStore } from "react";
import { flushSync } from "react-dom";
import type { TimelineTimeRange } from "../lib/timelineClipIndex";
import { usePlayerStore } from "../store/playerStore";
import { markTimelineMotion, TIMELINE_REST_MS } from "./timelineMotion";
import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
import {
clampTimelineZoomPercent,
getNextTimelineZoomPercent,
getTimelinePixelsPerSecond,
getTimelineZoomPercent,
} from "./timelineZoom";
/** Where a zoom holds its place: `time` stays `x` px from the viewport's left edge. */
export interface TimelineZoomAnchor {
time: number;
x: number;
}
/** The mounted timeline's scroll viewport, which every zoom measures and previews against. */
export interface TimelineZoomViewport {
scroll: HTMLDivElement;
contentOrigin: number;
publishScroll: (scroll: HTMLDivElement) => void;
}
/** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
export type TimelineZoomResult = "done" | "cancelled";
/**
* A zoom drawn by scaling what is already laid out, on the compositor, until it is committed.
* `shift` is the scrollLeft minus the scrollLeft the zoom will have: the translate that places it.
*/
interface ZoomPreview {
percent: number;
pps: number;
shift: number;
basePps: number;
/** The times laid out (clips mounted, ruler drawn) when it began; past them it shows gaps. */
drawn: TimelineTimeRange;
byPerson: boolean;
}
const RANGE_MARGIN_PX = 24;
const SMOOTH_ZOOM_MS = 220;
/** Past this the scaled-up preview turns soft. */
const MAX_PREVIEW_SCALE = 4;
/** Rounding at a drawn edge (whole-pixel content width, the fit track's 2px) is not a gap. */
const EDGE_SLACK_PX = 2;
const SCALED = "[data-timeline-zoom-scale]";
let viewport: TimelineZoomViewport | null = null;
/** While a preview shows, scales rows and strips React mounts into the timeline before they paint. */
let mounts: MutationObserver | null = null;
let preview: ZoomPreview | null = null;
let frame = 0;
let restTimer: ReturnType<typeof setTimeout> | null = null;
let anchorForCommit: TimelineZoomAnchor | null = null;
let animation = 0;
let easingTo: number | null = null;
let resolveEase: ((result: TimelineZoomResult) => void) | null = null;
const previewListeners = new Set<() => void>();
export function currentTimelineZoomPercent(): number {
if (preview) return preview.percent;
const s = usePlayerStore.getState();
return getTimelineZoomPercent(s.zoomMode, s.manualZoomPercent, s.timelineFitPps);
}
/** The scale the timeline shows and the scrollLeft that scale would have. */
function shown(scroll: HTMLDivElement): { pps: number; left: number } {
if (preview) return { pps: preview.pps, left: scroll.scrollLeft - preview.shift };
return { pps: usePlayerStore.getState().timelinePps, left: scroll.scrollLeft };
}
/** The time under `x` px from the timeline viewport's left edge, as it is drawn now. */
export function timelineTimeAtX(x: number): number | null {
if (!viewport) return null;
const { pps, left } = shown(viewport.scroll);
return pps > 0 ? (left + x - viewport.contentOrigin) / pps : null;
}
/** The scale and time-zero position to place something at a time by, while a zoom is previewed. */
export function timelineZoomMapping(pps: number, contentOrigin: number) {
return preview
? { pps: preview.pps, contentOrigin: contentOrigin + preview.shift }
: { pps, contentOrigin };
}
/** Whether a zoom is drawn scaled right now, so boxes read off the page are scaled too. */
export const isTimelineZoomPreviewing = (): boolean => preview !== null;
/** Called each frame a zoom preview moves, and once when it is laid out or dropped. */
export function subscribeTimelineZoomPreview(listener: () => void): () => void {
previewListeners.add(listener);
return () => previewListeners.delete(listener);
}
const subscribeShownZoom = (listener: () => void) => {
const unsubscribePreview = subscribeTimelineZoomPreview(listener);
const unsubscribeStore = usePlayerStore.subscribe(listener);
return () => {
unsubscribePreview();
unsubscribeStore();
};
};
/** The zoom percent the timeline shows, kept current through a preview. */
export function useShownTimelineZoomPercent(): number {
return useSyncExternalStore(subscribeShownZoom, currentTimelineZoomPercent);
}
function writeZoom(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
anchorForCommit = anchor;
usePlayerStore.setState((s) => {
const clamped = clampTimelineZoomPercent(percent, s.timelineFitPps);
return {
zoomMode: "manual",
manualZoomPercent: clamped,
// Only a person's zoom counts: the timeline and its host read it as the person taking over.
userZoomCount: s.userZoomCount + (byPerson ? 1 : 0),
timelinePps: getTimelinePixelsPerSecond(s.timelineFitPps, "manual", clamped),
};
});
}
const emitPreview = () => previewListeners.forEach((listener) => listener());
/** Stops the pending preview frame, rest timer and mount watch. */
function cancelPending() {
mounts?.disconnect();
mounts = null;
if (restTimer) clearTimeout(restTimer);
restTimer = null;
cancelAnimationFrame(frame);
frame = 0;
}
function clearScaled(scroll: HTMLElement) {
scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
el.style.transform = "";
el.style.transformOrigin = "";
el.style.willChange = "";
});
}
/** Whether the preview shows time outside what was mounted, or is scaled up too far. */
function previewNeedsLayout(p: ZoomPreview, scroll: HTMLDivElement, contentOrigin: number) {
if (p.pps / p.basePps > MAX_PREVIEW_SCALE) return true;
const left = scroll.scrollLeft - p.shift;
const start = left / p.pps;
const end = (left + scroll.clientWidth - contentOrigin) / p.pps;
const slack = EDGE_SLACK_PX / p.pps;
return start < p.drawn.start - slack || end > p.drawn.end + slack;
}
/** The times laid out now: the render window clips, ruler ticks and beat lines are drawn in. */
function drawnRange(scroll: HTMLDivElement, pps: number, contentOrigin: number): TimelineTimeRange {
const contentEnd = (scroll.scrollWidth - contentOrigin) / pps;
return getTimelineRenderTimeRange(scroll, pps, contentOrigin, contentEnd);
}
function scalePreview(scroll: HTMLElement) {
if (!preview) return;
const transform = `translateX(${preview.shift}px) scaleX(${preview.pps / preview.basePps})`;
scroll.querySelectorAll<HTMLElement>(SCALED).forEach((el) => {
// The attribute's value is where time zero sits in the element, when not at its left edge.
el.style.transformOrigin = `${el.dataset.timelineZoomScale || 0}px 0`;
el.style.willChange = "transform";
el.style.transform = transform;
});
}
const holdsScaled = (node: Node) =>
node instanceof Element && (node.matches(SCALED) || node.querySelector(SCALED) !== null);
function watchMounts(scroll: HTMLElement): MutationObserver {
const observer = new MutationObserver((records) => {
if (records.some((record) => [...record.addedNodes].some(holdsScaled))) scalePreview(scroll);
});
observer.observe(scroll, { childList: true, subtree: true });
return observer;
}
function drawPreview() {
cancelAnimationFrame(frame);
frame = 0;
const view = viewport;
if (!preview || !view) return;
if (previewNeedsLayout(preview, view.scroll, view.contentOrigin)) {
commitPreview();
return;
}
scalePreview(view.scroll);
mounts ??= watchMounts(view.scroll);
emitPreview();
}
/** Lays the previewed zoom out for real and drops the scaling in the same frame. */
function commitPreview() {
cancelPending();
const view = viewport;
const done = preview;
if (!view || !done) return;
const left = view.scroll.scrollLeft - done.shift;
// Ending at the scale already laid out (an eased zoom-out) needs a scroll, not a layout.
if (done.pps !== done.basePps) {
flushSync(() =>
writeZoom(done.percent, { time: left / done.pps, x: view.contentOrigin }, done.byPerson),
);
}
preview = null;
if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) {
view.scroll.scrollLeft = left;
flushSync(() => view.publishScroll(view.scroll));
}
clearScaled(view.scroll);
emitPreview();
}
/** The playhead's place if on screen, else the middle with the playhead brought to it. */
function defaultAnchor(view: TimelineZoomViewport, pps: number, left: number): TimelineZoomAnchor {
const { currentTime } = usePlayerStore.getState();
const x = view.contentOrigin + currentTime * pps - left;
const onScreen = x >= view.contentOrigin && x <= view.scroll.clientWidth;
return {
time: currentTime,
x: onScreen ? x : (view.contentOrigin + view.scroll.clientWidth) / 2,
};
}
function request(percent: number, anchor: TimelineZoomAnchor | null, byPerson: boolean) {
const view = viewport;
const fitPps = usePlayerStore.getState().timelineFitPps;
if (!view || !(fitPps > 0)) {
writeZoom(percent, anchor, byPerson);
return;
}
const clamped = clampTimelineZoomPercent(percent, fitPps);
const pps = getTimelinePixelsPerSecond(fitPps, "manual", clamped);
const { scroll, contentOrigin } = view;
const now = shown(scroll);
const at = anchor ?? defaultAnchor(view, now.pps, now.left);
preview ??= {
percent: clamped,
pps,
shift: 0,
basePps: now.pps,
drawn: drawnRange(scroll, now.pps, contentOrigin),
byPerson,
};
// The content's width at this scale: the fit track (getTimelineFitPps), never narrower.
const fitTrack = scroll.clientWidth - contentOrigin - 2;
const width = contentOrigin + fitTrack * Math.max(1, pps / fitPps);
const maxLeft = Math.max(0, width - scroll.clientWidth);
const left = Math.max(0, Math.min(maxLeft, at.time * pps + contentOrigin - at.x));
preview.percent = clamped;
preview.pps = pps;
preview.shift = scroll.scrollLeft - left;
preview.byPerson ||= byPerson;
if (!frame) frame = requestAnimationFrame(drawPreview);
if (restTimer) clearTimeout(restTimer);
restTimer = setTimeout(commitPreview, TIMELINE_REST_MS);
// After the commit timer of the same delay, so the zoom is laid out before the timeline rests.
markTimelineMotion();
}
/** A person's zoom input: previewed each frame, laid out once it rests. */
export function requestTimelineZoom(percent: number, anchor: TimelineZoomAnchor | null = null) {
stopEase();
request(percent, anchor, true);
}
/** Lays out a pending zoom now, so a press meets the real layout. */
export function settleTimelineZoom(): void {
if (preview) commitPreview();
}
/** After a scroll: scales what it mounted, or lays the zoom out if it shows past what is drawn. */
export function redrawTimelineZoomPreview(): void {
if (preview && !frame) frame = requestAnimationFrame(drawPreview);
}
/** Drops any pending or easing zoom without laying it out, as Fit does. */
export function cancelTimelineZoom(): void {
stopEase();
dropPreview();
}
function dropPreview() {
cancelPending();
if (!preview) return;
if (viewport) clearScaled(viewport.scroll);
preview = null;
emitPreview();
}
function stopEase(result: TimelineZoomResult = "cancelled") {
cancelAnimationFrame(animation);
animation = 0;
easingTo = null;
const done = resolveEase;
resolveEase = null;
done?.(result);
}
/** The anchor of the zoom being committed; read once by the timeline as it lays the zoom out. */
export function takeTimelineZoomAnchor(): TimelineZoomAnchor | null {
const anchor = anchorForCommit;
anchorForCommit = null;
return anchor;
}
export function registerTimelineZoomViewport(next: TimelineZoomViewport): () => void {
viewport = next;
return () => {
// Another timeline mounted since keeps its registration.
if (viewport !== next) return;
viewport = null;
// A re-render registers again in the same commit; only a real unmount drops the zoom.
queueMicrotask(() => {
if (!viewport) cancelTimelineZoom();
});
};
}
const reducedMotion = () =>
typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
/** The stretch a range zoom fills: from `x` px in, `width` px wide, inside the margins. */
function rangeBox(view: TimelineZoomViewport): { x: number; width: number } {
const x = view.contentOrigin + RANGE_MARGIN_PX;
return { x, width: Math.max(1, view.scroll.clientWidth - x - RANGE_MARGIN_PX) };
}
/** The seconds the timeline shows between its margins: what zoomTimelineToRange would fill. */
export function currentTimelineRange(): { start: number; end: number } | null {
const view = viewport;
const pps = view ? shown(view.scroll).pps : 0;
if (!view || !(pps > 0)) return null;
const { x, width } = rangeBox(view);
const start = timelineTimeAtX(x)!;
return { start, end: start + width / pps };
}
/**
* Zooms and scrolls so `start`..`end` (seconds) fills the timeline, eased unless `smooth` is false
* or motion is reduced. Resolves on landing; "cancelled" on a person's zoom, abort, or a newer one.
*/
export function zoomTimelineToRange(
start: number,
end: number,
options: { smooth?: boolean; signal?: AbortSignal } = {},
): Promise<TimelineZoomResult> {
return easeToRange(start, end, options, false);
}
function easeToRange(
start: number,
end: number,
{ smooth = true, signal }: { smooth?: boolean; signal?: AbortSignal },
byPerson: boolean,
): Promise<TimelineZoomResult> {
const view = viewport;
const fitPps = usePlayerStore.getState().timelineFitPps;
stopEase();
if (!view || !(end > start) || !(fitPps > 0) || signal?.aborted)
return Promise.resolve("cancelled");
let resolveThis: (result: TimelineZoomResult) => void = () => {};
const result = new Promise<TimelineZoomResult>((resolve) => (resolveThis = resolve));
resolveEase = resolveThis;
signal?.addEventListener("abort", () => resolveEase === resolveThis && stopEase(), {
once: true,
});
const { x, width } = rangeBox(view);
const toPercent = clampTimelineZoomPercent((width / (end - start) / fitPps) * 100, fitPps);
const finish = () => {
commitPreview();
stopEase("done");
};
if (!smooth || reducedMotion()) {
request(toPercent, { time: start, x }, byPerson);
// Laid out next frame, never inside a caller's render or effect.
animation = requestAnimationFrame(finish);
return result;
}
easeZoom(view, fitPps, toPercent, { time: start, x }, byPerson, finish);
return result;
}
/** Eases from the zoom shown now to `toPercent`, landing `to.time` at `to.x`, then `finish`es. */
function easeZoom(
view: TimelineZoomViewport,
fitPps: number,
toPercent: number,
to: TimelineZoomAnchor,
byPerson: boolean,
finish: () => void,
) {
const { time: start, x } = to;
const fromPercent = currentTimelineZoomPercent();
const from = shown(view.scroll);
const toPps = getTimelinePixelsPerSecond(fitPps, "manual", toPercent);
const fromStart = timelineTimeAtX(x)!;
const old = currentTimelineRange()!;
// The one point both views put at the same place on screen; zooming about it, in log space,
// moves every frame straight from the old view to the new. Equal scales are a plain scroll.
const shift = from.pps === toPps ? null : (start - fromStart) / (1 / from.pps - 1 / toPps);
const anchorAt = (k: number): TimelineZoomAnchor =>
shift === null
? { time: fromStart + (start - fromStart) * k, x }
: { time: fromStart + shift / from.pps, x: x + shift };
// Zooming out to a view that holds the old one: lay the target out once, in the first frame,
// and ease by scaling it down from the old view, instead of laying out again partway.
const holdsOld =
old.start >= start && old.end <= start + (old.end - old.start) * (from.pps / toPps);
let layoutFirst = toPps < from.pps && from.pps / toPps <= MAX_PREVIEW_SCALE && holdsOld;
const began = performance.now();
easingTo = toPercent;
const step = (now: number) => {
if (layoutFirst) {
layoutFirst = false;
request(toPercent, to, byPerson);
commitPreview();
}
const t = Math.min(1, Math.max(0, (now - began) / SMOOTH_ZOOM_MS));
const k = 1 - (1 - t) ** 3;
request(fromPercent * (toPercent / fromPercent) ** k, anchorAt(k), byPerson);
// Drawn in this frame, not the next: the first one would otherwise paint a laid-out zoom-out bare.
drawPreview();
if (t < 1) animation = requestAnimationFrame(step);
else finish();
};
animation = requestAnimationFrame(step);
}
/**
* A zoom button: twice or half the scale, eased, keeping the playhead where it is on screen,
* or centring it when it is off screen.
*/
export function zoomTimelineStep(direction: "in" | "out"): void {
const fitPps = usePlayerStore.getState().timelineFitPps;
const nextPercent = getNextTimelineZoomPercent(
direction,
"manual",
easingTo ?? currentTimelineZoomPercent(),
fitPps,
);
const view = viewport;
if (!view || !(fitPps > 0)) {
requestTimelineZoom(nextPercent);
return;
}
const { x, width } = rangeBox(view);
const nextPps = getTimelinePixelsPerSecond(fitPps, "manual", nextPercent);
const now = shown(view.scroll);
const at = defaultAnchor(view, now.pps, now.left);
const start = at.time - (at.x - x) / nextPps;
void easeToRange(start, start + width / nextPps, {}, true);
}