@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/evals/surfaces/timeline.js

@@ -0,0 +1,3267 @@
+/**
+ * Headless bridge for the timeline / video editor tool-loop eval.
+ *
+ * The real frontend tools (`web/src/lib/tools/builtin/timeline.ts`) delegate to
+ * a `TimelineAgentHandler` the live `TimelineEditor` registers per open
+ * sequence on `timelineAgentBridge` — it mutates Zustand document/UI/playback
+ * stores and (for `ui_timeline_get_clip_frames`) samples rendered video
+ * frames. None of that can run under Node. This bridge reimplements the
+ * *effects* of the non-rendering tools against a plain in-memory sequence
+ * (tracks + clips from `@nodetool-ai/timeline`), so a model can drive the same
+ * `ui_timeline_*` tool surface headlessly.
+ *
+ * What it does NOT fork is the tool *contract*: names, descriptions, and Zod
+ * parameter shapes are copied verbatim from the builtin file (minus the
+ * `timeline_id` parameter — this bridge holds a single implicit sequence, so
+ * there is nothing to disambiguate). `ui_timeline_get_clip_frames` is
+ * intentionally excluded: it requires real rendered video frames and has no
+ * meaningful headless equivalent.
+ *
+ * Real cut/preset logic is reused from the pure `@nodetool-ai/timeline`
+ * package (`splitClip`, `ANIMATION_PRESETS`, `makeClip`/`makeTrack`) rather
+ * than reimplemented, so this bridge exercises the same behavior the live
+ * editor does.
+ */
+import { z } from "zod";
+import { isShortResourceId } from "@nodetool-ai/protocol";
+import { parseWithTypeCoercion } from "@nodetool-ai/runtime";
+import { splitClip, trimClip, ANIMATION_PRESETS, ANIMATED_PROPERTIES, buildBakedAnimation, CUSTOM_ANIMATION_CONTRACT, CUSTOM_ANIMATION_PRESET_ID, normalizeCustomCurves, resolveCustomMask, computeModel3DBakeHash, makeClip, makeClipVersion, makeTrack, DEFAULT_TEXT_CLIP_DURATION_MS, DEFAULT_MEDIA_CLIP_DURATION_MS, DEFAULT_MODEL3D_CLIP_DURATION_MS, DEFAULT_MODEL3D_CLIP_NAME, model3dStyleWithPatch, shapeStyleWithDefaults, assertAuthorableFontFamily, textStyleWithDefaults, moveTrackOrder, mediaTypeForContentType, trackTypeForMediaType, STAGGER_UNITS, parseStaggerUnit, typewriterTiming, parseEasing, DEFAULT_BEAT_TOLERANCE_MS, buildBeatGrid, beatCountToCover, snapClipsToGrid, staggerClipAnimations, isGroupClip, moveGroup, ungroup, trimGroup, resliceTracksForSplitClip, resliceTracksForTrimmedClip, applyTransitionAtCutCandidate, planTransitionAtCut, instantiateComposition, DEFAULT_MIDI_INSTRUMENT, DEFAULT_TEMPO, MIDI_INSTRUMENT_PRESETS, createMidiNote, findInstrumentPreset, formatBarsBeats, presetIdForInstrument, quantizeNotes, scaleVelocity, sortNotes, transposeNotes, validateNotes, visibleNotes, rescaleClipsForTempo, resolveTempo, captureMediaEditSourceContext, composeGenerativeTakePatch, createMediaEditRequest, ensureBaselineTake, applyTakeToClip, selectGeneratedMatteVersion, activeTakeIdOf, selectTake, renameTake as renameTakeOnClip, deleteTake as deleteTakeOnClip, adaptSequenceFormat, addReframeKeyframe, clearReframe, isMediaTrackStale, mediaTrackCanDriveReframe } from "@nodetool-ai/timeline";
+import { computeActiveLayers, countTextStaggerUnits, parseSvgPath } from "@nodetool-ai/timeline/scene";
+import { APPLY_TRANSITION_AT_CUT_DESCRIPTION, applyTransitionAtCutParams, buildEffect, buildMask, buildTimeRemap, buildTransition, resolveDeleteTrackArgs, resolveMoveTrackArgs, resolveShapeArg, setBakedAnimationParams, SET_BAKED_ANIMATION_DESCRIPTION, setGeneratedMatteParams, SET_GENERATED_MATTE_DESCRIPTION, textStyleParams, textStylePatchParams } from "@nodetool-ai/protocol/api-schemas/timeline-tool-params.js";
+import { buildTimelineToolContracts, liftCustomAnimation, rejectUnknownClipParams } from "@nodetool-ai/protocol/api-schemas/timeline-tool-contracts.js";
+import { uiToolParams } from "@nodetool-ai/protocol/api-schemas/ui-tool-contract.js";
+import { findSystemSkill } from "../../system-skills.js";
+/**
+ * The `ui_timeline_*` contracts, shared with the browser registry
+ * (`web/src/lib/tools/builtin/timeline.ts`). The vocabulary comes from
+ * `@nodetool-ai/timeline`, which the protocol package sits below.
+ */
+const CONTRACTS = buildTimelineToolContracts({
+    staggerUnits: STAGGER_UNITS,
+    animatedProperties: ANIMATED_PROPERTIES,
+    beatToleranceMs: DEFAULT_BEAT_TOLERANCE_MS
+});
+const generatedTransitionCandidateParams = applyTransitionAtCutParams;
+const transitionCandidateParams = z.object({
+    candidate_id: z.string().trim().min(1)
+});
+const transitionCandidateLifecycleParams = applyTransitionAtCutParams
+    .partial()
+    .extend({ candidate_id: z.string().trim().min(1).optional() })
+    .superRefine((value, context) => {
+    if (value.candidate_id === undefined &&
+        (value.outgoingClipId === undefined || value.incomingClipId === undefined)) {
+        context.addIssue({
+            code: "custom",
+            message: "Provide outgoingClipId and incomingClipId to create a candidate, or candidate_id to apply one."
+        });
+    }
+});
+/** Units a failed lookup names before it stops and points at get_state. */
+const MAX_LISTED_UNITS = 12;
+/**
+ * Tools that read the sequence without changing it. Everything else is an
+ * edit, which is what {@link previewedAfterLastEdit} measures "last" against.
+ */
+export const TIMELINE_READ_ONLY_TOOLS = [
+    "ui_timeline_get_state",
+    "ui_timeline_list_animation_presets",
+    "ui_timeline_select_clip",
+    "ui_timeline_preview_transition_candidate",
+    "ui_timeline_seek",
+    "preview_timeline_frame"
+];
+/** Whether the last edit in a transcript is followed by a preview call. */
+export function previewedAfterLastEdit(toolLog) {
+    const lastEdit = toolLog.reduce((index, name, i) => (TIMELINE_READ_ONLY_TOOLS.includes(name) ? index : i), -1);
+    if (lastEdit === -1)
+        return false;
+    return toolLog.indexOf("preview_timeline_frame", lastEdit + 1) !== -1;
+}
+/**
+ * Whether a preview landed inside a motion rather than beside it.
+ *
+ * {@link previewedAfterLastEdit} reads the transcript's shape: a preview call
+ * came last. That passes on a look at 0ms, where an entrance has not started —
+ * the endpoints tell you nothing, which is what the skill's "sample the middle
+ * of a motion" is about. This reads the timecodes instead: at least one falls
+ * strictly inside the window of an animation the document now carries.
+ *
+ * Every animation in a graded final state is one the run authored, since the
+ * seeded worlds carry none.
+ */
+export function previewedMidMotion(previewTimesMs, clips, canvas) {
+    if (previewTimesMs.length === 0)
+        return false;
+    return clips.some((clip) => (clip.animations ?? []).some((animation) => {
+        const window = animationWindow(clip, animation, canvas);
+        if (!(window.endMs > window.startMs))
+            return false;
+        return previewTimesMs.some((timeMs) => timeMs > window.startMs && timeMs < window.endMs);
+    }));
+}
+/**
+ * How long an animation is in motion for: its own window, widened by the
+ * stagger's last unit. `durationMs` unset takes the preset's default.
+ */
+function motionSpanMs(clip, animation, canvas) {
+    const preset = ANIMATION_PRESETS.find((p) => p.id === animation.preset);
+    const durationMs = animation.durationMs ?? preset?.defaultDurationMs ?? 0;
+    const stagger = animation.stagger;
+    if (!stagger || !(stagger.offsetMs > 0))
+        return durationMs;
+    const units = staggerUnitsOf(clip, stagger.unit, canvas);
+    if (units < 2)
+        return durationMs;
+    return durationMs + stagger.offsetMs * (units - 1);
+}
+/**
+ * When an animation runs, in timeline ms. `delayMs` offsets an `in` and an
+ * `emphasis` from the clip's start and an `out` backwards from its end, which
+ * is the role rule the skill states. A `loop` runs for the whole clip.
+ */
+export function animationWindow(clip, animation, canvas) {
+    const clipEndMs = clip.startMs + clip.durationMs;
+    if (animation.role === "loop") {
+        return { startMs: clip.startMs, endMs: clipEndMs };
+    }
+    const delayMs = animation.delayMs ?? 0;
+    const spanMs = motionSpanMs(clip, animation, canvas);
+    if (animation.role === "out") {
+        const endMs = clipEndMs - delayMs;
+        return { startMs: endMs - spanMs, endMs };
+    }
+    const startMs = clip.startMs + delayMs;
+    return { startMs, endMs: startMs + spanMs };
+}
+/**
+ * Whether a staggered animation finishes inside its clip: the last unit
+ * starts `offsetMs × (units − 1)` in and still runs the full `durationMs`.
+ * An animation with no stagger, or one on a clip that splits into fewer than
+ * two units, fits by construction — it is one block.
+ */
+export function staggerSpanFitsClip(clip, animation, canvas) {
+    const stagger = animation.stagger;
+    if (!stagger || !(stagger.offsetMs > 0))
+        return true;
+    const units = staggerUnitsOf(clip, stagger.unit, canvas);
+    if (units < 2)
+        return true;
+    const preset = ANIMATION_PRESETS.find((p) => p.id === animation.preset);
+    const durationMs = animation.durationMs ?? preset?.defaultDurationMs ?? 0;
+    const span = (animation.delayMs ?? 0) + durationMs + stagger.offsetMs * (units - 1);
+    return span <= clip.durationMs;
+}
+/**
+ * How many units a clip's text splits into for a stagger unit. Line counting
+ * wraps against the sequence size; with no text measurer every authored
+ * paragraph is one line, which is what a headless surface can know.
+ */
+export function staggerUnitsOf(clip, unit, canvas) {
+    const style = clip.textStyle;
+    const parsed = parseStaggerUnit(unit);
+    // An unknown unit compiles as a plain block animation, so it splits into
+    // nothing — same answer as a clip with no text.
+    if (!style || !parsed)
+        return 0;
+    return countTextStaggerUnits(style, canvas, parsed);
+}
+/**
+ * The easing an animation actually runs with: its own, else the preset's, else
+ * the role default (`in` decelerates, `out` accelerates).
+ */
+export function effectiveEasing(animation) {
+    if (animation.easing)
+        return animation.easing;
+    const preset = ANIMATION_PRESETS.find((p) => p.id === animation.preset);
+    if (preset?.defaultEasing)
+        return preset.defaultEasing;
+    switch (animation.role) {
+        case "in":
+            return "easeOut";
+        case "out":
+            return "easeIn";
+        case "emphasis":
+            return "easeInOut";
+        default:
+            return "linear";
+    }
+}
+/** How far either side of the curve a slope is measured over. */
+const EASING_SLOPE_STEP = 0.02;
+/**
+ * Whether an easing decelerates into its landing.
+ *
+ * The `easeOut` family qualifies by name: its endpoints are exact, and
+ * `easeOutBounce` deliberately accelerates into its last bounce, which a slope
+ * reading at t=1 would score as an ease-in. Everything else in the grammar is
+ * measured — the curve's slope entering the landing against its slope leaving
+ * the start — so `cubic-bezier(0.16,1,0.3,1)`, the deceleration the skill
+ * recommends for entrances, passes and `cubic-bezier(0.7,0,0.84,0)`, the exit
+ * curve beside it, does not. An easing outside the grammar eases linearly and
+ * does not decelerate.
+ */
+export function easingDecelerates(easing) {
+    const text = easing.trim();
+    if (/^easeOut/.test(text))
+        return true;
+    const curve = parseEasing(text);
+    if (!curve)
+        return false;
+    const entry = (curve(EASING_SLOPE_STEP) - curve(0)) / EASING_SLOPE_STEP;
+    const landing = (curve(1) - curve(1 - EASING_SLOPE_STEP)) / EASING_SLOPE_STEP;
+    return landing < entry;
+}
+function tool(name, description, parameters, impl) {
+    return {
+        name,
+        description,
+        parameters,
+        execute: (args) => {
+            const parsed = parseWithTypeCoercion(parameters, args ?? {});
+            return impl(parsed);
+        }
+    };
+}
+/**
+ * `set_clip_params` takes the style as a patch merged over the clip's own, so
+ * every field is optional. The shared contract still declares the whole-bag
+ * `textStyleParams`, which refuses `{textStyle: {fontFamily}}` on a finished
+ * title. Both hosts override that one field; when protocol carries
+ * `textStylePatchParams` the two overrides go together.
+ */
+const CONTRACT_SHAPE_OVERRIDES = {
+    ui_timeline_set_clip_params: { textStyle: textStylePatchParams.optional() }
+};
+/** A tool whose name, description and argument shape both hosts share. */
+function sharedTool(name, impl) {
+    const contract = CONTRACTS[name];
+    const shape = { ...contract.shape, ...CONTRACT_SHAPE_OVERRIDES[name] };
+    // No host fields: this bridge drives one implicit sequence, so there is no
+    // `timeline_id` to disambiguate.
+    return tool(name, contract.description, uiToolParams({ ...contract, shape }), impl);
+}
+/**
+ * Keys a caller wraps the whole patch in.
+ *
+ * `set_clip_params` reads its fields off the op itself — `{op, target,
+ * textStyle}` — but a REST-shaped guess sends `{op, target, params: {…}}`, and
+ * that used to be refused as an unknown key with the real fields hidden one
+ * level down inside it. The wrapper says nothing the op does not already know,
+ * so it is unwrapped rather than argued with.
+ */
+const CLIP_PARAM_WRAPPERS = ["params", "patch", "props", "properties"];
+/** Lift a patch a caller nested under a wrapper key onto the op itself. */
+export function unwrapClipParams(patch) {
+    const wrapper = CLIP_PARAM_WRAPPERS.find((key) => isRecordValue(patch[key]));
+    if (!wrapper)
+        return patch;
+    const { [wrapper]: nested, ...rest } = patch;
+    // The op's own keys win: a caller that sent both meant the one it spelled
+    // out, and silently preferring the wrapper would drop it.
+    return { ...nested, ...rest };
+}
+const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function mergeClipTransform(current, patch) {
+    return {
+        position: { x: 0, y: 0, ...current?.position, ...patch.position },
+        scale: { x: 1, y: 1, ...current?.scale, ...patch.scale },
+        rotation: patch.rotation ?? current?.rotation ?? 0,
+        rotationX: patch.rotationX ?? current?.rotationX,
+        rotationY: patch.rotationY ?? current?.rotationY,
+        perspective: patch.perspective ?? current?.perspective,
+        anchor: { x: 0.5, y: 0.5, ...current?.anchor, ...patch.anchor }
+    };
+}
+/**
+ * A text style patch, merged over the clip's own and checked for a family that
+ * names no face.
+ *
+ * A clip that carries no text style yet still needs the three fields that make
+ * one drawable, so the merged result goes through the same schema the whole
+ * bag does rather than being stored half-built.
+ */
+function mergeTextStyle(clip, patch) {
+    const merged = { ...(clip.textStyle ?? {}), ...patch };
+    const parsed = textStyleParams.safeParse(merged);
+    if (!parsed.success) {
+        const missing = parsed.error.issues
+            .filter((issue) => issue.code === "invalid_type")
+            .map((issue) => issue.path.join("."));
+        throw new Error(missing.length > 0
+            ? `Clip "${clip.name}" has no text style yet, so this patch cannot ` +
+                `stand on its own — it still needs ${missing.join(", ")}.`
+            : `textStyle: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    }
+    assertAuthorableFontFamily(parsed.data.fontFamily);
+    return parsed.data;
+}
+function capitalize(s) {
+    return s.length > 0 ? s[0].toUpperCase() + s.slice(1) : s;
+}
+/**
+ * Units a staggered animation splits into — a text clip's word count, which is
+ * what a custom body reads off `inputs.staggerCount`. Zero when the clip does
+ * not stagger, matching the un-staggered block case.
+ */
+function staggerUnitCount(clip, stagger) {
+    if (!stagger || clip.mediaType !== "text")
+        return 0;
+    const text = clip.textStyle?.text ?? "";
+    const words = text.trim().split(/\s+/).filter((word) => word.length > 0);
+    return words.length;
+}
+/**
+ * Build an in-memory timeline bridge whose tools share the `ui_timeline_*`
+ * contract but run headlessly against a plain sequence of tracks/clips (no
+ * Zustand stores, no rendering).
+ */
+export function createTimelineToolBridge(initial = {}) {
+    const seed = initial.sequence;
+    const resolveAsset = initial.resolveAsset;
+    const bakeAnimation = initial.bakeAnimation;
+    const bakeModel3DClip = initial.bakeModel3DClip;
+    const loadComposition = initial.loadComposition;
+    const retargetFormat = initial.retargetFormat;
+    const generateTransition = initial.generateTransition;
+    const sequenceId = initial.sequenceId ?? "seq_eval";
+    const sequenceName = initial.sequenceName ?? "Sequence";
+    const projectId = initial.projectId ?? "";
+    const fps = seed?.fps ?? initial.fps ?? 30;
+    const width = seed?.width ?? initial.width ?? 1920;
+    const height = seed?.height ?? initial.height ?? 1080;
+    let playheadMs = 0;
+    let selectedClipIds = [];
+    // Absent until a midi track or `set_tempo` puts one there — a document with
+    // no midi in it should not grow a tempo field it never asked for.
+    let tempo = seed?.tempo;
+    let trackSeq = 0;
+    let clipSeq = 0;
+    let animSeq = 0;
+    let markerSeq = 0;
+    let versionSeq = 0;
+    let transitionSeq = 0;
+    const tracks = [];
+    let clips = [];
+    let markers = [];
+    // Document-level, like markers: a track is named by `clipId`, and a clip
+    // follows one through its own `trackBinding` (P0 AI Video, Phase 2).
+    let mediaTracks = [];
+    let transitionCandidates = [];
+    let auditionedTransitionCandidateId;
+    let appliedTransitionCandidates = [];
+    const derivedSequences = [];
+    let setup = seed?.setup
+        ? structuredClone(seed.setup)
+        : null;
+    let beatSeq = 0;
+    const toolLog = [];
+    const previewTimesMs = [];
+    const previewedLayerKinds = new Set();
+    // Ids the sequence already uses. A seeded document brings its own, which the
+    // `track_1`/`clip_1` counters would otherwise collide with on the first edit.
+    const usedIds = new Set();
+    const mint = (prefix, next) => {
+        let id = `${prefix}_${next()}`;
+        while (usedIds.has(id))
+            id = `${prefix}_${next()}`;
+        usedIds.add(id);
+        return id;
+    };
+    const nextTrackId = () => mint("track", () => ++trackSeq);
+    const nextClipId = () => mint("clip", () => ++clipSeq);
+    const nextAnimId = () => mint("anim", () => ++animSeq);
+    const nextMarkerId = () => mint("marker", () => ++markerSeq);
+    const nextVersionId = () => mint("version", () => ++versionSeq);
+    const nextTransitionId = () => mint("transition", () => ++transitionSeq);
+    const clipEnd = (clip) => clip.startMs + clip.durationMs;
+    function isAmbiguousCut(outgoing, incoming) {
+        const cutTimeMs = incoming.startMs;
+        return clips.some((candidate) => {
+            if (candidate.id === outgoing.id ||
+                candidate.id === incoming.id ||
+                candidate.trackId !== outgoing.trackId) {
+                return false;
+            }
+            return ((candidate.startMs <= cutTimeMs && clipEnd(candidate) > cutTimeMs) ||
+                candidate.startMs === cutTimeMs);
+        });
+    }
+    function transitionSource(outgoing, incoming, durationMs) {
+        return {
+            sequenceId,
+            outgoingClipId: outgoing.id,
+            incomingClipId: incoming.id,
+            outgoingTakeId: activeTakeIdOf(outgoing),
+            incomingTakeId: activeTakeIdOf(incoming),
+            outgoingAssetId: outgoing.currentAssetId,
+            incomingAssetId: incoming.currentAssetId,
+            outgoingTransition: outgoing.transitionIn
+                ? structuredClone(outgoing.transitionIn)
+                : undefined,
+            incomingTransition: incoming.transitionIn
+                ? structuredClone(incoming.transitionIn)
+                : undefined,
+            outgoingStartMs: outgoing.startMs,
+            outgoingDurationMs: outgoing.durationMs,
+            incomingStartMs: incoming.startMs,
+            incomingDurationMs: incoming.durationMs,
+            cutTimeMs: incoming.startMs,
+            durationMs
+        };
+    }
+    function assertFreshTransitionCandidate(candidate) {
+        const outgoing = clips.find((clip) => clip.id === candidate.source.outgoingClipId);
+        const incoming = clips.find((clip) => clip.id === candidate.source.incomingClipId);
+        if (!outgoing || !incoming) {
+            throw new Error("The generated transition candidate is stale because its selected clip no longer exists.");
+        }
+        if (isAmbiguousCut(outgoing, incoming)) {
+            throw new Error("The generated transition candidate is stale because the selected cut is ambiguous.");
+        }
+        const source = transitionSource(outgoing, incoming, candidate.source.durationMs);
+        if (JSON.stringify(source) !== JSON.stringify(candidate.source)) {
+            throw new Error("The generated transition candidate is stale because the selected clips or cut changed.");
+        }
+    }
+    async function createTransitionCandidate(input) {
+        const outgoingClipId = input.outgoingClipId;
+        const incomingClipId = input.incomingClipId;
+        const outgoing = resolveClip(outgoingClipId);
+        const incoming = resolveClip(incomingClipId);
+        if (isAmbiguousCut(outgoing, incoming)) {
+            throw new Error("The selected cut is ambiguous. Choose two adjacent clips with no other clip crossing the cut.");
+        }
+        const planned = planTransitionAtCut(clips, {
+            outgoingClipId: outgoing.id,
+            incomingClipId: incoming.id,
+            durationMs: input.durationMs,
+            overlapMs: input.overlapMs,
+            type: input.type,
+            easing: input.easing,
+            color: input.color,
+            direction: input.direction,
+            softness: input.softness
+        });
+        if (!planned.ok)
+            throw new Error(planned.error);
+        if (!generateTransition) {
+            throw new Error("Selected-cut transition generation is unavailable because this surface has no provider generator.");
+        }
+        const source = transitionSource(outgoing, incoming, planned.candidate.durationMs);
+        const request = {
+            durationMs: planned.candidate.durationMs,
+            overlapMs: planned.candidate.overlapMs,
+            type: planned.candidate.type,
+            easing: input.easing,
+            color: input.color,
+            direction: input.direction,
+            softness: input.softness
+        };
+        const generated = await generateTransition({
+            sequenceId,
+            source,
+            request
+        });
+        if (generated.generationId.trim().length === 0 ||
+            generated.assetId.trim().length === 0) {
+            throw new Error("Selected-cut transition generation returned no generation id or asset.");
+        }
+        const id = nextTransitionId();
+        const candidate = {
+            id,
+            generationId: generated.generationId,
+            kind: "generated_transition_at_cut",
+            status: "success",
+            asset: {
+                id: generated.assetId,
+                contentType: generated.contentType ?? "video/mp4"
+            },
+            source,
+            request,
+            operation: {
+                op: "apply_generated_transition_at_cut",
+                candidateId: id,
+                outgoingClipId: outgoing.id,
+                incomingClipId: incoming.id,
+                cutTimeMs: incoming.startMs,
+                durationMs: planned.candidate.durationMs,
+                undoable: true
+            }
+        };
+        transitionCandidates = [...transitionCandidates, candidate];
+        return candidate;
+    }
+    function applyTransitionCandidate(candidateId) {
+        const candidate = transitionCandidates.find((entry) => entry.id === candidateId);
+        if (!candidate) {
+            throw new Error(`No generated transition candidate named "${candidateId}" exists.`);
+        }
+        assertFreshTransitionCandidate(candidate);
+        if (appliedTransitionCandidates.some((entry) => entry.id === candidate.id)) {
+            throw new Error(`Generated transition candidate "${candidate.id}" was already applied.`);
+        }
+        const planned = planTransitionAtCut(clips, {
+            outgoingClipId: candidate.source.outgoingClipId,
+            incomingClipId: candidate.source.incomingClipId,
+            ...candidate.request
+        });
+        if (!planned.ok)
+            throw new Error(planned.error);
+        const applied = applyTransitionAtCutCandidate(clips, planned.candidate);
+        if (!applied.ok)
+            throw new Error(applied.error);
+        clips = applied.clips;
+        appliedTransitionCandidates = [
+            ...appliedTransitionCandidates,
+            structuredClone(candidate)
+        ];
+        if (auditionedTransitionCandidateId === candidate.id) {
+            auditionedTransitionCandidateId = undefined;
+        }
+        return {
+            candidate,
+            operation: candidate.operation,
+            description: `Apply generated transition candidate "${candidate.id}" to the selected cut as one undoable operation.`
+        };
+    }
+    function addTrackInternal(type, name) {
+        const index = tracks.length;
+        const track = makeTrack({
+            id: nextTrackId(),
+            type,
+            name: name ?? `${capitalize(type)} ${index + 1}`,
+            index
+        });
+        if (type === "midi") {
+            // The track owns the voice, so a midi track without one plays nothing.
+            track.instrument = DEFAULT_MIDI_INSTRUMENT;
+            // Ticks are read against the tempo, so the first midi track is where a
+            // document that never had one gets it — written down rather than left
+            // implicit, so the next reader does not have to know the default.
+            tempo ??= DEFAULT_TEMPO;
+        }
+        tracks.push(track);
+        return track;
+    }
+    /** The midi track a clip or instrument op names, refusing any other type. */
+    function resolveMidiTrack(idOrName) {
+        const track = resolveTrack(idOrName);
+        if (track.type !== "midi") {
+            throw new Error(`Track "${track.name}" is a ${track.type} track — notes are played by a midi track's instrument. ${validUnits(tracks.filter((t) => t.type === "midi"), "midi track")}`);
+        }
+        return track;
+    }
+    /** The midi clip a note op names, refusing any other kind. */
+    function resolveMidiClip(target) {
+        const clip = resolveClip(target);
+        if (clip.mediaType !== "midi") {
+            throw new Error(`Clip "${clip.name}" is a ${clip.mediaType} clip — only a midi clip carries notes. Place one with add_midi_clip.`);
+        }
+        return clip;
+    }
+    /**
+     * The voice an instrument argument names: `{preset}` resolved to the sound
+     * it stands for, or a spelled-out instrument taken as it came.
+     *
+     * The preset's object is copied onto the track rather than referenced, so
+     * the document keeps the sound it was given even if the shipped table
+     * changes under it.
+     */
+    function resolveInstrumentArg(raw) {
+        const value = (raw ?? {});
+        const presetId = value["preset"];
+        if (typeof presetId !== "string") {
+            return value;
+        }
+        const preset = findInstrumentPreset(presetId);
+        if (!preset) {
+            throw new Error(`No instrument preset named "${presetId}". Valid presets: ${MIDI_INSTRUMENT_PRESETS.map((p) => `${p.id} ("${p.name}")`).join(", ")}.`);
+        }
+        return structuredClone(preset.instrument);
+    }
+    /**
+     * The notes a caller sent, minted and checked as one list.
+     *
+     * Every problem is reported at once: an agent that fixes one note only to be
+     * told about the next spends a call per note.
+     */
+    function buildNotes(raw, clipName) {
+        const notes = (raw ?? []).map((note) => createMidiNote({
+            id: note["id"],
+            pitch: note["pitch"],
+            velocity: note["velocity"],
+            startTick: note["start_tick"],
+            durationTick: note["duration_tick"]
+        }));
+        const problems = validateNotes(notes);
+        if (problems.length > 0) {
+            throw new Error(`Clip "${clipName}" was not given its notes — ${problems.length} problem(s): ` +
+                problems
+                    .map((p) => (p.noteId ? `${p.noteId}: ${p.message}` : p.message))
+                    .join(" "));
+        }
+        return sortNotes(notes);
+    }
+    function findOrCreateTrack(type) {
+        const existing = tracks.find((t) => t.type === type);
+        if (existing)
+            return existing;
+        return addTrackInternal(type);
+    }
+    /**
+     * The ids and names a caller could have used, for the message a failed
+     * lookup throws. Capped, because a long cut has hundreds of clips and an
+     * error listing all of them is one an agent stops reading.
+     */
+    function validUnits(units, kind) {
+        if (units.length === 0)
+            return `The timeline has no ${kind}s yet.`;
+        const shown = units
+            .slice(0, MAX_LISTED_UNITS)
+            .map((u) => `${u.id} ("${u.name}")`)
+            .join(", ");
+        const rest = units.length - MAX_LISTED_UNITS;
+        return rest > 0
+            ? `Valid ${kind}s: ${shown}, and ${rest} more — call get_state for the full list.`
+            : `Valid ${kind}s: ${shown}.`;
+    }
+    function resolveTrack(idOrName) {
+        const byId = tracks.find((t) => t.id === idOrName);
+        if (byId)
+            return byId;
+        if (isShortResourceId(idOrName)) {
+            const matches = tracks.filter((track) => track.id.startsWith(idOrName));
+            if (matches.length === 1) {
+                return matches[0];
+            }
+            if (matches.length > 1) {
+                throw new Error(`Short track id "${idOrName}" matches more than one track. Use the full id or name.`);
+            }
+        }
+        const lower = idOrName.toLowerCase();
+        const byName = tracks.find((t) => t.name.toLowerCase() === lower);
+        if (byName)
+            return byName;
+        throw new Error(`No track found matching "${idOrName}". ${validUnits(tracks, "track")}`);
+    }
+    function trackEndMs(trackId) {
+        return clips
+            .filter((c) => c.trackId === trackId)
+            .reduce((m, c) => Math.max(m, c.startMs + c.durationMs), 0);
+    }
+    function resolveClip(target) {
+        if (target.toLowerCase() === "selected") {
+            if (selectedClipIds.length !== 1) {
+                throw new Error(`"selected" requires exactly one selected clip (currently ${selectedClipIds.length}).`);
+            }
+            const clip = clips.find((c) => c.id === selectedClipIds[0]);
+            if (!clip)
+                throw new Error("Selected clip no longer exists.");
+            return clip;
+        }
+        const byId = clips.find((c) => c.id === target);
+        if (byId)
+            return byId;
+        if (isShortResourceId(target)) {
+            const matches = clips.filter((clip) => clip.id.startsWith(target));
+            if (matches.length === 1) {
+                return matches[0];
+            }
+            if (matches.length > 1) {
+                throw new Error(`Short clip id "${target}" matches more than one clip. Use the full id or name.`);
+            }
+        }
+        const lower = target.toLowerCase();
+        const byName = clips.find((c) => c.name.toLowerCase() === lower);
+        if (byName)
+            return byName;
+        throw new Error(`No clip found matching "${target}". ${validUnits(clips, "clip")}`);
+    }
+    /**
+     * The body of `trim_clip`, shared with `set_clip_params`: a caller that sends
+     * `durationMs` alongside a style change means the same edit either way, and
+     * two copies of the group-trim rule would drift.
+     */
+    function applyTrim(clip, patch) {
+        // A group carries what it holds (D4): shortening one pulls its children
+        // inside the window that leaves, rather than leaving them hanging past an
+        // edge nothing draws.
+        if (isGroupClip(clip) && patch.durationMs !== undefined) {
+            clips = trimGroup(clips, clip.id, "end", patch.durationMs - clip.durationMs);
+            return clips.find((c) => c.id === clip.id);
+        }
+        let next = clip;
+        if (patch.durationMs !== undefined) {
+            if (patch.durationMs <= 0) {
+                throw new Error(`durationMs must be greater than 0 (got ${patch.durationMs}); delete the clip instead of trimming it to nothing`);
+            }
+            next = trimClip(clip, "end", patch.durationMs - clip.durationMs);
+            clips = clips.map((entry) => entry.id === clip.id ? next : entry);
+        }
+        if (patch.inPointMs !== undefined)
+            next.inPointMs = patch.inPointMs;
+        if (patch.outPointMs !== undefined)
+            next.outPointMs = patch.outPointMs;
+        return next;
+    }
+    function applyTrimStart(clip, startMs) {
+        const deltaMs = clip.startMs - Math.max(0, startMs);
+        if (deltaMs === 0)
+            return clip;
+        if (isGroupClip(clip)) {
+            clips = trimGroup(clips, clip.id, "start", deltaMs);
+            return clips.find((entry) => entry.id === clip.id);
+        }
+        const next = trimClip(clip, "start", deltaMs);
+        clips = clips.map((entry) => entry.id === clip.id ? next : entry);
+        return next;
+    }
+    /** The body of `move_clip`, shared with `set_clip_params`. */
+    function applyMove(clip, patch) {
+        // Moving a group moves what it holds by the same delta (D4). Children keep
+        // their own tracks, so their z-order is untouched (I9) — only the group
+        // itself takes a new `trackId`.
+        let moved = clip;
+        if (isGroupClip(clip) && patch.startMs !== undefined) {
+            const nextStartMs = Math.max(0, patch.startMs);
+            clips = moveGroup(clips, clip.id, nextStartMs - clip.startMs);
+            moved = clips.find((c) => c.id === clip.id);
+        }
+        else if (patch.startMs !== undefined) {
+            clip.startMs = Math.max(0, patch.startMs);
+        }
+        if (patch.trackId !== undefined) {
+            moved.trackId = resolveTrack(patch.trackId).id;
+        }
+        return moved;
+    }
+    /** Resolve a marker by id, or by case-insensitive label. */
+    function resolveMarker(target) {
+        const byId = markers.find((m) => m.id === target);
+        if (byId)
+            return byId;
+        const lower = target.toLowerCase();
+        const byLabel = markers.find((m) => m.label.toLowerCase() === lower);
+        if (byLabel)
+            return byLabel;
+        const known = markers
+            .map((m) => `${m.id} ("${m.label}") at ${m.timeMs}ms`)
+            .join(", ");
+        throw new Error(`No marker matches "${target}". Use a marker id or its label. ` +
+            (known.length > 0
+                ? `Markers: ${known}.`
+                : "This sequence has no markers yet."));
+    }
+    /**
+     * Resolve the clips one beat op addresses: the named ones, or every clip.
+     *
+     * A target that matches nothing comes back as a miss rather than throwing —
+     * a batch op that dies on one bad name hides what the other targets did.
+     */
+    function resolveSnapTargets(targets) {
+        if (!targets || targets.length === 0) {
+            return { clips: [...clips], missing: [] };
+        }
+        const resolved = [];
+        const missing = [];
+        for (const target of targets) {
+            try {
+                const clip = resolveClip(target);
+                if (!resolved.includes(clip))
+                    resolved.push(clip);
+            }
+            catch {
+                // Recorded as a skip in the op's own report, with the reason.
+                missing.push(target);
+            }
+        }
+        return { clips: resolved, missing };
+    }
+    function serializeTrack(t) {
+        return {
+            id: t.id,
+            name: t.name,
+            type: t.type,
+            index: t.index,
+            visible: t.visible,
+            locked: t.locked,
+            muted: t.muted ?? false,
+            solo: t.solo ?? false,
+            clipCount: clips.filter((c) => c.trackId === t.id).length,
+            // The voice every clip on this track plays. Absent on every other type.
+            instrument: t.instrument,
+            // Which shipped voice that is, when it is one. A track stores the
+            // instrument rather than the id it was picked from, so this is read
+            // back by sound — an instrument edited away from a preset reports none.
+            presetId: t.instrument ? presetIdForInstrument(t.instrument) : undefined
+        };
+    }
+    /**
+     * Build one `preset: "custom"` animation. `curves` are checked and stored;
+     * `code` is baked into curves first, by the host that supplied a baker. Both
+     * paths end at `normalizeCustomCurves`, the single gate the compiler and the
+     * validator also run, so what is stored is what will render.
+     */
+    async function buildCustomAnimation(clip, input) {
+        const code = typeof input.code === "string" ? input.code.trim() : "";
+        const hasCurves = input.curves !== undefined;
+        const hasCode = code !== "";
+        if (hasCurves && hasCode) {
+            throw new Error('A "custom" animation takes exactly one of `curves` and `code`; both were given. Pass the keyframes, or the body that produces them.');
+        }
+        if (!hasCurves && !hasCode) {
+            throw new Error('A "custom" animation needs `curves` or `code`. Accepted shape: ' +
+                '{role: "in", preset: "custom", curves: [{property: "offsetY", keyframes: [{t: 0, value: 160}, {t: 1, value: 0}]}]}' +
+                ' — `t` runs 0..1 over the window. `code` is a JS body baked into curves instead. Either may also be nested under `custom`.');
+        }
+        // Curves are normalized to 0..1 over the window, so a custom animation
+        // with no duration of its own spans the clip and nothing is cropped.
+        const durationMs = input.durationMs ?? clip.durationMs;
+        let curves;
+        let maskInput;
+        if (hasCurves) {
+            const normalized = normalizeCustomCurves(input.curves);
+            if (!normalized.ok)
+                throw new Error(normalized.error);
+            curves = normalized.curves;
+            maskInput = input.mask;
+        }
+        else {
+            if (!bakeAnimation) {
+                throw new Error('This surface cannot run `code`: no animation baker is wired to it. Pass `curves` instead, or bake the body through POST /api/timelines/animations/bake.');
+            }
+            const baked = await bakeAnimation({
+                code,
+                role: input.role,
+                durationMs,
+                clipDurationMs: clip.durationMs,
+                canvas: { width, height },
+                params: input.params,
+                staggerCount: staggerUnitCount(clip, input.stagger)
+            });
+            if (!baked.ok || !baked.curves) {
+                throw new Error(baked.error ?? "The animation body returned no curves.");
+            }
+            const normalized = normalizeCustomCurves(baked.curves);
+            if (!normalized.ok)
+                throw new Error(normalized.error);
+            curves = normalized.curves;
+            maskInput = baked.mask ?? input.mask;
+        }
+        const mask = resolveCustomMask(curves, maskInput);
+        if (!mask.ok)
+            throw new Error(mask.error);
+        const custom = {
+            curves,
+            bakedAt: new Date().toISOString()
+        };
+        if (hasCode)
+            custom.code = code;
+        if (mask.mask)
+            custom.mask = mask.mask;
+        return {
+            id: nextAnimId(),
+            role: input.role,
+            preset: CUSTOM_ANIMATION_PRESET_ID,
+            durationMs,
+            delayMs: input.delayMs,
+            easing: input.easing,
+            params: input.params,
+            stagger: input.stagger,
+            custom
+        };
+    }
+    function serializeClip(c) {
+        const track = tracks.find((t) => t.id === c.trackId);
+        return {
+            id: c.id,
+            name: c.name,
+            trackId: c.trackId,
+            trackName: track?.name ?? null,
+            mediaType: c.mediaType,
+            sourceType: c.sourceType,
+            startMs: c.startMs,
+            durationMs: c.durationMs,
+            endMs: c.startMs + c.durationMs,
+            inPointMs: c.inPointMs,
+            outPointMs: c.outPointMs,
+            status: c.status,
+            currentAssetId: c.currentAssetId,
+            activeTakeId: activeTakeIdOf(c),
+            takeCount: c.versions?.length ?? 0,
+            prompt: c.prompt,
+            provider: c.provider,
+            model: c.model,
+            voice: c.voice,
+            animations: (c.animations ?? []).map((a) => ({
+                role: a.role,
+                preset: a.preset
+            })),
+            hidden: c.hidden ?? false,
+            muted: c.muted ?? false,
+            locked: c.locked,
+            opacity: c.opacity,
+            transform: c.transform,
+            textStyle: c.textStyle,
+            shapeStyle: c.shapeStyle,
+            captionStyle: c.caption?.style,
+            transitionIn: c.transitionIn,
+            mask: c.mask,
+            matte: c.matte,
+            timeRemap: c.timeRemap,
+            effects: c.effects,
+            parentId: c.parentId,
+            reframe: c.reframe
+                ? {
+                    mode: c.reframe.mode,
+                    trackId: c.reframe.trackId,
+                    safeMargin: c.reframe.safeMargin,
+                    smoothing: c.reframe.smoothing,
+                    sampleCount: c.reframe.samples?.length ?? 0,
+                    keyframeCount: c.reframe.keyframes?.length ?? 0
+                }
+                : undefined,
+            // The notes themselves are the clip's bulk — a phrase is hundreds of
+            // them — so state reports how many there are and how many the window
+            // actually plays. `set_notes` sends the list; nothing reads it back.
+            noteCount: c.notes?.length,
+            audibleNoteCount: c.mediaType === "midi"
+                ? visibleNotes(c, resolveTempo({ tempo }).bpm).length
+                : undefined,
+            // Where the phrase starts in musical time, so placing the next one is
+            // reading a bar number rather than dividing milliseconds by the tempo.
+            startBarsBeats: c.mediaType === "midi"
+                ? formatBarsBeats(c.startMs, resolveTempo({ tempo }))
+                : undefined
+        };
+    }
+    // Seed from a real sequence when one was handed over, otherwise from the
+    // shorthand. Cloned, so the bridge never writes through to the caller's state.
+    if (seed) {
+        for (const track of seed.tracks) {
+            const copy = structuredClone(track);
+            usedIds.add(copy.id);
+            tracks.push(copy);
+        }
+        for (const clip of seed.clips) {
+            const copy = structuredClone(clip);
+            usedIds.add(copy.id);
+            for (const animation of copy.animations ?? [])
+                usedIds.add(animation.id);
+            clips.push(copy);
+        }
+        for (const marker of seed.markers ?? []) {
+            const copy = structuredClone(marker);
+            usedIds.add(copy.id);
+            markers.push(copy);
+        }
+        for (const mediaTrack of seed.mediaTracks ?? []) {
+            const copy = structuredClone(mediaTrack);
+            usedIds.add(copy.id);
+            mediaTracks.push(copy);
+        }
+    }
+    // Seed initial tracks and clips.
+    for (const t of seed ? [] : (initial.tracks ?? [])) {
+        addTrackInternal(t.type, t.name);
+    }
+    for (const c of seed ? [] : (initial.clips ?? [])) {
+        const track = tracks[c.trackIndex];
+        if (!track) {
+            throw new Error(`Initial clip "${c.name}" references trackIndex ${c.trackIndex}, but only ${tracks.length} track(s) exist.`);
+        }
+        clips.push(makeClip({
+            id: nextClipId(),
+            trackId: track.id,
+            name: c.name,
+            startMs: c.startMs,
+            durationMs: c.durationMs,
+            mediaType: c.mediaType ?? "video",
+            sourceType: "imported",
+            status: "generated"
+        }));
+    }
+    /** Resolve a beat by id, or by its 1-based position in the plan. */
+    function resolveBeat(target) {
+        const beats = setup?.beats ?? [];
+        const byId = beats.find((beat) => beat.id === target);
+        if (byId)
+            return byId;
+        const position = Number.parseInt(target, 10);
+        const byPosition = beats[position - 1];
+        if (Number.isFinite(position) && byPosition)
+            return byPosition;
+        throw new Error(`No beat matches "${target}". Use a beat id or its 1-based position. ` +
+            (beats.length > 0
+                ? `This plan has ${beats.length} beats.`
+                : "This sequence has no beat plan yet; run ui_timeline_plan_beats first."));
+    }
+    const tools = [
+        sharedTool("ui_timeline_get_state", async () => {
+            const durationMs = clips.reduce((m, c) => Math.max(m, c.startMs + c.durationMs), 0);
+            return {
+                ok: true,
+                sequenceId,
+                fps,
+                width,
+                height,
+                durationMs,
+                playheadMs,
+                selectedClipIds: [...selectedClipIds],
+                // Absent when the document carries none: a reader that needs a
+                // number reads DEFAULT_TEMPO, and saying so beats printing a tempo
+                // the document does not store.
+                tempo,
+                tracks: tracks.map(serializeTrack),
+                clips: clips.map(serializeClip),
+                mediaTracks: mediaTracks.map((track) => ({
+                    id: track.id,
+                    clipId: track.clipId,
+                    sourceAssetId: track.sourceAssetId,
+                    name: track.name,
+                    kind: track.kind,
+                    sourceStartMs: track.sourceStartMs,
+                    sourceEndMs: track.sourceEndMs,
+                    sampleCount: track.samples.length,
+                    confidence: track.confidence,
+                    status: track.status,
+                    provenance: track.provenance
+                })),
+                markers: markers.map((m) => ({ ...m }))
+            };
+        }),
+        sharedTool("ui_timeline_add_track", async ({ type, name }) => {
+            const track = addTrackInternal(type, name);
+            return { ok: true, track: serializeTrack(track) };
+        }),
+        sharedTool("ui_timeline_move_track", async (args) => {
+            const { target, toIndex, before, after } = resolveMoveTrackArgs(args);
+            const track = resolveTrack(target);
+            const destination = {};
+            if (toIndex !== undefined)
+                destination.toIndex = toIndex;
+            if (before !== undefined) {
+                destination.beforeId = resolveTrack(before).id;
+            }
+            if (after !== undefined) {
+                destination.afterId = resolveTrack(after).id;
+            }
+            const orderedIds = moveTrackOrder(tracks, track.id, destination);
+            const byId = new Map(tracks.map((t) => [t.id, t]));
+            // The array order is what `get_state` prints, so keep it and the
+            // indices saying the same thing.
+            tracks.length = 0;
+            orderedIds.forEach((id, i) => {
+                const moved = byId.get(id);
+                moved.index = i;
+                tracks.push(moved);
+            });
+            return {
+                ok: true,
+                track: serializeTrack(track),
+                tracks: tracks.map(serializeTrack)
+            };
+        }),
+        sharedTool("ui_timeline_add_text_clip", async ({ text, name, transform, trackId, startMs, durationMs, opacity, style, ...loose }) => {
+            const track = trackId
+                ? resolveTrack(trackId)
+                : findOrCreateTrack("overlay");
+            // `style` wins over a top-level twin: a caller that sent both meant the
+            // bag it named.
+            const s = {
+                ...loose,
+                ...(style ??
+                    {})
+            };
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: track.id,
+                name: name ?? text,
+                startMs: startMs ?? trackEndMs(track.id),
+                durationMs: durationMs ?? DEFAULT_TEXT_CLIP_DURATION_MS,
+                mediaType: "text",
+                sourceType: "imported",
+                status: "generated",
+                textStyle: textStyleWithDefaults(text, s)
+            });
+            if (opacity !== undefined)
+                clip.opacity = opacity;
+            if (transform)
+                clip.transform = mergeClipTransform(clip.transform, transform);
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_delete_track", async (args) => {
+            const { target, deleteClips } = resolveDeleteTrackArgs(args);
+            const track = resolveTrack(target);
+            const onIt = clips.filter((c) => c.trackId === track.id);
+            if (onIt.length > 0 && !deleteClips) {
+                throw new Error(`Track "${track.name}" still holds ${onIt.length} clip(s): ` +
+                    `${onIt.map((c) => c.id).join(", ")}. Move them first, or pass ` +
+                    "deleteClips: true to delete them with the track.");
+            }
+            const removedClipIds = onIt.map((c) => c.id);
+            const kept = clips.filter((c) => c.trackId !== track.id);
+            clips.length = 0;
+            clips.push(...kept);
+            // A parent that went with the track would leave its children pointing
+            // at a clip that no longer exists, which the validator reads as a
+            // broken document rather than a deletion.
+            for (const clip of clips) {
+                if (clip.parentId && removedClipIds.includes(clip.parentId)) {
+                    delete clip.parentId;
+                }
+            }
+            selectedClipIds = selectedClipIds.filter((id) => !removedClipIds.includes(id));
+            const remaining = tracks.filter((t) => t.id !== track.id);
+            tracks.length = 0;
+            // Index is z-order, so the stack has to close over the gap.
+            remaining.forEach((t, i) => {
+                t.index = i;
+                tracks.push(t);
+            });
+            return {
+                ok: true,
+                deleted: { id: track.id, name: track.name, type: track.type },
+                deletedClipIds: removedClipIds,
+                tracks: tracks.map(serializeTrack)
+            };
+        }),
+        sharedTool("ui_timeline_add_media_clip", async ({ asset, trackId, startMs, durationMs, name, transform }) => {
+            if (!resolveAsset) {
+                throw new Error("This timeline surface cannot look up assets, so an existing asset cannot be placed here.");
+            }
+            const ref = asset;
+            const found = await resolveAsset(ref);
+            if (!found) {
+                throw new Error(`No asset found for "${ref}". Pass an asset id or an asset:// URI from list_assets.`);
+            }
+            const mediaType = mediaTypeForContentType(found.contentType);
+            if (!mediaType) {
+                throw new Error(`Asset "${found.name}" is ${found.contentType}, which is not video, image, or audio and cannot go on a timeline.`);
+            }
+            if (mediaType !== "image" && durationMs === undefined && !found.durationMs) {
+                throw new Error(`Asset "${found.name}" has no known duration. Supply durationMs or import media that can be probed.`);
+            }
+            const track = trackId
+                ? resolveTrack(trackId)
+                : findOrCreateTrack(trackTypeForMediaType(mediaType));
+            const init = {
+                id: nextClipId(),
+                trackId: track.id,
+                name: name ?? found.name,
+                startMs: startMs ?? trackEndMs(track.id),
+                durationMs: durationMs ??
+                    found.durationMs ??
+                    DEFAULT_MEDIA_CLIP_DURATION_MS,
+                mediaType,
+                sourceType: "imported",
+                status: "generated",
+                currentAssetId: found.id
+            };
+            if (found.thumbnailAssetId) {
+                init.thumbnailAssetId = found.thumbnailAssetId;
+            }
+            const clip = makeClip(init);
+            if (transform)
+                clip.transform = mergeClipTransform(clip.transform, transform);
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_add_shape_clip", async ({ shape, shapeStyle, name, transform, trackId, startMs, durationMs, opacity, ...loose }) => {
+            const track = trackId
+                ? resolveTrack(trackId)
+                : findOrCreateTrack("overlay");
+            const shapeArg = resolveShapeArg(shape, shapeStyle, loose);
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: track.id,
+                name: name ?? capitalize(shapeArg.kind),
+                startMs: startMs ?? trackEndMs(track.id),
+                durationMs: durationMs ?? DEFAULT_TEXT_CLIP_DURATION_MS,
+                mediaType: "shape",
+                sourceType: "imported",
+                status: "generated",
+                shapeStyle: shapeStyleWithDefaults(shapeArg)
+            });
+            if (opacity !== undefined)
+                clip.opacity = opacity;
+            if (transform)
+                clip.transform = mergeClipTransform(clip.transform, transform);
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_add_model3d_clip", async ({ assetId, trackId, startMs, durationMs, style, transform }) => {
+            // 3D is picture (D1), so it lands where a title lands.
+            const track = trackId
+                ? resolveTrack(trackId)
+                : findOrCreateTrack("overlay");
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: track.id,
+                name: DEFAULT_MODEL3D_CLIP_NAME,
+                startMs: startMs ?? trackEndMs(track.id),
+                durationMs: durationMs ??
+                    DEFAULT_MODEL3D_CLIP_DURATION_MS,
+                mediaType: "model3d",
+                sourceType: "imported",
+                status: "generated",
+                currentAssetId: assetId.trim(),
+                model3dStyle: model3dStyleWithPatch(undefined, style)
+            });
+            if (transform)
+                clip.transform = mergeClipTransform(clip.transform, transform);
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_model3d_style", async ({ target, patch }) => {
+            const clip = resolveClip(target);
+            if (clip.mediaType !== "model3d") {
+                throw new Error(`Clip "${clip.name}" is a ${clip.mediaType} clip, not a 3D clip — ` +
+                    "model3dStyle names a camera, an animation and lighting for a " +
+                    "glTF, and nothing else reads it.");
+            }
+            clip.model3dStyle = model3dStyleWithPatch(clip.model3dStyle, patch);
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_bake_model3d_clip", async ({ target }) => {
+            const clip = resolveClip(target);
+            if (clip.mediaType !== "model3d") {
+                throw new Error(`Clip "${clip.name}" is a ${clip.mediaType} clip, not a 3D clip — ` +
+                    "only a 3D clip has a camera, lighting and a glTF to render.");
+            }
+            const style = clip.model3dStyle;
+            if (!style) {
+                throw new Error(`Clip "${clip.name}" has no model3dStyle, so nothing names the ` +
+                    "camera, lighting or animation a bake would render.");
+            }
+            if (!clip.currentAssetId) {
+                throw new Error(`Clip "${clip.name}" has no glTF asset to bake — a 3D clip draws ` +
+                    "its asset the way an image clip draws its image.");
+            }
+            const sequence = { fps, width, height };
+            const dependencyHash = computeModel3DBakeHash(clip, sequence);
+            if (!bakeModel3DClip) {
+                return {
+                    ok: true,
+                    clip: serializeClip(clip),
+                    bakeStarted: false,
+                    note: "This surface has no Blender renderer, so nothing was baked."
+                };
+            }
+            const baked = await bakeModel3DClip({ clip, sequence, dependencyHash });
+            clip.model3dStyle = {
+                ...style,
+                bake: { assetId: baked.assetId, dependencyHash }
+            };
+            const now = new Date().toISOString();
+            clip.versions = [
+                ...(clip.versions ?? []),
+                makeClipVersion({
+                    id: nextVersionId(),
+                    createdAt: now,
+                    workflowUpdatedAt: now,
+                    jobId: baked.jobId ?? "",
+                    assetId: baked.assetId,
+                    dependencyHash
+                })
+            ];
+            return { ok: true, clip: serializeClip(clip), bakeStarted: true };
+        }),
+        sharedTool("ui_timeline_generate_clip", async ({ kind, prompt, trackId, startMs, durationMs, provider, model, voice, width: clipWidth, height: clipHeight, aspectRatio, resolution, autoGenerate }) => {
+            const mediaType = kind === "text-to-video"
+                ? "video"
+                : kind === "text-to-image"
+                    ? "image"
+                    : "audio";
+            const track = trackId
+                ? resolveTrack(trackId)
+                : kind === "text-to-audio"
+                    ? findOrCreateTrack("audio")
+                    : kind === "text-to-video"
+                        ? findOrCreateTrack("video")
+                        : (tracks.find((t) => t.type === "video" || t.type === "overlay") ??
+                            findOrCreateTrack("video"));
+            const generationStarted = autoGenerate !== false;
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: track.id,
+                name: prompt,
+                startMs: startMs ?? trackEndMs(track.id),
+                durationMs: durationMs ??
+                    (kind === "text-to-audio" ? 3000 : 5000),
+                mediaType,
+                sourceType: "generated",
+                bindingKind: kind,
+                status: generationStarted ? "generating" : "draft",
+                prompt: prompt,
+                provider: provider,
+                model: model,
+                voice: voice,
+                width: clipWidth,
+                height: clipHeight,
+                aspectRatio: aspectRatio,
+                resolution: resolution
+            });
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            const result = { ok: true, clip: serializeClip(clip), generationStarted };
+            if (!generationStarted) {
+                result.note = "Generation not started (autoGenerate=false).";
+            }
+            return result;
+        }),
+        sharedTool("ui_timeline_generatively_edit_clip", async ({ clip_id, instruction, provider, model }) => {
+            // The P0 request captures a durable destination. Unlike general
+            // timeline actions, this intentionally refuses names and selection.
+            const clip = clips.find((candidate) => candidate.id === clip_id);
+            if (!clip) {
+                throw new Error(`No clip with id "${clip_id}" exists on this timeline. Call ui_timeline_get_state and pass the clip id.`);
+            }
+            const baseline = ensureBaselineTake(clip);
+            if (baseline !== clip) {
+                clips = clips.map((candidate) => candidate.id === clip.id ? baseline : candidate);
+            }
+            const source = captureMediaEditSourceContext(sequenceId, baseline);
+            if (!source.ok)
+                throw new Error(source.error);
+            // Eval hosts have no selected model catalog. These deterministic
+            // placeholders only stand in for a real provider's returned asset;
+            // browser and server execution keep their normal model validation.
+            const resolvedProvider = provider ?? "headless";
+            const resolvedModel = model ?? "headless-video-to-video";
+            const request = createMediaEditRequest({
+                sourceContext: source.context,
+                instruction: instruction,
+                provider: resolvedProvider,
+                model: resolvedModel
+            });
+            const generationId = nextVersionId();
+            const now = new Date().toISOString();
+            const next = composeGenerativeTakePatch(baseline, "restyle", {
+                assetId: `generative://${baseline.id}/${generationId}`,
+                jobId: generationId,
+                createdAt: now,
+                workflowUpdatedAt: now,
+                provider: request.provider,
+                model: request.model,
+                prompt: request.instruction,
+                durationMs: request.sourceContext.timelineDurationMs,
+                mediaEdit: request
+            });
+            clips = clips.map((candidate) => candidate.id === baseline.id ? next : candidate);
+            const take = next.versions?.find((candidate) => candidate.id === generationId);
+            if (!take) {
+                throw new Error("The AI edit candidate could not be recorded.");
+            }
+            return {
+                ok: true,
+                requestId: generationId,
+                generationId,
+                activeTakeId: activeTakeIdOf(next) ?? null,
+                candidate: {
+                    id: take.id,
+                    status: take.status,
+                    source: take.source
+                },
+                clip: serializeClip(next)
+            };
+        }),
+        sharedTool("ui_timeline_apply_take", async ({ clip_id, take_id }) => {
+            const clip = clips.find((candidate) => candidate.id === clip_id);
+            if (!clip) {
+                throw new Error(`No clip with id "${clip_id}" exists on this timeline. Call ui_timeline_get_state and pass the clip id.`);
+            }
+            const take = (clip.versions ?? []).find((candidate) => candidate.id === take_id);
+            if (!take?.mediaEdit) {
+                throw new Error(`Take "${take_id}" is not an AI edit candidate for "${clip.name}". Apply only the candidate returned by ui_timeline_generatively_edit_clip.`);
+            }
+            const result = applyTakeToClip(clip, take_id);
+            if (result.error)
+                throw new Error(result.error);
+            clips = clips.map((candidate) => candidate.id === clip.id ? result.clip : candidate);
+            return { ok: true, clip: serializeClip(result.clip) };
+        }),
+        sharedTool("ui_timeline_split_clip", async ({ target, atMs }) => {
+            const clip = resolveClip(target);
+            const at = atMs ?? playheadMs;
+            const [left, right] = splitClip(clip, at);
+            left.id = nextClipId();
+            right.id = nextClipId();
+            const idx = clips.findIndex((c) => c.id === clip.id);
+            clips.splice(idx, 1, left, right);
+            selectedClipIds = selectedClipIds.filter((id) => id !== clip.id);
+            mediaTracks = resliceTracksForSplitClip(mediaTracks, clip.id, left, right, nextTrackId);
+            return { ok: true, clips: [serializeClip(left), serializeClip(right)] };
+        }),
+        sharedTool("ui_timeline_trim_clip", async ({ target, durationMs, inPointMs, outPointMs }) => {
+            const trimmed = applyTrim(resolveClip(target), {
+                durationMs: durationMs,
+                inPointMs: inPointMs,
+                outPointMs: outPointMs
+            });
+            mediaTracks = resliceTracksForTrimmedClip(mediaTracks, trimmed);
+            return { ok: true, clip: serializeClip(trimmed) };
+        }),
+        sharedTool("ui_timeline_move_clip", async ({ target, startMs, trackId }) => {
+            const moved = applyMove(resolveClip(target), {
+                startMs: startMs,
+                trackId: trackId
+            });
+            return { ok: true, clip: serializeClip(moved) };
+        }),
+        sharedTool("ui_timeline_delete_clip", async ({ target }) => {
+            const clip = resolveClip(target);
+            // Deleting a group deletes the parent, not the picture: its children
+            // stay where they are and stop inheriting (D4). Leaving them with a
+            // `parentId` nothing answers is what the validator calls a dangling
+            // parent.
+            const remaining = isGroupClip(clip) ? ungroup(clips, clip.id) : clips;
+            clips = remaining.filter((c) => c.id !== clip.id);
+            selectedClipIds = selectedClipIds.filter((id) => id !== clip.id);
+            return { ok: true, deleted: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_duplicate_clip", async ({ target, gapMs }) => {
+            const src = resolveClip(target);
+            const copy = {
+                ...src,
+                id: nextClipId(),
+                startMs: src.startMs + src.durationMs + (gapMs ?? 0),
+                versions: [],
+                animations: src.animations?.map((a) => ({ ...a, id: nextAnimId() }))
+            };
+            clips.push(copy);
+            selectedClipIds = [copy.id];
+            return { ok: true, clip: serializeClip(copy) };
+        }),
+        sharedTool("ui_timeline_set_clip_params", async ({ target, ...wrapped }) => {
+            const patch = unwrapClipParams(wrapped);
+            let clip = resolveClip(target);
+            rejectUnknownClipParams(patch);
+            // Timing belongs to move_clip and trim_clip, but a caller sending it
+            // here means one edit either way — so apply it through the same code
+            // rather than dropping it or making them call twice.
+            clip = applyTrim(clip, {
+                durationMs: patch.durationMs,
+                inPointMs: patch.inPointMs,
+                outPointMs: patch.outPointMs
+            });
+            clip = applyMove(clip, {
+                startMs: patch.startMs,
+                trackId: patch.trackId
+            });
+            // The style is a patch over what the clip already carries: changing one
+            // field used to mean re-sending the whole bag, and re-sending it is how
+            // the four fields the caller did not mean to touch get overwritten.
+            if (patch.textStyle !== undefined) {
+                patch.textStyle = mergeTextStyle(clip, patch.textStyle);
+            }
+            if (patch.fontSizePx !== undefined) {
+                // Shorthand for the one text field callers reach for by name.
+                const size = patch.fontSizePx;
+                const style = (patch.textStyle ?? clip.textStyle);
+                if (!style) {
+                    throw new Error(`Clip "${clip.name}" carries no text to size; fontSizePx applies to a text clip's textStyle.`);
+                }
+                patch.textStyle = { ...style, fontSizePx: size };
+            }
+            if (patch.name !== undefined)
+                clip.name = patch.name;
+            if (patch.transform !== undefined)
+                clip.transform = mergeClipTransform(clip.transform, patch.transform);
+            if (patch.opacity !== undefined)
+                clip.opacity = patch.opacity;
+            if (patch.speedMultiplier !== undefined)
+                clip.speedMultiplier = patch.speedMultiplier;
+            if (patch.volumeDb !== undefined)
+                clip.volumeDb = patch.volumeDb;
+            if (patch.fadeInMs !== undefined)
+                clip.fadeInMs = patch.fadeInMs;
+            if (patch.fadeOutMs !== undefined)
+                clip.fadeOutMs = patch.fadeOutMs;
+            if (patch.fadeInShape !== undefined)
+                clip.fadeInShape = patch.fadeInShape;
+            if (patch.fadeOutShape !== undefined)
+                clip.fadeOutShape = patch.fadeOutShape;
+            if (patch.blendMode !== undefined)
+                clip.blendMode = patch.blendMode;
+            if (patch.borderRadius !== undefined)
+                clip.borderRadius = patch.borderRadius;
+            if (patch.hidden !== undefined)
+                clip.hidden = patch.hidden;
+            if (patch.muted !== undefined)
+                clip.muted = patch.muted;
+            if (patch.locked !== undefined)
+                clip.locked = patch.locked;
+            if (patch.textStyle !== undefined)
+                clip.textStyle = patch.textStyle;
+            if (patch.shapeStyle !== undefined)
+                clip.shapeStyle = patch.shapeStyle;
+            if (patch.captionStyle !== undefined) {
+                // The style rides on the clip's caption, so a clip with no words to
+                // draw has nowhere to put it. Say so rather than storing a look
+                // nothing renders.
+                if (!clip.caption) {
+                    throw new Error(`Clip "${clip.name}" carries no caption to style.`);
+                }
+                clip.caption = {
+                    ...clip.caption,
+                    style: patch.captionStyle
+                };
+            }
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_add_group", async ({ name, startMs, durationMs, trackId, children, transform }) => {
+            // Resolve every child before anything is written: a half-applied group
+            // leaves the caller with an empty group and no idea which of its clips
+            // moved.
+            const targets = (children ?? []).map((ref) => resolveClip(ref));
+            const track = trackId
+                ? resolveTrack(trackId)
+                : findOrCreateTrack("overlay");
+            const group = makeClip({
+                id: nextClipId(),
+                trackId: track.id,
+                name: name,
+                startMs: startMs,
+                durationMs: durationMs,
+                mediaType: "group",
+                sourceType: "imported",
+                status: "generated"
+            });
+            if (transform)
+                group.transform = mergeClipTransform(group.transform, transform);
+            clips.push(group);
+            for (const child of targets) {
+                child.parentId = group.id;
+            }
+            selectedClipIds = [group.id];
+            return {
+                ok: true,
+                clip: serializeClip(group),
+                children: targets.map((c) => c.id)
+            };
+        }),
+        sharedTool("ui_timeline_set_parent", async ({ target, parentId }) => {
+            const clip = resolveClip(target);
+            if (parentId === null) {
+                delete clip.parentId;
+                return { ok: true, clip: serializeClip(clip) };
+            }
+            const parent = resolveClip(parentId);
+            if (parent.mediaType !== "group") {
+                throw new Error(`"${parent.name}" is a ${parent.mediaType} clip, not a group — parent to a clip created with add_group. ${validUnits(clips.filter((c) => c.mediaType === "group"), "group")}`);
+            }
+            // A cycle renders unparented and warns, so refusing it here is the
+            // only place it can still be fixed.
+            let cursor = parent;
+            while (cursor) {
+                if (cursor.id === clip.id) {
+                    throw new Error(`"${parent.name}" is inside "${clip.name}" — parenting them would make a cycle.`);
+                }
+                const next = cursor.parentId;
+                cursor = next ? clips.find((c) => c.id === next) : undefined;
+            }
+            clip.parentId = parent.id;
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_transition", async ({ target, transition }) => {
+            const clip = resolveClip(target);
+            if (transition === null) {
+                delete clip.transitionIn;
+            }
+            else {
+                clip.transitionIn = buildTransition(transition);
+            }
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        tool("ui_timeline_generate_transition_at_cut", "Generate an inactive cut-level transition candidate for two explicitly adjacent clips. This does not change either clip or create a clip take. Preview the returned candidate before applying it.", generatedTransitionCandidateParams, async (args) => {
+            const candidate = await createTransitionCandidate(args);
+            return {
+                ok: true,
+                requestId: candidate.generationId,
+                generationId: candidate.generationId,
+                candidate,
+                source: candidate.source
+            };
+        }),
+        tool("ui_timeline_preview_transition_candidate", "Audition one generated cut-level transition candidate without changing the timeline document. Refuses candidates whose selected clips, source takes, or cut are stale.", transitionCandidateParams, async ({ candidate_id }) => {
+            const candidate = transitionCandidates.find((entry) => entry.id === candidate_id);
+            if (!candidate) {
+                throw new Error(`No generated transition candidate named "${candidate_id}" exists.`);
+            }
+            assertFreshTransitionCandidate(candidate);
+            auditionedTransitionCandidateId = candidate.id;
+            return { ok: true, previewOnly: true, candidate };
+        }),
+        tool("ui_timeline_apply_transition_at_cut", `${APPLY_TRANSITION_AT_CUT_DESCRIPTION} With clip ids and timing, this creates an inactive cut-level candidate. Apply a returned candidate_id explicitly to commit it as one undoable operation.`, transitionCandidateLifecycleParams, async (args) => {
+            if (args.candidate_id !== undefined) {
+                const applied = applyTransitionCandidate(args.candidate_id);
+                return { ok: true, applied: true, ...applied };
+            }
+            const candidate = await createTransitionCandidate(args);
+            return {
+                ok: true,
+                applied: false,
+                requestId: candidate.generationId,
+                generationId: candidate.generationId,
+                candidate,
+                source: candidate.source,
+                next: "Preview with ui_timeline_preview_transition_candidate, then call this tool with candidate_id to apply."
+            };
+        }),
+        sharedTool("ui_timeline_set_mask", async ({ target, mask }) => {
+            const clip = resolveClip(target);
+            if (mask === null) {
+                delete clip.mask;
+            }
+            else {
+                clip.mask = buildMask(mask, parseSvgPath);
+            }
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_matte", async ({ target, matte }) => {
+            const clip = resolveClip(target);
+            if (matte === null) {
+                delete clip.matte;
+                return { ok: true, clip: serializeClip(clip) };
+            }
+            const input = matte;
+            const source = resolveClip(input.source);
+            if (source.id === clip.id) {
+                throw new Error(`"${clip.name}" cannot be its own matte source — name another clip.`);
+            }
+            const matteOut = {
+                sourceClipId: source.id,
+                mode: input.mode
+            };
+            if (input.invert !== undefined)
+                matteOut.invert = input.invert;
+            clip.matte = matteOut;
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        // Headless-only: the inspector's own controls write these knobs into the
+        // store. Both this and the ops module's `set_generated_matte` reach
+        // `selectGeneratedMatteVersion`, so the version list cannot fork.
+        tool("ui_timeline_set_generated_matte", SET_GENERATED_MATTE_DESCRIPTION, setGeneratedMatteParams, async (args) => {
+            const input = args;
+            const clip = resolveClip(input.target);
+            if (input.clear === true) {
+                delete clip.generatedMatte;
+                return {
+                    ok: true,
+                    clip: serializeClip(clip),
+                    generatedMatte: null
+                };
+            }
+            if (!clip.generatedMatte) {
+                throw new Error(`"${clip.name}" carries no generated matte. Run isolate_subject ` +
+                    "on it first; this op only adjusts one that exists.");
+            }
+            if (input.selectVersionAssetId !== undefined) {
+                clip.generatedMatte = selectGeneratedMatteVersion(clip, input.selectVersionAssetId).generatedMatte;
+            }
+            const matte = clip.generatedMatte;
+            if (input.invert !== undefined)
+                matte.invert = input.invert;
+            if (input.strength !== undefined) {
+                matte.strength = Math.min(1, Math.max(0, input.strength));
+            }
+            if (input.featherPx !== undefined) {
+                matte.featherPx = Math.max(0, input.featherPx);
+            }
+            return { ok: true, clip: serializeClip(clip), generatedMatte: matte };
+        }),
+        sharedTool("ui_timeline_set_time_remap", async ({ target, timeRemap }) => {
+            const clip = resolveClip(target);
+            if (timeRemap === null) {
+                delete clip.timeRemap;
+            }
+            else {
+                clip.timeRemap = buildTimeRemap(timeRemap);
+            }
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_effects", async ({ target, effects }) => {
+            const clip = resolveClip(target);
+            const list = effects.map(buildEffect);
+            if (list.length === 0) {
+                delete clip.effects;
+            }
+            else {
+                clip.effects = list;
+            }
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_clip_binding", async ({ target, ...patch }) => {
+            const clip = resolveClip(target);
+            if (clip.sourceType !== "generated") {
+                throw new Error(`"${clip.name}" is not a generated clip — ui_timeline_set_clip_binding only applies to clips created with ui_timeline_generate_clip.`);
+            }
+            if (patch.prompt !== undefined)
+                clip.prompt = patch.prompt;
+            if (patch.negativePrompt !== undefined)
+                clip.negativePrompt = patch.negativePrompt;
+            if (patch.provider !== undefined)
+                clip.provider = patch.provider;
+            if (patch.model !== undefined)
+                clip.model = patch.model;
+            if (patch.voice !== undefined)
+                clip.voice = patch.voice;
+            if (patch.width !== undefined)
+                clip.width = patch.width;
+            if (patch.height !== undefined)
+                clip.height = patch.height;
+            if (patch.aspectRatio !== undefined)
+                clip.aspectRatio = patch.aspectRatio;
+            if (patch.resolution !== undefined)
+                clip.resolution = patch.resolution;
+            if (patch.strength !== undefined)
+                clip.strength = patch.strength;
+            if (patch.numInferenceSteps !== undefined)
+                clip.numInferenceSteps = patch.numInferenceSteps;
+            if (patch.regenerate)
+                clip.status = "queued";
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_animate_clip", async ({ target, mode, animations }) => {
+            const clip = resolveClip(target);
+            const inputs = animations;
+            const built = [];
+            for (const input of inputs) {
+                if (input.preset === CUSTOM_ANIMATION_PRESET_ID) {
+                    // `{preset: "custom", custom: {curves}}` reads as naturally as the
+                    // flat form, so lift it rather than refusing it.
+                    built.push(await buildCustomAnimation(clip, liftCustomAnimation(input)));
+                    continue;
+                }
+                const preset = ANIMATION_PRESETS.find((p) => p.id === input.preset);
+                if (!preset) {
+                    const ids = ANIMATION_PRESETS.map((p) => p.id).join(", ");
+                    throw new Error(`Unknown animation preset "${input.preset}". Valid presets: ${ids}, ${CUSTOM_ANIMATION_PRESET_ID}.`);
+                }
+                if (!preset.roles.includes(input.role)) {
+                    throw new Error(`Preset "${input.preset}" does not support role "${input.role}". Valid roles for "${input.preset}": ${preset.roles.join(", ")}.`);
+                }
+                if (input.preset === "typewriter" && clip.mediaType !== "text") {
+                    throw new Error('Preset "typewriter" requires a text clip.');
+                }
+                const timing = input.preset === "typewriter"
+                    ? typewriterTiming(clip.textStyle?.text ?? "", clip.durationMs - (input.delayMs ?? 0), input.durationMs, input.stagger)
+                    : null;
+                built.push({
+                    id: nextAnimId(),
+                    role: input.role,
+                    preset: input.preset,
+                    durationMs: timing?.durationMs ?? input.durationMs ?? preset.defaultDurationMs,
+                    delayMs: input.delayMs,
+                    easing: input.easing,
+                    params: input.params,
+                    stagger: timing?.stagger ?? input.stagger,
+                    caret: input.preset === "typewriter" ? input.caret : undefined
+                });
+            }
+            clip.animations =
+                mode === "add"
+                    ? [...(clip.animations ?? []), ...built]
+                    : built;
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        // Headless-only: the browser writes curves through the inspector, not
+        // through an agent call. Both this and the ops module's `set_baked_animation`
+        // go through `buildBakedAnimation`, so the replace rule cannot fork.
+        tool("ui_timeline_set_baked_animation", SET_BAKED_ANIMATION_DESCRIPTION, setBakedAnimationParams, async ({ target, animation }) => {
+            const clip = resolveClip(target);
+            const outcome = buildBakedAnimation(clip, animation, nextAnimId);
+            clip.animations = outcome.animations;
+            return {
+                ok: true,
+                clip: serializeClip(clip),
+                animationId: outcome.animationId,
+                keyframeCount: outcome.animation.custom?.curves[0]?.keyframes.length ?? 0,
+                replaced: outcome.replaced
+            };
+        }),
+        sharedTool("ui_timeline_stagger_animations", async ({ clip_ids, offset_ms }) => {
+            const selected = clip_ids.map(resolveClip);
+            const ids = selected.map((clip) => clip.id);
+            if (new Set(ids).size !== ids.length) {
+                throw new Error("clip_ids must contain distinct clip IDs.");
+            }
+            for (const clip of selected) {
+                if (!clip.animations?.length)
+                    throw new Error(`Clip "${clip.name}" has no animations to stagger.`);
+            }
+            const staggered = staggerClipAnimations(clips, ids, offset_ms);
+            const byId = new Map(staggered.map((clip) => [clip.id, clip]));
+            clips.splice(0, clips.length, ...staggered);
+            return { ok: true, clips: ids.map((id) => serializeClip(byId.get(id))) };
+        }),
+        sharedTool("ui_timeline_clear_animations", async ({ target, role }) => {
+            const clip = resolveClip(target);
+            clip.animations = role
+                ? (clip.animations ?? []).filter((a) => a.role !== role)
+                : [];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_list_animation_presets", async () => {
+            const presets = ANIMATION_PRESETS.map((p) => ({
+                id: p.id,
+                roles: p.roles,
+                defaultDurationMs: p.defaultDurationMs,
+                defaultEasing: p.defaultEasing,
+                params: p.params,
+                describe: p.describe
+            }));
+            return {
+                ok: true,
+                presets,
+                custom: CUSTOM_ANIMATION_CONTRACT,
+                properties: CUSTOM_ANIMATION_CONTRACT.properties
+            };
+        }),
+        sharedTool("ui_timeline_select_clip", async ({ target }) => {
+            const t = target;
+            if (!t) {
+                selectedClipIds = [];
+                return { ok: true, selected: null };
+            }
+            const clip = resolveClip(t);
+            selectedClipIds = [clip.id];
+            return { ok: true, selected: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_seek", async ({ timeMs }) => {
+            playheadMs = Math.max(0, timeMs);
+            return { ok: true, playheadMs };
+        }),
+        sharedTool("ui_timeline_add_marker", async ({ timeMs, label, color, note }) => {
+            const at = timeMs;
+            if (at < 0) {
+                throw new Error(`A marker cannot sit before zero; got ${at}ms.`);
+            }
+            const marker = {
+                id: nextMarkerId(),
+                timeMs: Math.round(at),
+                label: label ?? ""
+            };
+            if (color !== undefined)
+                marker.color = color;
+            if (note !== undefined)
+                marker.note = note;
+            markers.push(marker);
+            return { ok: true, marker: { ...marker } };
+        }),
+        // ── Guided video flow (PRD § 8.6) ───────────────────────────────────
+        sharedTool("ui_timeline_set_setup", async ({ stage, brief, format, voiceover }) => {
+            setup = {
+                stage: stage ?? setup?.stage ?? "idea",
+                brief: brief ?? setup?.brief ?? "",
+                format: format ?? setup?.format,
+                // Absent leaves the choice unsaid; `false` is a deliberate silence,
+                // so it is written rather than read as "nothing passed".
+                voiceover: voiceover ?? setup?.voiceover,
+                beats: setup?.beats
+            };
+            return { ok: true, setup: structuredClone(setup) };
+        }),
+        sharedTool("ui_timeline_plan_beats", async ({ beats }) => {
+            // There is no Director on this surface — the caller *is* the model, so
+            // it writes the plan rather than asking for one. Refusing without
+            // `beats` says which half of the shared contract this host implements.
+            const written = beats;
+            if (!written || written.length === 0) {
+                throw new Error("This surface has no Director: pass `beats` with the plan you want. Each beat needs a prompt and a durationMs.");
+            }
+            const planned = written.map((beat) => ({
+                id: `beat_${++beatSeq}`,
+                prompt: beat.prompt,
+                duration_ms: Math.max(1, Math.round(beat.durationMs)),
+                transition: beat.transition,
+                voiceover: beat.voiceover,
+                music: beat.music
+            }));
+            setup = {
+                stage: "review",
+                brief: setup?.brief ?? "",
+                format: setup?.format,
+                voiceover: setup?.voiceover,
+                beats: planned
+            };
+            // Named in the answer because it is the contract: the plan is text,
+            // and costs nothing until generate_from_beats runs (D4).
+            return {
+                ok: true,
+                beats: planned.map((beat) => ({ ...beat })),
+                clipsCreated: 0,
+                jobsStarted: 0
+            };
+        }),
+        sharedTool("ui_timeline_update_beat", async ({ beat, prompt, durationMs, transition, voiceover, music }) => {
+            const found = resolveBeat(beat);
+            const next = { ...found };
+            if (prompt !== undefined)
+                next.prompt = prompt;
+            if (durationMs !== undefined) {
+                next.duration_ms = Math.max(1, Math.round(durationMs));
+            }
+            if (transition !== undefined) {
+                next.transition = transition ?? undefined;
+            }
+            if (voiceover !== undefined)
+                next.voiceover = voiceover;
+            if (music !== undefined)
+                next.music = music;
+            setup = {
+                stage: setup?.stage ?? "review",
+                brief: setup?.brief ?? "",
+                format: setup?.format,
+                voiceover: setup?.voiceover,
+                beats: (setup?.beats ?? []).map((candidate) => candidate.id === found.id ? next : candidate)
+            };
+            return { ok: true, beat: { ...next } };
+        }),
+        sharedTool("ui_timeline_remove_beat", async ({ beat }) => {
+            // Resolved before it is dropped, so the answer names what went and an
+            // unresolvable target says so rather than reporting a silent success.
+            const found = resolveBeat(beat);
+            setup = {
+                stage: setup?.stage ?? "review",
+                brief: setup?.brief ?? "",
+                format: setup?.format,
+                voiceover: setup?.voiceover,
+                beats: (setup?.beats ?? []).filter((candidate) => candidate.id !== found.id)
+            };
+            return { ok: true, removed: { ...found } };
+        }),
+        sharedTool("ui_timeline_generate_from_beats", async ({ model, provider, voice, music }) => {
+            const plan = setup?.beats ?? [];
+            if (plan.length === 0) {
+                throw new Error("There is no beat plan to generate from; call ui_timeline_plan_beats first.");
+            }
+            const videoTrack = findOrCreateTrack("video");
+            const wantsMusic = music ??
+                plan.some((beat) => beat.music === true);
+            const voiceTrack = voice !== undefined && plan.some((beat) => (beat.voiceover ?? "") !== "")
+                ? findOrCreateTrack("audio")
+                : null;
+            const videoClipIds = [];
+            const voiceoverClipIds = [];
+            const planned = [];
+            let startMs = 0;
+            for (const [index, beat] of plan.entries()) {
+                const durationMs = Math.max(1, Math.round(beat.duration_ms));
+                const clip = makeClip({
+                    id: nextClipId(),
+                    trackId: videoTrack.id,
+                    name: `Beat ${index + 1}`,
+                    startMs,
+                    durationMs,
+                    mediaType: "video",
+                    sourceType: "generated",
+                    bindingKind: "text-to-video",
+                    prompt: beat.prompt,
+                    provider: provider,
+                    model: model,
+                    beatId: beat.id,
+                    status: "draft"
+                });
+                if (beat.transition) {
+                    clip.transitionIn = buildTransition({
+                        type: beat.transition,
+                        durationMs: 500
+                    });
+                }
+                clips.push(clip);
+                videoClipIds.push(clip.id);
+                const line = (beat.voiceover ?? "").trim();
+                if (voiceTrack && line.length > 0) {
+                    const voiceClip = makeClip({
+                        id: nextClipId(),
+                        trackId: voiceTrack.id,
+                        name: `Beat ${index + 1} voiceover`,
+                        startMs,
+                        durationMs,
+                        mediaType: "audio",
+                        sourceType: "generated",
+                        bindingKind: "text-to-audio",
+                        prompt: line,
+                        voice: voice,
+                        beatId: beat.id,
+                        status: "draft"
+                    });
+                    clips.push(voiceClip);
+                    voiceoverClipIds.push(voiceClip.id);
+                }
+                planned.push({ ...beat, clip_id: clip.id });
+                startMs += durationMs;
+            }
+            let musicClipId = null;
+            if (wantsMusic) {
+                // One bed under the whole cut, never one per beat: overlapping music
+                // clips would play at once.
+                const musicTrack = findOrCreateTrack("audio");
+                const musicClip = makeClip({
+                    id: nextClipId(),
+                    trackId: musicTrack.id,
+                    name: "Music",
+                    startMs: 0,
+                    durationMs: startMs,
+                    mediaType: "audio",
+                    sourceType: "generated",
+                    bindingKind: "text-to-audio",
+                    prompt: `Instrumental score under: ${setup?.brief ?? ""}`,
+                    status: "draft"
+                });
+                clips.push(musicClip);
+                musicClipId = musicClip.id;
+            }
+            setup = {
+                stage: "done",
+                brief: setup?.brief ?? "",
+                format: setup?.format,
+                voiceover: setup?.voiceover,
+                beats: planned
+            };
+            return {
+                ok: true,
+                videoClipIds,
+                voiceoverClipIds,
+                musicClipId,
+                // Nothing renders headlessly: this authors the cut, and the clips are
+                // drafts until a renderer runs them.
+                startedClipIds: [],
+                note: "Clips created as drafts — this surface renders nothing."
+            };
+        }),
+        sharedTool("ui_timeline_delete_marker", async ({ target }) => {
+            const marker = resolveMarker(target);
+            markers = markers.filter((m) => m.id !== marker.id);
+            return { ok: true, deleted: { ...marker } };
+        }),
+        sharedTool("ui_timeline_set_markers_from_beats", async ({ onsets_ms, bpm, offset_ms, count, label }) => {
+            const grid = buildBeatGrid({
+                onsetsMs: onsets_ms,
+                bpm: bpm,
+                offsetMs: offset_ms,
+                count: count
+            });
+            const stem = (label ?? "Beat").trim() || "Beat";
+            const taken = new Set(markers.map((m) => m.timeMs));
+            const added = [];
+            const skipped = [];
+            for (const [index, timeMs] of grid.entries()) {
+                if (taken.has(timeMs)) {
+                    skipped.push(timeMs);
+                    continue;
+                }
+                const marker = {
+                    id: nextMarkerId(),
+                    timeMs,
+                    label: `${stem} ${index + 1}`
+                };
+                markers.push(marker);
+                taken.add(timeMs);
+                added.push(marker);
+            }
+            return {
+                ok: true,
+                grid: { count: grid.length, firstMs: grid[0], lastMs: grid[grid.length - 1] },
+                added: added.map((m) => ({ ...m })),
+                skipped_times_ms: skipped,
+                markers: markers.length
+            };
+        }),
+        sharedTool("ui_timeline_snap_to_beats", async ({ targets, onsets_ms, bpm, offset_ms, tolerance_ms, mode, action }) => {
+            const named = targets === undefined || targets === "all"
+                ? undefined
+                : targets;
+            const { clips: targeted, missing } = resolveSnapTargets(named);
+            const offsetMs = offset_ms ?? 0;
+            // A tempo grid has to reach the last boundary being snapped, so its
+            // length comes from the targets rather than from the caller.
+            const reachMs = targeted.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0);
+            const grid = buildBeatGrid({
+                onsetsMs: onsets_ms,
+                bpm: bpm,
+                offsetMs: offset_ms,
+                count: bpm === undefined
+                    ? undefined
+                    : beatCountToCover(bpm, offsetMs, reachMs)
+            });
+            const options = {};
+            if (tolerance_ms !== undefined) {
+                options.toleranceMs = tolerance_ms;
+            }
+            if (mode !== undefined)
+                options.mode = mode;
+            if (action !== undefined)
+                options.action = action;
+            const result = snapClipsToGrid(targeted.map((clip) => ({
+                id: clip.id,
+                startMs: clip.startMs,
+                durationMs: clip.durationMs
+            })), grid, options);
+            const byId = new Map(targeted.map((clip) => [clip.id, clip]));
+            const reported = result.clips.map((entry) => {
+                const clip = byId.get(entry.clipId);
+                if (entry.snapped && clip) {
+                    // Through the same ops the caller would use: a group carries its
+                    // children (D4) and a trim carries the source points, neither of
+                    // which a raw startMs/durationMs write does.
+                    try {
+                        if (entry.after.durationMs === entry.before.durationMs) {
+                            applyMove(clip, { startMs: entry.after.startMs });
+                        }
+                        else {
+                            let trimmed = clip;
+                            if (entry.after.startMs !== entry.before.startMs) {
+                                trimmed = applyTrimStart(clip, entry.after.startMs);
+                            }
+                            applyTrim(trimmed, { durationMs: entry.after.durationMs });
+                        }
+                    }
+                    catch (error) {
+                        return {
+                            ...entry,
+                            snapped: false,
+                            after: entry.before,
+                            delta: { startMs: 0, endMs: 0 },
+                            reason: error instanceof Error ? error.message : String(error),
+                            clipName: clip.name
+                        };
+                    }
+                }
+                return { ...entry, clipName: clip?.name ?? null };
+            });
+            // A name nothing matched is a skip like any other: the caller has to
+            // see it in the same list, not infer it from a shorter one.
+            for (const target of missing) {
+                reported.push({
+                    clipId: target,
+                    clipName: null,
+                    snapped: false,
+                    before: { startMs: 0, endMs: 0, durationMs: 0 },
+                    after: { startMs: 0, endMs: 0, durationMs: 0 },
+                    delta: { startMs: 0, endMs: 0 },
+                    reason: `no clip matches "${target}"`
+                });
+            }
+            return {
+                ok: true,
+                grid: {
+                    count: grid.length,
+                    firstMs: grid[0],
+                    lastMs: grid[grid.length - 1]
+                },
+                toleranceMs: result.toleranceMs,
+                mode: result.mode,
+                action: result.action,
+                snapped: result.snapped,
+                skipped: result.skipped + missing.length,
+                clips: reported
+            };
+        }),
+        // ── MIDI ────────────────────────────────────────────────────────────
+        // Notes live on the clip, the instrument on the track, and the tempo on
+        // the document, so each gets its own op.
+        sharedTool("ui_timeline_add_midi_clip", async ({ track, start_ms, duration_ms, name, notes }) => {
+            const midiTrack = resolveMidiTrack(track);
+            const clipName = name ?? "Phrase";
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: midiTrack.id,
+                name: clipName,
+                startMs: start_ms,
+                durationMs: duration_ms,
+                mediaType: "midi",
+                sourceType: "imported",
+                status: "generated",
+                notes: buildNotes(notes, clipName)
+            });
+            clips.push(clip);
+            selectedClipIds = [clip.id];
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_notes", async ({ clip: target, notes }) => {
+            const clip = resolveMidiClip(target);
+            // Built before anything is written: a refused list must leave the clip
+            // exactly as it was, not half replaced.
+            clip.notes = buildNotes(notes, clip.name);
+            return { ok: true, clip: serializeClip(clip) };
+        }),
+        sharedTool("ui_timeline_set_tempo", async ({ bpm, offset_ms, beats_per_bar, beat_unit }) => {
+            const previous = resolveTempo({ tempo });
+            const next = {
+                bpm: bpm,
+                offsetMs: offset_ms ?? previous.offsetMs,
+                timeSignature: {
+                    beatsPerBar: beats_per_bar ??
+                        previous.timeSignature.beatsPerBar,
+                    beatUnit: beat_unit ?? previous.timeSignature.beatUnit
+                }
+            };
+            // Milliseconds are the master clock, so the stored ms of every midi
+            // clip move and nothing else on the timeline does.
+            clips = rescaleClipsForTempo(clips, tracks, previous, next);
+            tempo = next;
+            return {
+                ok: true,
+                tempo: next,
+                previousTempo: previous,
+                rescaledClipIds: clips
+                    .filter((c) => c.mediaType === "midi")
+                    .map((c) => c.id)
+            };
+        }),
+        sharedTool("ui_timeline_set_track_instrument", async ({ track, instrument }) => {
+            const midiTrack = resolveMidiTrack(track);
+            // Resolved before the track is touched, so an unknown preset id leaves
+            // the voice the track already had.
+            midiTrack.instrument = resolveInstrumentArg(instrument);
+            return { ok: true, track: serializeTrack(midiTrack) };
+        }),
+        // The note edits. Each runs the whole list through one pure function from
+        // `@nodetool-ai/timeline` and replaces it — the ids survive, so a
+        // selection and an undo in the editor still point at the same notes.
+        sharedTool("ui_timeline_transpose_clip", async ({ clip: target, semitones }) => {
+            const clip = resolveMidiClip(target);
+            clip.notes = transposeNotes(clip.notes ?? [], semitones);
+            return {
+                ok: true,
+                clip: serializeClip(clip),
+                noteCount: clip.notes.length
+            };
+        }),
+        sharedTool("ui_timeline_quantize_notes", async ({ clip: clipRef, division, strength, target }) => {
+            const clip = resolveMidiClip(clipRef);
+            const before = clip.notes ?? [];
+            const options = { division: division };
+            if (strength !== undefined)
+                options.strength = strength;
+            if (target !== undefined)
+                options.target = target;
+            const quantized = quantizeNotes(before, options);
+            // The notes come back in the order they went in, so this pairs each
+            // one with itself. A phrase already on the grid reports 0 moved
+            // instead of reading as an edit that changed something.
+            const movedNoteCount = quantized.filter((note, i) => note.startTick !== before[i].startTick ||
+                note.durationTick !== before[i].durationTick).length;
+            clip.notes = quantized;
+            return {
+                ok: true,
+                clip: serializeClip(clip),
+                noteCount: quantized.length,
+                movedNoteCount
+            };
+        }),
+        sharedTool("ui_timeline_scale_velocity", async ({ clip: target, factor }) => {
+            const clip = resolveMidiClip(target);
+            clip.notes = scaleVelocity(clip.notes ?? [], factor);
+            return {
+                ok: true,
+                clip: serializeClip(clip),
+                noteCount: clip.notes.length
+            };
+        }),
+        tool("ui_timeline_insert_composition", "Insert a stored composition — a group of clips with named parameters (a lower third, a title card, a callout) — at a timecode. Its children keep the layering the template declares: each template track becomes an overlay track of its own, front-most on top, reused across insertions. `params` overrides the template's defaults by name; anything omitted keeps its default. Call list_compositions for the ids and their parameters.", z.object({
+            composition_id: z
+                .string()
+                .describe("Composition id, from list_compositions."),
+            startMs: z
+                .number()
+                .describe("Where the group starts on the timeline, in ms."),
+            trackId: z
+                .string()
+                .optional()
+                .describe("Track for the group clip itself. Its children still get their own overlay tracks. Defaults to an overlay track."),
+            params: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe("Parameter overrides by name, e.g. {name: \"Ada Lovelace\"}. A name the template does not declare, or a value of the wrong type, is refused.")
+        }), async ({ composition_id, startMs, trackId, params }) => {
+            if (!loadComposition) {
+                throw new Error("This surface has no composition library, so insert_composition cannot resolve a template.");
+            }
+            const id = composition_id;
+            const composition = await loadComposition.get(id);
+            if (!composition) {
+                const available = await loadComposition.listIds();
+                throw new Error(`No composition with id "${id}". ` +
+                    (available.length > 0
+                        ? `Available: ${available.join(", ")}.`
+                        : "This install has none — save one with save_composition."));
+            }
+            const minted = instantiateComposition(composition, {
+                startMs: startMs,
+                params: params,
+                newId: nextClipId
+            });
+            // Template track ids are names, not document ids. Two clips overlapping
+            // on one track auto-dissolve into each other, so each template track
+            // becomes a track of its own — created front-most first, because the
+            // lowest track index draws on top (I9).
+            const templateTracks = [];
+            for (const child of composition.children) {
+                if (!templateTracks.includes(child.trackId)) {
+                    templateTracks.push(child.trackId);
+                }
+            }
+            const mapped = new Map();
+            for (const name of [...templateTracks].reverse()) {
+                const existing = tracks.find((t) => t.type === "overlay" && t.name === name);
+                mapped.set(name, (existing ?? addTrackInternal("overlay", name)).id);
+            }
+            // The group draws nothing, but it still occupies its track's timeline,
+            // and a group sharing a track with one of its children reads as an
+            // overlap. It gets a track named after the composition instead.
+            const groupTrack = trackId
+                ? resolveTrack(trackId)
+                : (tracks.find((t) => t.type === "overlay" && t.name === composition.name) ?? addTrackInternal("overlay", composition.name));
+            const [group, ...children] = minted;
+            group.trackId = groupTrack.id;
+            for (const [index, child] of children.entries()) {
+                child.trackId =
+                    mapped.get(composition.children[index].trackId) ?? groupTrack.id;
+            }
+            clips.push(group, ...children);
+            selectedClipIds = [group.id];
+            return {
+                ok: true,
+                compositionId: composition.id,
+                clip: serializeClip(group),
+                children: children.map((child) => serializeClip(child)),
+                params: group.compositionParams ?? {}
+            };
+        }),
+        // Headless-only: the editor's ClipVersionHistory panel writes take
+        // switches, renames and deletes straight into TimelineStore via
+        // restoreVersion/renameTake/deleteTake. This op reaches the same
+        // `selectTake`/`renameTake`/`deleteTake` helpers, so the take list cannot
+        // fork between the two hosts (P0 AI Video, PRD § 8.10).
+        tool("ui_timeline_list_takes", "List a clip's take history (clip.versions): id, label, source, " +
+            "provider, model, createdAt, costCredits, durationMs, status, " +
+            "favorite, and which one is active.", z.object({ target: z.string().describe("Clip id or name.") }), async ({ target }) => {
+            const clip = resolveClip(target);
+            const versions = clip.versions ?? [];
+            const activeId = activeTakeIdOf(clip);
+            return {
+                ok: true,
+                takes: versions.map((v) => ({
+                    id: v.id,
+                    label: v.label,
+                    source: v.source,
+                    provider: v.provider,
+                    model: v.model,
+                    createdAt: v.createdAt,
+                    costCredits: v.costCredits,
+                    durationMs: v.durationMs,
+                    status: v.status,
+                    favorite: v.favorite,
+                    active: v.id === activeId
+                })),
+                activeTakeId: activeId ?? null
+            };
+        }),
+        tool("ui_timeline_select_take", "Make a stored take current on a clip — the same switch " +
+            "restoreVersion does in the editor. Refuses a take that is not " +
+            '`status: "success"`.', z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes.")
+        }), async ({ target, takeId }) => {
+            const clip = resolveClip(target);
+            if (clip.mediaType === "model3d") {
+                throw new Error(`Clip "${clip.name}" is a 3D clip — its version history includes ` +
+                    "bake renders that must not replace the glTF source. Take " +
+                    "selection is not available for model3d clips yet.");
+            }
+            const version = (clip.versions ?? []).find((v) => v.id === takeId);
+            if (!version) {
+                throw new Error(`No take "${takeId}" on "${clip.name}". ` +
+                    validUnits((clip.versions ?? []).map((v) => ({
+                        id: v.id,
+                        name: v.label ?? v.id
+                    })), "take"));
+            }
+            if (version.status !== "success") {
+                throw new Error(`Take "${takeId}" on "${clip.name}" did not finish successfully ` +
+                    `(status: ${version.status}) — only a successful take can be selected.`);
+            }
+            const next = selectTake(clip, takeId);
+            clips = clips.map((c) => (c.id === clip.id ? next : c));
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        tool("ui_timeline_rename_take", "Set a take's display label.", z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes."),
+            label: z.string().describe("The new display label.")
+        }), async ({ target, takeId, label }) => {
+            const clip = resolveClip(target);
+            if (!(clip.versions ?? []).some((v) => v.id === takeId)) {
+                throw new Error(`No take "${takeId}" on "${clip.name}". ` +
+                    validUnits((clip.versions ?? []).map((v) => ({
+                        id: v.id,
+                        name: v.label ?? v.id
+                    })), "take"));
+            }
+            const next = renameTakeOnClip(clip, takeId, label);
+            clips = clips.map((c) => (c.id === clip.id ? next : c));
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        tool("ui_timeline_delete_take", "Remove a take from a clip's history. Refuses when `takeId` is the " +
+            "active take — select_take a different take first, then delete the " +
+            "one you no longer want; a clip must always keep at least one take.", z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes.")
+        }), async ({ target, takeId }) => {
+            const clip = resolveClip(target);
+            const { clip: next, error } = deleteTakeOnClip(clip, takeId);
+            if (error)
+                throw new Error(error);
+            clips = clips.map((c) => (c.id === clip.id ? next : c));
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        // Subject/object tracks (P0 AI Video, Phase 2). The async provider call
+        // that fills a track's samples is the `track_object` capability, not an
+        // op — these four are the structural half over it, and they carry the
+        // same semantics as `applyTimelineOp`'s own cases so the two hosts cannot
+        // fork (`packages/timeline/src/ops/apply.ts`).
+        tool("ui_timeline_list_tracks", "List the document's subject/object tracks — id, clipId, name, kind, " +
+            "status, source window and sample count. The samples themselves are " +
+            "not returned: a track carries one per frame it covers, which is a " +
+            "wall of numbers no caller reads through a listing.", z.object({
+            target: z
+                .string()
+                .optional()
+                .describe("A clip id or name to filter by. Omit for every track.")
+        }), async ({ target }) => {
+            const clipId = typeof target === "string" && target.trim() !== ""
+                ? resolveClip(target).id
+                : undefined;
+            const listed = mediaTracks.filter((t) => clipId === undefined || t.clipId === clipId);
+            return {
+                ok: true,
+                tracks: listed.map((t) => ({
+                    id: t.id,
+                    clipId: t.clipId,
+                    name: t.name,
+                    kind: t.kind,
+                    status: t.status,
+                    sourceStartMs: t.sourceStartMs,
+                    sourceEndMs: t.sourceEndMs,
+                    sampleCount: t.samples.length,
+                    confidence: t.confidence
+                }))
+            };
+        }),
+        tool("ui_timeline_delete_track_object", "Delete a subject/object track and unbind every clip that was " +
+            "following it — a clip left pointing at a track that is gone reads " +
+            "as bound while following nothing.", z.object({
+            trackId: z.string().describe("A track id, from list_tracks.")
+        }), async ({ trackId }) => {
+            const track = mediaTracks.find((t) => t.id === trackId);
+            if (!track) {
+                throw new Error(`No track "${trackId}". ` + validUnits(mediaTracks, "track"));
+            }
+            mediaTracks = mediaTracks.filter((t) => t.id !== trackId);
+            clips = clips.map((c) => {
+                if (c.trackBinding?.trackId !== trackId)
+                    return c;
+                const { trackBinding: _dropped, ...rest } = c;
+                return rest;
+            });
+            return { ok: true, deleted: { id: track.id, name: track.name } };
+        }),
+        tool("ui_timeline_bind_to_track", "Make a clip follow a subject/object track, so its position moves " +
+            'with the tracked subject. Only "position" and "position_scale" are ' +
+            "implemented; the other modes are named by the document format for a " +
+            "later phase and are refused here rather than silently doing nothing.", z.object({
+            target: z.string().describe("Clip id or name."),
+            trackId: z.string().describe("A track id, from list_tracks."),
+            mode: z
+                .string()
+                .describe('"position" or "position_scale".'),
+            offset: z
+                .object({ x: z.number(), y: z.number() })
+                .optional()
+                .describe("Canvas-pixel offset added on top of the tracked point."),
+            scale: z
+                .number()
+                .optional()
+                .describe('Scale multiplier, "position_scale" only.'),
+            rotationOffset: z
+                .number()
+                .optional()
+                .describe("Radians added to the clip's rotation."),
+            smoothing: z
+                .number()
+                .optional()
+                .describe("0..1; higher follows the track more loosely.")
+        }), async ({ target, trackId, mode, offset, scale, rotationOffset, smoothing }) => {
+            const clip = resolveClip(target);
+            if (!mediaTracks.some((t) => t.id === trackId)) {
+                throw new Error(`No track "${trackId}". ` + validUnits(mediaTracks, "track"));
+            }
+            if (mode !== "position" && mode !== "position_scale") {
+                throw new Error(`bind_to_track mode "${String(mode)}" is not implemented yet — ` +
+                    `only "position" and "position_scale" affect rendering in this ` +
+                    "build. The field accepts the other modes so a document can " +
+                    "name the intent without a schema migration later, but binding " +
+                    "to one today would be a no-op, so the call is refused instead.");
+            }
+            const binding = {
+                trackId: trackId,
+                mode: mode
+            };
+            if (offset !== undefined) {
+                binding.offset = offset;
+            }
+            if (scale !== undefined)
+                binding.scale = scale;
+            if (rotationOffset !== undefined) {
+                binding.rotationOffset = rotationOffset;
+            }
+            if (smoothing !== undefined)
+                binding.smoothing = smoothing;
+            const next = { ...clip, trackBinding: binding };
+            clips = clips.map((c) => (c.id === clip.id ? next : c));
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        tool("ui_timeline_unbind_track", "Stop a clip following a track. A clip that follows none is a no-op.", z.object({ target: z.string().describe("Clip id or name.") }), async ({ target }) => {
+            const clip = resolveClip(target);
+            if (!clip.trackBinding)
+                return { ok: true, clip: serializeClip(clip) };
+            const { trackBinding: _dropped, ...next } = clip;
+            clips = clips.map((c) => (c.id === clip.id ? next : c));
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        sharedTool("ui_timeline_retarget_format", async ({ aspect_ratio, strategy, safe_margin, track_ids }) => {
+            if (track_ids) {
+                for (const [clipId, trackId] of Object.entries(track_ids)) {
+                    const clip = clips.find((candidate) => candidate.id === clipId);
+                    if (!clip) {
+                        throw new Error(`track_ids names unknown clip "${clipId}". ` +
+                            validUnits(clips, "clip"));
+                    }
+                    const track = mediaTracks.find((candidate) => candidate.id === trackId);
+                    if (!track || track.clipId !== clip.id) {
+                        throw new Error(`Track "${trackId}" does not belong to clip "${clip.name}". ` +
+                            validUnits(mediaTracks.filter((candidate) => candidate.clipId === clip.id), "track"));
+                    }
+                    if (track.status !== "ready") {
+                        throw new Error(`Track "${track.name}" is ${track.status}; a format adaptation can only follow a ready track.`);
+                    }
+                }
+            }
+            const now = new Date().toISOString();
+            const source = {
+                id: sequenceId,
+                projectId,
+                name: sequenceName,
+                fps,
+                width,
+                height,
+                durationMs: clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0),
+                tracks: tracks.map((track) => structuredClone(track)),
+                clips: clips.map((clip) => structuredClone(clip)),
+                markers: markers.map((marker) => structuredClone(marker)),
+                mediaTracks: mediaTracks.map((track) => structuredClone(track)),
+                createdAt: now,
+                updatedAt: now
+            };
+            if (seed?.transcript !== undefined) {
+                source.transcript = structuredClone(seed.transcript);
+            }
+            if (seed?.scriptEnabled !== undefined) {
+                source.scriptEnabled = seed.scriptEnabled;
+            }
+            if (seed?.templateId !== undefined)
+                source.templateId = seed.templateId;
+            if (tempo)
+                source.tempo = structuredClone(tempo);
+            source.camera2d = structuredClone(seed?.camera2d ?? null);
+            if (setup)
+                source.setup = structuredClone(setup);
+            const adapted = adaptSequenceFormat(source, aspect_ratio, {
+                strategy: strategy,
+                safeMargin: safe_margin,
+                trackIdByClipId: track_ids
+            });
+            const stored = retargetFormat
+                ? await retargetFormat(structuredClone(adapted.sequence))
+                : { sequenceId: adapted.sequence.id, name: adapted.sequence.name };
+            derivedSequences.push(structuredClone(adapted.sequence));
+            return {
+                ok: true,
+                sourceSequenceId: sequenceId,
+                sequenceId: stored.sequenceId,
+                name: stored.name ?? adapted.sequence.name,
+                width: adapted.sequence.width,
+                height: adapted.sequence.height,
+                strategy,
+                croppedClipIds: adapted.croppedClipIds
+            };
+        }),
+        sharedTool("ui_timeline_set_reframe_subject", async ({ clip_id, track_id, safe_margin, smoothing }) => {
+            const clip = resolveClip(clip_id);
+            const track = mediaTracks.find((candidate) => candidate.id === track_id);
+            if (!track || track.clipId !== clip.id) {
+                throw new Error(`No track "${String(track_id)}" belongs to clip "${clip.name}". ` +
+                    validUnits(mediaTracks.filter((candidate) => candidate.clipId === clip.id), "track"));
+            }
+            if (track.status !== "ready") {
+                throw new Error(`Track "${track.name}" is ${track.status}; Smart Reframe can only follow a ready track.`);
+            }
+            if (!mediaTrackCanDriveReframe(track) ||
+                isMediaTrackStale(track, clip)) {
+                throw new Error(`Track "${track.name}" has no current analysis for clip "${clip.name}".`);
+            }
+            const previous = clip.reframe;
+            const reframe = {
+                mode: "track",
+                trackId: track.id,
+                sourceAssetId: clip.currentAssetId
+            };
+            if (safe_margin !== undefined)
+                reframe.safeMargin = safe_margin;
+            else if (previous?.safeMargin !== undefined) {
+                reframe.safeMargin = previous.safeMargin;
+            }
+            if (smoothing !== undefined)
+                reframe.smoothing = smoothing;
+            else if (previous?.smoothing !== undefined) {
+                reframe.smoothing = previous.smoothing;
+            }
+            if (previous?.keyframes) {
+                reframe.keyframes = structuredClone(previous.keyframes);
+            }
+            if (previous?.sourceWidth !== undefined) {
+                reframe.sourceWidth = previous.sourceWidth;
+            }
+            if (previous?.sourceHeight !== undefined) {
+                reframe.sourceHeight = previous.sourceHeight;
+            }
+            const next = { ...clip, reframe };
+            clips = clips.map((candidate) => candidate.id === clip.id ? next : candidate);
+            return { ok: true, clip: serializeClip(next) };
+        }),
+        sharedTool("ui_timeline_add_reframe_keyframe", async ({ clip_id, source_ms, x, y, zoom }) => {
+            const clip = resolveClip(clip_id);
+            if (!clip.reframe) {
+                throw new Error(`Clip "${clip.name}" has no Smart Reframe path. Retarget the format or set_reframe_subject first.`);
+            }
+            const keyframe = {
+                sourceMs: source_ms,
+                x: x,
+                y: y
+            };
+            if (zoom !== undefined) {
+                keyframe.zoom = zoom;
+            }
+            const next = {
+                ...clip,
+                reframe: addReframeKeyframe(clip.reframe, keyframe)
+            };
+            clips = clips.map((candidate) => candidate.id === clip.id ? next : candidate);
+            return { ok: true, clip: serializeClip(next), keyframe };
+        }),
+        sharedTool("ui_timeline_clear_reframe", async ({ clip_id }) => {
+            const clip = resolveClip(clip_id);
+            const next = clearReframe(clip);
+            clips = clips.map((candidate) => candidate.id === clip.id ? next : candidate);
+            return { ok: true, clip: serializeClip(next) };
+        })
+    ];
+    // Opt-in, and outside the `ui_timeline_` prefix on purpose: `edit_timeline`
+    // builds this same bridge and matches its ops by that prefix, so a preview
+    // tool it can never call has no business in its op catalogue. A case that
+    // grades "did it look at the frame" asks for it.
+    if (initial.preview) {
+        tools.push(tool("preview_timeline_frame", "Look at the sequence at one or more timecodes: what is on screen, layered top of the stack first, with each layer's opacity and track index. This surface has no rasterizer, so it reports the layer stack rather than pixels — enough to see a layer that is covered, missing, or drawing nothing. Call it after an edit, before you say you are done.", z.object({
+            times_ms: z
+                .array(z.number().nonnegative())
+                .min(1)
+                .max(8)
+                .describe("Absolute timeline positions to look at, in ms.")
+        }), async ({ times_ms }) => {
+            const frames = times_ms.map((timeMs) => ({
+                time_ms: timeMs,
+                layers: computeActiveLayers(tracks, clips, timeMs)
+                    .map((layer) => ({
+                    clip_id: layer.clipId,
+                    clip_name: clips.find((c) => c.id === layer.clipId)?.name ?? layer.clipId,
+                    kind: layer.kind,
+                    track_index: layer.trackIndex,
+                    z_index: 1000 - layer.trackIndex,
+                    opacity: layer.opacity,
+                    text: layer.textStyle?.text
+                }))
+                    // Top of the stack first, the order the skill's report describes.
+                    .sort((a, b) => b.z_index - a.z_index)
+            }));
+            previewTimesMs.push(...times_ms);
+            for (const frame of frames) {
+                for (const layer of frame.layers) {
+                    previewedLayerKinds.add(layer.kind);
+                }
+            }
+            return { ok: true, width, height, frames };
+        }));
+    }
+    // Recorded rather than counted: a predicate asks where the last edit sits
+    // relative to a preview, which a tally cannot answer. The push happens
+    // before the call, so a tool that throws is still in the transcript.
+    const recorded = tools.map((entry) => ({
+        ...entry,
+        execute: (args) => {
+            toolLog.push(entry.name);
+            return entry.execute(args);
+        }
+    }));
+    return {
+        tools: recorded,
+        finalState: () => ({
+            fps,
+            width,
+            height,
+            durationMs: clips.reduce((m, c) => Math.max(m, c.startMs + c.durationMs), 0),
+            playheadMs,
+            tracks: tracks.map((t) => ({
+                id: t.id,
+                name: t.name,
+                type: t.type,
+                index: t.index
+            })),
+            clips: clips.map((c) => ({
+                id: c.id,
+                name: c.name,
+                trackId: c.trackId,
+                mediaType: c.mediaType,
+                startMs: c.startMs,
+                durationMs: c.durationMs,
+                prompt: c.prompt,
+                animations: (c.animations ?? []).map((a) => ({
+                    role: a.role,
+                    preset: a.preset
+                }))
+            })),
+            documentTracks: tracks.map((t) => structuredClone(t)),
+            documentClips: clips.map((c) => structuredClone(c)),
+            markers: markers.map((m) => structuredClone(m)),
+            mediaTracks: mediaTracks.map((t) => structuredClone(t)),
+            derivedSequences: derivedSequences.map((sequence) => structuredClone(sequence)),
+            tempo: tempo ? structuredClone(tempo) : undefined,
+            camera2d: structuredClone(seed?.camera2d ?? null),
+            setup: setup ? structuredClone(setup) : null,
+            transitionCandidates: structuredClone(transitionCandidates),
+            auditionedTransitionCandidateId,
+            appliedTransitionCandidates: structuredClone(appliedTransitionCandidates),
+            toolLog: [...toolLog],
+            previewTimesMs: [...previewTimesMs],
+            previewedLayerKinds: [...previewedLayerKinds]
+        })
+    };
+}
+const TIMELINE_SYSTEM_PROMPT = `You are an assistant driving a timeline / video editor through UI tools.
+
+Use the ui_timeline_* tools to inspect and modify the sequence:
+- Call ui_timeline_get_state first to see what's already there and get track/clip ids and names.
+- Add content with ui_timeline_add_text_clip, ui_timeline_add_shape_clip, or ui_timeline_generate_clip; add tracks with ui_timeline_add_track when needed.
+- Address existing clips by id, name, or "selected" with ui_timeline_split_clip, ui_timeline_trim_clip, ui_timeline_move_clip, ui_timeline_delete_clip, ui_timeline_duplicate_clip, ui_timeline_set_clip_params, ui_timeline_set_clip_binding, ui_timeline_set_transition, ui_timeline_set_time_remap, ui_timeline_animate_clip, ui_timeline_clear_animations, ui_timeline_select_clip.
+- Use ui_timeline_generatively_edit_clip for a nondestructive video edit. Pass the exact clip_id, an instruction, and an optional provider/model. It captures the clip's playable source window, returns an inactive candidate and generationId, and never changes the active take. After that candidate succeeds, call ui_timeline_apply_take with the same clip_id and the returned take_id to promote it in one undoable action. Do not request extend, object, range, or operation fields: the instruction is the edit target.
+- Before animating a clip, call ui_timeline_list_animation_presets to discover the exact preset ids, allowed roles, and params.
+- For motion no preset covers, animate with preset "custom" and pass curves — [{property, keyframes: [{t, value}]}], where t runs 0..1 over the animation window. list_animation_presets reports which properties a curve may drive.
+- ui_timeline_seek moves the playhead (useful before a playhead-relative split).
+- Use ui_timeline_list_tracks to inspect source-time subject tracks. ui_timeline_set_reframe_subject makes one ready track drive a clip's crop; ui_timeline_add_reframe_keyframe adds a manual source-time correction, and ui_timeline_clear_reframe removes only that framing state.
+- Generate a selected-cut transition with ui_timeline_generate_transition_at_cut. It returns an inactive cut-level candidate without changing either source clip. Audition it with ui_timeline_preview_transition_candidate, then explicitly apply it with ui_timeline_apply_transition_at_cut and the returned candidate_id. Never use a normal clip take or ordinary built-in transition as the generated result, and re-read state if the cut may have changed.
+- ui_timeline_retarget_format creates a new sequence for one target aspect ratio and leaves this sequence unchanged. Run it once per portrait, square, or other adaptation, then continue editing the returned sequence id.
+- For a played part: add a midi track, place phrases with ui_timeline_add_midi_clip (notes in ticks from the clip's content start, 960 ticks = a quarter note), rewrite them with ui_timeline_set_notes, pick the synth with ui_timeline_set_track_instrument — either a named voice ({"preset": "bass"}: saw-lead, square-lead, soft-pad, pluck, bass, bell) or every field spelled out — and set the speed once with ui_timeline_set_tempo, which rescales the midi clips and leaves picture and audio where they are.
+- Edit a phrase you already placed without resending it: ui_timeline_transpose_clip moves every note by whole semitones, ui_timeline_quantize_notes snaps onsets to a note grid (1/4, 1/8, 1/16, 1/32, 1/8T, 1/16T; strength below 1 keeps some of the feel) and reports how many notes moved, ui_timeline_scale_velocity multiplies how hard they are struck. get_state reports each midi clip's startBarsBeats, so the next phrase goes on a bar line.
+- Flag moments with ui_timeline_add_marker / ui_timeline_delete_marker. To cut to music, lay the grid down with ui_timeline_set_markers_from_beats and put clip boundaries on it with ui_timeline_snap_to_beats, then read its per-clip report — a clip further than the tolerance from every beat is left alone and says so.
+
+- Look at what you made with preview_timeline_frame before you stop.
+
+Call one tool at a time and use the result before the next call. When the objective is fully satisfied, STOP calling tools and give a one-line summary.
+${motionGraphicsSection()}`;
+/**
+ * The shipped `motion-graphics` skill, verbatim, plus the two lines that
+ * reconcile it with this surface. The eval measures motion the skill teaches,
+ * so the model gets the same document a product agent gets rather than a
+ * paraphrase that drifts from it. Empty when the build ships no skills —
+ * a skill file missing is not a reason to fail every timeline case.
+ */
+function motionGraphicsSection() {
+    const skill = findSystemSkill("motion-graphics")?.content;
+    if (!skill)
+        return "";
+    return `
+---
+
+The motion-graphics craft, as shipped. It names the capability tools: read \`get_timeline\` as ui_timeline_get_state and every \`edit_timeline\` op as the matching ui_timeline_* tool. \`preview_timeline_frame\` is here and reports the layer stack rather than pixels.
+
+${skill}`;
+}
+export const TIMELINE_TOOL_LOOP_CASES = [
+    {
+        id: "titles-with-motion",
+        description: "Add a text clip and give it a fade-in entrance animation",
+        objective: "Add a text clip that says 'Hello' and give it a fade-in entrance animation.",
+        createBridge: () => createTimelineToolBridge(),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: ["ui_timeline_add_text_clip", "ui_timeline_animate_clip"],
+            ordering: [["ui_timeline_add_text_clip", "ui_timeline_animate_clip"]],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "hasAnimatedTextClip",
+                    detail: "no text clip with an 'in' animation",
+                    test: (s) => s.clips.some((c) => c.mediaType === "text" &&
+                        c.animations.some((a) => a.role === "in"))
+                }
+            ]
+        }
+    },
+    {
+        id: "generate-and-arrange",
+        description: "Generate a video clip and move it to a specific start time",
+        objective: "Add a video track, generate a text-to-video clip on it, then move the clip to start at 2000ms on the timeline.",
+        createBridge: () => createTimelineToolBridge(),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: ["ui_timeline_generate_clip", "ui_timeline_move_clip"],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "hasGeneratedVideoClipAt2000",
+                    detail: "no generated video clip at startMs=2000 with a prompt",
+                    test: (s) => s.clips.some((c) => c.mediaType === "video" && c.startMs === 2000 && !!c.prompt)
+                }
+            ]
+        }
+    },
+    {
+        id: "cut-and-trim",
+        description: "Split a clip and delete the second half",
+        objective: "The timeline has one video clip named 'shot' running from 0ms to 6000ms. Split it at 3000ms and delete the second half.",
+        createBridge: () => createTimelineToolBridge({
+            tracks: [{ type: "video" }],
+            clips: [
+                {
+                    name: "shot",
+                    trackIndex: 0,
+                    mediaType: "video",
+                    startMs: 0,
+                    durationMs: 6000
+                }
+            ]
+        }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        userPrompt: "Objective: The timeline has one video clip named 'shot' running from 0ms to 6000ms. Split it at 3000ms and delete the second half.",
+        expect: {
+            requiredTools: ["ui_timeline_split_clip", "ui_timeline_delete_clip"],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "oneClipLeftAt3000ms",
+                    detail: "expected exactly 1 clip with durationMs 3000",
+                    test: (s) => s.clips.length === 1 && s.clips[0].durationMs === 3000
+                }
+            ]
+        }
+    },
+    {
+        id: "keyframed-slide",
+        description: "Keyframe an entrance with a custom animation instead of a preset",
+        objective: "Add a text clip that says 'Launch' and give it a keyframed entrance: over the first 800ms it rises 120 pixels into place, from offsetY 120 down to 0. Use a custom animation with explicit keyframes, not a preset.",
+        createBridge: () => createTimelineToolBridge(),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_add_text_clip",
+                "ui_timeline_animate_clip"
+            ],
+            ordering: [["ui_timeline_add_text_clip", "ui_timeline_animate_clip"]],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "hasCustomOffsetYCurve",
+                    detail: "no text clip carrying a custom 'in' animation whose offsetY curve ends at 0",
+                    test: (s) => s.documentClips.some((clip) => {
+                        if (clip.mediaType !== "text")
+                            return false;
+                        const animation = (clip.animations ?? []).find((a) => a.role === "in" && a.preset === "custom");
+                        const curve = animation?.custom?.curves.find((c) => c.property === "offsetY");
+                        if (!curve)
+                            return false;
+                        const keyframes = curve.keyframes;
+                        const first = keyframes[0];
+                        const last = keyframes[keyframes.length - 1];
+                        // A rise into place: starts below, lands on the layout
+                        // position, and the window is the 800ms that was asked for.
+                        return (first.t === 0 &&
+                            last.t === 1 &&
+                            first.value >= 100 &&
+                            last.value === 0 &&
+                            animation?.durationMs === 800);
+                    })
+                }
+            ]
+        }
+    },
+    {
+        id: "kinetic-title-staggered",
+        description: "Stagger a title's words so the entrance still finishes inside the clip",
+        objective: "Put the title 'MAKE IT MOVE' on screen for 2500ms and have the words arrive one after another instead of all at once. The whole entrance has to be over while the card is still up.",
+        createBridge: () => createTimelineToolBridge({ preview: true }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_add_text_clip",
+                "ui_timeline_animate_clip"
+            ],
+            ordering: [["ui_timeline_add_text_clip", "ui_timeline_animate_clip"]],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 14,
+            finalState: [
+                {
+                    name: "staggerSpanFitsTheCard",
+                    detail: "no text clip whose entrance staggers over at least two units and finishes inside the clip",
+                    test: (s) => s.documentClips.some((clip) => {
+                        if (clip.mediaType !== "text")
+                            return false;
+                        const entrance = (clip.animations ?? []).find((a) => a.role === "in" && a.stagger);
+                        const stagger = entrance?.stagger;
+                        if (!entrance || !stagger)
+                            return false;
+                        return (staggerUnitsOf(clip, stagger.unit, s) >= 2 &&
+                            staggerSpanFitsClip(clip, entrance, s));
+                    })
+                }
+            ]
+        }
+    },
+    {
+        id: "lower-third-layered",
+        description: "Put a scrim behind a name plate and keep both inside the shot",
+        objective: "The shot named 'Host' runs from 0ms to 6000ms. While it is on screen, put the name 'Maya Chen' on the picture with a dark bar behind the words so they stay readable against the shot. Both have to sit inside that shot's window.",
+        createBridge: () => createTimelineToolBridge({
+            preview: true,
+            tracks: [{ type: "video", name: "Picture" }],
+            clips: [
+                {
+                    name: "Host",
+                    trackIndex: 0,
+                    mediaType: "video",
+                    startMs: 0,
+                    durationMs: 6000
+                }
+            ]
+        }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_add_text_clip",
+                "ui_timeline_add_shape_clip"
+            ],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 14,
+            finalState: [
+                {
+                    name: "scrimBehindTextInsideTheShot",
+                    detail: "no shape clip drawn over the picture and under the text, sharing frames with it inside 0-6000ms",
+                    test: (s) => {
+                        const indexOf = (trackId) => s.tracks.find((t) => t.id === trackId)?.index ?? -1;
+                        const inShot = (c) => c.startMs >= 0 && c.startMs + c.durationMs <= 6000;
+                        const overlaps = (a, b) => a.startMs < b.startMs + b.durationMs &&
+                            b.startMs < a.startMs + a.durationMs;
+                        const texts = s.clips.filter((c) => c.mediaType === "text" && inShot(c));
+                        const shapes = s.clips.filter((c) => c.mediaType === "shape" && inShot(c));
+                        const picture = s.clips.filter((c) => c.mediaType === "video");
+                        // Lowest index draws on top, so the scrim sits between the two:
+                        // over the shot it darkens, under the words it backs. A scrim
+                        // that never shares a frame with the text backs nothing.
+                        return texts.some((text) => shapes.some((shape) => indexOf(shape.trackId) > indexOf(text.trackId) &&
+                            overlaps(shape, text) &&
+                            picture.some((shot) => indexOf(shot.trackId) > indexOf(shape.trackId))));
+                    }
+                }
+            ]
+        }
+    },
+    {
+        id: "entrance-decelerates",
+        description: "Every entrance eases out or springs, never accelerates in",
+        objective: "Add two title cards, 'Chapter One' and 'Chapter Two', and bring each one on so it arrives and settles rather than speeding up as it lands.",
+        createBridge: () => createTimelineToolBridge({ preview: true }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: ["ui_timeline_animate_clip"],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 16,
+            finalState: [
+                {
+                    name: "everyEntranceDecelerates",
+                    detail: "an 'in' animation runs on an easing that is neither an ease-out family nor a spring",
+                    test: (s) => {
+                        const entrances = s.documentClips.flatMap((clip) => (clip.animations ?? []).filter((a) => a.role === "in"));
+                        return (entrances.length >= 2 &&
+                            entrances.every((a) => easingDecelerates(effectiveEasing(a))));
+                    }
+                }
+            ]
+        }
+    },
+    {
+        id: "beat-cut",
+        description: "Move every picture boundary onto a named musical onset",
+        objective: "The music hits at 0ms, 2000ms, 4000ms and 6000ms. My three shots — A, B and C — are roughly laid out and none of the cuts land on those hits. Put every cut on a hit, keeping the shots back to back with no gap.",
+        createBridge: () => createTimelineToolBridge({
+            preview: true,
+            tracks: [{ type: "video", name: "Picture" }],
+            clips: [
+                {
+                    name: "A",
+                    trackIndex: 0,
+                    mediaType: "video",
+                    startMs: 0,
+                    durationMs: 2180
+                },
+                {
+                    name: "B",
+                    trackIndex: 0,
+                    mediaType: "video",
+                    startMs: 2180,
+                    durationMs: 2080
+                },
+                {
+                    name: "C",
+                    trackIndex: 0,
+                    mediaType: "video",
+                    startMs: 4260,
+                    durationMs: 1740
+                }
+            ]
+        }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            noErrorResults: true,
+            minToolCalls: 1,
+            maxToolCalls: 16,
+            finalState: [
+                {
+                    name: "everyBoundaryOnAnOnset",
+                    detail: "a picture clip's start or end is further than 60ms from 0/2000/4000/6000ms",
+                    test: (s) => {
+                        const onsets = [0, 2000, 4000, 6000];
+                        const onBeat = (ms) => onsets.some((onset) => Math.abs(ms - onset) <= 60);
+                        const picture = s.clips.filter((c) => c.mediaType === "video");
+                        return (picture.length === 3 &&
+                            picture.every((c) => onBeat(c.startMs) && onBeat(c.startMs + c.durationMs)));
+                    }
+                }
+            ]
+        }
+    },
+    {
+        id: "looked-before-done",
+        description: "Check the frame after the last edit, before reporting done",
+        objective: "Add an end card that says 'END' starting at 4000ms, then look at what is actually on screen there before you tell me it is finished.",
+        createBridge: () => createTimelineToolBridge({ preview: true }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: ["ui_timeline_add_text_clip", "preview_timeline_frame"],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "previewedAfterTheLastEdit",
+                    detail: "the run's last edit is not followed by a preview_timeline_frame call",
+                    test: (s) => s.clips.some((c) => c.mediaType === "text") &&
+                        previewedAfterLastEdit(s.toolLog) &&
+                        previewedMidMotion(s.previewTimesMs, s.documentClips, s)
+                }
+            ]
+        }
+    },
+    {
+        id: "video-flow-plan-then-generate",
+        description: "Plan a video's beats, then cut it — the guided flow through the tools",
+        objective: "This is a 15-second ad for a paper boat. Write the brief onto the sequence, plan four beats — the second and fourth each carry a voiceover line — then generate the video from that plan with model 'nodetool/kling-turbo' and voice 'alloy'.",
+        createBridge: () => createTimelineToolBridge(),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_plan_beats",
+                "ui_timeline_generate_from_beats"
+            ],
+            noErrorResults: true,
+            minToolCalls: 2,
+            maxToolCalls: 12,
+            finalState: [
+                {
+                    name: "onePictureClipPerBeat",
+                    detail: "the picture track does not hold exactly one clip per planned beat",
+                    test: (s) => (s.setup?.beats?.length ?? 0) > 0 &&
+                        s.clips.filter((c) => c.mediaType === "video").length ===
+                            (s.setup?.beats?.length ?? 0)
+                },
+                {
+                    name: "oneVoiceoverClipPerVoicedBeat",
+                    detail: "the voiceover clips do not match the beats that carry a line",
+                    test: (s) => {
+                        const voiced = (s.setup?.beats ?? []).filter((beat) => (beat.voiceover ?? "").trim().length > 0).length;
+                        const audio = s.documentClips.filter((c) => c.bindingKind === "text-to-audio" && c.beatId).length;
+                        return voiced > 0 && audio === voiced;
+                    }
+                },
+                {
+                    name: "flowFinished",
+                    detail: "the flow's stage is not done after generating",
+                    test: (s) => s.setup?.stage === "done"
+                }
+            ]
+        }
+    },
+    {
+        id: "three-d-turntable",
+        description: "Put a glTF on the timeline, spin its camera, then look",
+        objective: "Put the 3D model asset 'asset_lantern_glb' on an overlay track for 4 seconds, make its camera go all the way round the model over that time, and then look at the frame in the middle to check the model is actually on screen.",
+        createBridge: () => createTimelineToolBridge({ preview: true }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_add_model3d_clip",
+                "ui_timeline_animate_clip",
+                "preview_timeline_frame"
+            ],
+            noErrorResults: true,
+            minToolCalls: 3,
+            maxToolCalls: 14,
+            finalState: [
+                {
+                    name: "modelClipCarriesAnOrbit",
+                    detail: "no model3d clip holding the asset with a loop animation driving its camera",
+                    test: (s) => s.documentClips.some((clip) => clip.mediaType === "model3d" &&
+                        clip.currentAssetId === "asset_lantern_glb" &&
+                        clip.model3dStyle !== undefined &&
+                        (clip.animations ?? []).some((a) => a.role === "loop"))
+                },
+                {
+                    // The document can say a 3D clip exists; only the report says one
+                    // was drawn — which is the whole point of looking before stopping.
+                    name: "previewReportedTheModel",
+                    detail: "no preview reported a model3d layer",
+                    test: (s) => s.previewedLayerKinds.includes("model3d")
+                }
+            ]
+        }
+    },
+    {
+        id: "trimmed-video-edit-candidate-apply",
+        description: "Edit a trimmed source into an inactive candidate, inspect it, then apply it",
+        objective: "The timeline contains a trimmed imported video clip. Edit that exact clip to make the station deserted at night, inspect the inactive candidate, then explicitly apply the returned take while keeping the current cut.",
+        createBridge: () => createTimelineToolBridge({
+            sequenceId: "sequence-trimmed-edit",
+            sequence: {
+                tracks: [
+                    {
+                        id: "track-video",
+                        name: "Video",
+                        type: "video",
+                        index: 0,
+                        visible: true,
+                        locked: false
+                    }
+                ],
+                clips: [
+                    {
+                        id: "clip-trimmed",
+                        trackId: "track-video",
+                        name: "Station",
+                        startMs: 1200,
+                        durationMs: 4000,
+                        inPointMs: 40000,
+                        outPointMs: 44000,
+                        mediaType: "video",
+                        sourceType: "imported",
+                        status: "generated",
+                        locked: false,
+                        currentAssetId: "asset-original",
+                        activeTakeId: "take-original",
+                        versions: [
+                            {
+                                id: "take-original",
+                                createdAt: "2026-01-01T00:00:00.000Z",
+                                workflowUpdatedAt: "2026-01-01T00:00:00.000Z",
+                                jobId: "original-job",
+                                assetId: "asset-original",
+                                dependencyHash: "",
+                                paramOverridesSnapshot: {},
+                                durationMs: 4000,
+                                status: "success",
+                                source: "imported",
+                                sourceMapping: {
+                                    inPointMs: 40000,
+                                    outPointMs: 44000,
+                                    speedMultiplier: 1,
+                                    speedBaked: false
+                                }
+                            }
+                        ]
+                    }
+                ]
+            }
+        }),
+        systemPrompt: TIMELINE_SYSTEM_PROMPT,
+        expect: {
+            requiredTools: [
+                "ui_timeline_generatively_edit_clip",
+                "ui_timeline_list_takes",
+                "ui_timeline_apply_take"
+            ],
+            ordering: [
+                ["ui_timeline_generatively_edit_clip", "ui_timeline_list_takes"],
+                ["ui_timeline_list_takes", "ui_timeline_apply_take"]
+            ],
+            noErrorResults: true,
+            minToolCalls: 3,
+            maxToolCalls: 8,
+            finalState: [
+                {
+                    name: "appliedEditPreservesTheTimelineCut",
+                    detail: "the edit candidate was not applied to the trimmed clip with its timeline placement intact",
+                    test: (s) => {
+                        const clip = s.documentClips.find((candidate) => candidate.id === "clip-trimmed");
+                        const active = clip?.versions?.find((take) => take.id === clip.activeTakeId);
+                        return (clip?.startMs === 1200 &&
+                            clip.durationMs === 4000 &&
+                            clip.currentAssetId?.startsWith("generative://clip-trimmed/") ===
+                                true &&
+                            clip.inPointMs === 0 &&
+                            clip.outPointMs === 4000 &&
+                            active?.mediaEdit?.sourceContext.sourceStartMs === 40000 &&
+                            active.mediaEdit.sourceContext.sourceEndMs === 44000);
+                    }
+                }
+            ]
+        }
+    }
+];
+//# sourceMappingURL=timeline.js.map