@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/timelines.js

@@ -0,0 +1,2825 @@
+/**
+ * The `timelines` capability module.
+ *
+ * Timeline CRUD, versioning, editing, rendering, tracking, and native media
+ * candidate capabilities that used to live across several `Tool` subclasses.
+ * The native media actions are kept in `timeline-native-media.ts` and attached
+ * here so they share the timelines namespace and registry entry.
+ *
+ * Wire names, descriptions and schemas come from `timelines.specs.ts`; the
+ * native media entries are attached here by name so the belt stays lazy.
+ *
+ * What was a constructor argument is now a field on the run: the tRPC-only
+ * timeline loader `validate_timeline` takes is `run.loaders?.timeline`. Every
+ * heavy dependency (`@nodetool-ai/models`, the timeline validator, the eval
+ * surface's bridge) is imported inside the implementation that needs it, so
+ * loading this module costs nothing.
+ *
+ * Design: docs/tool-class-retirement-design.md § "Migration".
+ */
+import { z } from "zod";
+import { applyTimelineTrackOp } from "@nodetool-ai/timeline/ops";
+import { STAGGER_UNITS, ANIMATED_PROPERTIES, DEFAULT_BEAT_TOLERANCE_MS } from "@nodetool-ai/timeline";
+import { buildTimelineToolContracts } from "@nodetool-ai/protocol/api-schemas/timeline-tool-contracts.js";
+import { resolveMoveTrackArgs, resolveDeleteTrackArgs } from "@nodetool-ai/protocol/api-schemas/timeline-tool-params.js";
+import { parseWithTypeCoercion } from "@nodetool-ai/runtime";
+import { listTimelinesSpec, createTimelineSpec, getTimelineSpec, listTimelineVersionsSpec, getTimelineVersionSpec, createTimelineVersionSpec, restoreTimelineVersionSpec, deleteTimelineVersionSpec, editTimelineSpec, validateTimelineSpec, setTimelineDocumentSpec, previewTimelineFrameSpec, compareTimelineFramesSpec, renderTimelineSpec, bakeAudioAnimationSpec, isolateSubjectSpec, ISOLATE_SUBJECT_MODELS, ISOLATE_SUBJECT_RESOLUTIONS, DEFAULT_ISOLATE_SUBJECT_MODEL, DEFAULT_ISOLATE_SUBJECT_RESOLUTION, DEFAULT_BAKE_ATTACK_MS, DEFAULT_BAKE_RELEASE_MS, DEFAULT_BAKE_TOLERANCE, DEFAULT_BAKE_MAX_POINTS, DEFAULT_BAKE_MAX_SECONDS, MAX_BAKE_POINTS, DEFAULT_RENDER_TIMEOUT_MS, MAX_RENDER_TIMEOUT_MS, DEFAULT_PREVIEW_COUNT, DEFAULT_COMPARE_WIDTH, MAX_PREVIEW_TIMES, MAX_PREVIEW_RANGE_COUNT, DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT, trackObjectSpec, TRACK_OBJECT_DIRECTIONS, getTimelineCodeSpec, setTimelineCodeSpec, editTimelineCodeSpec, rebakeTimelineCodeSpec, detachTimelineCodeSpec, deleteTimelineSpec } from "./timelines.specs.js";
+import { AUDIO_BAKED_ANIMATION_KIND, normalizeAuthoredDocument, hashSceneSubtree, mergeTimelineSource } from "@nodetool-ai/timeline";
+import { bakeTimelineCode, bakedDocumentMatchesSaved } from "../timeline-code-bake.js";
+import { applyJsScriptEditOps, parseJsScriptEditOps } from "./js-scripts.js";
+import { clipSourceWindowMs } from "./timeline-audio-bake.js";
+import { TIMELINE_NATIVE_MEDIA_CAPABILITIES } from "./timeline-native-media.js";
+import { isFiniteNumber, isRecord, isString } from "../utils/type-guards.js";
+import { resolveProjectId } from "./project-scope.js";
+const isError = (value) => !!value &&
+    typeof value === "object" &&
+    typeof value.error === "string";
+async function loadTimeline(run, timelineId) {
+    if (!isString(timelineId) || !timelineId) {
+        return {
+            error: "timeline_id is required (use list_timelines to find one)."
+        };
+    }
+    const { TimelineSequence } = await import("@nodetool-ai/models");
+    const seq = await TimelineSequence.findById(timelineId);
+    // A sequence owned by someone else reads as missing — the same rule the tRPC
+    // router's ownership check applies.
+    if (!seq || seq.user_id !== run.context.userId) {
+        return { error: `Timeline ${timelineId} was not found.` };
+    }
+    return seq;
+}
+/** The list-item shape the tRPC router returns for a snapshot. */
+function toVersionListItem(version) {
+    return {
+        id: version.id,
+        version: version.version,
+        name: version.name,
+        saveType: version.save_type,
+        fps: version.fps,
+        width: version.width,
+        height: version.height,
+        durationMs: version.duration_ms,
+        createdAt: version.created_at
+    };
+}
+/**
+ * A snapshot's document is JSON text on SQLite and an object on Postgres, so
+ * parse only when it is a string. A row that is neither is corrupt, and saying
+ * so beats handing back a string the caller will treat as a document.
+ */
+function parseVersionDocument(raw) {
+    if (!isString(raw))
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return { error: "The stored version document is not valid JSON." };
+    }
+}
+/** One-line count of what a validation found. */
+function validationSummary(validation) {
+    const errors = validation.errors.length;
+    const warnings = validation.warnings.length;
+    if (errors === 0 && warnings === 0)
+        return "No issues found.";
+    const parts = [];
+    if (errors > 0)
+        parts.push(`${errors} error${errors === 1 ? "" : "s"}`);
+    if (warnings > 0)
+        parts.push(`${warnings} warning${warnings === 1 ? "" : "s"}`);
+    return parts.join(", ");
+}
+function versionNumber(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        return {
+            error: "version must be a positive integer (use list_timeline_versions to see the available ones)."
+        };
+    }
+    return n;
+}
+const listTimelines = {
+    spec: listTimelinesSpec,
+    impl: async (run, params) => {
+        const userId = run.context.userId;
+        if (!userId)
+            return { error: "No user is bound to this session." };
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const limit = Math.max(1, Math.min(Number(params["limit"]) || 20, 100));
+        const query = isString(params["query"])
+            ? params["query"].trim().toLowerCase()
+            : "";
+        // Filter after the read: the name filter is not indexed, and the per-user
+        // limit is what bounds the scan.
+        const rows = await TimelineSequence.listByUser(userId, 100);
+        const matching = query
+            ? rows.filter((row) => row.name.toLowerCase().includes(query))
+            : rows;
+        return {
+            timelines: matching.slice(0, limit).map((row) => ({
+                id: row.id,
+                name: row.name,
+                project_id: row.project_id,
+                fps: row.fps,
+                width: row.width,
+                height: row.height,
+                duration_ms: row.duration_ms,
+                updated_at: row.updated_at
+            }))
+        };
+    }
+};
+/** A positive integer setting, or the default when the caller gave none. */
+function sequenceSetting(value, fallback, field) {
+    if (value === undefined || value === null)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        return { error: `${field} must be a positive number.` };
+    }
+    return Math.round(n);
+}
+/**
+ * A new, empty sequence.
+ *
+ * Every other document surface could make one — sketches, scripts,
+ * storyboards — and timelines could not, which left "cut these clips
+ * together" with two ways in, both wrong: edit the sequence the user happens
+ * to have open, or assemble from a storyboard, which builds a timeline only
+ * out of media the board itself rendered. A live session did the first, wiped
+ * six clips of somebody's work, and had to restore from a snapshot.
+ */
+const createTimeline = {
+    spec: createTimelineSpec,
+    impl: async (run, params) => {
+        const userId = run.context.userId;
+        if (!userId)
+            return { error: "No user is bound to this session." };
+        const name = params["name"];
+        if (!isString(name) || name.trim() === "") {
+            return { error: "name is required and must be a non-empty string." };
+        }
+        const fps = sequenceSetting(params["fps"], 30, "fps");
+        if (isError(fps))
+            return fps;
+        const width = sequenceSetting(params["width"], 1920, "width");
+        if (isError(width))
+            return width;
+        const height = sequenceSetting(params["height"], 1080, "height");
+        if (isError(height))
+            return height;
+        const projectId = resolveProjectId(run, params);
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const sequence = new TimelineSequence({
+            user_id: userId,
+            project_id: projectId,
+            name: name.trim(),
+            fps,
+            width,
+            height,
+            duration_ms: 0,
+            document: JSON.stringify({ tracks: [], clips: [], markers: [] })
+        });
+        await sequence.save();
+        return {
+            ok: true,
+            timeline_id: sequence.id,
+            name: sequence.name,
+            fps: sequence.fps,
+            width: sequence.width,
+            height: sequence.height,
+            project_id: sequence.project_id,
+            updated_at: sequence.updated_at
+        };
+    }
+};
+const getTimeline = {
+    spec: getTimelineSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        return { timeline: seq.toTimelineSequence(), revision: seq.revision };
+    }
+};
+const listTimelineVersions = {
+    spec: listTimelineVersionsSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const { TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const limit = Math.max(1, Math.min(Number(params["limit"]) || DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT));
+        const saveType = isString(params["save_type"])
+            ? params["save_type"]
+            : undefined;
+        const versions = await TimelineSequenceVersion.listForTimeline(seq.id, {
+            limit,
+            saveType
+        });
+        return {
+            timeline_id: seq.id,
+            name: seq.name,
+            versions: versions.map(toVersionListItem)
+        };
+    }
+};
+const getTimelineVersion = {
+    spec: getTimelineVersionSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const number = versionNumber(params["version"]);
+        if (isError(number))
+            return number;
+        const { TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const version = await TimelineSequenceVersion.findByVersion(seq.id, number);
+        if (!version) {
+            return {
+                error: `Timeline ${seq.id} has no version ${number}. Call list_timeline_versions to see the available ones.`
+            };
+        }
+        const document = parseVersionDocument(version.document);
+        if (isError(document))
+            return document;
+        return {
+            timeline_id: seq.id,
+            ...toVersionListItem(version),
+            document
+        };
+    }
+};
+const createTimelineVersion = {
+    spec: createTimelineVersionSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const { TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const name = isString(params["name"]) && params["name"]
+            ? params["name"]
+            : null;
+        const version = await TimelineSequenceVersion.snapshot(seq, {
+            saveType: "manual",
+            name
+        });
+        return {
+            ok: true,
+            timeline_id: seq.id,
+            ...toVersionListItem(version)
+        };
+    }
+};
+const restoreTimelineVersion = {
+    spec: restoreTimelineVersionSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const number = versionNumber(params["version"]);
+        if (isError(number))
+            return number;
+        const { TimelineSequence, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const version = await TimelineSequenceVersion.findByVersion(seq.id, number);
+        if (!version) {
+            return {
+                error: `Timeline ${seq.id} has no version ${number}. Call list_timeline_versions to see the available ones.`
+            };
+        }
+        const document = parseVersionDocument(version.document);
+        if (isError(document))
+            return document;
+        // Snapshot what is about to be overwritten first, so a restore is itself
+        // undoable.
+        const undo = await TimelineSequenceVersion.snapshot(seq, {
+            saveType: "restore",
+            name: `Before restore to v${number}`
+        });
+        let updated;
+        try {
+            updated = await TimelineSequence.updateFieldsIfUnchanged(seq.id, seq.updated_at, {
+                document: JSON.stringify(document),
+                fps: version.fps,
+                width: version.width,
+                height: version.height,
+                duration_ms: version.duration_ms
+            });
+        }
+        catch (error) {
+            // The write rejects a document without tracks/clips/markers arrays. That
+            // is a snapshot too old or too broken to restore, not a failed call.
+            return {
+                error: `Version ${number} of timeline ${seq.id} cannot be restored: ${error instanceof Error ? error.message : String(error)}`,
+                undo_version: undo.version
+            };
+        }
+        if (!updated) {
+            return {
+                error: `Timeline ${seq.id} was modified since it was read (optimistic concurrency conflict); nothing was restored. Retry the call.`,
+                undo_version: undo.version
+            };
+        }
+        const { validateTimelineSequence } = await import("@nodetool-ai/execution/timeline-debug");
+        const validation = validateTimelineSequence(document, {
+            fps: version.fps,
+            width: version.width,
+            height: version.height
+        });
+        return {
+            ok: true,
+            timeline_id: seq.id,
+            restored_version: number,
+            undo_version: undo.version,
+            fps: updated.fps,
+            width: updated.width,
+            height: updated.height,
+            duration_ms: updated.duration_ms,
+            updated_at: updated.updated_at,
+            validation,
+            summary: validationSummary(validation)
+        };
+    }
+};
+const deleteTimelineVersion = {
+    spec: deleteTimelineVersionSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const number = versionNumber(params["version"]);
+        if (isError(number))
+            return number;
+        const { TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const version = await TimelineSequenceVersion.findByVersion(seq.id, number);
+        if (!version) {
+            return {
+                error: `Timeline ${seq.id} has no version ${number}. Call list_timeline_versions to see the available ones.`
+            };
+        }
+        await version.delete();
+        return {
+            ok: true,
+            timeline_id: seq.id,
+            deleted_version: number
+        };
+    }
+};
+// ---------------------------------------------------------------------------
+// edit_timeline
+// ---------------------------------------------------------------------------
+/** Attempts to land the document write before reporting a conflict. */
+const CAS_ATTEMPTS = 2;
+/** Operations one call may apply, so a runaway script cannot rewrite a cut. */
+const MAX_OPS = 60;
+const TOOL_PREFIX = "ui_timeline_";
+/** Browser generation without a real provider adapter remains excluded. */
+const EXCLUDED_OPS = new Set([`${TOOL_PREFIX}generate_clip`]);
+const READ_ONLY_OPS = new Set([`${TOOL_PREFIX}get_clip_frames`]);
+/** `add_track`, `ui_add_track`, and `ui_timeline_add_track` all name one tool. */
+function normalizeOpName(name) {
+    const trimmed = name.trim();
+    if (trimmed.startsWith(TOOL_PREFIX))
+        return trimmed;
+    const bare = trimmed.startsWith("ui_")
+        ? trimmed.slice("ui_".length)
+        : trimmed;
+    return `${TOOL_PREFIX}${bare}`;
+}
+/** An op is `{op, ...args}` — the arguments sit alongside the verb. */
+export function parseOps(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return {
+            error: 'ops must be a non-empty array, e.g. [{"op": "add_track", "type": "audio"}].'
+        };
+    }
+    if (raw.length > MAX_OPS) {
+        return {
+            error: `ops holds ${raw.length} entries; at most ${MAX_OPS} per call.`
+        };
+    }
+    const parsed = [];
+    for (const [index, entry] of raw.entries()) {
+        if (!isRecord(entry)) {
+            return { error: `ops[${index}] must be an object.` };
+        }
+        const { op, ...input } = entry;
+        if (!isString(op) || op.trim() === "") {
+            return { error: `ops[${index}] has no \`op\` name.` };
+        }
+        parsed.push({ op: normalizeOpName(op), input });
+    }
+    return parsed;
+}
+/**
+ * Read one of the caller's assets for `add_media_clip`.
+ *
+ * The ref a model has in hand is whatever `list_assets` printed — a bare id or
+ * an `asset://<id>.<ext>` URI — so both resolve here.
+ */
+async function resolveTimelineAsset(run, ref) {
+    const id = ref.startsWith("asset://")
+        ? ref.slice("asset://".length).replace(/\.[A-Za-z0-9]{1,8}$/, "")
+        : ref;
+    if (!id)
+        return null;
+    const userId = run.context.userId;
+    if (!userId)
+        return null;
+    const { Asset } = await import("@nodetool-ai/models");
+    // `find` is already user-scoped: someone else's asset reads as missing.
+    const asset = await Asset.find(userId, id);
+    if (!asset)
+        return null;
+    const thumbnails = isRecord(asset.metadata)
+        ? asset.metadata["thumbnails"]
+        : undefined;
+    const thumbnailAssetId = Array.isArray(thumbnails) && isString(thumbnails[0])
+        ? thumbnails[0]
+        : undefined;
+    const resolved = {
+        id: asset.id,
+        name: asset.name,
+        contentType: asset.content_type
+    };
+    let duration = asset.duration;
+    if ((!isFiniteNumber(duration) || duration <= 0) &&
+        (asset.content_type.startsWith("audio/") || asset.content_type.startsWith("video/"))) {
+        try {
+            const { loadMediaRefBytes, probeVideoDurationSeconds } = await import("@nodetool-ai/runtime");
+            const bytes = await loadMediaRefBytes({ asset_id: asset.id }, run.context);
+            if (bytes) {
+                duration = await probeVideoDurationSeconds(bytes, new AbortController().signal);
+                if (isFiniteNumber(duration) && duration > 0) {
+                    asset.duration = duration;
+                    await asset.save();
+                }
+            }
+        }
+        catch {
+            // An explicit clip duration remains usable when the source cannot be probed.
+        }
+    }
+    if (isFiniteNumber(duration) && duration > 0) {
+        resolved.durationMs = Math.round(duration * 1000);
+    }
+    if (thumbnailAssetId)
+        resolved.thumbnailAssetId = thumbnailAssetId;
+    return resolved;
+}
+/**
+ * Run a custom animation's body once and return its curves.
+ *
+ * The bake is the only place that code runs — the curves are stored and every
+ * render site samples them — so it goes through `bakeCustomAnimation`, the
+ * same hermetic path `POST /api/timelines/animations/bake` uses. Imported
+ * lazily: the sandbox is a heavy dependency for a capability most calls never
+ * reach.
+ */
+async function bakeTimelineAnimation(run, request) {
+    const { bakeCustomAnimation } = await import("../custom-animation-bake.js");
+    const params = {
+        code: request.code,
+        role: request.role,
+        durationMs: request.durationMs,
+        clipDurationMs: request.clipDurationMs,
+        canvas: request.canvas
+    };
+    if (request.params !== undefined)
+        params.params = request.params;
+    if (request.staggerCount !== undefined) {
+        params.staggerCount = request.staggerCount;
+    }
+    const baked = await bakeCustomAnimation(run.context, params);
+    const result = { ok: baked.ok };
+    if (baked.curves !== undefined)
+        result.curves = baked.curves;
+    if (baked.mask !== undefined)
+        result.mask = baked.mask;
+    if (baked.error !== undefined)
+        result.error = baked.error;
+    return result;
+}
+/**
+ * The bridge hooks that write outside the document: a Blender render of a 3D
+ * clip, and the new sequence `retarget_format` creates.
+ */
+function writingHooks(run, sequence) {
+    return {
+        bakeModel3DClip: async (request) => {
+            const { bakeModel3DClipOnServer } = await import("./timeline-bake.js");
+            return bakeModel3DClipOnServer(run.context, request);
+        },
+        retargetFormat: async (adapted) => {
+            const { TimelineSequence } = await import("@nodetool-ai/models");
+            const derivedDocument = {
+                tracks: adapted.tracks,
+                clips: adapted.clips,
+                markers: adapted.markers
+            };
+            if (adapted.transcript !== undefined) {
+                derivedDocument.transcript = adapted.transcript;
+            }
+            if (adapted.scriptEnabled !== undefined) {
+                derivedDocument.scriptEnabled = adapted.scriptEnabled;
+            }
+            if (adapted.tempo !== undefined)
+                derivedDocument.tempo = adapted.tempo;
+            if (adapted.camera2d !== undefined)
+                derivedDocument.camera2d = adapted.camera2d;
+            if (adapted.setup !== undefined)
+                derivedDocument.setup = adapted.setup;
+            if (adapted.templateId !== undefined) {
+                derivedDocument.templateId = adapted.templateId;
+            }
+            if (adapted.mediaTracks !== undefined) {
+                derivedDocument.mediaTracks = adapted.mediaTracks;
+            }
+            const name = `${sequence.name} (${adapted.width}×${adapted.height})`;
+            const created = await TimelineSequence.create({
+                user_id: run.context.userId,
+                project_id: sequence.project_id,
+                workflow_id: sequence.workflow_id,
+                name,
+                fps: adapted.fps,
+                width: adapted.width,
+                height: adapted.height,
+                duration_ms: adapted.durationMs,
+                document: JSON.stringify(derivedDocument)
+            });
+            return { sequenceId: created.id, name };
+        }
+    };
+}
+/** Track-only batches need no simulated editor or external hooks. */
+function applyTrackOps(sequence, document, ops) {
+    const contracts = buildTimelineToolContracts({
+        staggerUnits: STAGGER_UNITS,
+        animatedProperties: ANIMATED_PROPERTIES,
+        beatToleranceMs: DEFAULT_BEAT_TOLERANCE_MS
+    });
+    let state = {
+        fps: sequence.fps,
+        width: sequence.width,
+        height: sequence.height,
+        tracks: document.tracks,
+        clips: document.clips,
+        markers: document.markers,
+        mediaTracks: document.mediaTracks,
+        tempo: document.tempo,
+        playheadMs: 0,
+        selectedClipIds: []
+    };
+    const usedIds = new Set([
+        ...[
+            ...document.tracks,
+            ...document.clips,
+            ...document.markers,
+            ...(document.mediaTracks ?? [])
+        ].map((unit) => unit.id),
+        ...document.clips.flatMap((clip) => (clip.animations ?? []).map((animation) => animation.id))
+    ]);
+    let nextId = 0;
+    const newId = () => {
+        let id;
+        do {
+            id = `track_${++nextId}`;
+        } while (usedIds.has(id));
+        usedIds.add(id);
+        return id;
+    };
+    const records = [];
+    for (const entry of ops) {
+        try {
+            let op;
+            if (entry.op === "ui_timeline_add_track") {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_add_track.shape), entry.input);
+                op = { op: "add_track", ...args };
+            }
+            else if (entry.op === "ui_timeline_move_track") {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_move_track.shape), entry.input);
+                op = { op: "move_track", ...resolveMoveTrackArgs(args) };
+            }
+            else {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_delete_track.shape), entry.input);
+                op = { op: "delete_track", ...resolveDeleteTrackArgs(args) };
+            }
+            const outcome = applyTimelineTrackOp(state, op, { newId });
+            if (outcome.error)
+                throw new Error(outcome.error);
+            state = outcome.state;
+            records.push({ op: entry.op, ok: true, result: outcome.result });
+        }
+        catch (error) {
+            records.push({
+                op: entry.op,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return {
+        records,
+        state: {
+            fps: state.fps,
+            width: state.width,
+            height: state.height,
+            durationMs: state.clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0),
+            playheadMs: state.playheadMs,
+            tracks: state.tracks.map(({ id, name, type, index }) => ({
+                id,
+                name,
+                type,
+                index
+            })),
+            clips: state.clips.map((clip) => ({
+                id: clip.id,
+                name: clip.name,
+                trackId: clip.trackId,
+                mediaType: clip.mediaType,
+                startMs: clip.startMs,
+                durationMs: clip.durationMs,
+                prompt: clip.prompt,
+                animations: (clip.animations ?? []).map(({ role, preset }) => ({
+                    role,
+                    preset
+                }))
+            })),
+            documentTracks: state.tracks,
+            documentClips: state.clips,
+            markers: state.markers,
+            mediaTracks: state.mediaTracks ?? [],
+            derivedSequences: [],
+            tempo: state.tempo,
+            camera2d: document.camera2d ?? null,
+            setup: document.setup ?? null,
+            transitionCandidates: [],
+            appliedTransitionCandidates: [],
+            toolLog: ops.map((entry) => entry.op),
+            previewTimesMs: [],
+            previewedLayerKinds: []
+        }
+    };
+}
+/**
+ * Run `ops` against a bridge seeded from `document`.
+ *
+ * A failing op is recorded and the script continues: stopping at the first
+ * error hides every problem behind it, and the caller wants the whole picture.
+ *
+ * `hermetic` leaves out the hooks that write outside the document: the 3D
+ * render and the new sequence a retarget creates. A code bake sets it. The
+ * bridge then uses its in-memory fallbacks for those ops.
+ */
+export async function applyOps(run, sequence, document, ops, options = {}) {
+    if (ops.every(({ op }) => op === "ui_timeline_add_track" || op === "ui_timeline_move_track" || op === "ui_timeline_delete_track")) {
+        return applyTrackOps(sequence, document, ops);
+    }
+    const { createTimelineToolBridge } = await import("./timeline-bridge.js");
+    let operationIndex = 0;
+    const init = {
+        sequenceId: sequence.id,
+        sequenceName: sequence.name,
+        projectId: sequence.project_id,
+        sequence: {
+            fps: sequence.fps,
+            width: sequence.width,
+            height: sequence.height,
+            tracks: document.tracks,
+            clips: document.clips,
+            markers: document.markers,
+            transcript: document.transcript,
+            scriptEnabled: document.scriptEnabled,
+            templateId: document.templateId,
+            tempo: document.tempo,
+            camera2d: document.camera2d,
+            setup: document.setup,
+            mediaTracks: document.mediaTracks
+        },
+        resolveAsset: (ref) => resolveTimelineAsset(run, ref),
+        bakeAnimation: (request) => bakeTimelineAnimation(run, request),
+        loadComposition: {
+            get: async (id) => {
+                const { loadComposition } = await import("./compositions.js");
+                const found = await loadComposition(run, id);
+                return found ? found.composition : null;
+            },
+            listIds: async () => {
+                const { loadShippedCompositions, loadUserCompositions } = await import("./compositions.js");
+                const mine = await loadUserCompositions(run);
+                return [
+                    ...loadShippedCompositions().map((comp) => comp.id),
+                    ...(Array.isArray(mine) ? mine.map((comp) => comp.id) : [])
+                ];
+            }
+        }
+    };
+    if (!options.hermetic) {
+        Object.assign(init, writingHooks(run, sequence));
+        const { timelineMediaEditGenerator } = await import("./timeline-media-edit.js");
+        const generate = options.generateMediaEdit ?? timelineMediaEditGenerator(run);
+        init.generateMediaEdit = (request) => generate(request, operationIndex);
+        init.getClipFrames = async (clip, frameOptions) => {
+            const current = bridge.finalState();
+            const { inspectTimelineClipFrames } = await import("./timeline-clip-frames.js");
+            return inspectTimelineClipFrames(run.context, { ...sequence.toDocument(),
+                tracks: current.documentTracks, clips: current.documentClips, markers: current.markers,
+                mediaTracks: current.mediaTracks, tempo: current.tempo, camera2d: current.camera2d,
+                id: sequence.id, projectId: sequence.project_id ?? "default", name: sequence.name,
+                fps: sequence.fps, width: sequence.width, height: sequence.height,
+                durationMs: sequence.duration_ms, createdAt: sequence.created_at, updatedAt: sequence.updated_at
+            }, clip, frameOptions);
+        };
+    }
+    const bridge = createTimelineToolBridge(init);
+    const byName = new Map(bridge.tools
+        .filter((tool) => !EXCLUDED_OPS.has(tool.name) && !(options.hermetic && (tool.name === `${TOOL_PREFIX}generatively_edit_clip` || READ_ONLY_OPS.has(tool.name))))
+        .map((tool) => [tool.name, tool]));
+    const records = [];
+    for (const [index, { op, input }] of ops.entries()) {
+        operationIndex = index;
+        const tool = byName.get(op);
+        if (!tool) {
+            const known = [...byName.keys()]
+                .map((name) => name.slice(TOOL_PREFIX.length))
+                .sort()
+                .join(", ");
+            records.push({
+                op,
+                ok: false,
+                error: `No timeline operation named "${op.slice(TOOL_PREFIX.length)}". Available: ${known}.`
+            });
+            continue;
+        }
+        try {
+            records.push({ op, ok: true, result: await tool.execute(input) });
+        }
+        catch (e) {
+            records.push({
+                op,
+                ok: false,
+                error: e instanceof Error ? e.message : String(e)
+            });
+        }
+    }
+    return { records, state: bridge.finalState() };
+}
+/**
+ * The keys an op names its unit under, and which list each one means.
+ *
+ * `id`, `target`, `clip_id` and `track_id` are resolved against both lists,
+ * because `target` addresses a clip on most ops and a track on `move_track`.
+ * The midi ops spell theirs `clip` and `track`, which already say which they
+ * mean — so each is resolved against that list alone, and a clip sharing a
+ * track's name cannot capture it.
+ */
+const TIMELINE_OP_ID_KEYS = {
+    id: "any",
+    target: "any",
+    clip_id: "any",
+    track_id: "any",
+    clip: "clip",
+    track: "track"
+};
+function resolveNamedUnit(value, clips, tracks, scope) {
+    const lower = value.toLowerCase();
+    const match = (units) => (units.find((u) => u.id === value) ??
+        units.find((u) => u.name.toLowerCase() === lower))?.id;
+    if (scope !== "track") {
+        const clip = match(clips);
+        if (clip)
+            return clip;
+    }
+    if (scope !== "clip") {
+        const track = match(tracks);
+        if (track)
+            return track;
+    }
+    return value;
+}
+/**
+ * The unit ids one op's result names.
+ *
+ * The bridge answers `{ok, clip}`, `{ok, track}`, `{ok, marker}`, `{ok, clips}`
+ * (a split), `{ok, deleted}` (a delete) or `{ok, selected}` — never a bare
+ * `id`, which is why reading `result.id` alone left every `"selected"` target
+ * unresolved.
+ */
+export function resultUnitIds(result) {
+    if (!isRecord(result))
+        return [];
+    const ids = [];
+    const push = (value) => {
+        if (isRecord(value) && isString(value["id"]))
+            ids.push(value["id"]);
+    };
+    for (const key of ["clip", "track", "marker", "deleted", "selected"]) {
+        push(result[key]);
+    }
+    const clips = result["clips"];
+    if (Array.isArray(clips)) {
+        for (const clip of clips)
+            push(clip);
+    }
+    if (isString(result["id"]))
+        ids.push(result["id"]);
+    return ids;
+}
+/**
+ * Canonicalize one op input for the `resource_change` broadcast: names and
+ * `"selected"` become ids, and an op that created something carries the id it
+ * created. Without that stamp an editor merging this write cannot tell which
+ * unit an `add_track` touched and falls back to contesting every unit that
+ * happens to have drifted.
+ */
+export function resolveTimelineOpInput(input, before, state, result) {
+    const clips = [
+        ...before.clips.map((c) => ({ id: c.id, name: c.name })),
+        ...state.clips
+    ];
+    const tracks = [
+        ...before.tracks.map((t) => ({ id: t.id, name: t.name })),
+        ...state.tracks
+    ];
+    const resultIds = resultUnitIds(result);
+    const next = { ...input };
+    for (const [key, scope] of Object.entries(TIMELINE_OP_ID_KEYS)) {
+        const value = next[key];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        if (value.toLowerCase() === "selected") {
+            if (resultIds[0])
+                next[key] = resultIds[0];
+            continue;
+        }
+        next[key] = resolveNamedUnit(value, clips, tracks, scope);
+    }
+    // An op that named no unit either created one or addressed the selection;
+    // the result says which, so stamp it.
+    if (next["id"] === undefined && resultIds.length > 0) {
+        next["id"] = resultIds.length === 1 ? resultIds[0] : resultIds;
+    }
+    return next;
+}
+const editTimeline = {
+    spec: editTimelineSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        if (!isString(timelineId) || !timelineId) {
+            return {
+                error: "timeline_id is required (use list_timelines to find one)."
+            };
+        }
+        const ops = parseOps(params["ops"]);
+        if (isError(ops))
+            return ops;
+        if (ops.length > 1 &&
+            ops.some((entry) => entry.op === `${TOOL_PREFIX}retarget_format`)) {
+            return {
+                error: "retarget_format creates a new sequence and must be the only op in " +
+                    "an edit_timeline call. Call it once per target format, then edit " +
+                    "the returned timeline id."
+            };
+        }
+        const { TimelineSequence, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const { timelineMediaEditGenerator } = await import("./timeline-media-edit.js");
+        const generateMediaEdit = timelineMediaEditGenerator(run);
+        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
+            const sequence = await TimelineSequence.findById(timelineId);
+            // A sequence owned by someone else reads as missing — the rule the tRPC
+            // router's ownership check applies.
+            if (!sequence || sequence.user_id !== run.context.userId) {
+                return { error: `Timeline ${timelineId} was not found.` };
+            }
+            const document = sequence.toDocument();
+            const { records, state } = await applyOps(run, sequence, document, ops, { generateMediaEdit });
+            // The transcript rides along untouched — no timeline operation edits it,
+            // so the stored copy stays authoritative. Markers come back from the
+            // bridge, which seeded them and which the marker ops write to.
+            const next = {
+                ...document,
+                tracks: state.documentTracks,
+                clips: state.documentClips,
+                markers: state.markers
+            };
+            // `set_tempo` and the first midi track both write it. Without this the
+            // stored document keeps the old BPM while the clips carry the rescaled
+            // milliseconds, so the part plays at the wrong speed on the next read.
+            if (state.tempo)
+                next.tempo = state.tempo;
+            // The guided flow's stage and plan are document state like the rest: an
+            // op run that moved the flow on has to be what the row holds afterwards,
+            // or the next surface to open the sequence resumes at the old step.
+            if (state.setup) {
+                next.setup = state.setup;
+            }
+            // Subject/object tracks come back from the bridge the way markers do.
+            // A document that never carried one keeps the field absent rather than
+            // growing an empty array; one that did keeps what the ops left it with,
+            // including the empty array `delete_track_object` leaves behind.
+            if (state.mediaTracks.length > 0 || document.mediaTracks !== undefined) {
+                next.mediaTracks = state.mediaTracks;
+            }
+            const failed = records.filter((record) => !record.ok);
+            // Only the ops that landed describe the write, and a script where none
+            // landed is not a write at all: saving it would bump the revision and
+            // hand an open editor a merge with nothing in it.
+            const appliedOps = ops
+                .map((parsed, index) => ({ parsed, index }))
+                .filter(({ parsed, index }) => records[index]?.ok && !READ_ONLY_OPS.has(parsed.op));
+            if (appliedOps.length === 0) {
+                return {
+                    timeline_id: timelineId,
+                    updated_at: sequence.updated_at,
+                    applied: records.filter((record) => record.ok).length,
+                    failed: failed.length,
+                    ops: records,
+                    tracks: state.tracks,
+                    clips: state.clips.map((clip) => ({
+                        id: clip.id,
+                        name: clip.name,
+                        track_id: clip.trackId,
+                        media_type: clip.mediaType,
+                        start_ms: clip.startMs,
+                        duration_ms: clip.durationMs,
+                        animations: clip.animations
+                    }))
+                };
+            }
+            // retarget_format has already created a derived row through the bridge's
+            // host callback. It deliberately leaves this source document untouched,
+            // including its revision and updated_at timestamp.
+            if (appliedOps[0]?.parsed.op === `${TOOL_PREFIX}retarget_format`) {
+                return {
+                    timeline_id: timelineId,
+                    updated_at: sequence.updated_at,
+                    applied: 1,
+                    failed: failed.length,
+                    ops: records,
+                    tracks: state.tracks,
+                    clips: state.clips.map((clip) => ({
+                        id: clip.id,
+                        name: clip.name,
+                        track_id: clip.trackId,
+                        media_type: clip.mediaType,
+                        start_ms: clip.startMs,
+                        duration_ms: clip.durationMs,
+                        animations: clip.animations
+                    }))
+                };
+            }
+            const undo = appliedOps.some(({ parsed }) => parsed.op === `${TOOL_PREFIX}apply_take`)
+                ? await TimelineSequenceVersion.snapshot(sequence, { saveType: "manual", name: "Before applying AI edit take" })
+                : undefined;
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(sequence.id, sequence.updated_at, next, {
+                ops: appliedOps.map(({ parsed, index }) => ({
+                    tool: parsed.op,
+                    input: resolveTimelineOpInput(parsed.input, document, state, records[index]?.result)
+                }))
+            }).catch(async (error) => {
+                await undo?.delete();
+                throw error;
+            });
+            if (!saved) {
+                await undo?.delete();
+                continue;
+            }
+            const response = {
+                timeline_id: timelineId,
+                updated_at: saved.updated_at,
+                applied: records.length - failed.length,
+                failed: failed.length,
+                ops: records,
+                tracks: state.tracks,
+                clips: state.clips.map((clip) => ({
+                    id: clip.id,
+                    name: clip.name,
+                    track_id: clip.trackId,
+                    media_type: clip.mediaType,
+                    start_ms: clip.startMs,
+                    duration_ms: clip.durationMs,
+                    animations: clip.animations
+                }))
+            };
+            if (undo) {
+                Object.assign(response, { undo_version: undo.version });
+            }
+            return response;
+        }
+        return {
+            error: `Timeline ${timelineId} is being modified concurrently; nothing was saved. Retry the call.`
+        };
+    }
+};
+// ---------------------------------------------------------------------------
+// validate_timeline
+// ---------------------------------------------------------------------------
+/**
+ * The media ref a clip's `currentAssetId` names. Usually a bare asset id, but a
+ * shipped example names its stills by `package://` URI, which resolves for
+ * every user without an asset row; wrapping that in `asset://` made an id no
+ * store holds.
+ */
+function clipAssetRef(assetId) {
+    return assetId.includes("://")
+        ? { uri: assetId }
+        : { uri: `asset://${assetId}`, asset_id: assetId };
+}
+/** A positive finite number from a tool param, or undefined. */
+function numberParam(value) {
+    return isFiniteNumber(value) && value > 0
+        ? value
+        : undefined;
+}
+/**
+ * Like {@link numberParam} but keeps 0, for a shutter angle: 0 degrees is a
+ * closed shutter, a value the schema can express and `numberParam` would read
+ * as unset and silently replace with the 180-degree default.
+ */
+function angleParam(value) {
+    return isFiniteNumber(value) && value >= 0 ? value : undefined;
+}
+/** Unwrap a stored document that may still be JSON text. */
+function parseStoredDocument(document) {
+    if (!isString(document))
+        return document;
+    try {
+        return JSON.parse(document);
+    }
+    catch {
+        return undefined;
+    }
+}
+const validateTimeline = {
+    spec: validateTimelineSpec,
+    // The timeline API is tRPC-only, so there is no REST route to fall back on.
+    // A host may put a loader on the run — the MCP server does, to apply its own
+    // ownership rule — and without one the row is read the way every other
+    // capability in this module reads it. The "no loader" refusal this replaced
+    // meant a chat belt could edit a sequence it could not then validate.
+    impl: async (run, params) => {
+        const tier = params["tier"];
+        if (tier !== undefined && tier !== "standard" && tier !== "showcase") {
+            return { error: "Unsupported validation tier. Use standard or showcase." };
+        }
+        const inline = params["document"];
+        const timelineId = params["timeline_id"];
+        let document = inline;
+        // An inline document carries no stored render settings, so the caller
+        // supplies them; the timeline_id path overwrites these from the row.
+        let meta = {
+            fps: numberParam(params["fps"]),
+            width: numberParam(params["width"]),
+            height: numberParam(params["height"])
+        };
+        let name;
+        if (document === undefined && timelineId) {
+            const loadRow = run.loaders?.timeline;
+            const record = loadRow
+                ? await loadRow(run.context, timelineId)
+                : await (async () => {
+                    const seq = await loadTimeline(run, timelineId);
+                    return isError(seq) ? null : seq;
+                })();
+            if (!record) {
+                return {
+                    error: `Timeline ${timelineId} was not found.`,
+                    validated: false
+                };
+            }
+            document = parseStoredDocument(record.document);
+            meta = { fps: record.fps, width: record.width, height: record.height };
+            name = record.name;
+        }
+        if (document === undefined || document === null) {
+            return {
+                error: "No timeline to validate — pass an inline `document` ({tracks, clips, markers}) or a valid `timeline_id`."
+            };
+        }
+        const { validateTimelineSequence } = await import("@nodetool-ai/execution/timeline-debug");
+        const validationMeta = { ...meta };
+        if (tier !== undefined) {
+            validationMeta.tier = tier;
+        }
+        // Inline preflight must use the same authoring normalization as setDocument.
+        if (inline !== undefined && params["normalize"] === true && isRecord(document)) {
+            const normalized = documentToStore(document);
+            document = normalized.document;
+            meta = { ...normalized.settings, ...Object.fromEntries(Object.entries(meta).filter(([, value]) => value !== undefined)) };
+            Object.assign(validationMeta, meta);
+        }
+        const validation = validateTimelineSequence(document, validationMeta);
+        const report = { ...validation, summary: validationSummary(validation) };
+        if (timelineId)
+            report.timeline_id = timelineId;
+        if (name)
+            report.name = name;
+        return report;
+    }
+};
+// ---------------------------------------------------------------------------
+// set_timeline_document
+// ---------------------------------------------------------------------------
+/**
+ * A document the caller sent, ready to validate.
+ *
+ * A hand-authored cut leaves out the bookkeeping the schema requires — track
+ * `index`/`visible`/`locked`, clip `sourceType`/`status`/`locked`/`versions`,
+ * animation ids, `markers` — and refusing it with two dozen schema errors
+ * teaches the caller nothing. `normalizeAuthoredDocument` fills exactly what is
+ * missing and lifts document-level `fps`/`width`/`height` out as sequence
+ * settings; a value the caller sent is never replaced, because the point of a
+ * whole-document write is that what was sent is what the sequence becomes.
+ */
+function documentToStore(raw) {
+    return normalizeAuthoredDocument(raw);
+}
+/** The end of the last clip — what the sequence's stored duration means. */
+function documentDurationMs(document) {
+    const clips = document["clips"];
+    if (!Array.isArray(clips))
+        return 0;
+    return clips.reduce((end, clip) => {
+        if (!isRecord(clip))
+            return end;
+        const start = Number(clip["startMs"]) || 0;
+        const length = Number(clip["durationMs"]) || 0;
+        return Math.max(end, start + length);
+    }, 0);
+}
+/**
+ * Replace a sequence's whole document in one call.
+ *
+ * `edit_timeline` is a script of ops against what is already stored, which is
+ * the wrong shape for authoring a cut from nothing: every clip costs an op,
+ * and the ops only reach the fields the bridge exposes. This takes the
+ * document itself.
+ *
+ * The order is validate → snapshot → CAS → validate again, and each step
+ * exists for a failure the one before it cannot catch:
+ *
+ * 1. **Validate first.** A document that would not render must not reach the
+ *    database — a refusal that still wrote is worse than no capability at all.
+ *    Errors return the issues and nothing else happens, snapshot included: a
+ *    refused call that left a version row behind is still a write.
+ * 2. **Snapshot.** The state being replaced becomes a manual version, so the
+ *    write is undoable with `restore_timeline_version` the way a restore is.
+ * 3. **CAS.** The write lands only while the row still reads as it did, so a
+ *    concurrent edit is reported instead of overwritten. There is no retry
+ *    loop here, unlike `edit_timeline`: ops re-apply against a newer document
+ *    and compose, a whole-document replace does not — retrying it would clobber
+ *    exactly the change CAS caught.
+ * 4. **Validate again.** The caller sees what it created rather than what it
+ *    intended. The two validations differ: the second runs against the stored
+ *    fps/width/height and the document as the row now holds it.
+ */
+const setTimelineDocument = {
+    spec: setTimelineDocumentSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const raw = params["document"];
+        if (!isRecord(raw)) {
+            return {
+                error: "document is required and must be an object ({tracks, clips, markers}). Read the current one with get_timeline."
+            };
+        }
+        const expected = params["expected_updated_at"];
+        if (expected !== undefined && expected !== null) {
+            if (!isString(expected)) {
+                return { error: "expected_updated_at must be a string timestamp." };
+            }
+            if (expected !== sequence.updated_at) {
+                return {
+                    error: `Timeline ${sequence.id} was modified since it was read at ${expected} (it now reads ${sequence.updated_at}); nothing was written. Read it again with get_timeline and re-apply your changes.`,
+                    written: false,
+                    conflict: true,
+                    timeline_id: sequence.id
+                };
+            }
+        }
+        const { document, settings } = documentToStore(raw);
+        // Document-level fps/width/height are sequence settings, so opts win and a
+        // document that carries them configures the sequence instead of having
+        // them stripped with a `field_stripped` warning.
+        const fps = sequenceSetting(params["fps"] ?? settings.fps, sequence.fps, "fps");
+        if (isError(fps))
+            return fps;
+        const width = sequenceSetting(params["width"] ?? settings.width, sequence.width, "width");
+        if (isError(width))
+            return width;
+        const height = sequenceSetting(params["height"] ?? settings.height, sequence.height, "height");
+        if (isError(height))
+            return height;
+        const { validateTimelineSequence } = await import("@nodetool-ai/execution/timeline-debug");
+        const before = validateTimelineSequence(document, {
+            fps,
+            width,
+            height
+        });
+        if (!before.ok) {
+            return {
+                error: `The document has ${before.errors.length} error${before.errors.length === 1 ? "" : "s"} and was not written to timeline ${sequence.id}. Fix them and call again.`,
+                written: false,
+                timeline_id: sequence.id,
+                validation: before,
+                summary: validationSummary(before)
+            };
+        }
+        const { TimelineSequence, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const snapshotName = isString(params["snapshot_name"]) && params["snapshot_name"]
+            ? params["snapshot_name"]
+            : "Before set_timeline_document";
+        const undo = await TimelineSequenceVersion.snapshot(sequence, {
+            saveType: "manual",
+            name: snapshotName
+        });
+        const durationMs = documentDurationMs(document);
+        let saved;
+        try {
+            saved = await TimelineSequence.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, {
+                document: JSON.stringify(document),
+                fps,
+                width,
+                height,
+                duration_ms: durationMs
+            });
+        }
+        catch (error) {
+            // The model rejects a document without tracks/clips/markers arrays. The
+            // validation above already covers that, so reaching here means the two
+            // disagree — report it rather than throwing out of the capability.
+            return {
+                error: `The document was refused by the store: ${error instanceof Error ? error.message : String(error)}`,
+                written: false,
+                timeline_id: sequence.id,
+                undo_version: undo.version
+            };
+        }
+        if (!saved) {
+            return {
+                error: `Timeline ${sequence.id} was modified concurrently; nothing was written. Read it again with get_timeline and re-apply your changes.`,
+                written: false,
+                conflict: true,
+                timeline_id: sequence.id,
+                undo_version: undo.version
+            };
+        }
+        const after = validateTimelineSequence(saved.toDocument(), { fps: saved.fps, width: saved.width, height: saved.height });
+        return {
+            ok: true,
+            written: true,
+            timeline_id: saved.id,
+            updated_at: saved.updated_at,
+            undo_version: undo.version,
+            fps: saved.fps,
+            width: saved.width,
+            height: saved.height,
+            duration_ms: saved.duration_ms,
+            track_count: Array.isArray(document["tracks"])
+                ? document["tracks"].length
+                : 0,
+            clip_count: Array.isArray(document["clips"])
+                ? document["clips"].length
+                : 0,
+            validation: after,
+            summary: validationSummary(after)
+        };
+    }
+};
+/**
+ * The timecodes to render when the caller names none: evenly spaced across the
+ * sequence, avoiding both ends — the first and last frame of a cut are the two
+ * least informative places to look.
+ */
+function evenlySpacedTimes(durationMs, count) {
+    const span = Math.max(1, durationMs);
+    return Array.from({ length: count }, (_, i) => Math.round((span * (i + 1)) / (count + 1)));
+}
+/** A persisted PNG as the image reference `view_image` reads. */
+function imageHandle(saved) {
+    return {
+        type: "image",
+        asset_id: saved.asset_id,
+        asset_uri: saved.asset_uri,
+        uri: saved.asset_uri ?? saved.path,
+        path: saved.path,
+        mime_type: saved.mime_type,
+        bytes: saved.bytes
+    };
+}
+/**
+ * The timecodes a `range` names: `count` of them from `from_ms` to `to_ms`,
+ * both ends included. Inclusive because a range is how a caller watches a move
+ * play out, and a move's start and end are the two instants it is defined by —
+ * the opposite of the default sweep, which avoids the ends of the whole cut.
+ */
+function rangeTimes(raw) {
+    if (!isRecord(raw)) {
+        return { error: "range must be an object ({from_ms, to_ms, count})." };
+    }
+    const from = Number(raw["from_ms"]);
+    const to = Number(raw["to_ms"]);
+    if (!isFiniteNumber(from) || !isFiniteNumber(to) || from < 0 || to < 0) {
+        return { error: "range needs a non-negative from_ms and to_ms." };
+    }
+    if (to < from) {
+        return {
+            error: `range runs backwards: from_ms ${from} is after to_ms ${to}.`
+        };
+    }
+    const count = raw["count"] === undefined || raw["count"] === null
+        ? DEFAULT_PREVIEW_COUNT
+        : Math.round(Number(raw["count"]));
+    if (!isFiniteNumber(count) || count < 1) {
+        return { error: "range.count must be a whole number of 1 or more." };
+    }
+    if (count > MAX_PREVIEW_RANGE_COUNT) {
+        return {
+            error: `range.count is ${count}; at most ${MAX_PREVIEW_RANGE_COUNT} frames render per call.`
+        };
+    }
+    if (count === 1)
+        return [from];
+    return Array.from({ length: count }, (_, i) => Math.round(from + ((to - from) * i) / (count - 1)));
+}
+/** The timecodes a preview or compare call asks for. */
+function requestedTimes(params, durationMs, maxTimes = MAX_PREVIEW_TIMES) {
+    const raw = params["times_ms"];
+    const range = params["range"];
+    const hasRange = range !== undefined && range !== null;
+    if (hasRange && raw !== undefined && raw !== null) {
+        return {
+            error: "Pass times_ms or range, not both — they name the timecodes two different ways."
+        };
+    }
+    if (hasRange)
+        return rangeTimes(range);
+    if (raw === undefined || raw === null) {
+        const count = Math.max(1, Math.min(MAX_PREVIEW_TIMES, Math.round(Number(params["count"]) || DEFAULT_PREVIEW_COUNT)));
+        return evenlySpacedTimes(durationMs, count);
+    }
+    if (!Array.isArray(raw)) {
+        return { error: "times_ms must be an array of milliseconds." };
+    }
+    if (raw.length === 0) {
+        return { error: "times_ms was empty — omit it to sample evenly instead." };
+    }
+    if (raw.length > maxTimes) {
+        return {
+            error: `times_ms holds ${raw.length} timecodes; at most ${maxTimes} render per call. ` +
+                `Split them across ${Math.ceil(raw.length / maxTimes)} calls of ${maxTimes} or fewer, ` +
+                "or pass `range` with `count` to sample a span evenly in one call."
+        };
+    }
+    const times = [];
+    for (const value of raw) {
+        if (!isFiniteNumber(value) || value < 0) {
+            return {
+                error: `times_ms must hold non-negative numbers; got ${JSON.stringify(value)}.`
+            };
+        }
+        times.push(value);
+    }
+    return times;
+}
+/**
+ * Render the composited frame at chosen timecodes.
+ *
+ * Frames are persisted as assets and returned as handles, not as pixels: this
+ * follows the rule `view_image` exists for — a tool that produces an image
+ * hands back a reference, and the model pulls the pixels into context only for
+ * the frame it decides to look at. Three frames of inline base64 would be in
+ * every subsequent turn of the conversation whether or not they were read.
+ */
+const previewTimelineFrame = {
+    spec: previewTimelineFrameSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        const inline = params["document"];
+        let document = inline;
+        let meta = {
+            fps: numberParam(params["fps"]) ?? 30,
+            width: numberParam(params["width_px"]) ?? 1920,
+            height: numberParam(params["height_px"]) ?? 1080
+        };
+        let durationMs = 0;
+        let name = "Inline timeline";
+        if (document === undefined || document === null) {
+            const seq = await loadTimeline(run, timelineId);
+            if (isError(seq))
+                return seq;
+            const resolved = seq.toTimelineSequence();
+            document = resolved;
+            meta = { fps: resolved.fps, width: resolved.width, height: resolved.height };
+            durationMs = resolved.durationMs;
+            name = resolved.name;
+        }
+        if (!isRecord(document)) {
+            return {
+                error: "No timeline to render — pass an inline `document` ({tracks, clips, markers}) or a valid `timeline_id`."
+            };
+        }
+        const tracks = Array.isArray(document["tracks"]) ? document["tracks"] : [];
+        const clips = Array.isArray(document["clips"]) ? document["clips"] : [];
+        if (clips.length === 0) {
+            return {
+                error: `${name} has no clips to render.`,
+                timeline_id: isString(timelineId) ? timelineId : undefined
+            };
+        }
+        if (durationMs <= 0) {
+            // An inline document carries no stored duration, so derive it from the
+            // clips: the end of the last one is the end of the cut.
+            durationMs = clips.reduce((end, clip) => {
+                if (!isRecord(clip))
+                    return end;
+                const start = Number(clip["startMs"]) || 0;
+                const length = Number(clip["durationMs"]) || 0;
+                return Math.max(end, start + length);
+            }, 0);
+        }
+        const times = requestedTimes(params, durationMs);
+        if (isError(times))
+            return times;
+        const { renderTimelineFrames } = await import("../timeline-preview/frames.js");
+        const { loadMediaRefBytes } = await import("@nodetool-ai/runtime");
+        const { persistOutput } = await import("../tools/asset-persist.js");
+        let result;
+        try {
+            result = await renderTimelineFrames({
+                sequence: {
+                    ...document,
+                    tracks,
+                    clips,
+                    fps: meta.fps,
+                    width: meta.width,
+                    height: meta.height,
+                    durationMs
+                },
+                timesMs: times,
+                width: numberParam(params["width"]),
+                motionBlur: {
+                    samplesPerFrame: numberParam(params["motion_blur_samples"]),
+                    shutterAngle: angleParam(params["shutter_angle"])
+                },
+                loadAsset: (assetId) => loadMediaRefBytes(clipAssetRef(assetId), run.context)
+            });
+        }
+        catch (error) {
+            return {
+                error: `Could not render the timeline: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+        // With a sheet the pixels leave as one image, so no frame persists its
+        // own: N handles the caller will never open cost N asset writes.
+        const wantSheet = params["sheet"] === true;
+        let sheet;
+        if (wantSheet) {
+            const { composeContactSheet } = await import("../timeline-preview/sheet.js");
+            const tiled = await composeContactSheet(result.frames.map((frame) => ({
+                label: `${frame.time_ms}ms`,
+                png: frame.png
+            })));
+            const saved = await persistOutput(run.context, tiled.png, {
+                namePrefix: "timeline-sheet",
+                mime: "image/png"
+            });
+            sheet = {
+                complete: result.complete,
+                columns: tiled.columns,
+                rows: tiled.rows,
+                cells: tiled.cells,
+                cell_width: tiled.cell_width,
+                cell_height: tiled.cell_height,
+                width: tiled.width,
+                height: tiled.height,
+                image: imageHandle(saved)
+            };
+        }
+        const frames = [];
+        for (const frame of result.frames) {
+            const entry = {
+                complete: frame.complete,
+                time_ms: frame.time_ms,
+                width: frame.width,
+                height: frame.height,
+                layers: frame.layers,
+                failures: frame.failures,
+                dropped: frame.dropped,
+                degraded: frame.degraded,
+                degradations: frame.degraded
+            };
+            if (!wantSheet) {
+                const saved = await persistOutput(run.context, frame.png, {
+                    namePrefix: "timeline-frame",
+                    mime: "image/png"
+                });
+                entry.image = imageHandle(saved);
+            }
+            frames.push(entry);
+        }
+        return {
+            complete: result.complete,
+            visual_output_verified: false,
+            timeline_id: isString(timelineId) ? timelineId : undefined,
+            name,
+            fps: meta.fps,
+            sequence_width: meta.width,
+            sequence_height: meta.height,
+            duration_ms: durationMs,
+            frames,
+            sheet,
+            effects_not_applied: result.effectsNotApplied,
+            fonts_unavailable: result.fontsUnavailable,
+            hint: (!result.complete
+                ? "Incomplete preview: requested content was skipped or approximated. Inspect failures, dropped, degradations, skipped layers, effects_not_applied and fonts_unavailable. This image cannot verify the complete composition. "
+                : "") + (wantSheet
+                ? "Call view_image with the sheet's asset_id to see every frame at " +
+                    "once; the cells run left to right, labelled with their timecode. " +
+                    "Each frame's layers are listed top of the stack first."
+                : "Call view_image with a frame's asset_id to see it. The layers are " +
+                    "listed top of the stack first — the first one covers the rest.")
+        };
+    }
+};
+/**
+ * Resolve `a` or `b` — a timeline id, `{timeline_id}`, `{timeline_id,
+ * version}`, `{document}`, or a bare document — to a renderable sequence.
+ *
+ * A version is read the way `get_timeline_version` reads one: the snapshot's
+ * own document and its own frame geometry, since a sequence resized after the
+ * snapshot would otherwise render the old cut at the new size and report every
+ * frame as changed.
+ */
+async function resolveCompareSide(run, raw, which) {
+    const side = isString(raw) ? { timeline_id: raw } : raw;
+    if (!isRecord(side)) {
+        return {
+            error: `${which} must be a timeline id, {timeline_id}, {timeline_id, version} or {document}.`
+        };
+    }
+    if (side["timeline_id"] !== undefined && side["timeline_id"] !== null) {
+        const seq = await loadTimeline(run, side["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        if (side["version"] === undefined || side["version"] === null) {
+            const resolved = seq.toTimelineSequence();
+            return {
+                document: resolved,
+                fps: resolved.fps,
+                width: resolved.width,
+                height: resolved.height,
+                durationMs: resolved.durationMs,
+                source: { timeline_id: seq.id, name: resolved.name }
+            };
+        }
+        const number = versionNumber(side["version"]);
+        if (isError(number))
+            return number;
+        const { TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const version = await TimelineSequenceVersion.findByVersion(seq.id, number);
+        if (!version) {
+            return {
+                error: `Timeline ${seq.id} has no version ${number}. Call list_timeline_versions to see the available ones.`
+            };
+        }
+        const document = parseVersionDocument(version.document);
+        if (isError(document))
+            return document;
+        if (!isRecord(document)) {
+            return { error: `Version ${number} of timeline ${seq.id} is not a document.` };
+        }
+        return {
+            document,
+            fps: version.fps,
+            width: version.width,
+            height: version.height,
+            durationMs: version.duration_ms || documentDurationMs(document),
+            source: { timeline_id: seq.id, version: number, name: version.name }
+        };
+    }
+    const inline = isRecord(side["document"]) ? side["document"] : side;
+    if (!Array.isArray(inline["tracks"]) && !Array.isArray(inline["clips"])) {
+        return {
+            error: `${which} carries no timeline — pass a timeline id, {timeline_id, version} or {document: {tracks, clips}}.`
+        };
+    }
+    return {
+        document: inline,
+        fps: numberParam(inline["fps"]) ?? 30,
+        width: numberParam(inline["width"]) ?? 1920,
+        height: numberParam(inline["height"]) ?? 1080,
+        durationMs: documentDurationMs(inline),
+        source: { document: true }
+    };
+}
+/**
+ * Difference two timelines frame by frame.
+ *
+ * The pixels are the measurement an agent has no other way to take: a
+ * structural diff of two documents says a clip moved, not whether the picture
+ * moved with it, and a clip nudged 2ms reads there exactly like one moved 2s.
+ * Every frame gets a score, and the sheet is what makes a score readable —
+ * 0.04 at 1500ms means nothing until the pair is next to each other.
+ */
+const compareTimelineFrames = {
+    spec: compareTimelineFramesSpec,
+    impl: async (run, params) => {
+        const a = await resolveCompareSide(run, params["a"], "a");
+        if (isError(a))
+            return a;
+        const b = await resolveCompareSide(run, params["b"], "b");
+        if (isError(b))
+            return b;
+        const times = requestedTimes(params, Math.max(a.durationMs, b.durationMs), MAX_PREVIEW_RANGE_COUNT);
+        if (isError(times))
+            return times;
+        const { renderTimelineFrames } = await import("../timeline-preview/frames.js");
+        const { loadMediaRefBytes } = await import("@nodetool-ai/runtime");
+        const { frameDifference, sideBySide } = await import("../timeline-preview/compare.js");
+        const { composeContactSheet } = await import("../timeline-preview/sheet.js");
+        const { persistOutput } = await import("../tools/asset-persist.js");
+        const width = numberParam(params["width"]) ?? DEFAULT_COMPARE_WIDTH;
+        const renderSide = (side) => renderTimelineFrames({
+            sequence: {
+                ...side.document,
+                tracks: Array.isArray(side.document["tracks"])
+                    ? side.document["tracks"]
+                    : [],
+                clips: Array.isArray(side.document["clips"])
+                    ? side.document["clips"]
+                    : [],
+                fps: side.fps,
+                width: side.width,
+                height: side.height,
+                durationMs: side.durationMs
+            },
+            timesMs: times,
+            width,
+            loadAsset: (assetId) => loadMediaRefBytes(clipAssetRef(assetId), run.context)
+        });
+        let rendered;
+        try {
+            rendered = await Promise.all([renderSide(a), renderSide(b)]);
+        }
+        catch (error) {
+            return {
+                error: `Could not render the timelines: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+        const [left, right] = rendered;
+        const frames = [];
+        const cells = [];
+        for (let i = 0; i < times.length; i++) {
+            const complete = left.frames[i].complete && right.frames[i].complete;
+            const difference = complete ? Number((await frameDifference(left.frames[i].png, right.frames[i].png)).toFixed(4)) : null;
+            frames.push({
+                time_ms: times[i], complete, difference,
+                a: { failures: left.frames[i].failures, dropped: left.frames[i].dropped, degradations: left.frames[i].degraded, skipped: left.frames[i].layers.filter((layer) => layer.skipped) },
+                b: { failures: right.frames[i].failures, dropped: right.frames[i].dropped, degradations: right.frames[i].degraded, skipped: right.frames[i].layers.filter((layer) => layer.skipped) }
+            });
+            cells.push({
+                label: `${times[i]}ms  ${difference === null ? "incomplete" : difference.toFixed(3)}`,
+                png: await sideBySide(left.frames[i].png, right.frames[i].png)
+            });
+        }
+        const tiled = await composeContactSheet(cells);
+        const saved = await persistOutput(run.context, tiled.png, {
+            namePrefix: "timeline-compare",
+            mime: "image/png"
+        });
+        const complete = left.complete && right.complete;
+        const differences = frames.flatMap((frame) => frame.difference === null ? [] : [frame.difference]);
+        const changed = frames.filter((frame) => frame.difference !== null && frame.difference > 0);
+        return {
+            complete,
+            visual_output_verified: false,
+            a: a.source,
+            b: b.source,
+            frames,
+            changed_times_ms: complete ? changed.map((frame) => frame.time_ms) : null,
+            max_difference: complete ? Math.max(...differences) : null,
+            mean_difference: complete ? Number((differences.reduce((sum, d) => sum + d, 0) / differences.length).toFixed(4)) : null,
+            sheet: {
+                complete,
+                columns: tiled.columns,
+                rows: tiled.rows,
+                cells: tiled.cells,
+                width: tiled.width,
+                height: tiled.height,
+                image: imageHandle(saved)
+            },
+            effects_not_applied: [
+                ...new Set([...left.effectsNotApplied, ...right.effectsNotApplied])
+            ].sort(),
+            fonts_unavailable: [
+                ...new Set([...left.fontsUnavailable, ...right.fontsUnavailable])
+            ].sort(),
+            hint: (!complete ? "Incomplete previews cannot establish visual equivalence. Difference scores are null for incomplete pairs and aggregate metrics are unavailable. " : "") +
+                "difference is the mean absolute RGB difference, 0 (identical) to 1. " +
+                "Each cell of the sheet is a pair: `a` on the left, `b` on the right, " +
+                "labelled with its timecode and score."
+        };
+    }
+};
+/** The node id the one render node carries inside the graph this builds. */
+const RENDER_NODE_ID = "render";
+/** The Output node that turns the rendered bytes into an asset. */
+const RENDER_OUTPUT_NODE_ID = "output";
+/** The handle the render's asset comes back under. */
+const RENDER_OUTPUT_NAME = "video";
+/** The Output node a png_sequence's zip goes through. */
+const RENDER_FRAMES_OUTPUT_NODE_ID = "frames_output";
+/** The handle a png_sequence's zip comes back under. */
+const RENDER_FRAMES_OUTPUT_NAME = "frames";
+/**
+ * Bits per second from a `bitrate` argument, or undefined when there is none
+ * to read. The node takes a number; a caller writes what ffmpeg takes, so
+ * "8M" and "800k" parse here rather than being dropped on the way to the graph.
+ */
+export function parseBitrate(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) && value > 0 ? Math.round(value) : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    const match = /^\s*([0-9]*\.?[0-9]+)\s*([kKmM]?)\s*$/.exec(value);
+    if (!match)
+        return undefined;
+    const scale = match[2]?.toLowerCase() === "m"
+        ? 1_000_000
+        : match[2]?.toLowerCase() === "k"
+            ? 1_000
+            : 1;
+    const bits = Number(match[1]) * scale;
+    return bits > 0 ? Math.round(bits) : undefined;
+}
+/** How often a `wait: true` render re-reads the job row. */
+const RENDER_POLL_INTERVAL_MS = 1000;
+/**
+ * The call arguments that are render-node properties, passed through under the
+ * same name. Everything else in the call — `wait`, `timeout_ms` — is how long
+ * this capability watches the job, and never reaches the graph.
+ */
+const RENDER_NODE_PROPS = [
+    "format",
+    "alpha",
+    "video_codec",
+    "bitrate",
+    "motion_blur_samples",
+    "shutter_angle",
+    "preview_scale",
+    "include_audio"
+];
+/**
+ * The graph a render runs as: the render node, and an Output node that turns
+ * its bytes into an asset.
+ *
+ * The Output node is what makes the result addressable. `RenderTimeline` emits
+ * a `VideoRef` carrying base64 and no asset id, so a graph ending at it leaves
+ * the render inside the job row and nowhere else; `nodetool.output.Output`
+ * stores the bytes and stamps the id `render_timeline` hands back.
+ */
+export function buildRenderTimelineGraph(timelineId, params) {
+    const properties = {
+        timeline: { type: "timeline", id: timelineId, data: null }
+    };
+    for (const prop of RENDER_NODE_PROPS) {
+        const value = params[prop];
+        if (value === undefined || value === null)
+            continue;
+        if (prop === "bitrate") {
+            const bitrate = parseBitrate(value);
+            if (bitrate !== undefined)
+                properties[prop] = bitrate;
+            continue;
+        }
+        properties[prop] = value;
+    }
+    const nodes = [
+        {
+            id: RENDER_NODE_ID,
+            type: "nodetool.timeline.RenderTimeline",
+            data: properties
+        },
+        {
+            id: RENDER_OUTPUT_NODE_ID,
+            type: "nodetool.output.Output",
+            data: { name: RENDER_OUTPUT_NAME }
+        }
+    ];
+    const edges = [
+        {
+            id: "render-to-output",
+            source: RENDER_NODE_ID,
+            sourceHandle: "output",
+            target: RENDER_OUTPUT_NODE_ID,
+            targetHandle: "value"
+        }
+    ];
+    // A png_sequence leaves the zip on the node's `frames` handle and an empty
+    // ref on `output`, so a graph wired to `output` alone comes back with
+    // nothing to open.
+    if (params["format"] === "png_sequence") {
+        nodes.push({
+            id: RENDER_FRAMES_OUTPUT_NODE_ID,
+            type: "nodetool.output.Output",
+            data: { name: RENDER_FRAMES_OUTPUT_NAME }
+        });
+        edges.push({
+            id: "render-to-frames-output",
+            source: RENDER_NODE_ID,
+            sourceHandle: "frames",
+            target: RENDER_FRAMES_OUTPUT_NODE_ID,
+            targetHandle: "value"
+        });
+    }
+    return { nodes, edges };
+}
+/**
+ * The ref a finished render left on the job row, wherever it sits — a video,
+ * or the zipped document a png_sequence renders to. A png_sequence leaves an
+ * empty ref on the video handle beside the zip, so a ref carrying an asset id
+ * wins over one that carries none.
+ */
+export function findRenderedVideo(outputs) {
+    const found = [];
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item);
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        if (value["type"] === "video" || value["type"] === "document") {
+            found.push(value);
+            return;
+        }
+        for (const nested of Object.values(value))
+            walk(nested);
+    };
+    walk(outputs);
+    return (found.find((ref) => (isString(ref["asset_id"]) && ref["asset_id"].length > 0) ||
+        (isString(ref["uri"]) && ref["uri"].length > 0)) ??
+        found[0] ??
+        null);
+}
+/** What a settled render reports beyond its job id. */
+export function renderResult(job) {
+    const metadata = job.metadata_json ?? {};
+    const video = findRenderedVideo(metadata["outputs"]);
+    const refMetadata = video && isRecord(video["metadata"]) ? video["metadata"] : {};
+    const duration = video ? Number(video["duration"]) : Number.NaN;
+    return {
+        status: job.status,
+        asset_id: video && isString(video["asset_id"]) ? video["asset_id"] : null,
+        uri: video && isString(video["uri"]) ? video["uri"] : null,
+        render_mode: isString(refMetadata["render_mode"])
+            ? refMetadata["render_mode"]
+            : null,
+        duration_ms: Number.isFinite(duration) ? Math.round(duration * 1000) : null,
+        job_error: job.error_message ?? job.error ?? null
+    };
+}
+/**
+ * How long a `wait: true` render blocks, and what to say when the caller asked
+ * for longer.
+ *
+ * A blocking call inside `execute_code` runs against the CodeAct action budget
+ * (`DEFAULT_CODEACT_ACTION_TIMEOUT_MS`, 600_000 in
+ * `codeact/codeact-executor.ts`). A wait at or near that number loses the race:
+ * the sandbox aborts the whole action first and the caller reads the sandbox's
+ * `Execution cancelled`, which names neither the render nor the job to come
+ * back to. `MAX_RENDER_TIMEOUT_MS` sits well below it so this capability always
+ * reports its own timeout — and says the wait was shortened, rather than
+ * silently waiting for a different number than the one that was asked for.
+ */
+export function renderWaitBudget(param) {
+    const requestedMs = numberParam(param) ?? DEFAULT_RENDER_TIMEOUT_MS;
+    const timeoutMs = Math.min(MAX_RENDER_TIMEOUT_MS, Math.max(RENDER_POLL_INTERVAL_MS, requestedMs));
+    const clampNote = requestedMs > MAX_RENDER_TIMEOUT_MS
+        ? `timeout_ms ${requestedMs} was clamped to ${MAX_RENDER_TIMEOUT_MS}, ` +
+            "the longest a blocking render can wait before the surrounding " +
+            "action budget kills the call. For a longer render, pass wait: false " +
+            "and poll get_job, or draft it with preview_scale below 1."
+        : null;
+    return { timeoutMs, clampNote };
+}
+/**
+ * Render a timeline sequence as a job (D12, docs/plans/motion-graphics.md).
+ *
+ * The run goes through the same execution service `run_workflow` uses, so the
+ * render gets the job row, the logs, the `node_progress` messages and cancel
+ * without a workflow being saved for it. Always detached: `wait` polls the job
+ * row rather than blocking the service call, so a render that outlives the
+ * caller's patience still hands back a `job_id` to come back to.
+ */
+const renderTimeline = {
+    spec: renderTimelineSpec,
+    impl: async (run, params) => {
+        const seq = await loadTimeline(run, params["timeline_id"]);
+        if (isError(seq))
+            return seq;
+        const { resolveRunEnvironment, userIdOf, noRegistryError } = await import("../tools/mcp-tool-support.js");
+        const environment = await resolveRunEnvironment(run.workflowEnvironment, run.nodeRegistry);
+        if (!environment)
+            return noRegistryError("render a timeline");
+        const { runWorkflow } = await import("@nodetool-ai/execution/service");
+        const userId = userIdOf(run.context);
+        const outcome = await runWorkflow({
+            workflowId: "",
+            userId,
+            environment,
+            graph: buildRenderTimelineGraph(seq.id, params),
+            jobName: `Render ${seq.name}`,
+            background: true,
+            projectId: run.projectId ?? null
+        });
+        if (outcome.kind !== "payload") {
+            return { error: outcome.detail, status: outcome.status };
+        }
+        const jobId = outcome.payload["job_id"];
+        if (!isString(jobId)) {
+            return { error: "The render started but reported no job id." };
+        }
+        const receipt = { job_id: jobId, timeline_id: seq.id };
+        const stillRunning = {
+            ...receipt,
+            status: "running",
+            poll: `Poll get_job with job_id "${jobId}" until it settles. get_job_logs ` +
+                "reports what the render is doing and cancel_job stops it."
+        };
+        if (params["wait"] !== true)
+            return stillRunning;
+        const { timeoutMs, clampNote } = renderWaitBudget(params["timeout_ms"]);
+        const { Job } = await import("@nodetool-ai/models");
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const job = await Job.find(userId, jobId);
+            if (job && job.status !== "running" && job.status !== "queued") {
+                return { ...receipt, ...renderResult(job) };
+            }
+            if (Date.now() >= deadline) {
+                return {
+                    ...stillRunning,
+                    timed_out: true,
+                    timeout_ms: timeoutMs,
+                    timeout_clamped: clampNote,
+                    note: `The render did not finish within ${timeoutMs}ms. It is still ` +
+                        "running — read it back with get_job." +
+                        (clampNote ? ` ${clampNote}` : "")
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, RENDER_POLL_INTERVAL_MS));
+        }
+    }
+};
+/** Every timeline capability, in the order the tool files declared them. */
+/**
+ * Delete a timeline sequence the caller owns.
+ *
+ * The ownership check and the version cascade are `TimelineSequence.deleteOwned`, the
+ * same function the tRPC route calls — a delete is not a place for two copies
+ * of one rule, and version rows outliving their document would be unreachable
+ * garbage. Missing and not-yours are one answer.
+ */
+// ---------------------------------------------------------------------------
+// bake_audio_animation
+// ---------------------------------------------------------------------------
+/** A number param, or the default when it is absent or not finite. */
+function numberOr(value, fallback) {
+    return isFiniteNumber(value) ? value : fallback;
+}
+/** The `[lo, hi]` a curve's values run between. */
+function outputRange(value) {
+    if (!Array.isArray(value) ||
+        value.length !== 2 ||
+        !isFiniteNumber(value[0]) ||
+        !isFiniteNumber(value[1])) {
+        return {
+            error: "output_range must be two numbers, [quiet, loud] — e.g. [1, 1.12] " +
+                "for scale, [0.6, 1] for opacity."
+        };
+    }
+    return [value[0], value[1]];
+}
+/** The clip a name, id or "selected" addresses, or a message naming the rest. */
+function findClip(clips, target, field) {
+    if (!isString(target) || target.trim() === "") {
+        return { error: `${field} is required (a clip id or name).` };
+    }
+    const lower = target.trim().toLowerCase();
+    const clip = clips.find((c) => c.id === target.trim()) ??
+        clips.find((c) => c.name.toLowerCase() === lower);
+    if (clip)
+        return clip;
+    const known = clips
+        .slice(0, 12)
+        .map((c) => `${c.id} ("${c.name}")`)
+        .join(", ");
+    return {
+        error: `No clip matching "${target}" for ${field}. Clips: ${known || "none"}.`
+    };
+}
+const bakeAudioAnimation = {
+    spec: bakeAudioAnimationSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        if (!isString(timelineId) || !timelineId) {
+            return {
+                error: "timeline_id is required (use list_timelines to find one)."
+            };
+        }
+        const property = params["property"];
+        if (!isString(property)) {
+            return { error: "property is required (scale, opacity, offsetX, offsetY)." };
+        }
+        const range = outputRange(params["output_range"]);
+        if (isError(range))
+            return range;
+        const mode = params["mode"] === "beats" ? "beats" : "envelope";
+        const attackMs = Math.max(0, numberOr(params["attack_ms"], DEFAULT_BAKE_ATTACK_MS));
+        const releaseMs = Math.max(0, numberOr(params["release_ms"], DEFAULT_BAKE_RELEASE_MS));
+        const offsetMs = numberOr(params["offset_ms"], 0);
+        const tolerance = Math.max(0, numberOr(params["tolerance"], DEFAULT_BAKE_TOLERANCE));
+        const maxPoints = Math.min(MAX_BAKE_POINTS, Math.max(2, Math.floor(numberOr(params["max_points"], DEFAULT_BAKE_MAX_POINTS))));
+        const maxSeconds = Math.max(1, numberOr(params["max_seconds"], DEFAULT_BAKE_MAX_SECONDS));
+        const frameMs = Math.max(1, numberOr(params["frame_ms"], 20));
+        const replace = params["replace"] !== false;
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const sequence = await TimelineSequence.findById(timelineId);
+        if (!sequence || sequence.user_id !== run.context.userId) {
+            return { error: `Timeline ${timelineId} was not found.` };
+        }
+        const document = sequence.toDocument();
+        const audioClip = findClip(document.clips, params["audio_clip_id"], "audio_clip_id");
+        if (isError(audioClip))
+            return audioClip;
+        const targetClip = findClip(document.clips, params["target_clip_id"], "target_clip_id");
+        if (isError(targetClip))
+            return targetClip;
+        // Both hops are affine only while neither clip's source position is a
+        // curve. A remap makes "which source ms plays here" normalized over the
+        // clip's own window, so there is no inverse to map an onset through.
+        for (const [clip, field] of [
+            [audioClip, "audio_clip_id"],
+            [targetClip, "target_clip_id"]
+        ]) {
+            if ((clip.timeRemap?.keyframes.length ?? 0) > 0) {
+                return {
+                    error: `Clip "${clip.name}" (${field}) carries a time remap, so its ` +
+                        "source position is a curve over its own window and an audio " +
+                        "time cannot be placed in it. Clear `timeRemap` with " +
+                        "set_time_remap, or bake the remap into the media first."
+                };
+            }
+        }
+        const assetId = audioClip.currentAssetId;
+        if (!isString(assetId) || !assetId) {
+            return {
+                error: `Clip "${audioClip.name}" has no asset to measure — it has not ` +
+                    "been generated or imported yet."
+            };
+        }
+        const [analyzeFromMs, analyzeToMs] = clipSourceWindowMs(audioClip);
+        const { loadMediaRefBytes } = await import("@nodetool-ai/runtime");
+        let bytes;
+        try {
+            bytes = await loadMediaRefBytes({ uri: `asset://${assetId}`, asset_id: assetId }, run.context);
+        }
+        catch (error) {
+            return {
+                error: `Could not read the audio of "${audioClip.name}": ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+        if (!bytes || bytes.byteLength === 0) {
+            return {
+                error: `The asset behind "${audioClip.name}" resolved to no bytes.`
+            };
+        }
+        const { analyzeAudioFrames } = await import("./analysis.js");
+        let envelope;
+        try {
+            envelope = await analyzeAudioFrames(bytes, {
+                fromMs: analyzeFromMs,
+                toMs: analyzeToMs,
+                frameMs,
+                maxSeconds,
+                detectTempo: false
+            });
+        }
+        catch (error) {
+            return {
+                error: `Could not analyze "${audioClip.name}": ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+        const analyzed = envelope.truncated
+            ? envelope.truncated.analyzed
+            : [analyzeFromMs, analyzeToMs];
+        const { beatCurve, envelopeCurve, mapAudioCurveToTarget } = await import("./timeline-audio-bake.js");
+        const measured = mode === "beats"
+            ? beatCurve(envelope.onsetsMs, {
+                attackMs,
+                releaseMs,
+                outputRange: range,
+                tolerance,
+                maxPoints,
+                windowMs: [analyzed[0], analyzed[1]]
+            })
+            : envelopeCurve(envelope.frames, {
+                attackMs,
+                releaseMs,
+                outputRange: range,
+                sensitivity: Math.max(0.01, numberOr(params["sensitivity"], 1)),
+                tolerance,
+                maxPoints
+            });
+        const keyframes = mapAudioCurveToTarget(measured, {
+            audioClip,
+            targetClip,
+            offsetMs
+        });
+        if (keyframes.length === 0) {
+            return {
+                error: `Nothing to write: the stretch of "${audioClip.name}" that was ` +
+                    `analyzed does not overlap "${targetClip.name}" on the timeline` +
+                    (offsetMs === 0 ? "." : ` after the ${offsetMs}ms offset.`)
+            };
+        }
+        const { records, state } = await applyOps(run, sequence, document, [
+            {
+                op: `${TOOL_PREFIX}set_baked_animation`,
+                input: {
+                    target: targetClip.id,
+                    animation: {
+                        property,
+                        keyframes,
+                        timeBase: "source",
+                        replace,
+                        bakedFrom: {
+                            kind: AUDIO_BAKED_ANIMATION_KIND,
+                            clipId: audioClip.id,
+                            assetId,
+                            settings: {
+                                mode,
+                                attackMs,
+                                releaseMs,
+                                offsetMs,
+                                tolerance,
+                                maxPoints,
+                                frameMs,
+                                sensitivity: Math.max(0.01, numberOr(params["sensitivity"], 1)),
+                                outputLow: range[0],
+                                outputHigh: range[1]
+                            }
+                        }
+                    }
+                }
+            }
+        ]);
+        const record = records[0];
+        if (!record || !record.ok) {
+            return { error: record?.error ?? "The bake wrote nothing." };
+        }
+        const next = {
+            ...document,
+            tracks: state.documentTracks,
+            clips: state.documentClips,
+            markers: state.markers
+        };
+        const saved = await TimelineSequence.updateDocumentIfUnchanged(sequence.id, sequence.updated_at, next, {
+            ops: [
+                {
+                    tool: `${TOOL_PREFIX}set_baked_animation`,
+                    input: { id: targetClip.id, target: targetClip.id }
+                }
+            ]
+        });
+        if (!saved) {
+            return {
+                error: `Timeline ${timelineId} is being modified concurrently; nothing was saved. Retry the call.`
+            };
+        }
+        const result = isRecord(record.result) ? record.result : {};
+        return {
+            timeline_id: timelineId,
+            updated_at: saved.updated_at,
+            clip_id: targetClip.id,
+            property,
+            mode,
+            animationId: result["animationId"],
+            keyframeCount: keyframes.length,
+            analyzed: { fromMs: analyzed[0], toMs: analyzed[1] },
+            truncated: envelope.truncated !== null,
+            replaced: result["replaced"] === true
+        };
+    }
+};
+// ---------------------------------------------------------------------------
+// isolate_subject
+// ---------------------------------------------------------------------------
+/** One of `allowed`, or the default when the caller named none of them. */
+function enumOr(value, allowed, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (isString(value) && allowed.includes(value))
+        return value;
+    return {
+        error: `"${String(value)}" is not one of: ${allowed.join(", ")}.`
+    };
+}
+/**
+ * Cut the subject out of a clip's own source and carry the mask on that clip.
+ *
+ * The document work is `isolateSubjectOnClip`; everything here is the wiring
+ * it refuses to know about — the sequence row, the CAS save, the node registry
+ * the provider call needs, and the background receipt. The save closure
+ * carries `updated_at` forward, so the in-flight write and the settled write
+ * are two CAS updates rather than one lost one.
+ */
+const isolateSubject = {
+    spec: isolateSubjectSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        if (!isString(timelineId) || !timelineId) {
+            return {
+                error: "timeline_id is required (use list_timelines to find one)."
+            };
+        }
+        const registry = run.nodeRegistry;
+        if (!registry) {
+            const { noRegistryError } = await import("../tools/mcp-tool-support.js");
+            return noRegistryError("isolate a subject");
+        }
+        const model = enumOr(params["model"], ISOLATE_SUBJECT_MODELS, DEFAULT_ISOLATE_SUBJECT_MODEL);
+        if (isError(model))
+            return model;
+        const resolution = enumOr(params["operating_resolution"], ISOLATE_SUBJECT_RESOLUTIONS, DEFAULT_ISOLATE_SUBJECT_RESOLUTION);
+        if (isError(resolution))
+            return resolution;
+        const settings = {
+            model,
+            operating_resolution: resolution,
+            refine_foreground: params["refine_foreground"] !== false
+        };
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const sequence = await TimelineSequence.findById(timelineId);
+        if (!sequence || sequence.user_id !== run.context.userId) {
+            return { error: `Timeline ${timelineId} was not found.` };
+        }
+        const document = sequence.toDocument();
+        const clip = findClip(document.clips, params["clip_id"], "clip_id");
+        if (isError(clip))
+            return clip;
+        // The asset row is the only statement of how long the source runs; a row
+        // without one falls back to the clip's own window inside the state
+        // machine, which is still an interval the generation covered.
+        let sourceDurationMs;
+        const userId = run.context.userId;
+        if (isString(clip.currentAssetId) && clip.currentAssetId && userId) {
+            const { Asset } = await import("@nodetool-ai/models");
+            const asset = await Asset.find(userId, clip.currentAssetId);
+            if (asset && isFiniteNumber(asset.duration) && asset.duration > 0) {
+                sourceDurationMs = Math.round(asset.duration * 1000);
+            }
+        }
+        const { contextMaskStore, falIsolateSubjectRunner, isolateSubjectOnClip } = await import("./timeline-isolate-subject.js");
+        const { randomUUID } = await import("node:crypto");
+        const generationId = randomUUID();
+        let expectedUpdatedAt = sequence.updated_at;
+        const persist = async (next) => {
+            const clips = document.clips.map((c) => (c.id === next.id ? next : c));
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(timelineId, expectedUpdatedAt, { ...document, clips }, {
+                ops: [
+                    {
+                        tool: `${TOOL_PREFIX}set_generated_matte`,
+                        input: { id: next.id, target: next.id }
+                    }
+                ]
+            });
+            if (!saved)
+                return false;
+            document.clips = clips;
+            expectedUpdatedAt = saved.updated_at;
+            return true;
+        };
+        const deps = {
+            runner: falIsolateSubjectRunner(run.context, registry, generationId),
+            storeMask: contextMaskStore(run.context),
+            persist
+        };
+        const input = {
+            clip,
+            settings,
+            regenerate: params["regenerate"] === true
+        };
+        if (sourceDurationMs !== undefined) {
+            input.sourceDurationMs = sourceDurationMs;
+        }
+        if (params["background"] === true) {
+            const { startBackgroundGeneration, backgroundGenerationLimitError } = await import("./background-generation.js");
+            const started = startBackgroundGeneration(run.context, () => isolateSubjectOnClip(deps, input));
+            if (!started)
+                return backgroundGenerationLimitError();
+            return {
+                timeline_id: timelineId,
+                clip_id: clip.id,
+                generation_id: generationId,
+                // The clip's own matte status, which is what the caller reads back —
+                // the generation row carries `running` for `await_generation`.
+                status: "generating",
+                background: true,
+                next: "Call await_generation with this generation_id, or read the clip " +
+                    "back with get_timeline once it settles."
+            };
+        }
+        const settled = await isolateSubjectOnClip(deps, input);
+        // A refusal carries only `error`; an outcome always carries `status`,
+        // including the failed one that kept the previous matte.
+        if (!("status" in settled))
+            return settled;
+        const result = {
+            timeline_id: timelineId,
+            clip_id: clip.id,
+            status: settled.status,
+            source_range: settled.sourceRange,
+            reused: settled.reused
+        };
+        if (settled.assetId !== undefined)
+            result["asset_id"] = settled.assetId;
+        if (settled.generationId !== undefined) {
+            result["generation_id"] = settled.generationId;
+        }
+        if (settled.costUsd !== undefined)
+            result["cost_usd"] = settled.costUsd;
+        if (settled.error !== undefined)
+            result["error"] = settled.error;
+        return result;
+    }
+};
+// ---------------------------------------------------------------------------
+// track_object
+// ---------------------------------------------------------------------------
+/**
+ * Follow a subject through a clip's source. The document work is
+ * `trackObjectOnDocument`; everything here is the wiring it refuses to know
+ * about: the sequence row, provider selection and the CAS save.
+ */
+const trackObject = {
+    spec: trackObjectSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        if (!isString(timelineId) || !timelineId) {
+            return {
+                error: "timeline_id is required (use list_timelines to find one)."
+            };
+        }
+        const region = params["initial_region"];
+        if (!isRecord(region)) {
+            return { error: "initial_region is required: {x, y, width, height}." };
+        }
+        const regionFields = ["x", "y", "width", "height"];
+        for (const field of regionFields) {
+            if (!isFiniteNumber(region[field])) {
+                return { error: `initial_region.${field} must be a number.` };
+            }
+        }
+        const startMs = params["start_ms"];
+        const endMs = params["end_ms"];
+        if (!isFiniteNumber(startMs) || !isFiniteNumber(endMs)) {
+            return { error: "start_ms and end_ms are required numbers." };
+        }
+        const directionRaw = params["direction"];
+        const direction = isString(directionRaw) &&
+            TRACK_OBJECT_DIRECTIONS.includes(directionRaw)
+            ? directionRaw
+            : "forward";
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const sequence = await TimelineSequence.findById(timelineId);
+        if (!sequence || sequence.user_id !== run.context.userId) {
+            return { error: `Timeline ${timelineId} was not found.` };
+        }
+        const document = sequence.toDocument();
+        const clip = findClip(document.clips, params["clip_id"], "clip_id");
+        if (isError(clip))
+            return clip;
+        const { randomUUID } = await import("node:crypto");
+        const trackId = isString(params["track_id"])
+            ? params["track_id"]
+            : `track_${randomUUID()}`;
+        const name = isString(params["name"]) ? params["name"] : "Tracked subject";
+        let expectedUpdatedAt = sequence.updated_at;
+        let mediaTracks = document.mediaTracks ?? [];
+        const persist = async (next) => {
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(timelineId, expectedUpdatedAt, { ...document, mediaTracks: next }, { ops: [{ tool: "track_object", input: { clip_id: clip.id, track_id: trackId } }] });
+            if (!saved)
+                return false;
+            mediaTracks = next;
+            expectedUpdatedAt = saved.updated_at;
+            return true;
+        };
+        const { contextTrackObjectRunner, trackObjectOnDocument } = await import("./timeline-track-object.js");
+        const runner = await contextTrackObjectRunner(run.context, isString(params["provider"]) ? params["provider"] : undefined, isString(params["model"]) ? params["model"] : undefined);
+        const input = {
+            clip,
+            mediaTracks,
+            name,
+            initialRegion: {
+                x: region["x"],
+                y: region["y"],
+                width: region["width"],
+                height: region["height"]
+            },
+            startMs,
+            endMs,
+            direction,
+            regenerate: params["regenerate"] === true,
+            trackId
+        };
+        const settled = await trackObjectOnDocument({ runner, persist }, input);
+        if (!("status" in settled))
+            return settled;
+        const result = {
+            timeline_id: timelineId,
+            clip_id: clip.id,
+            track_id: settled.track.id,
+            status: settled.status,
+            reused: settled.reused
+        };
+        if (settled.generationId !== undefined) {
+            result["generation_id"] = settled.generationId;
+        }
+        if (settled.costUsd !== undefined)
+            result["cost_usd"] = settled.costUsd;
+        if (settled.error !== undefined)
+            result["error"] = settled.error;
+        return result;
+    }
+};
+/**
+ * The report shape `get_timeline_code`, `set_timeline_code`, `edit_timeline_code`
+ * and `rebake_timeline_code` all answer for `scenes`: `edited` means "kept
+ * as-is rather than reflecting the code" — either the code has never been
+ * baked into a current merge (`get`), or this call's own merge kept it as a
+ * conflict (`set`/`edit`/`rebake`).
+ */
+function sceneReport(scenes, editedNames) {
+    return Object.entries(scenes).map(([name, recorded]) => ({
+        name,
+        group_id: recorded.groupId,
+        edited: editedNames.has(name)
+    }));
+}
+/** `force` is a boolean or an array of scene names; anything else is refused. */
+function normalizeForceOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === true)
+        return true;
+    if (value === false)
+        return undefined;
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value;
+    }
+    return { error: "force must be a boolean or an array of scene names." };
+}
+/**
+ * Validate, snapshot, and CAS-write a document the way `set_timeline_document`
+ * does (see its own docstring for why each step is there): validate first so
+ * a document that would not render never reaches the database, snapshot the
+ * state being replaced so the write is undoable, then a CAS write so a
+ * concurrent edit is reported rather than clobbered.
+ */
+export async function writeTimelineCodeDocument(sequence, document, snapshotName) {
+    const { validateTimelineSequence } = await import("@nodetool-ai/execution/timeline-debug");
+    const before = validateTimelineSequence(document, { fps: sequence.fps, width: sequence.width, height: sequence.height });
+    const errors = before.errors.map((issue) => issue.message);
+    const warnings = before.warnings.map((issue) => issue.message);
+    if (!before.ok) {
+        return {
+            written: false,
+            error: `The baked document has ${before.errors.length} error${before.errors.length === 1 ? "" : "s"} and was not written to timeline ${sequence.id}.`,
+            errors,
+            warnings
+        };
+    }
+    const { TimelineSequence: TimelineSequenceModel, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+    await TimelineSequenceVersion.snapshot(sequence, {
+        saveType: "manual",
+        name: snapshotName
+    });
+    const saved = await TimelineSequenceModel.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, {
+        document: JSON.stringify(document),
+        duration_ms: documentDurationMs(document)
+    });
+    if (!saved) {
+        return {
+            written: false,
+            error: `Timeline ${sequence.id} was modified concurrently; nothing was written. Read it again and try again.`,
+            errors,
+            warnings
+        };
+    }
+    return { written: true, timeline_id: saved.id, errors, warnings };
+}
+/**
+ * Bake `code`, merge the result into `sequence`'s current document (see
+ * `mergeTimelineSource` in `@nodetool-ai/timeline` for the merge rule), and
+ * write it through the same path `set_timeline_document` uses. Shared by
+ * `set_timeline_code`, `edit_timeline_code` and `rebake_timeline_code` — they
+ * differ only in where `code` comes from.
+ */
+async function bakeAndMergeTimelineCode(run, sequence, code, force) {
+    const current = sequence.toDocument();
+    const baked = await bakeTimelineCode(run.context, code);
+    if (!baked.ok || !baked.document) {
+        return {
+            timeline_id: sequence.id,
+            errors: [baked.error ?? "The code failed to build a document."],
+            warnings: [],
+            conflicts: [],
+            scenes: []
+        };
+    }
+    const previousScenes = current.source?.scenes ?? {};
+    const merged = mergeTimelineSource(current, baked.document, previousScenes, force !== undefined ? { force } : {});
+    const mergedWithSource = {
+        ...merged.document,
+        source: {
+            lang: "js",
+            code,
+            bakedAt: new Date().toISOString(),
+            scenes: merged.scenes
+        }
+    };
+    const editedNames = new Set(merged.conflicts.map((c) => c.scene));
+    const scenes = sceneReport(merged.scenes, editedNames);
+    const write = await writeTimelineCodeDocument(sequence, mergedWithSource, "Before writing timeline code");
+    if (!write.written) {
+        return {
+            timeline_id: sequence.id,
+            errors: [write.error, ...write.errors],
+            warnings: write.warnings,
+            conflicts: merged.conflicts,
+            scenes
+        };
+    }
+    return {
+        timeline_id: write.timeline_id,
+        errors: write.errors,
+        warnings: write.warnings,
+        conflicts: merged.conflicts,
+        scenes
+    };
+}
+/**
+ * Attach `code` as `sequence`'s authoring source only when a hermetic bake
+ * of it gives exactly the document that is saved now. This is
+ * `set_timeline_code` with `require_match: true`, which `v.save()` calls
+ * with the retained program it printed (docs/timeline-code-capture.md).
+ *
+ * A mismatch writes nothing and returns a warning. The document stays as it
+ * was saved, only without code, because code that does not rebuild it would
+ * make a later rebake diverge from what the timeline shows.
+ */
+async function attachMatchingTimelineCode(run, sequence, code) {
+    const current = sequence.toDocument();
+    const notEmbedded = (warning) => ({
+        timeline_id: sequence.id,
+        embedded: false,
+        errors: [],
+        warnings: [warning],
+        conflicts: [],
+        scenes: []
+    });
+    const baked = await bakeTimelineCode(run.context, code);
+    if (!baked.ok || !baked.document) {
+        return notEmbedded(`Code not embedded: the retained program failed to rebake (${baked.error ?? "unknown error"}).`);
+    }
+    if (!bakedDocumentMatchesSaved(current, baked.document)) {
+        return notEmbedded("Code not embedded: the retained program rebakes to a different " +
+            "timeline than the one saved. A scene clip probably changed after " +
+            "v.series(), or a value came from Math.random() or Date.now().");
+    }
+    // Every scene is new here: the saved document was just written from this
+    // same run, so there are no hand edits to keep.
+    const merged = mergeTimelineSource(current, baked.document, {}, { force: true });
+    const write = await writeTimelineCodeDocument(sequence, {
+        ...merged.document,
+        source: {
+            lang: "js",
+            code,
+            bakedAt: new Date().toISOString(),
+            scenes: merged.scenes
+        }
+    }, "Attach authoring code");
+    if (!write.written) {
+        return notEmbedded(`Code not embedded: ${write.error}`);
+    }
+    return {
+        timeline_id: write.timeline_id,
+        embedded: true,
+        errors: write.errors,
+        warnings: write.warnings,
+        conflicts: [],
+        scenes: sceneReport(merged.scenes, new Set())
+    };
+}
+const getTimelineCode = {
+    spec: getTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const doc = sequence.toDocument();
+        const source = doc.source;
+        if (!source)
+            return { code: null, baked_at: null, scenes: [] };
+        const groupIdByScene = new Map();
+        for (const clip of doc.clips) {
+            if (typeof clip.sourceScene === "string" && clip.sourceScene) {
+                groupIdByScene.set(clip.sourceScene, clip.id);
+            }
+        }
+        const editedNames = new Set();
+        for (const [name, recorded] of Object.entries(source.scenes)) {
+            const groupId = groupIdByScene.get(name);
+            const edited = groupId === undefined ||
+                hashSceneSubtree(doc.clips, groupId) !== recorded.hash;
+            if (edited)
+                editedNames.add(name);
+        }
+        return {
+            code: source.code,
+            baked_at: source.bakedAt,
+            scenes: sceneReport(source.scenes, editedNames)
+        };
+    }
+};
+const setTimelineCode = {
+    spec: setTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const code = params["code"];
+        if (!isString(code) || !code.trim()) {
+            return { error: "code is required and must be a non-empty script." };
+        }
+        if (params["require_match"] === true) {
+            return attachMatchingTimelineCode(run, sequence, code);
+        }
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, code, force);
+    }
+};
+const editTimelineCode = {
+    spec: editTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const source = sequence.toDocument().source;
+        if (!source) {
+            return {
+                error: `Timeline ${sequence.id} has no authoring code to edit. Call set_timeline_code first.`
+            };
+        }
+        const ops = parseJsScriptEditOps(params["edits"]);
+        if (isError(ops))
+            return ops;
+        const applied = applyJsScriptEditOps(source.code, ops);
+        if (isError(applied))
+            return applied;
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, applied.code, force);
+    }
+};
+const rebakeTimelineCode = {
+    spec: rebakeTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const source = sequence.toDocument().source;
+        if (!source) {
+            return { error: `Timeline ${sequence.id} has no authoring code to rebake.` };
+        }
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, source.code, force);
+    }
+};
+const detachTimelineCode = {
+    spec: detachTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const current = sequence.toDocument();
+        const source = current.source;
+        if (!source)
+            return { scenes: [] };
+        const scenesParam = params["scenes"];
+        // "all" drops the code entirely — there is nothing left to track, and
+        // nothing left worth rebaking. Naming every currently-tracked scene one
+        // by one is a different request: those scenes stop being tracked, but
+        // the code stays, so a later edit that reintroduces a scene (or adds a
+        // new one) still has somewhere to bake into.
+        const dropCode = scenesParam === "all";
+        let detachedNames;
+        if (dropCode) {
+            detachedNames = Object.keys(source.scenes);
+        }
+        else if (Array.isArray(scenesParam) &&
+            scenesParam.length > 0 &&
+            scenesParam.every((s) => typeof s === "string")) {
+            detachedNames = scenesParam.filter((name) => name in source.scenes);
+        }
+        else {
+            return {
+                error: 'scenes must be "all" or a non-empty array of scene names.'
+            };
+        }
+        if (detachedNames.length === 0)
+            return { scenes: [] };
+        const remaining = { ...source.scenes };
+        for (const name of detachedNames)
+            delete remaining[name];
+        const nextDocument = { ...current };
+        if (dropCode) {
+            delete nextDocument["source"];
+        }
+        else {
+            nextDocument["source"] = { ...source, scenes: remaining };
+        }
+        const { TimelineSequence: TimelineSequenceModel, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        await TimelineSequenceVersion.snapshot(sequence, {
+            saveType: "manual",
+            name: "Before detaching timeline code"
+        });
+        const saved = await TimelineSequenceModel.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, { document: JSON.stringify(nextDocument) });
+        if (!saved) {
+            return {
+                error: `Timeline ${sequence.id} was modified concurrently; nothing was written. Try again.`
+            };
+        }
+        return { timeline_id: saved.id, scenes: detachedNames };
+    }
+};
+const deleteTimeline = {
+    spec: deleteTimelineSpec,
+    impl: async (run, params) => {
+        const userId = run.context.userId;
+        if (!userId)
+            return { error: "No user is bound to this session." };
+        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const id = String(params["timeline_id"]);
+        const deleted = await TimelineSequence.deleteOwned(userId, id);
+        return deleted
+            ? { timeline_id: id, deleted: true }
+            : { error: `Timeline sequence ${id} was not found, or it is not yours.` };
+    }
+};
+export const TIMELINE_CAPABILITIES = [
+    listTimelines,
+    createTimeline,
+    getTimeline,
+    listTimelineVersions,
+    getTimelineVersion,
+    createTimelineVersion,
+    restoreTimelineVersion,
+    deleteTimelineVersion,
+    editTimeline,
+    validateTimeline,
+    setTimelineDocument,
+    previewTimelineFrame,
+    compareTimelineFrames,
+    renderTimeline,
+    bakeAudioAnimation,
+    isolateSubject,
+    trackObject,
+    ...TIMELINE_NATIVE_MEDIA_CAPABILITIES,
+    getTimelineCode,
+    setTimelineCode,
+    editTimelineCode,
+    rebakeTimelineCode,
+    detachTimelineCode,
+    deleteTimeline
+];
+export const module = {
+    module: "timelines",
+    exports: TIMELINE_CAPABILITIES
+};
+export { listTimelines, createTimeline, getTimeline, listTimelineVersions, getTimelineVersion, createTimelineVersion, restoreTimelineVersion, deleteTimelineVersion, editTimeline, validateTimeline, setTimelineDocument, previewTimelineFrame, compareTimelineFrames, renderTimeline, bakeAudioAnimation, isolateSubject, trackObject, getTimelineCode, setTimelineCode, editTimelineCode, rebakeTimelineCode, detachTimelineCode, deleteTimeline };
+//# sourceMappingURL=timelines.js.map