Open source CapCut alternative.
TypeScript
feat(site): a move is a slot on the element [rebuild]
David Le2a81cc8a3291
diff --git a/docs/guides/cut/README.md b/docs/guides/cut/README.mdindex a130e079..7917eef4 100644--- a/docs/guides/cut/README.md+++ b/docs/guides/cut/README.md@@ -34,7 +34,7 @@ The client probes the engine's health endpoint (dedicated port first, dev server**Words as the picture.** A lyric video, a kinetic-typography passage, a quote sequence: the assistant places a whole run of lines in one call, carrying a named look. A look is the design of the whole run rather than of one line — the frame color, the cards it cycles, and the ensemble the run walks across its length: the faces it rotates through, the entrances, where successive lines land in the frame, and what each line does while it holds. That is what stops a hundred lines coming out identical and dead center, which is the failure a text video actually has. The looks live in one registry the tools and the skills both read, so adding a look teaches the assistant a new style with no other change. Words ride one of two carriers — a caption track, which holds per-word timings and can light each word as it is sung, or elements, which give each line its own card, color and motion. Text the user already has (lyrics, a script) is timed by aligning it to a transcript of the audio: the recognizer supplies the clock and the user's wording is kept exactly, which is what makes it survive singing.-**Motion is data.** Every animation in the editor — an entrance, an exit, a loop, and the moves an element makes while it holds — is one format: a pose keyframed over a normalized window with cubic-bezier easing, plus a range selector that says how the motion is handed from one character to the next. That is the After Effects text-animator model, the one Lottie serializes, and picking it means a preset and a hand-keyed track are the same object at two levels of convenience: a named move writes the ordinary pose track the user can then drag, and anything no name covers is keyed directly. The library is a JSON asset in the effects kit rather than code, and the menus, tool enums, prompts, and the frame sampler's crop budget are all read from it, so adding an animation is adding an entry. One evaluator samples it, which is what keeps the preview, the export, and the headless worker showing the same motion. A slot may also carry a preset of its own rather than naming one from the library, in the same shape a library entry has — the evaluator cannot tell the two apart, so an animation composed inside a project plays wherever a shipped one does.+**Motion is data.** Every animation in the editor — an entrance, an exit, a loop, and the moves an element makes while it holds — is one format: a pose keyframed over a normalized window with cubic-bezier easing, plus a range selector that says how the motion is handed from one character to the next. That is the After Effects text-animator model, the one Lottie serializes, and picking it means a preset and a hand-keyed track are the same object at two levels of convenience: the named entrances, loops, and moves are slots on the element, evaluated internally, and anything no name covers is keyed directly on the element's own pose track — the track stays whatever the user keys by hand. The library is a JSON asset in the effects kit rather than code, and the menus, tool enums, prompts, and the frame sampler's crop budget are all read from it, so adding an animation is adding an entry. One evaluator samples it, which is what keeps the preview, the export, and the headless worker showing the same motion. A slot may also carry a preset of its own rather than naming one from the library, in the same shape a library entry has — the evaluator cannot tell the two apart, so an animation composed inside a project plays wherever a shipped one does.## The previewdiff --git a/site/packages/effects-kit/src/anim.ts b/site/packages/effects-kit/src/anim.tsindex 8bfc5212..159ac972 100644--- a/site/packages/effects-kit/src/anim.ts+++ b/site/packages/effects-kit/src/anim.ts@@ -108,10 +108,21 @@ export interface OverlayLoop {preset?: MotionPreset;}+/** What the element does while it holds — the push that never stops, the+ * drift across the frame. A hold-catalog id evaluated across the element's+ * whole span; `strength` scales every offset from rest and leaves the timing+ * alone. The keyframe pose track stays the user's own tier: a move never+ * writes keys. */+export interface OverlayMove {+ style: string;+ strength: number;+}+export interface OverlayAnim {in?: OverlayEdge;out?: OverlayEdge;loop?: OverlayLoop;+ move?: OverlayMove;}/** The motion a slot plays: the one it carries, or the catalog entry it@@ -122,6 +133,9 @@ export const edgeMotion = (slot: OverlayEdge | undefined): MotionPreset | undefiexport const loopMotion = (slot: OverlayLoop | undefined): MotionPreset | undefined =>slot ? (slot.preset ?? loopPreset(slot.style)) : undefined;+export const moveMotion = (slot: OverlayMove | undefined): MotionPreset | undefined =>+ slot ? holdPreset(slot.style) : undefined;+// ── the registries, read from the catalog ─────────────────────────────────// A preset added to the motion catalog appears in every menu, tool enum and prompt// without being named anywhere else. The unions above stay hand-written:@@ -188,6 +202,23 @@ export function loopExtent(slot: OverlayLoop | undefined): {return preset ? presetExtent(preset) : { travel: 0, rotates: false };}+/** How far a move strays from rest at its strength — travel in design px,+ * whether it turns, and the largest scale it reaches. The frame sampler pads+ * its crop by all three. */+export function moveExtent(slot: OverlayMove | undefined): {+ travel: number;+ rotates: boolean;+ scale: number;+} {+ const preset = moveMotion(slot);+ if (!preset || !slot) return { travel: 0, rotates: false, scale: 1 };+ const k = slot.strength > 0 ? slot.strength : 1;+ const base = presetExtent(preset);+ let s = 1;+ for (const key of preset.animate.scale ?? []) s = Math.max(s, key.v[0], key.v[1]);+ return { travel: base.travel * k, rotates: base.rotates, scale: 1 + (s - 1) * k };+}+/** Where a per-glyph ramp stands. Renderers walk the element's characters and* ask `glyphAnimAt` where each one sits. */export interface GlyphPhase {@@ -392,9 +423,25 @@ export function evalOverlayAnim(const period = loopPeriod(anim) ?? 1;applyLoop(state, anim.loop, wrap01(tLocal / period), isText);}+ if (anim.move) applyMove(state, anim.move, tLocal, dur);return state;}+/** The move's contribution at `tLocal`: the hold preset sampled across the+ * element's whole [0, dur] span, every offset from rest scaled by strength,+ * folded onto the state the ramps and the loop left. */+function applyMove(state: OverlayAnimState, slot: OverlayMove, tLocal: number, dur: number): void {+ const preset = moveMotion(slot);+ if (!preset || dur <= 0) return;+ const k = slot.strength > 0 ? slot.strength : 1;+ const pose = sampleProperties(preset.animate, tLocal / dur, dur);+ state.dx += pose.dx * k;+ state.dy += pose.dy * k;+ state.rotate += pose.rotate * k;+ state.scale *= 1 + ((pose.sx + pose.sy) / 2 - 1) * k;+ state.alpha *= 1 + (pose.alpha - 1) * k;+}+/** The loop's exact cycle length in seconds (frame sequences render one cycle* and repeat it), or null when the element has no loop. */export function loopPeriod(anim: OverlayAnim | undefined): number | null {@@ -406,14 +453,14 @@ export function loopPeriod(anim: OverlayAnim | undefined): number | null {/** Whether any slot is set (an element with an empty anim object is static). */export function hasOverlayAnim(anim: OverlayAnim | undefined): boolean {- return !!anim && (!!anim.in || !!anim.out || !!anim.loop);+ return !!anim && (!!anim.in || !!anim.out || !!anim.loop || !!anim.move);}/**- * A hold move as the element's own pose track: absolute poses at seconds from- * its start, ready to write onto `kf`. A move is the same keyframe data every- * other animation is — sampled against the element's resting pose so a preset- * entrance still composes over it.+ * A hold move sampled into an element pose track: absolute poses at seconds+ * from its start. Moves used to ship this way — written onto `kf` — and docs+ * saved then still carry these tracks; the loader regenerates them through+ * here to recognize which move wrote one and lift it into `anim.move`.*/export function holdMoveKeys(id: string,diff --git a/site/packages/effects-kit/src/render.ts b/site/packages/effects-kit/src/render.tsindex ab3e4356..499c5ab2 100644--- a/site/packages/effects-kit/src/render.ts+++ b/site/packages/effects-kit/src/render.ts@@ -12,6 +12,7 @@ import {hasGlyphMotion,loopExtent,loopPeriod,+ moveExtent,type GlyphLoopPhase,type GlyphPhase,type OverlayAnim,@@ -793,15 +794,17 @@ export async function renderOverlayFrames(// A per-glyph ramp hands each character its share of the same tracks, so// the preset's own reach already covers where the glyphs get to.const loop = loopExtent(anim?.loop);- const travel = (edgeTravel + loop.travel) * scale;+ const move = moveExtent(anim?.move);+ const travel = (edgeTravel + loop.travel + move.travel) * scale;// A keyframed element carries its own travel and its own zoom: the region// spans every pose the track visits, at the largest scale it reaches.const keyed = hasOverlayKeys(overlay);const extent = poseExtent(overlay);- const maxScale = 1.15 * extent.scale;+ const maxScale = 1.15 * extent.scale * move.scale;const rotates =!!overlay.rotation ||loop.rotates ||+ move.rotates ||(keyed && sortedKeys(overlay.kf!).some((k) => !!k.rotation));let halfW = (base.w * maxScale) / 2 + travel + 4;let halfH = (base.h * maxScale) / 2 + travel + 4;@@ -877,10 +880,10 @@ export async function renderOverlayFrames(};const step = 1 / fps;- // A keyframed pose (or a keyframed mask) changes on its own schedule, so- // there is no still middle and no cycle to repeat: sample the whole element- // frame by frame.- if (keyed || isMaskAnimated(overlay.mask)) {+ // A keyframed pose, a move, or a keyframed mask changes on its own schedule+ // across the whole element, so there is no still middle and no cycle to+ // repeat: sample the element frame by frame.+ if (keyed || anim?.move || isMaskAnimated(overlay.mask)) {const n = Math.max(1, Math.round(dur * fps));for (let i = 0; i < n; i++) {await push(i * step, i === n - 1 ? dur - (n - 1) * step : step);diff --git a/site/src/cut/components/AnimationTiles.tools.ts b/site/src/cut/components/AnimationTiles.tools.tsindex 5f1deb5d..0a783dda 100644--- a/site/src/cut/components/AnimationTiles.tools.ts+++ b/site/src/cut/components/AnimationTiles.tools.ts@@ -31,13 +31,13 @@ export const OVERLAY_ANIMATION_TOOLS = [{name: "set_overlay_animation",description:- `Animate an overlay element (title, shape, or sticker): preset In/Out ramps, a Loop that runs its whole duration, and a Move that says what the element does WHILE it holds. Omitted slots keep their setting; pass "none" to clear one. In/Out styles: ${OVERLAY_ANIM_STYLE_IDS.join(", ")} — slide names are the motion direction; typewriter animates titles only; ${GLYPH_ANIM_STYLE_IDS.join(", ")} move a title's letters one at a time, and move any other kind as one piece. Loop styles: ${OVERLAY_LOOP_STYLE_IDS.join(", ")} — ${GLYPH_LOOP_STYLE_IDS.join(", ")} carry a title's letters on their own delays, and carry any other kind as one piece. A move writes the element's own keyframe pose track, so it lands as ordinary keys the user can then drag; set_overlay_keyframes replaces it when no named move fits.`,+ `Animate an overlay element (title, shape, or sticker): preset In/Out ramps, a Loop that runs its whole duration, and a Move that says what the element does WHILE it holds. Omitted slots keep their setting; pass "none" to clear one. In/Out styles: ${OVERLAY_ANIM_STYLE_IDS.join(", ")} — slide names are the motion direction; typewriter animates titles only; ${GLYPH_ANIM_STYLE_IDS.join(", ")} move a title's letters one at a time, and move any other kind as one piece. Loop styles: ${OVERLAY_LOOP_STYLE_IDS.join(", ")} — ${GLYPH_LOOP_STYLE_IDS.join(", ")} carry a title's letters on their own delays, and carry any other kind as one piece. A move is a slot like the others and never touches the element's keyframe track; use set_overlay_keyframes when no named move fits, and both compose together.`,inputSchema: obj({id: str("Overlay element id"),move: {type: "string",enum: [...TEXT_MOVE_IDS],- description: `What the element does while it holds, written onto its pose track. ${TEXT_MOVE_IDS.filter((m) => m !== "none").map((m) => `${m}: ${TEXT_MOVE_NOTES[m]}`).join(" ")}`,+ description: `What the element does while it holds. ${TEXT_MOVE_IDS.filter((m) => m !== "none").map((m) => `${m}: ${TEXT_MOVE_NOTES[m]}`).join(" ")}`,},move_strength: num(`How hard the move pushes, ${MOVE_STRENGTH_MIN}..${MOVE_STRENGTH_MAX} (1 = as written). Scales every offset from rest and leaves the timing alone, so the move stays on the beat.`diff --git a/site/src/cut/components/AnimationTiles.tsx b/site/src/cut/components/AnimationTiles.tsxindex 19e955c6..2a672fa8 100644--- a/site/src/cut/components/AnimationTiles.tsx+++ b/site/src/cut/components/AnimationTiles.tsx@@ -105,8 +105,8 @@ function demoStateAt(speed: number) {if (slot === "move") {- // A move is a pose track, not a preset slot: sample it straight and hand- // back the same shape the ramps produce, so the tile draws it the same way.+ // A move plays over the element's whole span; the tile sweeps one demo+ // window through it and hands back the same shape the ramps produce.const preset = MOTION.holds[style];if (!preset) return { dx: 0, dy: 0, scale: 1, rotate: 0, alpha: 1 };const pose = sampleProperties(diff --git a/site/src/cut/components/Inspector.tsx b/site/src/cut/components/Inspector.tsxindex 8a767144..b1a3bd04 100644--- a/site/src/cut/components/Inspector.tsx+++ b/site/src/cut/components/Inspector.tsx@@ -92,11 +92,9 @@ import {} from "@/cut/lib/types";import { GRADE_PRESETS, isNeutralGrade } from "@donkeycut/effects-kit";import {- matchTextMove,MOVE_STRENGTH_MAX,MOVE_STRENGTH_MIN,MOVE_STRENGTH_STEP,- textMoveKeys,} from "@/cut/lib/textMotion";import { getPreviewCanvas } from "@/cut/lib/previewCanvas";import { cn } from "@/lib/utils";@@ -1465,7 +1463,8 @@ function writeOverlayAnim(o: Overlay, anim: OverlayAnim, patch: Partial<OverlayAif (!next.in) delete next.in;if (!next.out) delete next.out;if (!next.loop) delete next.loop;- const value = next.in || next.out || next.loop ? next : undefined;+ if (!next.move) delete next.move;+ const value = next.in || next.out || next.loop || next.move ? next : undefined;const st = useEditor.getState();const peers = o.groupId ? st.overlays.filter((x) => x.groupId === o.groupId) : [];const ids = peers.length > 1 ? peers.map((p) => p.id) : [o.id];@@ -1573,7 +1572,7 @@ function AnimationSection({className="anim-open flex h-8 items-center gap-1 rounded-md border border-input px-2.5 text-[11.5px] font-medium text-muted-foreground transition-colors hover:text-foreground"onClick={onOpen}>- {slots.length ? "Change" : "None"}+ {slots.length || anim.move ? "Change" : "None"}<ChevronRight className="size-3.5 shrink-0" /></button>}@@ -1604,29 +1603,17 @@ function AnimationSection({);}-/** The move's strength: how hard the hold pushes, rewritten into the pose- * track on every step. The slider sits in two places — the collapsed- * section, and the animation panel's Move tab — so it is one component. */-function MoveStrengthSlider({- overlay: o,- move,- label,-}: {- overlay: Overlay;- move?: { id: string; strength: number };- label: string;-}) {+/** The move's strength: how hard the hold pushes. The slider sits in two+ * places — the collapsed section, and the animation panel's Move tab — so it+ * is one component. */+function MoveStrengthSlider({ overlay: o, label }: { overlay: Overlay; label: string }) {const ck = useSliderCheckpoint();+ const anim = o.anim ?? {};+ const move = anim.move;const write = (strength: number) => {if (!move) return;ck.begin();- const keys = textMoveKeys(- move.id,- { x: o.x, y: o.y, rotation: o.rotation ?? 0 },- o.end - o.start,- strength- );- useEditor.getState().updateOverlay(o.id, { kf: keys ?? [] });+ writeOverlayAnim(o, anim, { move: { ...move, strength } });};return (<Row label={label}>@@ -1653,15 +1640,11 @@ function MoveStrengthSlider({}/** The strength row in the collapsed section, there only once a move is on- * the element — a move lives on the pose track rather than in an animation- * slot, so there is no card above it to explain an empty slider. */+ * the element — an empty slider with no move to scale would explain+ * nothing. */function MoveStrengthRow({ overlay: o }: { overlay: Overlay }) {- const move = useMemo(- () => matchTextMove(o.kf, { x: o.x, y: o.y, rotation: o.rotation ?? 0 }, o.end - o.start),- [o.kf, o.x, o.y, o.rotation, o.start, o.end]- );- if (!move) return null;- return <MoveStrengthSlider overlay={o} move={move} label="Move strength" />;+ if (!o.anim?.move) return null;+ return <MoveStrengthSlider overlay={o} label="Move strength" />;}/** The animation subview an overlay panel pushes into: In / Out / Loop tabs@@ -1674,34 +1657,19 @@ function AnimationPanel({ overlay: o, onBack }: { overlay: Overlay; onBack: () =const active = slot === "move" ? undefined : anim[slot];const seconds =slot === "loop" || slot === "move" ? undefined : (anim[slot] as OverlayAnim["in"])?.seconds;- // Which move wrote the element's keys, and how hard. Nothing is stored on- // the element: the match is recomputed, so keys the user has since dragged- // stop matching and the tab simply shows none selected.- const activeMove = useMemo(- () => matchTextMove(o.kf, { x: o.x, y: o.y, rotation: o.rotation ?? 0 }, o.end - o.start),- [o.kf, o.x, o.y, o.rotation, o.start, o.end]- );+ const activeMove = anim.move;const pick = (style: string | null) => {if (slot === "move") {- // Nothing here wrote this track — the user keyed it by hand — so "None"- // has no move to take off and those keys stay put.if (!style && !activeMove) return;useEditor.getState().pushHistory();- // A move is not a fourth animation slot: it writes the same pose track- // the keyframe diamond writes, so the keys stay the user's to drag.// A newly picked move starts at full strength; switching moves keeps// whatever strength the last one was set to.- const keys = style- ? textMoveKeys(- style,- { x: o.x, y: o.y, rotation: o.rotation ?? 0 },- o.end - o.start,- activeMove?.strength ?? 1- )- : undefined;- useEditor.getState().updateOverlay(o.id, { kf: keys ?? [] });+ const patch: Partial<OverlayAnim> = {+ move: style ? { style, strength: activeMove?.strength ?? 1 } : undefined,+ };+ writeOverlayAnim(o, anim, patch);// The pick plays itself on the stage, the same as any other slot.- if (keys) playAnimPreview(o, "move");+ if (style) playAnimPreview({ ...o, anim: { ...anim, ...patch } }, "move");else stopAnimPreview();return;}@@ -1780,7 +1748,7 @@ function AnimationPanel({ overlay: o, onBack }: { overlay: Overlay; onBack: () =// A slot carrying its own preset is playing something no tile here// names, so the grid shows nothing selected rather than the catalog// entry the id happens to hold.- value={active?.preset ? undefined : slot === "move" ? activeMove?.id : active?.style}+ value={active?.preset ? undefined : slot === "move" ? activeMove?.style : active?.style}custom={!!active?.preset}isText={isTextOverlay(o)}seconds={seconds ?? OVERLAY_ANIM_DEFAULT_SECONDS}@@ -1788,7 +1756,7 @@ function AnimationPanel({ overlay: o, onBack }: { overlay: Overlay; onBack: () =onPick={pick}/></ScrollArea>- <AnimationToolbar overlay={o} slot={slot} move={activeMove} />+ <AnimationToolbar overlay={o} slot={slot} /></div>);}@@ -1802,11 +1770,9 @@ function AnimationPanel({ overlay: o, onBack }: { overlay: Overlay; onBack: () =function AnimationToolbar({overlay: o,slot,- move,}: {overlay: Overlay;slot: "in" | "out" | "loop" | "move";- move?: { id: string; strength: number };}) {const ck = useSliderCheckpoint();const anim = o.anim ?? {};@@ -1817,8 +1783,7 @@ function AnimationToolbar({<div className="shrink-0 border-t border-border bg-card px-3.5 py-0.5">{children}</div>);- if (slot === "move")- return bar(<MoveStrengthSlider overlay={o} move={move} label="Strength" />);+ if (slot === "move") return bar(<MoveStrengthSlider overlay={o} label="Strength" />);if (slot === "loop") {const write = (speed: number) => {diff --git a/site/src/cut/components/Timeline.tools.ts b/site/src/cut/components/Timeline.tools.tsindex 4d233238..8c7bf458 100644--- a/site/src/cut/components/Timeline.tools.ts+++ b/site/src/cut/components/Timeline.tools.ts@@ -212,7 +212,7 @@ export const TIMELINE_TOOLS = [type: "string",enum: [...TEXT_VARIATION_IDS],description:- "How far the run departs from one repeated design. Defaults to what the look carries: the plain look runs at none, the designed looks at bold. bold walks the look's whole ensemble — faces, tilts, palette, keyframe moves; subtle keeps one typeface and varies placement and entrance; none lays every line identical.",+ "How far the run departs from one repeated design. Defaults to what the look carries: the plain look runs at none, the designed looks at bold. bold walks the look's whole ensemble — faces, tilts, palette, moves; subtle keeps one typeface and varies placement and entrance; none lays every line identical.",},layout: {type: "string",@@ -248,7 +248,7 @@ export const TIMELINE_TOOLS = [move: {type: "string",enum: [...TEXT_MOVE_IDS],- description: `What this line does WHILE it holds (a keyframe move; the entrance is separate). ${TEXT_MOVE_IDS.filter((m) => m !== "none").map((m) => `${m}: ${TEXT_MOVE_NOTES[m]}`).join(" ")}`,+ description: `What this line does WHILE it holds (the entrance is separate). ${TEXT_MOVE_IDS.filter((m) => m !== "none").map((m) => `${m}: ${TEXT_MOVE_NOTES[m]}`).join(" ")}`,},},["text"]diff --git a/site/src/cut/lib/aiTools.ts b/site/src/cut/lib/aiTools.tsindex 62de1602..fd4425d7 100644--- a/site/src/cut/lib/aiTools.ts+++ b/site/src/cut/lib/aiTools.ts@@ -107,7 +107,6 @@ import {MOVE_STRENGTH_MAX,MOVE_STRENGTH_MIN,TEXT_MOVE_IDS,- textMoveKeys,type TextMoveId,} from "./textMotion";import { queueWatchSweep, withSweepPaused } from "./watch/sweep";@@ -436,28 +435,21 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {};edge("in", "in_style", "in_seconds");edge("out", "out_style", "out_seconds");- // A move is not a fourth slot on the element: it writes the pose track- // the inspector's diamond writes, so the user can drag the keys after.if (typeof input.move === "string") {- if (input.move === "none") s.updateOverlay(o.id, { kf: [] });+ if (input.move === "none") delete anim.move;else {if (!TEXT_MOVE_IDS.includes(input.move))throw new ToolError(`Unknown move: ${input.move}. Use one of: ${TEXT_MOVE_IDS.join(", ")}.`);const strength = isNum(input.move_strength)? clamp(input.move_strength, MOVE_STRENGTH_MIN, MOVE_STRENGTH_MAX)- : 1;- const keys = textMoveKeys(- input.move,- { x: o.x, y: o.y, rotation: o.rotation ?? 0 },- o.end - o.start,- strength- );- if (!keys)- throw new ToolError(- `This element is too short for a move to read (${round2(o.end - o.start)}s).`- );- s.updateOverlay(o.id, { kf: keys });+ : (anim.move?.strength ?? 1);+ anim.move = { style: input.move, strength };}+ } else if (isNum(input.move_strength) && anim.move) {+ anim.move = {+ ...anim.move,+ strength: clamp(input.move_strength, MOVE_STRENGTH_MIN, MOVE_STRENGTH_MAX),+ };}const rawLoop = input.loop_style;const speed = isNum(input.loop_speed) ? clamp(input.loop_speed, 0.25, 4) : undefined;@@ -469,7 +461,9 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {} else if (speed !== undefined && anim.loop) {anim.loop = { ...anim.loop, speed };}- s.updateOverlay(o.id, { anim: anim.in || anim.out || anim.loop ? anim : undefined });+ s.updateOverlay(o.id, {+ anim: anim.in || anim.out || anim.loop || anim.move ? anim : undefined,+ });const next = useEditor.getState().overlays.find((x) => x.id === o.id)!;return { id: next.id, anim: next.anim ?? null };},@@ -1529,10 +1523,7 @@ const toolRuns: Record<BrowserToolName, ToolRun> = {shadow: look.text.shadow ?? false,align: "center",});- useEditor.getState().updateOverlay(sel.id, {- anim: line.anim,- ...(line.kf ? { kf: line.kf } : {}),- });+ useEditor.getState().updateOverlay(sel.id, { anim: line.anim });const o = useEditor.getState().overlays.find((x) => x.id === sel.id);if (o) made.push({ id: o.id, start: round2(o.start), end: round2(o.end), text: line.text });});diff --git a/site/src/cut/lib/animPreview.ts b/site/src/cut/lib/animPreview.tsindex 290c38bb..d806dd68 100644--- a/site/src/cut/lib/animPreview.ts+++ b/site/src/cut/lib/animPreview.ts@@ -89,8 +89,6 @@ export function playAnimPreview(slot: "in" | "out" | "loop" | "move"): void {stopAnimPreview();- // A move is not an anim slot: it is written into the element's own pose- // track, so its run carries no anim at all and the track alone draws it.const anim: OverlayAnim =slot === "in"? { in: o.anim?.in }@@ -98,7 +96,8 @@ export function playAnimPreview(? { out: o.anim?.out }: slot === "loop"? { loop: o.anim?.loop }- : {};+ : { move: o.anim?.move };+ if (slot === "move" && !anim.move) return;const dur = Math.max(0.1, o.end - o.start);const span =slot === "move"diff --git a/site/src/cut/lib/store.ts b/site/src/cut/lib/store.tsindex 9ffe3c8b..b7d976e9 100644--- a/site/src/cut/lib/store.ts+++ b/site/src/cut/lib/store.ts@@ -61,6 +61,7 @@ import { clampPlayhead, playheadAt, previewAt, setPlayhead, setSkim } from "./plimport { engineTranscribeSamples, withEngineStt } from "./localStt";import { trackLocale } from "./subtitles";import { ANIM_STYLE_IDS, animStyleOfTransition, clipPoseAt, DEFAULT_BACKGROUND, emptySubtitles, frameOf, IMAGE_CLIP_SECONDS, isEffectOverlay, isStickerOverlay, MAX_SUBTITLE_LANES, mediaUrl, migrateBehindSubject, migrateLegacyTransitions, normalizeAspect, overlayAnimStyle, projectBackground, SPEED_FLOOR, SPEED_MIN, stampOverlayKinds, stripDefaultOverlayKinds, TRANSITION_MAX, TRANSITION_STYLE_IDS, transitionStyleOfAnim } from "./types";+import { liftMoveTracks } from "./textMotion";import { readTextStyle } from "./textStyle";import { loadUiState, saveUiState, type ProjectUiState } from "./uiState";import { captureTimelineFrames } from "./visualFrames";@@ -183,6 +184,18 @@ function placedState(export const TIMELINE_H_DEFAULT = 272;export const TIMELINE_H_MIN = 194;+/**+ * Timeline zoom bounds, in px per second of media. The low end is a sanity+ * floor only: how far out a project may zoom depends on how wide the timeline+ * is on screen, which the store cannot see, so the real floor is the+ * viewport-aware one the timeline computes (`zoomFloor`). A long project needs+ * to reach well under a px/s for its whole strip to fit, so anything higher+ * here silently overrides that and puts the end of the project out of reach.+ */+export const PPS_MIN = 0.01;+export const PPS_MAX = 800;+const clampPps = (v: number) =>+ Number.isFinite(v) ? Math.max(PPS_MIN, Math.min(PPS_MAX, v)) : 60;/** Tallest the timeline may grow: the window height less room for the top bar* and a usable preview. The constant covers code running without a window. */export const timelineHMax = () =>@@ -1725,9 +1738,11 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {// back when a look was a clip property gets that grade as an element// over it — so a project made before either rule reads like a new one.// The behind-speaker boolean becomes an inverted subject mask on load,- // so one mask model covers it everywhere in memory and on save.- const stamped = normalizeElementLanes(- migrateBehindSubject(stampOverlayKinds(doc.overlays ?? []))+ // so one mask model covers it everywhere in memory and on save. Key+ // tracks written by the retired move picker lift into the move slot,+ // leaving `kf` to the keys users set themselves.+ const stamped = liftMoveTracks(+ normalizeElementLanes(migrateBehindSubject(stampOverlayKinds(doc.overlays ?? []))));const subtitles = doc.subtitles ?? emptySubtitles();// Docs saved when edge transition styles existed convert them into the@@ -1768,7 +1783,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {background: projectBackground(doc.background),// View state lives in IndexedDB; doc.ui covers projects saved// before the move.- pxPerSec: Math.max(12, Math.min(800, ui.pxPerSec ?? doc.ui?.pxPerSec ?? 60)),+ pxPerSec: clampPps(ui.pxPerSec ?? doc.ui?.pxPerSec ?? 60),timelineH: Math.max(TIMELINE_H_MIN,Math.min(timelineHMax(), ui.timelineH ?? TIMELINE_H_DEFAULT)@@ -3494,13 +3509,15 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {...(a.duck !== undefined && a.duck < 1 ? { duck: a.duck } : {}),...(a.lane ? { lane: a.lane } : {}),}));- // Templates saved before the union carry bare titles — same stamp and- // behind-speaker migration as the doc loader, so every in-memory- // element has its discriminant and one mask model. Groups are remapped- // per application, so adding the same template twice gives two- // independent groups.+ // Templates saved before the union carry bare titles — same stamp,+ // behind-speaker migration, and move-track lift as the doc loader, so+ // every in-memory element has its discriminant, one mask model, and its+ // move in the slot. Groups are remapped per application, so adding the+ // same template twice gives two independent groups.const regroup = groupRemap(uid);- const newTexts: Overlay[] = migrateBehindSubject(stampOverlayKinds(template.texts)).map((o) => ({+ const newTexts: Overlay[] = liftMoveTracks(+ migrateBehindSubject(stampOverlayKinds(template.texts))+ ).map((o) => ({...o,id: uid(),start: o.start + shift,@@ -4279,7 +4296,7 @@ export const useEditor = create<EditorState>((baseSet, get, api) => {},})),setPxPerSec: (v) => {- const pxPerSec = Math.max(12, Math.min(800, v));+ const pxPerSec = clampPps(v);set({ pxPerSec });const id = get().projectId;if (id) saveUiState(id, { pxPerSec: Math.round(pxPerSec * 100) / 100 });diff --git a/site/src/cut/lib/textCompose.ts b/site/src/cut/lib/textCompose.tsindex e0d046b7..714136ce 100644--- a/site/src/cut/lib/textCompose.ts+++ b/site/src/cut/lib/textCompose.ts@@ -1,6 +1,6 @@-import type { OverlayAnim, OverlayAnimStyle, OverlayKey } from "@donkeycut/effects-kit";+import type { OverlayAnim, OverlayAnimStyle } from "@donkeycut/effects-kit";import type { TextLook } from "./textLooks";-import { type TextMoveId, textMoveKeys } from "./textMotion";+import type { TextMoveId } from "./textMotion";import type { FontId } from "./types";/**@@ -172,7 +172,7 @@ export interface TextEnsemble {/** Entrances, walked one per line. */motion: OverlayAnimStyle[];layout: TextLayout;- /** Keyframe moves the run walks while each line HOLDS — see textMotion.ts.+ /** Moves the run walks while each line HOLDS — see textMotion.ts.* Entrances say how a line arrives; these say what it does after. */moves: TextMoveId[];/** The move a hero line takes regardless of where the rota is. */@@ -197,7 +197,7 @@ export interface ComposeLine {y?: number;rotation?: number;inStyle?: OverlayAnimStyle;- /** A named keyframe move for this line, overriding the look's rota. */+ /** A named move for this line, overriding the look's rota. */move?: TextMoveId;}@@ -215,7 +215,6 @@ export interface ComposedLine {color: string;anim: OverlayAnim;move: TextMoveId | string;- kf?: OverlayKey[];/** Which of the look's cards sits behind this line. */cardIndex: number;}@@ -364,24 +363,23 @@ export function composeTextRun(const inStyle = line.inStyle ?? step(motions, i + sec);const inSeconds = Math.min(look.motion.in?.seconds ?? 0.35, Math.max(0.12, (line.end - line.start) * 0.4));- const anim: OverlayAnim = {- in: { style: inStyle, seconds: round2(inSeconds) },- ...(look.motion.out ? { out: look.motion.out } : {}),- ...(look.motion.loop- ? { loop: { style: look.motion.loop.style, speed: look.motion.loop.speed ?? 1 } }- : {}),- };const cardIndex = cardCount > 0 ? i % cardCount : -1;const onCard = cardIndex >= 0 && onCards.length > 0 ? step(onCards, cardIndex) : undefined;// What the line does while it holds. A hero line takes the look's hero// move; everything else walks the rota, so no two neighbours move alike.- const dur = line.end - line.start;const moveId =line.move ??(emphasis === "hero" ? ens?.heroMove ?? step(moves, i + sec) : step(moves, i + sec));- const kf = textMoveKeys(moveId, { x, y, rotation: tilt }, dur);+ const anim: OverlayAnim = {+ in: { style: inStyle, seconds: round2(inSeconds) },+ ...(look.motion.out ? { out: look.motion.out } : {}),+ ...(look.motion.loop+ ? { loop: { style: look.motion.loop.style, speed: look.motion.loop.speed ?? 1 } }+ : {}),+ ...(moveId && moveId !== "none" ? { move: { style: moveId, strength: 1 } } : {}),+ };return {text: fit.text,@@ -397,7 +395,6 @@ export function composeTextRun(color: line.color ?? onCard ?? step(palette, i + sec),anim,move: moveId,- ...(kf ? { kf } : {}),cardIndex,};});diff --git a/site/src/cut/lib/textMotion.ts b/site/src/cut/lib/textMotion.tsindex 1f723321..3aa995b6 100644--- a/site/src/cut/lib/textMotion.ts+++ b/site/src/cut/lib/textMotion.ts@@ -1,17 +1,19 @@import { holdMoveKeys, HOLD_IDS, MOTION } from "@donkeycut/effects-kit";-import type { OverlayKey } from "@donkeycut/effects-kit";+import type { OverlayAnim, OverlayKey } from "@donkeycut/effects-kit";/**- * Named keyframe moves for text.+ * Named moves for text.** Preset In/Out ramps decide how a line ARRIVES. These decide what it does* while it holds — the push-in that never stops, the drift across the frame,* the swing that overshoots and settles. That is the difference between text* that appears and text that is alive.*- * A move is not a special mechanism: it is an entry in the same motion- * catalog every entrance and loop lives in, sampled against the element's- * resting pose into the ordinary `kf` track a user could have keyed by hand.+ * A move lives in the element's `anim.move` slot beside In/Out/Loop and is+ * evaluated internally with them. The keyframe pose track stays the user's+ * own tier: picking a move never writes keys. Docs saved when moves shipped+ * as sampled key tracks still carry those keys; `liftMoveTracks` recognizes+ * them on load and lifts each into the slot.*/export type TextMoveId = string;@@ -35,9 +37,9 @@ export const MOVE_STRENGTHS: number[] = Array.from((_, i) => Math.round((MOVE_STRENGTH_MIN + i * MOVE_STRENGTH_STEP) * 100) / 100);-/** The pose track for a named move on an element resting at `rest` for- * `dur` seconds, scaled by `strength`. An unknown id, "none", or a duration- * too short to read gives back no track at all. */+/** The legacy pose track for a named move on an element resting at `rest`+ * for `dur` seconds, scaled by `strength` — the shape moves were saved in+ * when they wrote keys. Regenerated only to recognize old tracks on load. */export function textMoveKeys(id: string | undefined,rest: { x: number; y: number; rotation: number },@@ -48,9 +50,9 @@ export function textMoveKeys(return holdMoveKeys(id, rest, dur, strength);}-/** Which move wrote a pose track, and at what strength. Nothing is stored on- * the element: the answer is found by regenerating each move and seeing which- * one matches, so keys the user has since dragged simply stop matching. */+/** Which move wrote a legacy pose track, and at what strength. The answer is+ * found by regenerating each move and seeing which one matches, so keys the+ * user has since dragged simply stop matching and stay theirs. */export function matchTextMove(kf: OverlayKey[] | undefined,rest: { x: number; y: number; rotation: number },@@ -99,3 +101,33 @@ export function matchTextMove(/** The moves as prompt text: one line per id. */export const textMoveCatalog = (): string =>HOLD_IDS.map((id) => `- ${id}: ${TEXT_MOVE_NOTES[id]}`).join("\n");++/**+ * Lift legacy move key tracks into the `anim.move` slot on load. An element+ * whose `kf` regenerates exactly from one named move at one strength was+ * written by the old move picker, so it drops the keys and carries the move+ * in its slot; any other track is the user's own and is left alone.+ */+export function liftMoveTracks<+ T extends {+ kf?: OverlayKey[];+ anim?: OverlayAnim;+ x: number;+ y: number;+ rotation?: number;+ start: number;+ end: number;+ },+>(overlays: T[]): T[] {+ if (!overlays.some((o) => o.kf && o.kf.length > 0 && !o.anim?.move)) return overlays;+ return overlays.map((o) => {+ if (!o.kf || o.kf.length === 0 || o.anim?.move) return o;+ const m = matchTextMove(o.kf, { x: o.x, y: o.y, rotation: o.rotation ?? 0 }, o.end - o.start);+ if (!m) return o;+ return {+ ...o,+ kf: undefined,+ anim: { ...(o.anim ?? {}), move: { style: m.id, strength: m.strength } },+ };+ });+}diff --git a/site/src/cut/lib/textVideo.test.ts b/site/src/cut/lib/textVideo.test.tsindex e333a4f5..cb44cb3c 100644--- a/site/src/cut/lib/textVideo.test.ts+++ b/site/src/cut/lib/textVideo.test.ts@@ -3,7 +3,8 @@ import { runAiTool } from "./aiTools";import { useEditor } from "./store";import { composeTextRun, TEXT_LAYOUT_IDS, TEXT_LAYOUT_NOTES } from "./textCompose";import { TEXT_LOOKS, textLookCatalog } from "./textLooks";-import { matchTextMove, TEXT_MOVE_IDS, TEXT_MOVE_NOTES, textMoveKeys } from "./textMotion";+import { evalOverlayFrame } from "@donkeycut/effects-kit";+import { liftMoveTracks, matchTextMove, TEXT_MOVE_IDS, TEXT_MOVE_NOTES, textMoveKeys } from "./textMotion";import { emptySubtitles, frameOf, isTextOverlay, isShapeOverlay, type SubtitleCue } from "./types";/**@@ -65,13 +66,13 @@ describe("add_text_sequence", () => {const words = overlays().filter(isTextOverlay);expect(overlays().filter(isShapeOverlay)).toHaveLength(0);expect(words).toHaveLength(3);- // One face, one place, one entrance, no keyframe moves, no tilt.+ // One face, one place, one entrance, no moves, no tilt.expect(new Set(words.map((w) => w.font)).size).toBe(1);expect(new Set(words.map((w) => w.y)).size).toBe(1);expect(new Set(words.map((w) => w.x)).size).toBe(1);expect(new Set(words.map((w) => w.color)).size).toBe(1);expect(words.every((w) => (w.rotation ?? 0) === 0)).toBe(true);- expect(words.every((w) => !w.kf || w.kf.length === 0)).toBe(true);+ expect(words.every((w) => !w.anim?.move)).toBe(true);expect(words.every((w) => w.anim?.in?.style === "fade")).toBe(true);// The frame color is the user's, not the look's.expect(useEditor.getState().background).toBe("#123456");@@ -242,7 +243,7 @@ describe("composing a run", () => {const words = await runOf();expect(new Set(words.map((w) => w.font)).size).toBeGreaterThan(1);expect(new Set(words.map((w) => w.anim?.in?.style)).size).toBeGreaterThan(1);- expect(words.filter((w) => (w.kf?.length ?? 0) > 1).length).toBeGreaterThan(0);+ expect(words.filter((w) => !!w.anim?.move).length).toBeGreaterThan(0);});test('variation "none" lays the run exactly as the look describes it', async () => {@@ -250,7 +251,7 @@ describe("composing a run", () => {const words = await runOf({ variation: "none" });expect(new Set(words.map((w) => `${w.x},${w.y}`)).size).toBe(1);expect(new Set(words.map((w) => w.font))).toEqual(new Set([look.text.font]));- expect(words.every((w) => (w.kf?.length ?? 0) === 0)).toBe(true);+ expect(words.every((w) => !w.anim?.move)).toBe(true);});test("a named layout overrides the look's own", async () => {@@ -313,7 +314,7 @@ describe("composing a run", () => {expect(b.y).toBeCloseTo(0.8, 2);expect(b.rotation).toBe(12);expect(b.anim?.in?.style).toBe("wipe");- expect(b.kf!.length).toBeGreaterThan(2);+ expect(b.anim?.move?.style).toBe("orbit");});test("a line placed off-axis is broken to the room it actually has", async () => {@@ -338,7 +339,7 @@ describe("composing a run", () => {});});-describe("keyframe moves", () => {+describe("legacy move tracks", () => {test("every id has a note and a track, and none outlives its element", () => {for (const id of TEXT_MOVE_IDS) {expect(TEXT_MOVE_NOTES[id].length).toBeGreaterThan(0);@@ -412,26 +413,27 @@ describe("moves on an existing element", () => {return overlays().filter(isTextOverlay)[0];};- test("a named move writes the element's own pose track", async () => {+ test("a named move lands in the slot and leaves the keyframe track alone", async () => {const o = await aTitle();await runAiTool("set_overlay_animation", { id: o.id, move: "push" });const after = overlays().filter(isTextOverlay)[0];- expect(after.kf!.length).toBeGreaterThan(1);+ expect(after.anim?.move).toEqual({ style: "push", strength: 1 });+ expect(after.kf ?? []).toHaveLength(0);// A push grows across the hold and never leaves its resting spot.- expect(after.kf![after.kf!.length - 1].scale).toBeGreaterThan(after.kf![0].scale);- for (const key of after.kf!) {- expect(key.x).toBeCloseTo(after.x, 3);- expect(key.t).toBeGreaterThanOrEqual(0);- expect(key.t).toBeLessThanOrEqual(after.end - after.start + 1e-6);- }+ const dur = after.end - after.start;+ const early = evalOverlayFrame(after, 0.1);+ const late = evalOverlayFrame(after, dur - 0.1);+ expect(late.scale).toBeGreaterThan(early.scale);+ expect(late.x).toBeCloseTo(after.x, 3);+ expect(late.dx).toBeCloseTo(0, 3);});- test('move "none" clears the track', async () => {+ test('move "none" clears the slot', async () => {const o = await aTitle();await runAiTool("set_overlay_animation", { id: o.id, move: "swing" });- expect(overlays().filter(isTextOverlay)[0].kf!.length).toBeGreaterThan(1);+ expect(overlays().filter(isTextOverlay)[0].anim?.move?.style).toBe("swing");await runAiTool("set_overlay_animation", { id: o.id, move: "none" });- expect(overlays().filter(isTextOverlay)[0].kf ?? []).toHaveLength(0);+ expect(overlays().filter(isTextOverlay)[0].anim?.move).toBeUndefined();});test("an unknown move is refused", async () => {@@ -450,30 +452,76 @@ describe("moves on an existing element", () => {await runAiTool("set_overlay_animation", { id: o.id, in_style: "rise", move: "float" });const after = overlays().filter(isTextOverlay)[0];expect(after.anim?.in?.style).toBe("rise");- expect(after.kf!.length).toBeGreaterThan(1);+ expect(after.anim?.move?.style).toBe("float");});});describe("every move is real motion", () => {- test("each id moves the element somewhere", () => {+ test("each id moves the element somewhere, straight from its slot", () => {for (const id of TEXT_MOVE_IDS) {- const keys = textMoveKeys(id, { x: 0.5, y: 0.5, rotation: 0 }, 2.5);- if (id === "none") {- expect(keys).toBeUndefined();- continue;- }- expect(keys!.length).toBeGreaterThan(1);- const moves = keys!.some(- (k) =>- Math.abs(k.x - keys![0].x) > 1e-4 ||- Math.abs(k.y - keys![0].y) > 1e-4 ||- Math.abs(k.scale - keys![0].scale) > 1e-3 ||- Math.abs(k.rotation - keys![0].rotation) > 1e-3 ||- Math.abs(k.opacity - keys![0].opacity) > 1e-3- );+ if (id === "none") continue;+ const o = {+ start: 0,+ end: 2.5,+ x: 0.5,+ y: 0.5,+ anim: { move: { style: id, strength: 1 } },+ };+ const rest = evalOverlayFrame(o, 0);+ const moves = [0.4, 1.1, 1.9, 2.5].some((t) => {+ const f = evalOverlayFrame(o, t);+ return (+ Math.abs(f.dx - rest.dx) > 0.1 ||+ Math.abs(f.dy - rest.dy) > 0.1 ||+ Math.abs(f.scale - rest.scale) > 1e-3 ||+ Math.abs(f.rotation - rest.rotation) > 1e-3 ||+ Math.abs(f.opacity - rest.opacity) > 1e-3+ );+ });expect(moves).toBe(true);}});++ test("strength scales the offsets and leaves the timing alone", () => {+ const at = (strength: number, t: number) =>+ evalOverlayFrame(+ { start: 0, end: 3, x: 0.5, y: 0.5, anim: { move: { style: "push", strength } } },+ t+ );+ const full = at(1, 2);+ const half = at(0.5, 2);+ expect(half.scale - 1).toBeCloseTo((full.scale - 1) / 2, 5);+ });+});++describe("lifting legacy move tracks", () => {+ const rest = { x: 0.5, y: 0.5, rotation: 0 };+ const el = (+ kf?: ReturnType<typeof textMoveKeys>+ ): Parameters<typeof liftMoveTracks>[0][number] => ({+ start: 0,+ end: 2.5,+ x: rest.x,+ y: rest.y,+ rotation: rest.rotation,+ ...(kf ? { kf } : {}),+ });++ test("a track a move wrote becomes the move's slot and drops its keys", () => {+ const [lifted] = liftMoveTracks([el(textMoveKeys("orbit", rest, 2.5, 0.5))]);+ expect(lifted.anim?.move).toEqual({ style: "orbit", strength: 0.5 });+ expect(lifted.kf).toBeUndefined();+ });++ test("keys the user set stay theirs", () => {+ const keys = textMoveKeys("swing", rest, 2.5, 1)!;+ keys[1] = { ...keys[1], x: keys[1].x + 0.2 };+ const [kept] = liftMoveTracks([el(keys)]);+ expect(kept.anim?.move).toBeUndefined();+ expect(kept.kf).toEqual(keys);+ const [plain] = liftMoveTracks([el()]);+ expect(plain.anim?.move).toBeUndefined();+ });});describe("move strength", () => {@@ -513,8 +561,6 @@ describe("move strength", () => {const o = overlays().filter(isTextOverlay)[0];await runAiTool("set_overlay_animation", { id: o.id, move: "push", move_strength: 0.5 });const after = overlays().filter(isTextOverlay)[0];- expect(- matchTextMove(after.kf, { x: after.x, y: after.y, rotation: after.rotation ?? 0 }, 3)- ).toEqual({ id: "push", strength: 0.5 });+ expect(after.anim?.move).toEqual({ style: "push", strength: 0.5 });});});diff --git a/site/src/cut/server/ai/catalog.ts b/site/src/cut/server/ai/catalog.tsindex d4aa3879..ee54aee7 100644--- a/site/src/cut/server/ai/catalog.ts+++ b/site/src/cut/server/ai/catalog.ts@@ -190,7 +190,7 @@ In the UI: the timeline toolbar adds Text; the Elements side-panel tab browses s"text-videos": `# Text-driven videos: lyrics, kinetic type, quote cardsA video whose picture is words. Three pieces: the frame behind them (set_background, or the user's footage), the words themselves, and the clock that says when each line lands. For the device list — fifty ways to make a run of text worth watching — read the text-creativity skill.-**Design is something the user asks for.** "Add the text", "put what he says on screen", "add text from the audio" is a plain job: get the words and their times — the cues already in editor_state, a source's transcript, listen_audio, or subtitles_generate when the user wants a caption track — then place them with add_text_sequence and no \`look\`. That lays one readable face at one spot with a short fade, no cards, no keyframe moves, no tilts, and no repaint of the frame. Then align_to_audio: the times you placed came from a transcript, and that pass measures them against the mix's own waveform and moves each edge onto the speech. Reach for a look, cards, moves, or a variation only when the ask carries a design in it: a lyric video, kinetic type, a named style or vibe, "make it fun", a reference to match. A cut that comes back restyled when the user asked for words on screen is the failure this default exists to prevent.+**Design is something the user asks for.** "Add the text", "put what he says on screen", "add text from the audio" is a plain job: get the words and their times — the cues already in editor_state, a source's transcript, listen_audio, or subtitles_generate when the user wants a caption track — then place them with add_text_sequence and no \`look\`. That lays one readable face at one spot with a short fade, no cards, no moves, no tilts, and no repaint of the frame. Then align_to_audio: the times you placed came from a transcript, and that pass measures them against the mix's own waveform and moves each edge onto the speech. Reach for a look, cards, moves, or a variation only when the ask carries a design in it: a lyric video, kinetic type, a named style or vibe, "make it fun", a reference to match. A cut that comes back restyled when the user asked for words on screen is the failure this default exists to prevent.**Two ways to carry the words.** A caption track is one styled row of text that follows a voice — it holds word timings, so karaoke (each word lighting as it is sung) is only possible here, and one call restyles every line. Elements are separate titles and cards on the timeline — per-line face, per-line placement, per-glyph motion, a color card behind each line — which is what kinetic typography and lyric cards are made of. Captions for a song you want to sing along to; elements when each line is its own picture. Both burn into the export.@@ -198,7 +198,7 @@ A video whose picture is words. Three pieces: the frame behind them (set_backgro${textLookCatalog()}**Composing a run (this is the part that decides whether it reads as creative).** add_text_sequence takes the whole run in one call and walks the look's rotas by index, so no two neighbouring lines land the same. Steer it:-- \`variation\`: bold (default) walks faces, tilts, palette and keyframe moves; subtle keeps one face and varies placement and entrance; none lays every line identical — only for a run you are about to hand-compose yourself.+- \`variation\`: bold (default) walks faces, tilts, palette and moves; subtle keeps one face and varies placement and entrance; none lays every line identical — only for a run you are about to hand-compose yourself.- \`layout\` overrides where lines land: ${TEXT_LAYOUT_IDS.map((id) => `${id} — ${TEXT_LAYOUT_NOTES[id]}`).join(" ")}- \`emphasis\` per line: hero is markedly bigger and takes the look's hero move, whisper is small and quiet. Mark the hook, the title line, the punchline. Two or three heroes in a verse; a run where everything is a hero is a run where nothing is.- \`section\` per line ("verse", "chorus", "bridge"): a new label restarts the type and color rotas, so a chorus does not look like the verse before it. Label every line of a song — it is the cheapest way to make three passages read as three passages.@@ -270,7 +270,7 @@ Read this before any text-heavy job the user calls flat, boring, samey, or "not**Everything here is keyframes.** Entrances, exits, loops and moves are one format: a pose (position, scale, rotation, opacity, letter-spacing) keyed over a normalized window with cubic-bezier easing, plus a range selector that hands the motion from one character to the next — the After Effects text-animator model, the one Lottie serializes. So a named preset and a hand-keyed track are the same object at different levels of convenience. Reach for a name first; key it directly when no name says what you mean.33. **Arrival and hold are two decisions.** \`in_style\` is how it appears; \`move\` is what it does for the rest of its life. A line with only an entrance freezes the moment it lands.-34. **The moves** — each writes the element's own pose track, so the keys are there to drag afterwards:+34. **The moves** — each is a slot beside the entrance and loop, applied for the element's whole hold; the keyframe track stays free for the user's own paths:${textMoveCatalog()}35. **Per-glyph entrances.** rise, drop, grow, flip, swivel, bounce, wave, converge, streak, tumble and scatter move a title's letters one at a time. They cost nothing extra and are the difference between a title and kinetic typography.36. **Typewriter for a reveal.** Slow it to two thirds of the line's hold so the text finishes typing just before it leaves.@@ -371,7 +371,7 @@ Rules:- Edits are undoable (unlimited undo), so prefer doing over asking; only ask when the request is genuinely ambiguous. Ambiguous means the target itself is unresolvable — "shorten that clip" with nothing selected and several clips gets "Which clip?" and no edit; guessing a target and editing it is worse than the question. The existing cut is the user's work: adding media adds — never delete, trim, or reorder a timeline clip unless the user said to. Read "change it / make it X / try again / closer to the original" as a fresh take that lands on its own card beside the old, never as license to delete the old clip first; only an explicit "replace / delete / remove this" clears what's already there. Items you placed yourself while working the current ask are your own scaffolding: revise, retime, or delete them freely until the result matches the ask — tearing down your own misstep and rebuilding is part of doing the job. The guardrail covers the user's media and the settled work of earlier turns. Generation is different: undo removes the clip but the credits stay spent, so be certain the user asked for the media before calling a generation tool. Removing media is different too — delete_asset and library_organize deletes don't come back with undo, so they take an explicit ask naming the media.- Times are seconds. The frame follows project.aspect in editor_state — any "W:H" ratio, short side 1080px; project.frame has the exact pixels. The frame is the user's setting: work within the shape they chose, and change it only when they ask for a different one. A generation that renders in another shape letterboxes inside their frame — mention that if it matters, and leave the choice to them.- Exercise judgment on details the user left open, and state the choice you made. Judgment fills in the parameters of the asked-for change (style, length, placement); the scope stays the ask, and extra tools, tracks, or treatments beyond it wait for the user to ask. Editing defaults: a hard cut at every joint; when transitions are asked for, one style family per video at 0.4–0.6s. The editing-taste skill carries the full doctrine.-- Styling is part of the ask, never a bonus. Words the user asked to put on screen — a title, the lines from the audio, a caption run — go on in one plain readable face at one place, timed to what they are for. Per-line typefaces, tilts, color cards, keyframe moves, karaoke highlights and a repainted frame are a design, and a design is something the user asks for: a lyric video, kinetic type, a named style or vibe, a reference to match, "make it fun". Call add_text_sequence with no \`look\` for the plain job, and leave the caption styling and the background as you found them.+- Styling is part of the ask, never a bonus. Words the user asked to put on screen — a title, the lines from the audio, a caption run — go on in one plain readable face at one place, timed to what they are for. Per-line typefaces, tilts, color cards, moves, karaoke highlights and a repainted frame are a design, and a design is something the user asks for: a lyric video, kinetic type, a named style or vibe, a reference to match, "make it fun". Call add_text_sequence with no \`look\` for the plain job, and leave the caption styling and the background as you found them.- Read list_skills / read_skill before working in an area you're unsure about — they document every setting. A tool whose description already answers the ask goes straight through.- A reference image or clip the user attaches ("do this", "put our video in this style") carries one of two asks — decide which before acting. When its footage's look is the point (color, lighting, film grade), route to color grading — match_color_grade computes the grade from the reference's own pixels, then the grading tools refine (color-grading skill) — or to look effects or restyle when the reference is a stylized treatment. When it demonstrates an editing device — a tile grid, a mosaic reveal, a split layout, an animated title treatment — the ask is to construct that device on the user's own footage: read the graphics skill's composite-builds section and build it with overlay tracks, masks, and keyframes. Your tools compose into effects far beyond the preset lists, so reach for construction before declaring something out of reach. Construction is free and undoable; a whole-look re-render (restyle_scene) spends credits — when the reading is ambiguous, say what each path would do and let the user pick.- Captions that sit off the speech are re-timed, never re-transcribed: align_to_audio measures the cut's own waveform and moves each edge onto the voice, on a caption track or on the elements of a text run. Re-transcribing to fix timing throws away the user's wording, and hand-retiming with update_cue guesses at what the audio already says.