@nodetool-ai/video-nodes 0.8.1

package/dist/nodes/storyboard.js

@@ -0,0 +1,1017 @@
+/**
+ * Storyboard nodes — a persisted board as a graph value.
+ *
+ * A director approves one board in the editor; a graph then re-runs it for a
+ * new product, a new actor, a new SKU. These nodes are that loop: read a board
+ * (`LoadStoryboard`, `StoryboardShots`), derive a copy for a new cast
+ * (`RecastStoryboard`), spend on its frames (`RenderStills`, `RenderClips`),
+ * and cut it (`AssembleTimeline`). Design:
+ * [docs/graph-resources/design.md](../../../../docs/graph-resources/design.md) §4.2.
+ *
+ * The derivation, the render plan and the render path itself come from
+ * `@nodetool-ai/storyboard`, the same functions the agent capabilities and the
+ * board editor call, so a board rendered from a graph matches one rendered from
+ * chat.
+ *
+ * **Write contract.** A `StoryboardRef` is read-only unless it carries
+ * `writable: true`, and only a node that created or derived the row in this run
+ * sets it. `RenderStills`, `RenderClips` and `AssembleTimeline` refuse a ref
+ * without the flag before they read anything, so a picker wired straight into a
+ * render node fails before any spend rather than after it.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseNode, prop } from "@nodetool-ai/node-sdk";
+import { isObjectLike, isString } from "@nodetool-ai/node-sdk";
+import { loadMediaRefBytes, probeVideoDurationSeconds, resolveEntities } from "@nodetool-ai/runtime";
+import { shotRenderMode, requiredVideoTasksForShots } from "@nodetool-ai/protocol";
+import { planShotRenders, recastStoryboard, renderShots } from "@nodetool-ai/storyboard";
+import { applyMeasuredShotClipDurations, buildLinkedTimeline, buildStoryboardTimeline, cloneTimelineForBoard, foreignTimelineParts, frameSizeForAspect, makeSequence, refillShotClips, scriptLinesById } from "@nodetool-ai/timeline";
+import { tagAsServer } from "@nodetool-ai/nodes-utils";
+const storyboardRefDefault = {
+    type: "storyboard",
+    id: null,
+    data: null
+};
+/** An unset model selection: the picker's "nothing chosen" value. */
+const emptyModel = (type) => ({
+    type,
+    provider: "empty",
+    id: "",
+    name: "",
+    path: null,
+    supported_tasks: []
+});
+/**
+ * `RecastStoryboard` finds the copy a previous run made by (project,
+ * `templateId`, `recastKey`). A host that wires no `listStoryboards` cannot
+ * answer that, and `reuse_existing` says so rather than quietly making a
+ * second row — and a second bill — on every run.
+ */
+const isRecord = (value) => isObjectLike(value);
+/** A board row, when a host's answer carries what the node reads off one. */
+const asBoardRow = (value) => isRecord(value) && isString(value["id"]) && isRecord(value["document"])
+    ? value
+    : null;
+/** The board rows a host can list, or null when it cannot list any. */
+async function listBoards(context, projectId) {
+    if (!context.hasModelInterface("listStoryboards"))
+        return null;
+    const rows = await context.listStoryboards({ projectId });
+    return rows
+        .map(asBoardRow)
+        .filter((row) => row !== null);
+}
+// ---------------------------------------------------------------------------
+// Board access
+// ---------------------------------------------------------------------------
+const requireContext = (context, node) => {
+    if (!context) {
+        throw new Error(`${node} requires a processing context`);
+    }
+    return context;
+};
+/**
+ * The board a ref points at.
+ *
+ * An inline `data` document is read without touching the database — the shape
+ * the debug harness and the node tests use. Anything that writes needs the row,
+ * so it calls {@link loadBoardRow} instead.
+ */
+async function readBoard(ref, context, node) {
+    const boardRef = (ref ?? {});
+    if (!boardRef.id) {
+        if (isRecord(boardRef.data)) {
+            return {
+                id: "",
+                projectId: "default",
+                name: "",
+                document: boardRef.data,
+                updatedAt: ""
+            };
+        }
+        throw new Error(`${node}: storyboard input is empty — connect a Constant Storyboard node and pick a board`);
+    }
+    const ctx = requireContext(context, node);
+    const row = (await ctx.getStoryboard(boardRef.id));
+    if (!row) {
+        throw new Error(`${node}: storyboard not found: ${boardRef.id}`);
+    }
+    return row;
+}
+/** The persisted row a write needs; an inline document is not one. */
+async function loadBoardRow(ref, context, node) {
+    const ctx = requireContext(context, node);
+    const row = await readBoard(ref, ctx, node);
+    if (!row.id) {
+        throw new Error(`${node}: an inline storyboard document has no row to write to. Pick a persisted board.`);
+    }
+    return { row, context: ctx };
+}
+/**
+ * Refuse a board this run did not derive.
+ *
+ * The question is the flag on the ref, never whether a derived row happens to
+ * exist: a first run has no copies yet, and a copy picked from the library is
+ * as approved as the template it came from. Checked before the board is read,
+ * so a miswire costs nothing.
+ */
+function requireWritable(ref, allowWrites, node) {
+    if (allowWrites)
+        return;
+    const boardRef = (ref ?? {});
+    if (boardRef.writable === true)
+        return;
+    throw new Error(`${node} will not write a storyboard this run did not derive. Feed it the board from RecastStoryboard, or turn on allow_writes to render the board you picked.`);
+}
+/** The ref this run may keep writing to. */
+const writableRef = (id) => ({
+    type: "storyboard",
+    id,
+    writable: true
+});
+/** The board's cast, read from the library. */
+async function loadBoardEntities(context, doc) {
+    const ids = doc.entityIds ?? [];
+    if (ids.length === 0 || !context.hasModelInterface("getEntity"))
+        return [];
+    const loaded = await Promise.all(ids.map((id) => context.getEntity(id)));
+    return loaded.filter((entity) => !!entity);
+}
+/**
+ * The model a render uses: the node's override when set, else the board's.
+ *
+ * Unset is an error, never a default — a board rendered on a model nobody chose
+ * is a bill nobody agreed to.
+ */
+function resolveModel(boardModel, override, kind, capability) {
+    const provider = override?.provider && override.provider !== "empty"
+        ? override.provider
+        : isString(boardModel?.["provider"])
+            ? boardModel["provider"]
+            : "";
+    const model = override?.id && override.id !== ""
+        ? override.id
+        : isString(boardModel?.["id"])
+            ? boardModel["id"]
+            : "";
+    if (!provider || !model) {
+        throw new Error(`No ${kind} model is set on this storyboard. Set one on the board, or wire this node's ${kind === "still" ? "image_model" : "video_model"} input (find_model with capability=${capability} lists the choices).`);
+    }
+    return {
+        provider,
+        model,
+        supportedTasks: override?.id && override.id !== ""
+            ? override.supported_tasks
+            : Array.isArray(boardModel?.["supported_tasks"])
+                ? boardModel["supported_tasks"].filter(isString)
+                : undefined
+    };
+}
+/**
+ * The render path's host seam (`renderShots` in `@nodetool-ai/storyboard`).
+ *
+ * The same four operations the agent capability implements, over the context's
+ * model interfaces instead of the model classes — one render path, whether the
+ * board is rendered from a graph or from chat.
+ *
+ * `videoDurationSeconds` is absent here because render-time MP4 inspection is
+ * owned by the agent package. AssembleTimeline probes the persisted media
+ * independently, so graph-rendered clips still use their delivered length.
+ */
+function renderHost(context) {
+    return {
+        runGeneration: async (request) => {
+            const result = await context.runGeneration({
+                id: request.id,
+                provider: request.provider,
+                capability: request.capability,
+                model: request.model,
+                params: request.params,
+                origin: { surface: "workflow" },
+                persist: request.persist
+            });
+            return { output: result.output, assets: result.assets };
+        },
+        getStoryboard: async (id) => {
+            const row = (await context.getStoryboard(id));
+            return row ? { document: row.document, updatedAt: row.updatedAt } : null;
+        },
+        updateStoryboard: async ({ id, document, baseUpdatedAt }) => {
+            const saved = (await context.updateStoryboard(id, {
+                document,
+                baseUpdatedAt
+            }));
+            return saved ? { document, updatedAt: saved.updatedAt } : null;
+        },
+        loadMedia: async (ref) => loadMediaRefBytes(ref, context)
+    };
+}
+// ---------------------------------------------------------------------------
+// Shot selection
+// ---------------------------------------------------------------------------
+/** `targets` as the plan reads it: undefined means every shot. */
+const asTargets = (value) => {
+    if (!Array.isArray(value))
+        return undefined;
+    const targets = value.map((entry) => String(entry).trim()).filter(Boolean);
+    return targets.length > 0 ? targets : undefined;
+};
+const orderedShots = (doc) => [...doc.shots].sort((a, b) => a.index - b.index);
+const imageRefOf = (outcome) => ({
+    type: "image",
+    uri: outcome.assetUri ?? "",
+    asset_id: outcome.assetId ?? null
+});
+const videoRefOf = (outcome) => ({
+    type: "video",
+    uri: outcome.assetUri ?? "",
+    asset_id: outcome.assetId ?? null
+});
+/** The shots that already carry a take of this kind. */
+const shotsWithVersion = (doc, kind) => new Set(doc.shots
+    .filter((shot) => (kind === "keyframe" ? !!shot.keyframe : !!shot.clip))
+    .map((shot) => shot.id));
+/**
+ * Drop the plans a gate refuses, keeping the shot ids each gate skipped.
+ *
+ * `onlyStale` skips a shot the board would render exactly as it already did —
+ * which is a question only a shot that *has* a take can answer, so `rendered`
+ * bounds it. A never-rendered shot reads `fresh` on the plan (nothing recorded
+ * is nothing to be out of date with) and must still be rendered.
+ *
+ * `max_shots` truncates rather than failing: the cap is a spend gate, and a
+ * board bigger than the cap renders its first N and says which it left, rather
+ * than refusing the run (design §1, P4).
+ */
+function applyGates(plans, gates) {
+    const skipped = [];
+    let kept = plans;
+    const refused = gates.skipShotIds;
+    if (refused && refused.size > 0) {
+        skipped.push(...kept.filter((plan) => refused.has(plan.shotId)).map((plan) => plan.shotId));
+        kept = kept.filter((plan) => !refused.has(plan.shotId));
+    }
+    if (gates.onlyStale) {
+        const current = (plan) => plan.fresh && gates.rendered.has(plan.shotId);
+        skipped.push(...kept.filter(current).map((plan) => plan.shotId));
+        kept = kept.filter((plan) => !current(plan));
+    }
+    const limit = Math.max(0, Math.floor(gates.maxShots));
+    if (kept.length > limit) {
+        skipped.push(...kept.slice(limit).map((plan) => plan.shotId));
+        kept = kept.slice(0, limit);
+    }
+    return { plans: kept, skipped };
+}
+const clampConcurrency = (value) => {
+    const parsed = Math.floor(Number(value));
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return 1;
+    return Math.min(parsed, 8);
+};
+async function mapWithConcurrency(items, limit, task) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await task(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+export class LoadStoryboardNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.LoadStoryboard";
+    static title = "Load Storyboard";
+    static description = "Read a persisted storyboard's shots, cast and settings.\n    storyboard, board, shots, entities, load\n\n    Use cases:\n    - Feed a board's shots into a batch\n    - Read the cast a board was directed with\n    - Branch a workflow on a board's shot count";
+    static metadataOutputTypes = {
+        storyboard: "storyboard",
+        shots: "list[dict]",
+        entities: "list[entity]",
+        style: "str",
+        aspect_ratio: "str",
+        name: "str",
+        image_model: "image_model",
+        video_model: "video_model",
+        shot_count: "int"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard"];
+    async process(context) {
+        const row = await readBoard(this.storyboard, context, "LoadStoryboard");
+        const doc = row.document;
+        const shots = orderedShots(doc);
+        const entities = context ? await loadBoardEntities(context, doc) : [];
+        // The ref passes through as it arrived: reading a board never earns the
+        // right to write it (write contract, design §4.2).
+        return {
+            storyboard: { type: "storyboard", id: row.id || null },
+            shots,
+            entities,
+            style: doc.style ?? "",
+            aspect_ratio: doc.aspectRatio || "16:9",
+            name: row.name,
+            image_model: doc.imageModel ?? null,
+            video_model: doc.videoModel ?? null,
+            shot_count: shots.length
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The board to read."
+    })
+], LoadStoryboardNode.prototype, "storyboard", void 0);
+export class StoryboardShotsNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.StoryboardShots";
+    static title = "Storyboard Shots";
+    static description = "Fan a persisted storyboard out into one message per shot, with its rendered still and clip.\n    storyboard, shots, iterate, keyframe, clip\n\n    Use cases:\n    - Driving a per-shot pipeline from an approved board\n    - Collecting a board's stills or clips downstream\n    - Iterating over shots without re-directing them";
+    static metadataOutputTypes = {
+        shot: "dict",
+        index: "int",
+        slug: "str",
+        keyframe: "image",
+        clip: "video",
+        output: "list[dict]"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard"];
+    // Emit per-shot output_updates even when the handles are wired onward, so
+    // the node shows shots as they stream regardless of downstream connections.
+    static alwaysEmitOutputUpdates = true;
+    static inputMode = "buffered";
+    static outputCorrelation = {
+        shot: { kind: "iteration", source: "__execution__", group: "items" },
+        index: { kind: "iteration", source: "__execution__", group: "items" },
+        slug: { kind: "iteration", source: "__execution__", group: "items" },
+        keyframe: { kind: "iteration", source: "__execution__", group: "items" },
+        clip: { kind: "iteration", source: "__execution__", group: "items" },
+        output: { kind: "single", source: "__execution__" }
+    };
+    async process(context) {
+        const shots = [];
+        for await (const chunk of this.genProcess(context)) {
+            if (chunk.shot)
+                shots.push(chunk.shot);
+        }
+        return { output: shots };
+    }
+    async *genProcess(context) {
+        const row = await readBoard(this.storyboard, context, "StoryboardShots");
+        const shots = orderedShots(row.document);
+        for (const shot of shots) {
+            yield {
+                shot,
+                index: shot.index,
+                slug: shot.slug ?? "",
+                keyframe: shot.keyframe
+                    ? {
+                        type: "image",
+                        uri: shot.keyframe.uri ?? "",
+                        asset_id: shot.keyframe.asset_id ?? null
+                    }
+                    : null,
+                clip: shot.clip
+                    ? {
+                        type: "video",
+                        uri: shot.clip.uri ?? "",
+                        asset_id: shot.clip.asset_id ?? null
+                    }
+                    : null
+            };
+        }
+        yield {
+            shot: null,
+            index: null,
+            slug: null,
+            keyframe: null,
+            clip: null,
+            output: shots
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The board whose shots to stream."
+    })
+], StoryboardShotsNode.prototype, "storyboard", void 0);
+export class RecastStoryboardNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.RecastStoryboard";
+    static title = "Recast Storyboard";
+    static description = "Copy an approved storyboard onto a new cast, keeping every frame whose prompt did not change.\n    storyboard, recast, variant, batch, entities\n\n    Use cases:\n    - Re-running an approved board for another product\n    - Swapping the actor or location in a template\n    - Producing one variant per SKU without re-directing";
+    static metadataOutputTypes = {
+        storyboard: "storyboard",
+        invalidated: "list[str]",
+        kept: "list[str]"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard", "cast"];
+    async process(context) {
+        const { row, context: ctx } = await loadBoardRow(this.storyboard, context, "RecastStoryboard");
+        const doc = row.document;
+        const entities = await resolveEntities(this.cast, ctx);
+        if (entities.length === 0) {
+            throw new Error("RecastStoryboard: cast is empty — connect the entities that replace the template's.");
+        }
+        const replaces = Array.isArray(this.replaces) ? this.replaces : [];
+        const cast = entities.map((entity, index) => {
+            const target = String(replaces[index] ?? "").trim();
+            return target ? { entity, replaces: target } : { entity };
+        });
+        const boardEntities = await loadBoardEntities(ctx, doc);
+        // The mapping this cast resolves to. `recastKey` depends on which board
+        // entity each cast member ended up replacing, which only the derivation
+        // works out — so the copy is derived once to learn the key, and again
+        // against the copy that key finds. Both passes are pure.
+        const probe = recastStoryboard({
+            document: doc,
+            sourceId: row.id,
+            boardEntities,
+            cast
+        });
+        const existing = this.reuse_existing
+            ? await this.findExisting(ctx, row, probe.recastKey)
+            : null;
+        const result = existing
+            ? recastStoryboard({
+                document: doc,
+                sourceId: row.id,
+                boardEntities,
+                cast,
+                existing: existing.document
+            })
+            : probe;
+        const name = this.copyName(row, result.substitutions.map((s) => s.to));
+        const saved = existing
+            ? (await ctx.updateStoryboard(existing.id, {
+                document: result.document
+            }))
+            : (await ctx.createStoryboard({
+                name,
+                projectId: row.projectId,
+                document: result.document
+            }));
+        if (!saved) {
+            throw new Error(`RecastStoryboard: could not save the copy of ${row.name || row.id}.`);
+        }
+        return {
+            storyboard: writableRef(saved.id),
+            invalidated: result.invalidatedShotIds,
+            kept: result.keptShotIds
+        };
+    }
+    /**
+     * The copy this mapping made last time, when the host can look one up.
+     *
+     * The scoped lookup asks for that one row; the listing fallback scans what a
+     * host that wires no scoped lookup can answer with, which is a window of the
+     * most recently updated boards — enough for a handful of variants, not for a
+     * catalog whose copies fall out of it.
+     */
+    async findExisting(context, row, recastKey) {
+        if (context.hasModelInterface("findRecastStoryboard")) {
+            return asBoardRow(await context.findRecastStoryboard({
+                projectId: row.projectId,
+                templateId: row.id,
+                recastKey
+            }));
+        }
+        const boards = await listBoards(context, row.projectId);
+        if (boards === null) {
+            throw new Error("RecastStoryboard: this host cannot look up the copy a previous run made, so reuse_existing would create a second board (and a second bill) every run. Turn reuse_existing off to make a fresh copy each time.");
+        }
+        return (boards.find((board) => board.id !== row.id &&
+            board.document.templateId === row.id &&
+            board.document.recastKey === recastKey) ?? null);
+    }
+    copyName(row, cast) {
+        const given = String(this.name ?? "").trim();
+        if (given)
+            return given;
+        const names = cast.map((entity) => entity.name).filter(Boolean);
+        const base = row.name || "Storyboard";
+        return names.length > 0 ? `${base} — ${names.join(", ")}` : `${base} (recast)`;
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The template board to copy. It is never written."
+    })
+], RecastStoryboardNode.prototype, "storyboard", void 0);
+__decorate([
+    prop({
+        type: "list[entity]",
+        default: [],
+        title: "Cast",
+        description: "Entities to put in the copy. Each replaces the board entity named in `replaces`, or the board's single entity of the same kind."
+    })
+], RecastStoryboardNode.prototype, "cast", void 0);
+__decorate([
+    prop({
+        type: "list[str]",
+        default: [],
+        title: "Replaces",
+        description: "Board entity id or name each cast member stands in for, in cast order. Leave an entry empty to infer it from the entity's kind."
+    })
+], RecastStoryboardNode.prototype, "replaces", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "",
+        title: "Name",
+        description: "Name for the copy. Defaults to the template's name plus the new cast."
+    })
+], RecastStoryboardNode.prototype, "name", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: true,
+        title: "Reuse Existing",
+        description: "Re-derive the copy this mapping made last time instead of creating a second one, so a re-run pays only for what changed."
+    })
+], RecastStoryboardNode.prototype, "reuse_existing", void 0);
+export class RenderStillsNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.RenderStills";
+    static title = "Render Stills";
+    static description = "Render the keyframe of every stale shot on a storyboard and save it onto the board.\n    storyboard, keyframe, still, render, batch\n\n    Use cases:\n    - Filling a recast board's frames before the clips\n    - Re-rendering only the shots a template edit changed\n    - Stopping a batch at the stills to review the spend";
+    static metadataOutputTypes = {
+        storyboard: "storyboard",
+        keyframes: "list[image]",
+        rendered: "list[str]",
+        skipped: "list[str]",
+        failed: "list[str]"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard", "targets"];
+    async process(context) {
+        requireWritable(this.storyboard, this.allow_writes, "RenderStills");
+        const { row, context: ctx } = await loadBoardRow(this.storyboard, context, "RenderStills");
+        const doc = row.document;
+        const model = resolveModel(doc.imageModel, this.image_model, "still", "text_to_image");
+        const entities = await loadBoardEntities(ctx, doc);
+        const targets = asTargets(this.targets);
+        const options = {
+            provider: model.provider,
+            model: model.model
+        };
+        const plans = planShotRenders(doc, entities, "keyframe", targets, options);
+        // A direct-mode shot renders its clip from the prompt and needs no still —
+        // unless it was named, where a board frame to look at is worth having.
+        const direct = new Set(targets
+            ? []
+            : doc.shots
+                .filter((shot) => shotRenderMode(shot) === "direct")
+                .map((shot) => shot.id));
+        const selection = applyGates(plans, {
+            onlyStale: this.only_stale,
+            rendered: shotsWithVersion(doc, "keyframe"),
+            skipShotIds: direct,
+            maxShots: this.max_shots
+        });
+        const outcomes = await renderShots(renderHost(ctx), { id: row.id }, selection.plans, { concurrency: clampConcurrency(this.concurrency) });
+        return {
+            storyboard: writableRef(row.id),
+            keyframes: outcomes.filter((o) => o.ok).map(imageRefOf),
+            rendered: outcomes.filter((o) => o.ok).map((o) => o.shotId),
+            skipped: selection.skipped,
+            failed: outcomes.filter((o) => !o.ok).map((o) => o.shotId)
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The board whose stills to render."
+    })
+], RenderStillsNode.prototype, "storyboard", void 0);
+__decorate([
+    prop({
+        type: "list[str]",
+        default: [],
+        title: "Targets",
+        description: "Shot ids, indices or slugs to render. Empty renders every shot the gates allow."
+    })
+], RenderStillsNode.prototype, "targets", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 24,
+        title: "Max Shots",
+        description: "Most shots this call renders. The rest are reported as skipped, not rendered.",
+        min: 1,
+        max: 200
+    })
+], RenderStillsNode.prototype, "max_shots", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 2,
+        title: "Concurrency",
+        description: "Renders in flight at once.",
+        min: 1,
+        max: 8
+    })
+], RenderStillsNode.prototype, "concurrency", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: true,
+        title: "Only Stale",
+        description: "Skip a shot whose still already matches what the board would render."
+    })
+], RenderStillsNode.prototype, "only_stale", void 0);
+__decorate([
+    prop({
+        type: "image_model",
+        default: emptyModel("image_model"),
+        title: "Image Model",
+        description: "Overrides the board's still model for this call."
+    })
+], RenderStillsNode.prototype, "image_model", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Allow Writes",
+        description: "Render the board as it was picked, rather than only one this run derived."
+    })
+], RenderStillsNode.prototype, "allow_writes", void 0);
+export class RenderClipsNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.RenderClips";
+    static title = "Render Clips";
+    static description = "Animate every stale shot on a storyboard and save the clip onto the board.\n    storyboard, clip, video, render, batch\n\n    Use cases:\n    - Turning approved stills into shots\n    - Re-rendering only the clips a recast invalidated\n    - Bounding what one run spends on video";
+    static metadataOutputTypes = {
+        storyboard: "storyboard",
+        clips: "list[video]",
+        rendered: "list[str]",
+        skipped: "list[str]",
+        failed: "list[str]"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard", "targets"];
+    async process(context) {
+        requireWritable(this.storyboard, this.allow_writes, "RenderClips");
+        const { row, context: ctx } = await loadBoardRow(this.storyboard, context, "RenderClips");
+        const doc = row.document;
+        const model = resolveModel(doc.videoModel, this.video_model, "clip", doc.shots.some((shot) => shotRenderMode(shot) === "reference")
+            ? "reference_to_video"
+            : doc.shots.every((shot) => shotRenderMode(shot) === "direct")
+                ? "text_to_video"
+                : "image_to_video");
+        const requiredTasks = requiredVideoTasksForShots(doc.shots);
+        let supportedTasks = model.supportedTasks;
+        try {
+            const provider = await ctx.getProvider(model.provider);
+            const discovered = await provider.getAvailableVideoModels();
+            supportedTasks = discovered.find((entry) => entry.id === model.model)?.supportedTasks;
+        }
+        catch (error) {
+            if (requiredTasks.length > 1) {
+                throw new Error(`Could not verify video model ${model.provider}/${model.model} against the storyboard's mixed shot modes before rendering.`, { cause: error });
+            }
+            // Single-mode legacy providers may not implement model discovery.
+        }
+        if (requiredTasks.length > 1 && !supportedTasks?.length) {
+            throw new Error(`Could not verify video model ${model.provider}/${model.model} against the storyboard's mixed shot modes before rendering.`);
+        }
+        if (supportedTasks &&
+            requiredTasks.some((task) => !supportedTasks.includes(task))) {
+            throw new Error(`Video model ${model.provider}/${model.model} does not support every shot mode on this storyboard. Required capabilities: ${requiredTasks.join(", ")}.`);
+        }
+        const entities = await loadBoardEntities(ctx, doc);
+        const targets = asTargets(this.targets);
+        // A linked board times its shots from the words they cover, so a clip is
+        // rendered long enough to hold its voiceover.
+        const script = await loadLinkedScript(ctx, doc);
+        const options = {
+            provider: model.provider,
+            model: model.model,
+            scriptLines: scriptLinesById(script?.document.sections ?? [])
+        };
+        const plans = planShotRenders(doc, entities, "clip", targets, options);
+        // A shot whose picture is a window into another's clip has nothing of its
+        // own to render, and a keyframe-mode shot with no still has nothing to
+        // animate — refusing that one is what `require_keyframe` buys.
+        const covered = new Set(doc.shots.filter((shot) => shot.covered_by?.shot_id).map((shot) => shot.id));
+        const unrenderable = new Set([
+            ...covered,
+            ...(this.require_keyframe
+                ? plans
+                    .filter((plan) => plan.mode === "keyframe" && !plan.sourceKeyframe)
+                    .map((plan) => plan.shotId)
+                : [])
+        ]);
+        const selection = applyGates(plans, {
+            onlyStale: this.only_stale,
+            rendered: shotsWithVersion(doc, "clip"),
+            skipShotIds: unrenderable,
+            maxShots: this.max_shots
+        });
+        const outcomes = await renderShots(renderHost(ctx), { id: row.id }, selection.plans, { concurrency: clampConcurrency(this.concurrency) });
+        return {
+            storyboard: writableRef(row.id),
+            clips: outcomes.filter((o) => o.ok).map(videoRefOf),
+            rendered: outcomes.filter((o) => o.ok).map((o) => o.shotId),
+            skipped: selection.skipped,
+            failed: outcomes.filter((o) => !o.ok).map((o) => o.shotId)
+        };
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The board whose clips to render."
+    })
+], RenderClipsNode.prototype, "storyboard", void 0);
+__decorate([
+    prop({
+        type: "list[str]",
+        default: [],
+        title: "Targets",
+        description: "Shot ids, indices or slugs to render. Empty renders every shot the gates allow."
+    })
+], RenderClipsNode.prototype, "targets", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 8,
+        title: "Max Shots",
+        description: "Most shots this call renders. The rest are reported as skipped, not rendered.",
+        min: 1,
+        max: 100
+    })
+], RenderClipsNode.prototype, "max_shots", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: true,
+        title: "Require Keyframe",
+        description: "Skip a keyframe-mode shot that has no selected still, instead of spending on a clip with nothing to animate."
+    })
+], RenderClipsNode.prototype, "require_keyframe", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 1,
+        title: "Concurrency",
+        description: "Renders in flight at once.",
+        min: 1,
+        max: 8
+    })
+], RenderClipsNode.prototype, "concurrency", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: true,
+        title: "Only Stale",
+        description: "Skip a shot whose clip already matches what the board would render."
+    })
+], RenderClipsNode.prototype, "only_stale", void 0);
+__decorate([
+    prop({
+        type: "video_model",
+        default: emptyModel("video_model"),
+        title: "Video Model",
+        description: "Overrides the board's clip model for this call."
+    })
+], RenderClipsNode.prototype, "video_model", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Allow Writes",
+        description: "Render the board as it was picked, rather than only one this run derived."
+    })
+], RenderClipsNode.prototype, "allow_writes", void 0);
+// ---------------------------------------------------------------------------
+// AssembleTimeline
+// ---------------------------------------------------------------------------
+/** The script a board links, when it links one that can still be read. */
+async function loadLinkedScript(context, doc) {
+    const scriptId = doc.screenplay?.script_id;
+    if (!scriptId || !context.hasModelInterface("getScript"))
+        return null;
+    const row = (await context.getScript(scriptId));
+    return row ?? null;
+}
+export class AssembleTimelineNode extends BaseNode {
+    static nodeType = "nodetool.storyboard.AssembleTimeline";
+    static title = "Assemble Timeline";
+    static description = "Cut a storyboard's rendered shots into a timeline, inheriting the template's cut when the board is a copy.\n    storyboard, timeline, assemble, cut, edit\n\n    Use cases:\n    - Turning a finished board into an editable sequence\n    - Giving every recast copy the approved cut, titles and music\n    - Re-cutting a board after re-rendering some shots";
+    static metadataOutputTypes = {
+        timeline: "timeline",
+        skipped_shots: "list[str]",
+        retimed: "list[dict]"
+    };
+    static inlineFields = ["storyboard"];
+    static inputFields = ["storyboard"];
+    async process(context) {
+        requireWritable(this.storyboard, this.allow_writes, "AssembleTimeline");
+        const { row, context: ctx } = await loadBoardRow(this.storyboard, context, "AssembleTimeline");
+        const doc = row.document;
+        const script = await loadLinkedScript(ctx, doc);
+        const scriptId = script ? doc.screenplay?.script_id ?? null : null;
+        const signal = ctx.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, ctx);
+                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 assembled = script
+            ? buildLinkedTimeline({
+                boardId: row.id,
+                shots: measuredShots,
+                musicPrompt: doc.screenplay?.music_prompt,
+                script: {
+                    scriptId: script.id,
+                    cast: script.document.cast,
+                    sections: script.document.sections
+                }
+            })
+            : buildStoryboardTimeline({
+                boardId: row.id,
+                shots: measuredShots,
+                narration: doc.screenplay?.narration,
+                musicPrompt: doc.screenplay?.music_prompt
+            });
+        if (assembled.clips.length === 0) {
+            throw new Error("AssembleTimeline: no shot has a rendered clip, so there is nothing to assemble. Run RenderStills, then RenderClips.");
+        }
+        const { width, height } = frameSizeForAspect(doc.aspectRatio);
+        const fps = Math.max(1, Math.min(Math.floor(Number(this.fps) || 30), 120));
+        const name = String(this.name ?? "").trim() || row.name;
+        // The cut this board writes into: its own, else the one it inherits from
+        // the template it was recast from, else a fresh sequence. Only the board's
+        // own sequence already exists as a row; the other two are created below.
+        const owned = await this.loadOwnSequence(ctx, row);
+        const base = owned ?? (await this.templateCut(ctx, row));
+        const { tracks, clips } = this.mergeCut(base, assembled, {
+            owns: (clip) => clip.storyboardBoardId === row.id ||
+                (!!scriptId && clip.scriptId === scriptId),
+            liveShotIds: new Set(doc.shots.map((shot) => shot.id)),
+            scriptLinked: scriptId !== null
+        });
+        const durationMs = clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0);
+        const sequence = {
+            ...(base ??
+                makeSequence({ projectId: row.projectId, name })),
+            name,
+            fps,
+            width,
+            height,
+            durationMs,
+            tracks,
+            clips,
+            markers: base?.markers ?? []
+        };
+        const saved = (owned
+            ? await ctx.updateTimelineSequence(sequence.id, sequence)
+            : await ctx.createTimelineSequence(sequence));
+        if (!saved) {
+            throw new Error(`AssembleTimeline: could not save the sequence for ${row.name || row.id}.`);
+        }
+        if (row.timelineId !== saved.id) {
+            await ctx.updateStoryboard(row.id, { timelineId: saved.id });
+        }
+        return {
+            timeline: { type: "timeline", id: saved.id },
+            skipped_shots: assembled.skippedShotIds,
+            retimed: assembled.retimedShots
+        };
+    }
+    /**
+     * The cut this assembly writes, over the one that was there.
+     *
+     * An unlinked board's shot clips are refilled in place
+     * ({@link refillShotClips}): a copy inherits the approved cut, and a
+     * re-render lands in the edit rather than rebuilding it in board order. A
+     * script-linked board is rebuilt, because there the words decide where each
+     * shot sits and how long it runs, and a re-assemble has to be free to re-time
+     * the cut when a line is re-voiced. Both keep every clip the board does not
+     * own (design §3.2, §4.2).
+     */
+    mergeCut(base, assembled, how) {
+        if (!base) {
+            return { tracks: [...assembled.tracks], clips: [...assembled.clips] };
+        }
+        if (how.scriptLinked) {
+            const previous = foreignTimelineParts(base, how.owns);
+            return {
+                tracks: [...assembled.tracks, ...previous.tracks],
+                clips: [...assembled.clips, ...previous.clips]
+            };
+        }
+        return refillShotClips(base, assembled, how);
+    }
+    /** The sequence this board already owns, when it still exists. */
+    async loadOwnSequence(context, row) {
+        if (!row.timelineId)
+            return null;
+        return (await context.getTimelineSequence(row.timelineId));
+    }
+    /**
+     * The template's cut, cloned for this copy.
+     *
+     * A copy inherits the approved edit rather than a bare assembly: the
+     * template's shot clips are re-stamped to this board (and refilled from its
+     * own renders by the assemble above), while the text overlay, the music bed
+     * and every other track come across untouched. The clone is returned
+     * unsaved — the assemble writes it as one row, so a failure part way leaves
+     * no half-built sequence behind.
+     */
+    async templateCut(context, row) {
+        const templateId = row.document.templateId;
+        if (!templateId)
+            return null;
+        const template = (await context.getStoryboard(templateId));
+        if (!template?.timelineId)
+            return null;
+        const source = (await context.getTimelineSequence(template.timelineId));
+        if (!source)
+            return null;
+        return cloneTimelineForBoard(source, { boardId: templateId }, { boardId: row.id });
+    }
+}
+__decorate([
+    prop({
+        type: "storyboard",
+        default: storyboardRefDefault,
+        title: "Storyboard",
+        description: "The board to cut."
+    })
+], AssembleTimelineNode.prototype, "storyboard", void 0);
+__decorate([
+    prop({
+        type: "str",
+        default: "",
+        title: "Name",
+        description: "Name for the sequence. Defaults to the board's name."
+    })
+], AssembleTimelineNode.prototype, "name", void 0);
+__decorate([
+    prop({
+        type: "int",
+        default: 30,
+        title: "FPS",
+        description: "Frame rate of the assembled sequence.",
+        min: 1,
+        max: 120
+    })
+], AssembleTimelineNode.prototype, "fps", void 0);
+__decorate([
+    prop({
+        type: "bool",
+        default: false,
+        title: "Allow Writes",
+        description: "Cut the board as it was picked, rather than only one this run derived."
+    })
+], AssembleTimelineNode.prototype, "allow_writes", void 0);
+export const STORYBOARD_NODES = tagAsServer([
+    LoadStoryboardNode,
+    StoryboardShotsNode,
+    RecastStoryboardNode,
+    RenderStillsNode,
+    RenderClipsNode,
+    AssembleTimelineNode
+]);
+//# sourceMappingURL=storyboard.js.map