@nodetool-ai/agents 0.8.1 → 0.8.3

package/dist/capabilities/timelines.js

@@ -17,8 +17,12 @@
  *
  * Design: docs/tool-class-retirement-design.md § "Migration".
  */
-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, deleteTimelineSpec } from "./timelines.specs.js";
-import { AUDIO_BAKED_ANIMATION_KIND, normalizeAuthoredDocument } from "@nodetool-ai/timeline";
+import { parseOps, applyOps, TOOL_PREFIX, READ_ONLY_OPS, timelineModel3DBaker } from "./timeline-operations.js";
+export { parseOps, applyOps } from "./timeline-operations.js";
+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";
@@ -193,7 +197,7 @@ const getTimeline = {
         const seq = await loadTimeline(run, params["timeline_id"]);
         if (isError(seq))
             return seq;
-        return { timeline: seq.toTimelineSequence() };
+        return { timeline: seq.toTimelineSequence(), revision: seq.revision };
     }
 };
 const listTimelineVersions = {
@@ -364,266 +368,6 @@ const deleteTimelineVersion = {
 // ---------------------------------------------------------------------------
 /** 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_";
-/**
- * Tools the browser bridge exposes that this capability cannot run safely.
- *
- * `edit_timeline` persists document mutations but has no durable media-edit
- * generation adapter or callback path. Exposing generative editing here would
- * require it to invent an asset id, so it remains browser-only until a server
- * generation runner can create and attach the candidate take. `apply_take`
- * stays available because it only promotes an existing candidate.
- */
-const EXCLUDED_OPS = new Set([
-    `${TOOL_PREFIX}get_clip_frames`,
-    `${TOOL_PREFIX}generate_clip`,
-    `${TOOL_PREFIX}generatively_edit_clip`
-]);
-/** `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. */
-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;
-}
-/**
- * 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.
- */
-async function applyOps(run, sequence, document, ops) {
-    const { createTimelineToolBridge } = await import("../evals/surfaces/timeline.js");
-    const bridge = createTimelineToolBridge({
-        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),
-        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 };
-        },
-        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) : [])
-                ];
-            }
-        }
-    });
-    const byName = new Map(bridge.tools
-        .filter((tool) => !EXCLUDED_OPS.has(tool.name))
-        .map((tool) => [tool.name, tool]));
-    const records = [];
-    for (const { op, input } of ops) {
-        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.
  *
@@ -741,7 +485,12 @@ const editTimeline = {
                     "the returned timeline id."
             };
         }
-        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const { TimelineSequence, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const { timelineMediaEditGenerator } = await import("./timeline-media-edit.js");
+        const generateMediaEdit = timelineMediaEditGenerator(run);
+        // Shared across retries, like the media edit generator: a retry re-applies
+        // every op, and a 3D bake already rendered must not render again.
+        const bakeModel3DClip = timelineModel3DBaker(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
@@ -750,7 +499,7 @@ const editTimeline = {
                 return { error: `Timeline ${timelineId} was not found.` };
             }
             const document = sequence.toDocument();
-            const { records, state } = await applyOps(run, sequence, document, ops);
+            const { records, state } = await applyOps(run, sequence, document, ops, { generateMediaEdit, bakeModel3DClip });
             // 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.
@@ -784,12 +533,12 @@ const editTimeline = {
             // hand an open editor a merge with nothing in it.
             const appliedOps = ops
                 .map((parsed, index) => ({ parsed, index }))
-                .filter(({ index }) => records[index]?.ok);
+                .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: 0,
+                    applied: records.filter((record) => record.ok).length,
                     failed: failed.length,
                     ops: records,
                     tracks: state.tracks,
@@ -826,15 +575,23 @@ const editTimeline = {
                     }))
                 };
             }
+            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)
+            if (!saved) {
+                await undo?.delete();
                 continue;
-            return {
+            }
+            const response = {
                 timeline_id: timelineId,
                 updated_at: saved.updated_at,
                 applied: records.length - failed.length,
@@ -851,6 +608,10 @@ const editTimeline = {
                     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.`
@@ -978,7 +739,11 @@ const validateTimeline = {
  * whole-document write is that what was sent is what the sequence becomes.
  */
 function documentToStore(raw) {
-    return normalizeAuthoredDocument(raw);
+    const { name, id: _id, projectId: _projectId, workflowId: _workflowId, durationMs: _durationMs, createdAt: _createdAt, updatedAt: _updatedAt, ...document } = raw;
+    return {
+        ...normalizeAuthoredDocument(document),
+        name: isString(name) && name.trim() ? name.trim() : undefined
+    };
 }
 /** The end of the last clip — what the sequence's stored duration means. */
 function documentDurationMs(document) {
@@ -1045,7 +810,11 @@ const setTimelineDocument = {
                 };
             }
         }
-        const { document, settings } = documentToStore(raw);
+        // `get_timeline` returns the sequence row's fields beside the document.
+        // A caller that sends that object back renames the sequence with `name`.
+        // The other row fields are owned by the row, so they are dropped rather
+        // than reported as stripped document fields.
+        const { document, settings, name } = 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.
@@ -1081,16 +850,19 @@ const setTimelineDocument = {
             saveType: "manual",
             name: snapshotName
         });
-        const durationMs = documentDurationMs(document);
+        const fields = {
+            document: JSON.stringify(document),
+            fps,
+            width,
+            height,
+            duration_ms: documentDurationMs(document)
+        };
+        if (name !== undefined) {
+            fields.name = name;
+        }
         let saved;
         try {
-            saved = await TimelineSequence.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, {
-                document: JSON.stringify(document),
-                fps,
-                width,
-                height,
-                duration_ms: durationMs
-            });
+            saved = await TimelineSequence.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, fields);
         }
         catch (error) {
             // The model rejects a document without tracks/clips/markers arrays. The
@@ -1117,6 +889,7 @@ const setTimelineDocument = {
             ok: true,
             written: true,
             timeline_id: saved.id,
+            name: saved.name,
             updated_at: saved.updated_at,
             undo_version: undo.version,
             fps: saved.fps,
@@ -1333,6 +1106,7 @@ const previewTimelineFrame = {
                 mime: "image/png"
             });
             sheet = {
+                complete: result.complete,
                 columns: tiled.columns,
                 rows: tiled.rows,
                 cells: tiled.cells,
@@ -1346,12 +1120,15 @@ const previewTimelineFrame = {
         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
+                degraded: frame.degraded,
+                degradations: frame.degraded
             };
             if (!wantSheet) {
                 const saved = await persistOutput(run.context, frame.png, {
@@ -1363,6 +1140,8 @@ const previewTimelineFrame = {
             frames.push(entry);
         }
         return {
+            complete: result.complete,
+            visual_output_verified: false,
             timeline_id: isString(timelineId) ? timelineId : undefined,
             name,
             fps: meta.fps,
@@ -1372,12 +1151,15 @@ const previewTimelineFrame = {
             frames,
             sheet,
             effects_not_applied: result.effectsNotApplied,
-            hint: wantSheet
+            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."
+                    "listed top of the stack first — the first one covers the rest.")
         };
     }
 };
@@ -1510,10 +1292,15 @@ const compareTimelineFrames = {
         const frames = [];
         const cells = [];
         for (let i = 0; i < times.length; i++) {
-            const difference = Number((await frameDifference(left.frames[i].png, right.frames[i].png)).toFixed(4));
-            frames.push({ time_ms: times[i], difference });
+            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.toFixed(3)}`,
+                label: `${times[i]}ms  ${difference === null ? "incomplete" : difference.toFixed(3)}`,
                 png: await sideBySide(left.frames[i].png, right.frames[i].png)
             });
         }
@@ -1522,16 +1309,20 @@ const compareTimelineFrames = {
             namePrefix: "timeline-compare",
             mime: "image/png"
         });
-        const differences = frames.map((frame) => frame.difference);
-        const changed = frames.filter((frame) => frame.difference > 0);
+        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: changed.map((frame) => frame.time_ms),
-            max_difference: Math.max(...differences),
-            mean_difference: Number((differences.reduce((sum, d) => sum + d, 0) / differences.length).toFixed(4)),
+            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,
@@ -1542,7 +1333,11 @@ const compareTimelineFrames = {
             effects_not_applied: [
                 ...new Set([...left.effectsNotApplied, ...right.effectsNotApplied])
             ].sort(),
-            hint: "difference is the mean absolute RGB difference, 0 (identical) to 1. " +
+            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."
         };
@@ -2116,7 +1911,7 @@ const isolateSubject = {
         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 }, {
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(sequence.id, expectedUpdatedAt, { ...document, clips }, {
                 ops: [
                     {
                         tool: `${TOOL_PREFIX}set_generated_matte`,
@@ -2238,7 +2033,7 @@ const trackObject = {
         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 } }] });
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(sequence.id, expectedUpdatedAt, { ...document, mediaTracks: next }, { ops: [{ tool: "track_object", input: { clip_id: clip.id, track_id: trackId } }] });
             if (!saved)
                 return false;
             mediaTracks = next;
@@ -2283,6 +2078,322 @@ const trackObject = {
         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) => {
@@ -2316,11 +2427,16 @@ export const TIMELINE_CAPABILITIES = [
     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, deleteTimeline };
+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