@nodetool-ai/agents 0.8.1 → 0.8.2

package/dist/capabilities/storyboards.js

@@ -1,3 +1,4 @@
+import { finishStoryboard, layoutStoryboard, previewStoryboardDesign } from "./finish-storyboard.js";
 /**
  * The `storyboards` capability module.
  *
@@ -15,10 +16,15 @@
  *
  * Design: docs/tool-class-retirement-design.md § "Migration".
  */
-import { mp4DurationSeconds } from "@nodetool-ai/runtime";
+import { z } from "zod";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { mp4DurationSeconds, withSpan } from "@nodetool-ai/runtime";
+import { storyboardMotionDesign, storyboardShotGraphics } from "@nodetool-ai/protocol/api-schemas/storyboards.js";
+import { assertProductionGenerationAllowed, isFullResourceId, isShortResourceId, productionRequirement } from "@nodetool-ai/protocol";
 import { stampScriptStoryboardId } from "./script-link.js";
 import { listStoryboardsSpec, createStoryboardSpec, getStoryboardSpec, renderStoryboardStillsSpec, renderStoryboardClipsSpec, reviseStoryboardClipSpec, assembleStoryboardTimelineSpec, editStoryboardSpec, directStoryboardSpec, extractScriptFromStoryboardSpec, deleteStoryboardSpec } from "./storyboards.specs.js";
-import { clampConcurrency, mapWithConcurrency } from "./concurrency.js";
+import { measureStoryboardSources } from "./storyboard-measured-sources.js";
+import { clampConcurrency } from "./concurrency.js";
 import { isNonBlankString, isNumber, isRecord, isString } from "../utils/type-guards.js";
 import { resolveProjectId } from "./project-scope.js";
 /** Shots one call may render, so a stray `targets: "all"` cannot bankrupt a run. */
@@ -323,7 +329,8 @@ const listStoryboards = {
                     with_keyframe: doc.shots.filter((s) => !!s.keyframe).length,
                     with_clip: doc.shots.filter((s) => !!s.clip).length,
                     timeline_id: row.timeline_id ?? undefined,
-                    updated_at: row.updated_at
+                    updated_at: row.updated_at,
+                    revision: row.revision
                 };
             })
         };
@@ -342,7 +349,8 @@ function createdBoardSummary(row) {
         name: row.name,
         project_id: row.project_id,
         shots: doc.shots.length,
-        updated_at: row.updated_at
+        updated_at: row.updated_at,
+        revision: row.revision
     };
 }
 const createStoryboard = {
@@ -408,6 +416,7 @@ const getStoryboard = {
         const drifted = new Set(link.drifted_shot_ids);
         return {
             id: row.id,
+            revision: row.revision,
             name: row.name,
             brief: doc.brief,
             style: doc.style,
@@ -418,6 +427,7 @@ const getStoryboard = {
             timeline_id: row.timeline_id ?? undefined,
             narration: doc.screenplay?.narration ?? undefined,
             music_prompt: doc.screenplay?.music_prompt ?? undefined,
+            motion_design: doc.screenplay?.motion_design ?? null,
             script_id: link.script_id,
             script_link: link,
             shots: [...doc.shots]
@@ -429,6 +439,8 @@ const getStoryboard = {
                 action: shot.action,
                 camera: shot.camera,
                 motion: shot.motion,
+                graphics: shot.graphics,
+                production: shot.production,
                 duration_seconds: shot.duration_seconds,
                 status: shot.status,
                 has_keyframe: !!shot.keyframe,
@@ -531,6 +543,71 @@ async function filterStale(selected, params, doc, entities, kind) {
             .map((shot) => shot.id)
     };
 }
+function modelOverrides(params) {
+    const options = {};
+    if (isNonBlankString(params["provider"])) {
+        options.provider = params["provider"];
+    }
+    if (isNonBlankString(params["model"])) {
+        options.model = params["model"];
+    }
+    return options;
+}
+function missingPlanModel(plan) {
+    if (plan.model.provider && plan.model.model) {
+        return undefined;
+    }
+    return {
+        error: `No ${plan.kind === "keyframe" ? "still" : "clip"} model is set for shot ${plan.shotId}. Pass provider + model (use find_model), or set one on the shot or board.`
+    };
+}
+async function clipModelError(context, plans) {
+    const groups = new Map();
+    for (const plan of plans) {
+        const error = missingPlanModel(plan);
+        if (error) {
+            return error;
+        }
+        if (plan.preflightError) {
+            continue;
+        }
+        const key = JSON.stringify([plan.model.provider, plan.model.model]);
+        const group = groups.get(key) ?? [];
+        group.push(plan);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        const model = group[0].model;
+        let supportedTasks = model.supportedTasks;
+        try {
+            const provider = await context.getProvider(model.provider);
+            const models = await provider.getAvailableVideoModels();
+            supportedTasks =
+                models.find((entry) => entry.id === model.model)?.supportedTasks ??
+                    supportedTasks;
+        }
+        catch {
+            // Legacy providers can lack discovery, so their persisted task declarations apply.
+        }
+        const unsupported = group.find((plan) => {
+            const task = plan.mode === "direct" ? "text_to_video" : plan.mode === "reference" ? "reference_to_video" : "image_to_video";
+            return supportedTasks?.length && !supportedTasks.includes(task);
+        });
+        if (unsupported) {
+            const task = unsupported.mode === "direct" ? "text_to_video" : unsupported.mode === "reference" ? "reference_to_video" : "image_to_video";
+            return {
+                error: `The selected clip model ${model.provider}/${model.model} does not support ${task}; choose a model that supports the selected shot mode.`
+            };
+        }
+    }
+    return undefined;
+}
+function uniformModel(plans) {
+    const model = plans[0]?.model;
+    return model && plans.every((plan) => plan.model.provider === model.provider && plan.model.model === model.model)
+        ? { provider: model.provider, model: model.model }
+        : {};
+}
 const renderStoryboardStills = {
     spec: renderStoryboardStillsSpec,
     impl: async (run, params) => {
@@ -539,14 +616,11 @@ const renderStoryboardStills = {
         if (isError(board))
             return board;
         const { row, doc } = board;
-        const model = resolveModel(params, doc.imageModel, "still", "text_to_image");
-        if (isError(model))
-            return model;
         const { shotRenderMode } = await import("@nodetool-ai/protocol");
         // A direct shot renders its clip from the prompt, so it needs no still.
         // Naming it in `targets` still renders one — a board frame to look at is
         // worth having even when the clip does not come from it.
-        const selected = selectShots(doc.shots, params["targets"], (s) => !s.keyframe &&
+        const selected = selectShots(doc.shots, params["targets"], (s) => (params["stale_only"] === true ? !!s.keyframe : !s.keyframe) &&
             shotRenderMode(s) !== "direct" &&
             !shotHasPicture(s, doc.shots));
         if (isError(selected))
@@ -565,6 +639,10 @@ const renderStoryboardStills = {
                     : "No shot needs a still: each already has one, or renders its clip directly."
             };
         }
+        const protectedStill = chosen.find((shot) => shot.production?.protected_inputs?.some((input) => input.asset_id));
+        if (protectedStill) {
+            return { error: `Shot ${protectedStill.id} protects source assets; the current still renderer cannot prove source fidelity. Use those assets directly in Timeline materialization or a policy-aware finishing path.` };
+        }
         if (chosen.length > MAX_SHOTS_PER_CALL) {
             return {
                 error: `${chosen.length} shots selected, over the ${MAX_SHOTS_PER_CALL}-shot per-call limit. Pass targets in batches.`
@@ -575,22 +653,34 @@ const renderStoryboardStills = {
         // says: `style` and `model` can be overridden per call. Recording the
         // override is the point — a version rendered against something other than
         // the board's settings reads stale against the board, correctly.
-        const planOptions = {
-            provider: model.provider,
-            model: model.model
-        };
+        const planOptions = modelOverrides(params);
         if (isString(params["style"])) {
             planOptions.style = params["style"];
         }
         const plans = planShotRenders(doc, entities, "keyframe", chosen.map((shot) => shot.id), planOptions);
-        const outcomes = await renderShots(renderHost(context), { id: row.id }, plans, {
-            concurrency: clampConcurrency(params["concurrency"])
+        const { imageModelSupportsTask } = await import("@nodetool-ai/runtime");
+        for (const plan of plans) {
+            const modelError = missingPlanModel(plan);
+            if (modelError) {
+                return modelError;
+            }
+            plan.stillModelTakesImages = await imageModelSupportsTask(context, plan.model, "image_to_image", plan.model.supportedTasks);
+        }
+        const outcomes = await withSpan("render", {
+            "document.id": row.id,
+            "render.kind": "keyframe",
+            "render.shot_count": plans.length
+        }, async (span) => {
+            const rendered = await renderShots(renderHost(context), { id: row.id }, plans, { concurrency: clampConcurrency(params["concurrency"]) });
+            if (rendered.some((outcome) => !outcome.ok)) {
+                span?.setStatus({ code: SpanStatusCode.ERROR });
+            }
+            return rendered;
         });
         const results = outcomes.map((outcome) => outcomeRow(outcome, false));
         return {
             storyboard_id: row.id,
-            provider: model.provider,
-            model: model.model,
+            ...uniformModel(plans),
             rendered: results.filter((r) => r.ok).length,
             failed: results.filter((r) => !r.ok).length,
             skipped,
@@ -613,43 +703,23 @@ const renderStoryboardClips = {
             override !== "reference") {
             return { error: 'mode must be "keyframe", "direct", or "reference".' };
         }
-        // The call's override wins over the shot's own setting, for this call only.
-        const { shotRenderMode } = await import("@nodetool-ai/protocol");
-        const modeOf = (shot) => override === "keyframe" ||
-            override === "direct" ||
-            override === "reference"
-            ? override
-            : shotRenderMode(shot);
-        const selected = selectShots(doc.shots, params["targets"], (s) => !shotHasPicture(s, doc.shots) &&
-            (modeOf(s) === "direct" || modeOf(s) === "reference" || !!s.keyframe));
-        if (isError(selected))
-            return selected;
-        const requiredCapabilities = new Set(selected.map((shot) => modeOf(shot) === "direct"
-            ? "text_to_video"
-            : modeOf(shot) === "reference"
-                ? "reference_to_video"
-                : "image_to_video"));
-        const capability = requiredCapabilities.has("reference_to_video")
-            ? "reference_to_video"
-            : requiredCapabilities.has("image_to_video")
-                ? "image_to_video"
-                : "text_to_video";
-        const model = resolveModel(params, doc.videoModel, "clip", capability);
-        if (isError(model))
-            return model;
-        const declaredTasks = doc.videoModel?.supported_tasks;
-        if (Array.isArray(declaredTasks) &&
-            declaredTasks.length > 0 &&
-            model.model === doc.videoModel?.id &&
-            model.provider === doc.videoModel?.provider) {
-            const unsupported = [...requiredCapabilities].find((task) => !declaredTasks.includes(task));
-            if (unsupported) {
-                return {
-                    error: `The selected clip model does not support ${unsupported}; choose a model that supports every selected shot mode.`
-                };
-            }
+        const candidates = selectShots(doc.shots, params["targets"], (shot) => (params["stale_only"] === true ? !!shot.clip : !shotHasPicture(shot, doc.shots)) &&
+            !shot.covered_by?.shot_id);
+        if (isError(candidates)) {
+            return candidates;
         }
         const entities = await loadBoardEntities(context, doc);
+        const { planShotRenders, renderShots } = await import("@nodetool-ai/storyboard");
+        const readinessOptions = modelOverrides(params);
+        if (override !== undefined) {
+            readinessOptions.mode = override;
+        }
+        const ready = new Set(planShotRenders(doc, entities, "clip", candidates.map((shot) => shot.id), readinessOptions)
+            .filter((plan) => plan.mode !== "keyframe" || !!plan.sourceKeyframe)
+            .map((plan) => plan.shotId));
+        const selected = params["targets"] === undefined || params["targets"] === null
+            ? candidates.filter((shot) => ready.has(shot.id))
+            : candidates;
         const fresh = await filterStale(selected, params, doc, entities, "clip");
         const skipped = fresh.skipped;
         const chosen = fresh.shots;
@@ -663,13 +733,16 @@ const renderStoryboardClips = {
                     : 'No shot is ready for a clip. A keyframe-mode shot needs a still first (render_storyboard_stills), or set its render_mode to "direct" — or pass mode: "direct" here — to render straight from the prompt. Name shots explicitly with `targets` to override the selection.'
             };
         }
+        const forbiddenClip = chosen.find((shot) => shot.production?.media_strategy === "still_motion_graphics");
+        if (forbiddenClip) {
+            return { error: `Shot ${forbiddenClip.id} is still_motion_graphics; video generation is forbidden. Materialize its still/assets as Timeline layers instead.` };
+        }
         if (chosen.length > MAX_SHOTS_PER_CALL) {
             return {
                 error: `${chosen.length} shots selected, over the ${MAX_SHOTS_PER_CALL}-shot per-call limit. Pass targets in batches.`
             };
         }
         const { scriptLinesById } = await import("@nodetool-ai/timeline");
-        const { planShotRenders, renderShots } = await import("@nodetool-ai/storyboard");
         // A linked board times its shots from the words they cover, so a clip is
         // rendered long enough to hold its voiceover (design §2.3). A shot pinned
         // to `manual`, an unvoiced line, or an unlinked board keeps
@@ -678,8 +751,7 @@ const renderStoryboardClips = {
         // As in the stills path: the record says what this call rendered with, so
         // a per-call model or style override reads stale against the board.
         const planOptions = {
-            provider: model.provider,
-            model: model.model,
+            ...modelOverrides(params),
             style: isString(params["style"]) ? params["style"] : doc.style || "",
             scriptLines: scriptLinesById(scriptDoc?.sections ?? [])
         };
@@ -687,18 +759,31 @@ const renderStoryboardClips = {
             planOptions.mode = override;
         }
         const plans = planShotRenders(doc, entities, "clip", chosen.map((shot) => shot.id), planOptions);
+        const modelError = await clipModelError(context, plans);
+        if (modelError) {
+            return modelError;
+        }
         const renderOptions = {
             concurrency: clampConcurrency(params["concurrency"])
         };
         if (isString(params["resolution"])) {
             renderOptions.resolution = params["resolution"];
         }
-        const outcomes = await renderShots(renderHost(context), { id: row.id }, plans, renderOptions);
+        const outcomes = await withSpan("render", {
+            "document.id": row.id,
+            "render.kind": "clip",
+            "render.shot_count": plans.length
+        }, async (span) => {
+            const rendered = await renderShots(renderHost(context), { id: row.id }, plans, renderOptions);
+            if (rendered.some((outcome) => !outcome.ok)) {
+                span?.setStatus({ code: SpanStatusCode.ERROR });
+            }
+            return rendered;
+        });
         const results = outcomes.map((outcome) => outcomeRow(outcome, true));
         return {
             storyboard_id: row.id,
-            provider: model.provider,
-            model: model.model,
+            ...uniformModel(plans),
             rendered: results.filter((r) => r.ok).length,
             failed: results.filter((r) => !r.ok).length,
             skipped,
@@ -723,6 +808,15 @@ const reviseStoryboardClip = {
                 error: `No shot matches "${String(params["target"])}". Call get_storyboard to list shot ids.`
             };
         }
+        if (shot.production?.media_strategy === "still_motion_graphics") {
+            return { error: `Shot ${shot.id} is still_motion_graphics; video revision is forbidden.` };
+        }
+        try {
+            assertProductionGenerationAllowed(shot.production, "video_to_video");
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
         if (!shot.clip) {
             return {
                 error: "Shot has no clip to revise. Run render_storyboard_clips first."
@@ -739,6 +833,13 @@ const reviseStoryboardClip = {
                     error: "The shot's clip could not be read back from storage."
                 };
             }
+            const current = await loadBoard(run, row.id);
+            if (isError(current))
+                return current;
+            const currentShot = current.doc.shots.find((value) => value.id === shot.id);
+            if (!currentShot)
+                return { error: `Shot ${shot.id} no longer exists.` };
+            assertProductionGenerationAllowed(currentShot.production, "video_to_video");
             const saved = await renderMedia(context, {
                 provider: model.provider,
                 capability: "video_to_video",
@@ -786,7 +887,7 @@ const assembleStoryboardTimeline = {
             return board;
         const { row, doc } = board;
         const { Storyboard, TimelineSequence } = await import("@nodetool-ai/models");
-        const { buildLinkedTimeline, buildStoryboardTimeline, foreignTimelineParts, frameSizeForAspect } = await import("@nodetool-ai/timeline");
+        const { buildLinkedTimeline, buildStoryboardTimeline, foreignTimelineParts, assertStoryboardReassemblyAllowed, frameSizeForAspect } = await import("@nodetool-ai/timeline");
         // A board that links a script is cut against the words: shot lengths come
         // from the takes and every voiced line gets its own clip. A link pointing
         // at a script that is gone is a warning, not a failure — the board still
@@ -799,33 +900,7 @@ const assembleStoryboardTimeline = {
         if (scriptId && !script) {
             warnings.push(`Script ${scriptId} is linked but could not be loaded, so the board was assembled on its own.`);
         }
-        const { loadMediaRefBytes, probeVideoDurationSeconds } = await import("@nodetool-ai/runtime");
-        const { applyMeasuredShotClipDurations } = await import("@nodetool-ai/timeline");
-        const signal = context.signal ?? new AbortController().signal;
-        const measurements = await mapWithConcurrency(doc.shots, clampConcurrency(undefined), async (shot) => {
-            const clip = shot.clip;
-            const assetId = clip?.asset_id;
-            if (shot.status !== "rendered" || !assetId)
-                return null;
-            try {
-                const bytes = await loadMediaRefBytes(clip, context);
-                const seconds = bytes?.length
-                    ? await probeVideoDurationSeconds(bytes, signal)
-                    : null;
-                return seconds === null ? null : [assetId, seconds];
-            }
-            catch (error) {
-                if (signal.aborted)
-                    throw error;
-                return null;
-            }
-        });
-        const durations = new Map();
-        for (const measurement of measurements) {
-            if (measurement)
-                durations.set(...measurement);
-        }
-        const measuredShots = applyMeasuredShotClipDurations(doc.shots, durations);
+        const measuredShots = await measureStoryboardSources(doc.shots, context);
         const assembled = script
             ? buildLinkedTimeline({
                 boardId: row.id,
@@ -865,9 +940,9 @@ const assembleStoryboardTimeline = {
                 `(${worst.usedMs}ms in the cut, ${worst.sourceMs}ms rendered). ` +
                 `Re-render those shots at the length their lines need.`);
         }
-        if (assembled.clips.length === 0) {
+        if (assembled.durationMs === 0) {
             return {
-                error: "No shot has a rendered clip, so there is nothing to assemble. Run render_storyboard_stills, then render_storyboard_clips.",
+                error: "No shot has an allowed still, video, or graphics source. Add graphics intent or use render_storyboard_stills / render_storyboard_clips where allowed by the shot production policy.",
                 skipped_shot_ids: assembled.skippedShotIds,
                 skipped_line_ids: skippedLineIds
             };
@@ -934,11 +1009,12 @@ const assembleStoryboardTimeline = {
                 };
             }
             const previous = current.toDocument();
+            assertStoryboardReassemblyAllowed(previous, row.id);
             const foreign = foreignTimelineParts(previous, (clip) => clip.storyboardBoardId === row.id ||
                 (!!scriptId && clip.scriptId === scriptId));
             const tracks = [...assembled.tracks, ...foreign.tracks];
             const clips = [...assembled.clips, ...foreign.clips];
-            const durationMs = clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0);
+            const durationMs = clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), assembled.durationMs);
             const nextDocument = {
                 ...previous,
                 tracks,
@@ -1215,6 +1291,8 @@ const SHOT_EDIT_FIELDS = new Set([
     "slug",
     "camera",
     "motion",
+    "graphics",
+    "production",
     "dialogue",
     "narration",
     "notes",
@@ -1267,8 +1345,16 @@ const BOARD_EDIT_FIELDS = new Set([
     "aspect_ratio",
     "entity_ids",
     "image_model",
-    "video_model"
+    "video_model",
+    "narration",
+    "music_prompt",
+    "motion_design"
 ]);
+const screenplayDirection = z.object({
+    narration: z.string().optional(),
+    music_prompt: z.string().optional(),
+    motion_design: storyboardMotionDesign.nullable().optional()
+});
 /**
  * The board-level twin of {@link assertKnownShotFields}.
  *
@@ -1350,6 +1436,34 @@ function applyShotFields(shot, args, shots = []) {
         next.camera = args["camera"];
     if (args["motion"] !== undefined)
         next.motion = String(args["motion"]);
+    if (args["graphics"] !== undefined) {
+        if (args["graphics"] === null) {
+            delete next.graphics;
+        }
+        else {
+            const parsed = storyboardShotGraphics.safeParse(args["graphics"]);
+            if (!parsed.success) {
+                throw new Error(`graphics must be a valid Storyboard graphics object: ${parsed.error.issues
+                    .map((issue) => issue.path.join(".") || issue.message)
+                    .join(", ")}.`);
+            }
+            next.graphics = parsed.data;
+        }
+    }
+    if (args["production"] !== undefined) {
+        if (args["production"] === null) {
+            delete next.production;
+        }
+        else {
+            const parsed = productionRequirement.safeParse(args["production"]);
+            if (!parsed.success) {
+                throw new Error(`production must be a valid production requirement: ${parsed.error.issues
+                    .map((issue) => issue.path.join(".") || issue.message)
+                    .join(", ")}.`);
+            }
+            next.production = parsed.data;
+        }
+    }
     if (args["dialogue"] !== undefined)
         next.dialogue = String(args["dialogue"]);
     if (args["narration"] !== undefined)
@@ -1763,6 +1877,13 @@ function applyBoardOp(doc, { op, args }, entities = []) {
         }
         case "set_board": {
             assertKnownBoardFields(args);
+            const direction = screenplayDirection.safeParse(args);
+            if (!direction.success) {
+                throw new Error("set_board has invalid screenplay direction: " +
+                    direction.error.issues
+                        .map((issue) => `${issue.path.join(".") || "direction"}: ${issue.message}`)
+                        .join("; "));
+            }
             if (args["brief"] !== undefined)
                 doc.brief = String(args["brief"]);
             if (args["style"] !== undefined)
@@ -1797,13 +1918,45 @@ function applyBoardOp(doc, { op, args }, entities = []) {
                 }
                 doc.videoModel = videoModel;
             }
+            if (args["narration"] !== undefined ||
+                args["music_prompt"] !== undefined ||
+                args["motion_design"] !== undefined) {
+                const needsScreenplay = args["narration"] !== undefined ||
+                    args["music_prompt"] !== undefined ||
+                    direction.data.motion_design !== null;
+                if (needsScreenplay) {
+                    doc.screenplay = doc.screenplay ?? {
+                        type: "screenplay",
+                        id: newDocId("sp"),
+                        title: "",
+                        shots: []
+                    };
+                }
+                if (doc.screenplay && direction.data.narration !== undefined) {
+                    doc.screenplay.narration = direction.data.narration;
+                }
+                if (doc.screenplay && direction.data.music_prompt !== undefined) {
+                    doc.screenplay.music_prompt = direction.data.music_prompt;
+                }
+                if (doc.screenplay && direction.data.motion_design !== undefined) {
+                    if (direction.data.motion_design === null) {
+                        delete doc.screenplay.motion_design;
+                    }
+                    else {
+                        doc.screenplay.motion_design = direction.data.motion_design;
+                    }
+                }
+            }
             return {
                 brief: doc.brief,
                 style: doc.style,
                 aspect_ratio: doc.aspectRatio,
                 entity_ids: doc.entityIds,
                 image_model: doc.imageModel,
-                video_model: doc.videoModel
+                video_model: doc.videoModel,
+                narration: doc.screenplay?.narration,
+                music_prompt: doc.screenplay?.music_prompt,
+                motion_design: doc.screenplay?.motion_design
             };
         }
     }
@@ -1830,6 +1983,50 @@ async function loadStyleEntities(run, doc, ops) {
     });
     return [...cast, ...extra];
 }
+/** Resolve source refs before any edit writes. Guest IDs stay short, stored refs stay canonical. */
+async function resolveStoryboardEditSources(run, ops) {
+    const { Asset } = await import("@nodetool-ai/models");
+    const canonical = new Map();
+    const resolve = async (id) => {
+        if (!isFullResourceId(id) && !isShortResourceId(id)) {
+            return id;
+        }
+        const cached = canonical.get(id);
+        if (cached) {
+            return cached;
+        }
+        const asset = run.context.userId ? await Asset.find(run.context.userId, id) : null;
+        if (!asset) {
+            throw new Error(`Source asset or entity ${id} is unavailable.`);
+        }
+        canonical.set(id, asset.id);
+        return asset.id;
+    };
+    const resolved = structuredClone(ops);
+    for (const { args } of resolved) {
+        const references = [args];
+        const graphics = args["graphics"];
+        if (isRecord(graphics) && Array.isArray(graphics["elements"])) {
+            references.push(...graphics["elements"].filter(isRecord));
+        }
+        const production = args["production"];
+        if (isRecord(production) && Array.isArray(production["protected_inputs"])) {
+            references.push(...production["protected_inputs"].filter(isRecord));
+        }
+        for (const reference of references) {
+            for (const field of ["asset_id", "entity_id", "location_id"]) {
+                const id = reference[field];
+                if (isString(id)) {
+                    reference[field] = await resolve(id);
+                }
+            }
+        }
+        if (Array.isArray(args["entity_ids"])) {
+            args["entity_ids"] = await Promise.all(args["entity_ids"].map(async (id) => isString(id) ? resolve(id) : id));
+        }
+    }
+    return resolved;
+}
 const editStoryboard = {
     spec: editStoryboardSpec,
     impl: async (run, params) => {
@@ -1842,12 +2039,22 @@ const editStoryboard = {
             if (isError(board))
                 return board;
             const { row, doc } = board;
+            if (params["expected_revision"] !== undefined && params["expected_revision"] !== row.revision) {
+                return { error: "Storyboard revision conflict. Refresh the board before editing." };
+            }
             // A failing op is recorded and the script continues: stopping at the
             // first error hides every problem behind it.
             const records = [];
-            const entities = await loadStyleEntities(run, doc, ops);
+            let sourceOps;
+            try {
+                sourceOps = await resolveStoryboardEditSources(run, ops);
+            }
+            catch (error) {
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+            const entities = await loadStyleEntities(run, doc, sourceOps);
             const resolvedOps = [];
-            for (const parsed of ops) {
+            for (const parsed of sourceOps) {
                 try {
                     const result = applyBoardOp(doc, parsed, entities);
                     records.push({
@@ -1888,6 +2095,9 @@ const editStoryboard = {
                     resolvedOps.push({ tool: parsed.op, input: parsed.args });
                 }
             }
+            if (doc.screenplay) {
+                doc.screenplay.shots = doc.shots;
+            }
             const saved = await Storyboard.updateFieldsIfUnchanged(row.id, row.updated_at, {
                 document: JSON.stringify(doc)
             }, 
@@ -1900,6 +2110,7 @@ const editStoryboard = {
             return {
                 storyboard_id: row.id,
                 updated_at: saved.updated_at,
+                revision: saved.revision,
                 applied: records.length - failed.length,
                 failed: failed.length,
                 ops: records,
@@ -2021,6 +2232,8 @@ const directStoryboard = {
                     ...held,
                     ...shot,
                     index,
+                    graphics: held.graphics,
+                    production: held.production,
                     keyframe: held.keyframe,
                     keyframe_versions: held.keyframe_versions,
                     clip: held.clip,
@@ -2029,7 +2242,11 @@ const directStoryboard = {
                     status: held.status
                 };
             });
-            next.screenplay = screenplay;
+            const previousMotionDesign = next.screenplay?.motion_design;
+            next.screenplay = { ...screenplay, shots: next.shots };
+            if (previousMotionDesign !== undefined) {
+                next.screenplay.motion_design = previousMotionDesign;
+            }
             next.style = screenplay.style_bible ?? next.style;
             next.aspectRatio = screenplay.aspect_ratio ?? next.aspectRatio;
             if (screenplay.genre)
@@ -2040,6 +2257,7 @@ const directStoryboard = {
             return {
                 storyboard_id: current.row.id,
                 updated_at: saved.updated_at,
+                revision: saved.revision,
                 title: screenplay.title,
                 genre: next.genre,
                 redirected: params["redirect"] === true,
@@ -2226,6 +2444,9 @@ const deleteStoryboard = {
     }
 };
 export const STORYBOARD_CAPABILITIES = [
+    finishStoryboard,
+    layoutStoryboard,
+    previewStoryboardDesign,
     listStoryboards,
     createStoryboard,
     getStoryboard,
@@ -2242,5 +2463,5 @@ export const module = {
     module: "storyboards",
     exports: STORYBOARD_CAPABILITIES
 };
-export { listStoryboards, createStoryboard, getStoryboard, renderStoryboardStills, renderStoryboardClips, reviseStoryboardClip, assembleStoryboardTimeline, editStoryboard, directStoryboard, extractScriptFromStoryboard, deleteStoryboard };
+export { finishStoryboard, layoutStoryboard, previewStoryboardDesign, listStoryboards, createStoryboard, getStoryboard, renderStoryboardStills, renderStoryboardClips, reviseStoryboardClip, assembleStoryboardTimeline, editStoryboard, directStoryboard, extractScriptFromStoryboard, deleteStoryboard };
 //# sourceMappingURL=storyboards.js.map