@nodetool-ai/agents 0.8.1 → 0.8.2

package/dist/evals/surfaces/timeline.js

@@ -1,68 +1,8 @@
-/**
- * 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.
- */
+import { ANIMATION_PRESETS, parseEasing, parseStaggerUnit } from "@nodetool-ai/timeline";
+import { countTextStaggerUnits } from "@nodetool-ai/timeline/scene";
+import { createTimelineToolBridge } from "../../capabilities/timeline-bridge.js";
+export * from "../../capabilities/timeline-bridge.js";
 export const TIMELINE_READ_ONLY_TOOLS = [
     "ui_timeline_get_state",
     "ui_timeline_list_animation_presets",
@@ -212,2560 +152,6 @@ export function easingDecelerates(easing) {
     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:
@@ -2813,7 +199,10 @@ export const TIMELINE_TOOL_LOOP_CASES = [
         createBridge: () => createTimelineToolBridge(),
         systemPrompt: TIMELINE_SYSTEM_PROMPT,
         expect: {
-            requiredTools: ["ui_timeline_add_text_clip", "ui_timeline_animate_clip"],
+            requiredTools: [
+                "ui_timeline_add_text_clip",
+                "ui_timeline_animate_clip"
+            ],
             ordering: [["ui_timeline_add_text_clip", "ui_timeline_animate_clip"]],
             noErrorResults: true,
             minToolCalls: 2,
@@ -3252,8 +641,7 @@ export const TIMELINE_TOOL_LOOP_CASES = [
                         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.currentAssetId?.startsWith("generative://clip-trimmed/") === true &&
                             clip.inPointMs === 0 &&
                             clip.outPointMs === 4000 &&
                             active?.mediaEdit?.sourceContext.sourceStartMs === 40000 &&