videobook 0.0.0-stage → 0.2.0

package/dist/goal-state.js

@@ -0,0 +1,261 @@
+import { notebookGridTag } from "videobook-engine/notebook-grid";
+import { cancelChainRun, getChainRun } from "./chain-executor.js";
+import { coldOpenSource } from "./cold-open.js";
+import { emptyGoalEstimates, findGoalCell, goalContent, requireGoalContent, saveGoal, writeGoalContent } from "./goal-store.js";
+import { GOAL_VIDEO_TOOL, refreshGoalPlanV3 } from "./goal-plan.js";
+import { suggestedColdOpen } from "./lightning-defaults.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { goalStageAttempts, goalStillStaleReason } from "./goal-stills.js";
+export const LEGACY_GOAL_MESSAGE = "Goal mode now starts from character images. Start a new /goal.";
+export function activeGoalStage(goal) {
+    return goal.stage === "assembly" ? "videos" : goal.stage;
+}
+function outputString(outputs, key) {
+    const value = outputs?.[key];
+    return typeof value === "string" ? value : null;
+}
+function producerCell(document, chainId, step) {
+    const tagged = document.cells.filter(cell => cell.inputs?.chainRunId === `${chainId}:${step.id}`).sort((a, b) => b.id.localeCompare(a.id))[0];
+    const outputId = outputString(step.outputs, "cell_id");
+    const edge = document.edges.find(candidate => candidate.target === outputId && candidate.targetInput === "media");
+    return tagged ?? document.cells.find(cell => cell.id === edge?.source);
+}
+function goalChainSteps(engine, document, chainId) {
+    const chain = chainId ? getChainRun(engine, chainId) : null;
+    return chain?.steps.map(step => {
+        const producer = producerCell(document, chain.chainId, step);
+        return {
+            id: step.id, chainId: chain.chainId, status: step.status, error: step.error,
+            artifactId: outputString(step.outputs, "asset_id") ?? outputString(step.outputs, "img_asset_id") ?? outputString(step.outputs, "vid_asset_id"),
+            cellId: producer?.id ?? null,
+            address: producer ? notebookGridTag(producer.slot) : outputString(step.outputs, "address"),
+            outputCellId: outputString(step.outputs, "cell_id"), startedAt: step.startedAt ?? null,
+        };
+    }) ?? [];
+}
+function stageOutputIndex(stepId) {
+    if (stepId === "frame" || stepId === "scene" || stepId === "video")
+        return 0;
+    return Number(/\d+$/u.exec(stepId)?.[0]) - 1;
+}
+function completedStageOutputs(engine, goal, document) {
+    return goalChainSteps(engine, document, goal.chainId).flatMap(step => {
+        if (step.status !== "completed" || !step.artifactId || step.id === "assemble")
+            return [];
+        const index = stageOutputIndex(step.id);
+        if (!Number.isInteger(index) || index < 0)
+            return [];
+        const cell = document.cells.find(candidate => candidate.id === step.outputCellId);
+        return [{ index, artifactId: step.artifactId, cellId: step.outputCellId, producerCellId: step.cellId, address: cell ? notebookGridTag(cell.slot) : null }];
+    });
+}
+function allGoalChainSteps(engine, document, chainId) {
+    return goalChainSteps(engine, document, chainId).flatMap(step => {
+        const producers = document.cells.filter(cell => cell.inputs?.chainRunId === `${chainId}:${step.id}`);
+        if (producers.length === 0)
+            return [step];
+        return producers.map(producer => {
+            const outputCellId = document.edges.find(edge => edge.source === producer.id && edge.targetInput === "media")?.target ?? null;
+            return { ...step, cellId: producer.id, outputCellId, address: notebookGridTag(producer.slot) };
+        });
+    });
+}
+export async function writeGoalCombinationState(engine, goal, error) {
+    if (!goal.combined)
+        return goal;
+    const updated = await mutateNotebook(engine, goal.notebookId, "goal_combine_complete", document => ({
+        ...document, cells: document.cells.map(cell => cell.id === goal.combined?.cellId ? { ...cell, inputs: { ...cell.inputs, state: error ? "error" : "completed" } } : cell),
+    }));
+    if (!updated.ok)
+        throw new Error(updated.error.message);
+    return saveGoal(engine, { ...goal, combined: { ...goal.combined, status: error ? "failed" : "completed", error } });
+}
+export function reconcileFinish(engine, goal) {
+    const finish = goal.finish;
+    if (goal.planVersion !== 3 || !finish || finish.status !== "running")
+        return goal;
+    const job = finish.jobId ? engine.jobs.queue.get(finish.jobId) : null;
+    if (job && ["queued", "running", "completing"].includes(job.state))
+        return goal;
+    if (job?.state === "done") {
+        const result = job.result && typeof job.result === "object" ? job.result : null;
+        const finalArtifactId = finish.finalArtifactId ?? (typeof result?.finalArtifactId === "string" && result.finalArtifactId ? result.finalArtifactId : null);
+        if (finalArtifactId && engine.artifacts.get(finalArtifactId).ok) {
+            const coldOpenArtifactId = finish.coldOpenArtifactId ?? (typeof result?.coldOpenArtifactId === "string" ? result.coldOpenArtifactId : null);
+            return saveGoal(engine, { ...goal, status: "completed", error: null, finish: { ...finish, status: "completed", finalArtifactId, coldOpenArtifactId, error: null } });
+        }
+    }
+    return saveGoal(engine, { ...goal, status: "review", finish: { ...finish, status: "failed", error: job?.error?.message ?? "Finishing was interrupted. Retry the cold open." } });
+}
+async function coldOpenReview(engine, goal) {
+    if (goal.planVersion !== 3 || !goal.finish?.sourceArtifactId)
+        return null;
+    try {
+        const source = await coldOpenSource(engine, goal.finish.sourceArtifactId, goal.finish.sourceObjectHash ?? undefined);
+        const approved = goal.finish.status !== "review" && goal.finish.startSeconds != null && goal.finish.endSeconds != null;
+        const range = approved
+            ? { startSeconds: goal.finish.startSeconds, endSeconds: goal.finish.endSeconds }
+            : suggestedColdOpen(source.durationSeconds);
+        return { ...range, durationSeconds: source.durationSeconds, sourceObjectHash: source.file.objectHash, analysisUsd: 0 };
+    }
+    catch {
+        return null;
+    }
+}
+export async function reconcileGoal(engine, goal, document) {
+    if (goal.planVersion === 1) {
+        if (!["planning", "review", "running"].includes(goal.status))
+            return goal;
+        if (goal.chainId)
+            cancelChainRun(engine, goal.chainId);
+        if (goal.planningJobId)
+            await engine.jobs.queue.abort(goal.planningJobId, LEGACY_GOAL_MESSAGE);
+        return saveGoal(engine, { ...goal, status: "failed", error: LEGACY_GOAL_MESSAGE });
+    }
+    if (goal.combined?.status === "running") {
+        const job = goal.combined.jobId ? engine.jobs.queue.get(goal.combined.jobId) : null;
+        if (!job || ["failed", "aborted"].includes(job.state))
+            goal = await writeGoalCombinationState(engine, goal, job?.error?.message ?? "Combining was interrupted. Retry the combined video.");
+    }
+    if (["completed", "cancelled", "review"].includes(goal.status))
+        return goal;
+    if (goal.status === "planning") {
+        const job = goal.planningJobId ? engine.jobs.queue.get(goal.planningJobId) : null;
+        return job && ["failed", "aborted"].includes(job.state)
+            ? saveGoal(engine, { ...goal, status: "failed", error: job.error?.message ?? "Planning was interrupted" }) : goal;
+    }
+    const stage = activeGoalStage(goal);
+    const run = goal.stages[stage];
+    const chain = run ? getChainRun(engine, run.chainId) : null;
+    if (!run || !chain)
+        return goal;
+    const merged = new Map(run.outputs.map(output => [output.index, output]));
+    for (const output of completedStageOutputs(engine, goal, document))
+        merged.set(output.index, output);
+    const outputs = [...merged.values()].sort((a, b) => a.index - b.index);
+    const attempts = run.attempts?.map(attempt => {
+        if (attempt.artifactId)
+            return attempt;
+        const step = goalChainSteps(engine, document, attempt.chainId).find(candidate => candidate.id === attempt.stepId);
+        return step?.status === "completed" && step.artifactId ? { ...attempt, artifactId: step.artifactId, cellId: step.outputCellId } : attempt;
+    });
+    let next = { ...goal, stages: { ...goal.stages, [stage]: { ...run, outputs, ...(attempts ? { attempts } : {}) } } };
+    const assembled = stage === "videos" && goal.assembly?.artifactIds && JSON.stringify(goal.assembly.artifactIds) === JSON.stringify(outputs.map(output => output.artifactId));
+    if (chain.status === "completed" || assembled && !goal.resumeStage) {
+        const content = requireGoalContent(engine, goal);
+        if (goal.planVersion === 3) {
+            const cleared = { resumeStage: null, resumeStatus: null, resumeOutputs: null, resumeFinish: null };
+            if (outputs.length !== 1)
+                next = { ...next, status: "failed", error: "The stage finished without all of its media outputs. Retry the stage.", ...cleared };
+            else if (stage === "videos") {
+                next = {
+                    ...next, status: "review", error: null, ...cleared,
+                    finish: { status: "review", sourceArtifactId: outputs[0].artifactId, finalArtifactId: null, error: null },
+                };
+            }
+            else {
+                const previousScene = run.outputs[0]?.artifactId ?? null;
+                await writeGoalContent(engine, goal, { ...content, revision: content.revision + 1 });
+                const sceneChanged = previousScene !== null && previousScene !== outputs[0].artifactId;
+                const finish = sceneChanged ? null : goal.finish ?? goal.resumeFinish ?? null;
+                const keepCompleted = finish?.status === "completed" && Boolean(finish.finalArtifactId);
+                next = {
+                    ...next, stage: goal.resumeStage ?? "videos", status: keepCompleted ? "completed" : "review", error: null, ...cleared,
+                    finish,
+                };
+            }
+        }
+        else {
+            const stagedPlan = content.plan && "shots" in content.plan ? content.plan : null;
+            const shotCount = stagedPlan?.shots.length ?? 0;
+            const expected = stage === "frame" ? 1 : stage === "storyboards" && stagedPlan && "frameContinuity" in stagedPlan && stagedPlan.frameContinuity ? 2 * shotCount : shotCount;
+            if (outputs.length !== expected)
+                next = { ...next, status: "failed", error: "The stage finished without all of its media outputs. Retry the stage." };
+            else if (stage === "videos") {
+                next = { ...next, status: goal.assembly || expected === 1 || goal.resumeStage ? "completed" : "failed", error: goal.assembly || expected === 1 || goal.resumeStage ? null : "The finished clips still need to be assembled" };
+                if (goal.combined && JSON.stringify(run.outputs.map(output => output.artifactId)) !== JSON.stringify(outputs.map(output => output.artifactId)))
+                    next.combined = { ...goal.combined, status: "failed", error: "Video selection changed. Assemble the selected clips before combining again." };
+            }
+            else {
+                await writeGoalContent(engine, goal, { ...content, revision: content.revision + 1 });
+                next = { ...next, stage: goal.resumeStage ?? (stage === "frame" ? "storyboards" : "videos"), status: goal.resumeStatus ?? "review", error: null };
+            }
+            next = { ...next, resumeStage: null, resumeStatus: null, resumeOutputs: null };
+        }
+    }
+    else if (["failed", "interrupted", "cancelled"].includes(chain.status)) {
+        next = { ...next, status: chain.status, error: chain.error,
+            ...(goal.resumeOutputs ? { stages: { ...next.stages, [stage]: { ...next.stages[stage], outputs: goal.resumeOutputs } } } : {}),
+        };
+    }
+    else {
+        next = { ...next, stage: chain.steps.some(step => step.id === "assemble" && step.status === "running") ? "assembly" : stage, status: "running", error: null };
+    }
+    return JSON.stringify(next) === JSON.stringify(goal) ? goal : saveGoal(engine, next);
+}
+export async function publicGoal(engine, goal, document) {
+    const cell = findGoalCell(document, goal);
+    const content = cell ? goalContent(cell) : { brief: "", characters: [], revision: 0, plan: null, estimate: emptyGoalEstimates() };
+    const stages = Object.fromEntries(await Promise.all(Object.entries(goal.stages).map(async ([stage, run]) => [stage, {
+            ...run,
+            ...(stage === "videos" ? { attempts: goalStageAttempts(engine, goal, "videos") } : {}),
+            outputs: await Promise.all(run.outputs.map(async (output) => {
+                const outputCell = document.cells.find(candidate => candidate.id === output.cellId);
+                const versions = goalStageAttempts(engine, goal, stage).filter(attempt => attempt.index === output.index).slice().reverse().map(attempt => {
+                    const versionCell = document.cells.find(candidate => candidate.id === attempt.cellId);
+                    const step = getChainRun(engine, attempt.chainId)?.steps.find(candidate => candidate.id === attempt.stepId);
+                    return {
+                        ...attempt, address: versionCell ? notebookGridTag(versionCell.slot) : null,
+                        status: step?.status ?? "interrupted", current: attempt.artifactId === output.artifactId,
+                    };
+                });
+                const stagedPlan = content.plan && "version" in content.plan && content.plan.version === 2 ? content.plan : null;
+                const stale = stagedPlan && (stage === "frame" || stage === "storyboards" || stage === "videos")
+                    ? await goalStillStaleReason(engine, goal, document, stagedPlan, content.characters, stage, output) : null;
+                return { ...output, address: outputCell ? notebookGridTag(outputCell.slot) : null, versions, stale };
+            })),
+            steps: goalChainSteps(engine, document, run.chainId),
+            allSteps: [...run.previousChainIds, run.chainId].flatMap(chainId => allGoalChainSteps(engine, document, chainId)),
+        }])));
+    const shotPlan = content.plan && "shots" in content.plan ? content.plan : null;
+    const stillCount = shotPlan ? shotPlan.shots.length * ("frameContinuity" in shotPlan && shotPlan.frameContinuity ? 2 : 1) : 1;
+    const displayedPlan = content.plan && "version" in content.plan && content.plan.version === 3 ? refreshGoalPlanV3(content.plan, document) : content.plan;
+    const v3Plan = displayedPlan && "version" in displayedPlan && displayedPlan.version === 3;
+    const still = v3Plan
+        ? goal.stage === "videos" || goal.stage === "assembly" ? content.estimate.videos : content.estimate.frame
+        : goal.stage === "videos"
+            ? { ...content.estimate.storyboards, usd: content.estimate.storyboards.usd === null ? null : content.estimate.storyboards.usd / stillCount }
+            : content.estimate.frame;
+    return {
+        kind: "video-goal", ...goal, ...content, plan: displayedPlan,
+        finish: goal.finish ?? null,
+        finalArtifactId: goal.finish?.finalArtifactId ?? null,
+        coldOpen: await coldOpenReview(engine, goal),
+        estimate: { ...content.estimate, still },
+        address: cell ? notebookGridTag(cell.slot) : null,
+        assemblyStale: goalAssemblyStale(engine, goal),
+        stages: stages,
+        steps: goalChainSteps(engine, document, goal.chainId),
+    };
+}
+export function goalAssemblyStale(engine, goal) {
+    if (!goal.assembly)
+        return false;
+    const clips = engine.sequences.getPrimary().clips;
+    const sources = goal.assembly.artifactIds ?? goal.clipIds.map(id => clips.find(clip => clip.clipId === id)?.source.artifactId ?? null);
+    return JSON.stringify(sources) !== JSON.stringify(completedGoalVideos(engine, goal));
+}
+export function completedGoalVideos(engine, goal) {
+    const run = goal.stages.videos;
+    const selected = new Map((run?.outputs ?? []).map(output => [output.index, output.artifactId]));
+    const chainId = run?.chainId ?? (goal.planVersion === 1 ? goal.chainId : null);
+    if (goal.status === "running" || selected.size === 0) {
+        for (const step of chainId ? getChainRun(engine, chainId)?.steps ?? [] : []) {
+            const id = outputString(step.outputs, "asset_id") ?? outputString(step.outputs, "vid_asset_id");
+            const index = stageOutputIndex(step.id);
+            if (step.tool === GOAL_VIDEO_TOOL && step.status === "completed" && id && Number.isInteger(index) && index >= 0)
+                selected.set(index, id);
+        }
+    }
+    return [...selected.entries()].sort(([left], [right]) => left - right).map(([, id]) => id);
+}

package/dist/goal-stills.js

@@ -0,0 +1,153 @@
+import { resolveNotebookCellArtifactId } from "videobook-engine";
+import { notebookGridTag } from "videobook-engine/notebook-grid";
+import { getChainRun } from "./chain-executor.js";
+import { compileFrameSteps, compileStoryboardSteps, goalStillPrompt } from "./goal-plan.js";
+import { goalReferenceHashes } from "./goal-reference-images.js";
+function goalStepIndex(stage, stepId) {
+    if (stage === "frame" || stepId === "frame" || stepId === "scene" || stepId === "video")
+        return 0;
+    return Number(/\d+$/u.exec(stepId)?.[0]) - 1;
+}
+export async function goalV3Fingerprint(engine, plan, stage, sceneArtifactId) {
+    const ids = stage === "frame"
+        ? plan.scene.imageRefs.map(reference => reference.artifactId)
+        : [...plan.video.imageRefs, ...plan.video.videoRefs].map(reference => reference.artifactId);
+    return JSON.stringify({
+        prompt: stage === "frame" ? plan.scene.prompt : plan.video.prompt,
+        settings: stage === "frame"
+            ? { model: plan.scene.model, aspectRatio: plan.scene.aspectRatio, resolution: plan.scene.resolution, outputFormat: plan.scene.outputFormat }
+            : { aspectRatio: plan.video.aspectRatio, resolution: plan.video.resolution, duration: plan.video.durationSeconds, audio: plan.video.generateAudio, outputFormat: plan.video.outputFormat },
+        references: await goalReferenceHashes(engine, ids),
+        ...(stage === "videos" ? { sceneArtifactId } : {}),
+    });
+}
+export async function goalStageFingerprint(engine, goal, plan, characters, stage, index) {
+    const ids = characters.map(character => character.artifactId);
+    if (stage !== "frame")
+        ids.push(goal.stages.frame?.outputs[0]?.artifactId ?? "");
+    if (stage === "videos") {
+        ids.push(goal.stages.storyboards?.outputs.find(output => output.index === index)?.artifactId ?? "");
+        if (plan.frameContinuity)
+            ids.push(goal.stages.storyboards?.outputs.find(output => output.index === index + plan.shots.length)?.artifactId ?? "");
+    }
+    return JSON.stringify({
+        prompt: stage === "videos" ? plan.shots[index]?.videoPrompt : goalStillPrompt(plan, stage, index),
+        aspectRatio: plan.aspectRatio, style: { id: plan.style.id, options: Object.entries(plan.style.options).sort() },
+        referenceRoles: plan.referenceRoles ?? [], references: await goalReferenceHashes(engine, ids),
+        ...(stage === "videos" ? { duration: plan.shots[index]?.durationSeconds, resolution: plan.videoResolution, audio: true }
+            : { model: plan.imageModel, resolution: plan.imageResolution, ...(stage === "frame" ? { continuity: plan.continuity } : { layout: plan.storyboardLayout ?? "four-panel" }) }),
+    });
+}
+export async function goalAttemptFingerprints(engine, goal, plan, characters, stage, steps) {
+    return Object.fromEntries(await Promise.all(steps.filter(step => step.id !== "assemble").map(async (step) => [step.id, await goalStageFingerprint(engine, goal, plan, characters, stage, goalStepIndex(stage, step.id))])));
+}
+export function goalStageAttempts(engine, goal, stage) {
+    const run = goal.stages[stage];
+    const attempts = [...(run?.attempts ?? [])];
+    if (!run || stage !== "videos")
+        return attempts;
+    for (const chainId of [...run.previousChainIds, run.chainId]) {
+        for (const step of getChainRun(engine, chainId)?.steps ?? []) {
+            const artifactId = step.outputs?.asset_id ?? step.outputs?.vid_asset_id;
+            if (!/^shot\d+$/u.test(step.id) || step.status !== "completed" || typeof artifactId !== "string" || attempts.some(attempt => attempt.chainId === chainId && attempt.stepId === step.id))
+                continue;
+            attempts.push({
+                stage, index: goalStepIndex(stage, step.id), chainId, stepId: step.id, artifactId,
+                cellId: typeof step.outputs?.cell_id === "string" ? step.outputs.cell_id : null,
+                basePrompt: typeof step.params.prompt === "string" ? step.params.prompt.split("\n\n")[0] : "",
+                feedback: null, parentArtifactId: null, frameArtifactId: null, createdAt: run.approvedAt,
+            });
+        }
+    }
+    return attempts;
+}
+export function goalStillAttempts(goal, plan, stage, chainId, steps, createdAt, feedback = null, fingerprints, history = goal.stages[stage]?.attempts ?? []) {
+    return [...history, ...steps.filter(step => step.id !== "assemble").map(step => {
+            const index = goalStepIndex(stage, step.id);
+            return {
+                stage, index, chainId, stepId: step.id, artifactId: null, cellId: null,
+                basePrompt: stage === "videos" ? plan.shots[index].videoPrompt : goalStillPrompt(plan, stage, index), feedback,
+                ...(fingerprints?.[step.id] ? { fingerprint: fingerprints[step.id] } : {}),
+                ...(stage === "storyboards" && index < plan.shots.length ? { storyboardLayout: plan.storyboardLayout ?? "four-panel" } : {}),
+                parentArtifactId: feedback ? goal.stages[stage]?.outputs.find(output => output.index === index)?.artifactId ?? null : null,
+                frameArtifactId: stage === "storyboards" ? goal.stages.frame?.outputs[0]?.artifactId ?? null : null,
+                createdAt,
+            };
+        })];
+}
+function legacyStillPrompt(plan, characters, stage, index) {
+    const references = characters.map((character, position) => `@image${position + (stage === "storyboards" ? 2 : 1)} is Character ${position + 1}: ${character.label.replace(/@[\p{L}\p{N}_-]+/gu, "").slice(0, 160)}`);
+    if (stage === "frame")
+        return `${plan.continuity}\n\n${plan.frame.prompt}\n\nReferences: ${references.join("; ")}.`;
+    references.unshift("@image1 is the approved full frame; preserve its setting and visual style");
+    const shotIndex = index % plan.shots.length;
+    const shot = plan.shots[shotIndex];
+    const next = plan.shots[shotIndex + 1];
+    const ending = `Create one still image of the final moment of this shot, with the characters in their ending poses. ${shot.endingPrompt ?? shot.videoPrompt}${next ? `\nPrepare a natural transition into the next shot's opening composition: ${next.storyboardPrompt}` : "\nShow the final payoff with a clear, settled composition."}`;
+    return `${plan.continuity}\n\nShot ${shotIndex + 1}: ${shot.title}\n${index < plan.shots.length ? shot.storyboardPrompt : ending}\n\nReferences: ${references.join("; ")}.`;
+}
+function preStyleStillPrompt(plan, characters, stage, index) {
+    const references = characters.map((_, position) => `@image${position + (stage === "storyboards" ? 2 : 1)} is Character ${position + 1}`);
+    if (stage === "frame")
+        return `${plan.continuity}\n\n${plan.frame.prompt}\n\nReferences: ${references.join("; ")}.`;
+    references.unshift("@image1 is the full frame; keep its characters, setting and style");
+    const shot = plan.shots[index % plan.shots.length];
+    return `One ending frame. ${shot.endingPrompt ?? `Final moment: ${shot.videoPrompt}`}\n\nReferences: ${references.join("; ")}.`;
+}
+export async function goalStillStaleReason(engine, goal, document, plan, characters, stage, output) {
+    const cell = document.cells.find(candidate => candidate.id === output.cellId);
+    if (!cell || resolveNotebookCellArtifactId(document, cell) !== output.artifactId)
+        return "The selected output changed or was removed. Choose another version or regenerate it.";
+    if (characters.some(character => !document.cells.some(candidate => candidate.id === character.cellId && resolveNotebookCellArtifactId(document, candidate) === character.artifactId)))
+        return "A source reference changed or was removed.";
+    const attempt = goalStageAttempts(engine, goal, stage).find(item => item.index === output.index && item.artifactId === output.artifactId);
+    if (attempt?.fingerprint && attempt.fingerprint !== await goalStageFingerprint(engine, goal, plan, characters, stage, output.index))
+        return `${stage === "frame" ? "Scene" : stage === "storyboards" ? "Storyboard" : "Video"} uses older settings, prompts or references. Revise or regenerate it.`;
+    if (stage !== "frame") {
+        const frame = goal.stages.frame?.outputs[0];
+        if (!frame || await goalStillStaleReason(engine, goal, document, plan, characters, "frame", frame))
+            return "The scene has changed. Refresh it before continuing.";
+    }
+    if (stage === "videos") {
+        const indexes = [output.index, ...(plan.frameContinuity ? [output.index + plan.shots.length] : [])];
+        for (const index of indexes) {
+            const board = goal.stages.storyboards?.outputs.find(item => item.index === index);
+            if (!board || await goalStillStaleReason(engine, goal, document, plan, characters, "storyboards", board))
+                return "The storyboard has changed. Refresh it before generating video.";
+        }
+        if (attempt && !attempt.fingerprint) {
+            const step = getChainRun(engine, attempt.chainId)?.steps.find(item => item.id === attempt.stepId);
+            const expected = indexes.map(index => goal.stages.storyboards?.outputs.find(item => item.index === index)?.artifactId);
+            if (expected.some((id, index) => id !== step?.pins[index]?.artifactId))
+                return "Video uses an older storyboard. Revise or regenerate it.";
+        }
+        return attempt && attempt.basePrompt !== plan.shots[output.index]?.videoPrompt ? "Video uses older directions. Revise or regenerate it." : null;
+    }
+    if (attempt?.fingerprint)
+        return null;
+    const name = stage === "frame" ? "Full frame" : `${output.index >= plan.shots.length ? "Ending frame" : "Storyboard"} ${output.index % plan.shots.length + 1}`;
+    const run = goal.stages[stage];
+    if (stage === "storyboards" && output.index < plan.shots.length && attempt?.storyboardLayout !== (plan.storyboardLayout ?? "four-panel")) {
+        return `${name} is a legacy single-frame preview. Regenerate or revise it to create a four-panel storyboard.`;
+    }
+    const promptError = `${name} was made from an older prompt. Regenerate or revise it, or restore the prompt.`;
+    const frameError = `${name} was made from an older full frame. Regenerate the storyboards.`;
+    if (attempt) {
+        if (attempt.basePrompt !== goalStillPrompt(plan, stage, output.index))
+            return promptError;
+        if (stage === "storyboards" && attempt.frameArtifactId !== goal.stages.frame?.outputs[0]?.artifactId)
+            return frameError;
+        return null;
+    }
+    const source = run && [...run.previousChainIds, run.chainId].flatMap(id => getChainRun(engine, id)?.steps ?? [])
+        .find(step => step.id === (stage === "frame" ? "frame" : `storyboard${output.index + 1}`) && (step.outputs?.asset_id ?? step.outputs?.img_asset_id) === output.artifactId);
+    const frameOutput = goal.stages.frame?.outputs[0];
+    if (stage === "storyboards" && source?.pins[0]?.artifactId !== frameOutput?.artifactId)
+        return frameError;
+    const frameCell = document.cells.find(cell => cell.id === frameOutput?.cellId);
+    const compiled = stage === "frame" ? compileFrameSteps(plan, characters)[0]
+        : compileStoryboardSteps(plan, characters, frameCell ? notebookGridTag(frameCell.slot) : "", [output.index % plan.shots.length])
+            .find(step => step.id === `storyboard${output.index + 1}`);
+    return source?.params.prompt === compiled?.params.prompt || plan.style.id === "cinematic" && (source?.params.prompt === legacyStillPrompt(plan, characters, stage, output.index)
+        || source?.params.prompt === preStyleStillPrompt(plan, characters, stage, output.index)) ? null : promptError;
+}

package/dist/goal-store.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { firstEmptyNotebookGridSlot, notebookOccupiedSlots } from "videobook-engine/notebook-grid";
+import { goalMediaRefSchema, goalPlanSchema, goalPlanV3Schema, goalStyleSchema, legacyGoalPlanSchema } from "./goal-plan.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { arrangeGoalNotebook } from "./notebook-goal-layout.js";
+const KEY = "application.goals.v2";
+const LEGACY_KEY = "application.goals.v1";
+const GOAL_TILE_LABEL = "Video goal";
+const REMOVED_TILE_ERROR = "This goal's tile was removed from the notebook";
+function goalStore(engine) {
+    const legacy = engine.settings.get(LEGACY_KEY) ?? {};
+    return {
+        ...Object.fromEntries(Object.entries(legacy).map(([id, goal]) => [id, { ...goal, planVersion: 1, stage: "videos", stages: {} }])),
+        ...(engine.settings.get(KEY) ?? {}),
+    };
+}
+function hasTile(goal) {
+    return typeof goal.cellId === "string";
+}
+export function listGoals(engine, notebookId) {
+    return Object.values(goalStore(engine))
+        .filter((goal) => goal.notebookId === notebookId && hasTile(goal))
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export function readGoal(engine, goalId) {
+    const goal = goalStore(engine)[goalId];
+    if (!goal || !hasTile(goal) || goal.bookId !== engine.book.get().bookId)
+        throw new Error("Goal not found in this book");
+    return goal;
+}
+export function saveGoal(engine, goal) {
+    const next = { ...goal, updatedAt: new Date().toISOString() };
+    const result = engine.settings.set(KEY, { ...(engine.settings.get(KEY) ?? {}), [goal.goalId]: next });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    return next;
+}
+function estimateFrom(value) {
+    const record = value && typeof value === "object" ? value : {};
+    return {
+        usd: typeof record.usd === "number" && Number.isFinite(record.usd) ? record.usd : null,
+        warnings: Array.isArray(record.warnings) ? record.warnings.filter((entry) => typeof entry === "string") : [],
+    };
+}
+export function emptyGoalEstimates() {
+    return { frame: { usd: null, warnings: [] }, storyboards: { usd: null, warnings: [] }, videos: { usd: null, warnings: [] }, total: { usd: null, warnings: [] } };
+}
+function estimatesFrom(value) {
+    const record = value && typeof value === "object" ? value : {};
+    if (!("total" in record))
+        return { ...emptyGoalEstimates(), videos: estimateFrom(value), total: estimateFrom(value) };
+    return { frame: estimateFrom(record.frame), storyboards: estimateFrom(record.storyboards), videos: estimateFrom(record.videos), total: estimateFrom(record.total) };
+}
+function charactersFrom(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => entry && typeof entry === "object"
+        && ["artifactId", "cellId", "address", "label"].every(key => typeof entry[key] === "string"));
+}
+function mediaFrom(value) {
+    const parsed = z.array(z.unknown()).safeParse(value);
+    if (!parsed.success)
+        return [];
+    return parsed.data.flatMap(entry => {
+        const media = goalMediaRefSchema.safeParse(entry);
+        return media.success ? [media.data] : [];
+    });
+}
+export function goalContent(cell) {
+    const inputs = cell.inputs ?? {};
+    const plan = z.union([goalPlanV3Schema, goalPlanSchema, legacyGoalPlanSchema]).safeParse(inputs.plan);
+    const requestedStyle = goalStyleSchema.safeParse(inputs.requestedStyle);
+    const media = mediaFrom(inputs.media);
+    return {
+        brief: cell.prompt ?? "",
+        characters: charactersFrom(inputs.characters),
+        ...(media.length > 0 ? { media } : {}),
+        revision: typeof inputs.revision === "number" && Number.isInteger(inputs.revision) ? inputs.revision : 0,
+        plan: plan.success ? plan.data : null,
+        ...(!plan.success && requestedStyle.success ? { requestedStyle: requestedStyle.data } : {}),
+        estimate: estimatesFrom(inputs.estimate),
+    };
+}
+function goalCellInputs(goalId, content) {
+    return { goalId, revision: content.revision, plan: content.plan, characters: content.characters, estimate: content.estimate,
+        ...(content.media ? { media: content.media } : {}),
+        ...(!content.plan && content.requestedStyle ? { requestedStyle: content.requestedStyle } : {}),
+    };
+}
+function goalCellText(content) {
+    return { label: content.plan?.title ?? GOAL_TILE_LABEL, prompt: content.brief };
+}
+export function findGoalCell(document, goal) {
+    return document.cells.find((cell) => cell.id === goal.cellId && cell.type === "goal") ?? null;
+}
+export function readGoalCell(engine, goal) {
+    const notebook = engine.notebooks.read(goal.notebookId);
+    if (!notebook.ok)
+        throw new Error(notebook.error.message);
+    return findGoalCell(notebook.value, goal);
+}
+export function requireGoalContent(engine, goal) {
+    const cell = readGoalCell(engine, goal);
+    if (!cell)
+        throw new Error(REMOVED_TILE_ERROR);
+    return goalContent(cell);
+}
+export async function createGoalCell(engine, notebookId, goalId, content) {
+    const created = { cell: null };
+    const result = await mutateNotebook(engine, notebookId, "goal_create", (document) => {
+        const cell = engine.notebooks.createCell({
+            type: "goal",
+            ...goalCellText(content),
+            slot: firstEmptyNotebookGridSlot(notebookOccupiedSlots(document.cells)),
+            inputs: goalCellInputs(goalId, content),
+        });
+        created.cell = cell;
+        const edges = content.characters.map((character, index) => engine.notebooks.createEdge({
+            source: character.cellId, target: cell.id, targetInput: index === 0 ? "character" : `character_${index + 1}`,
+        }));
+        const arranged = arrangeGoalNotebook({ ...document, cells: [...document.cells, cell], edges: [...document.edges, ...edges] });
+        created.cell = arranged.cells.find(candidate => candidate.id === cell.id);
+        return arranged;
+    }, { goalId });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    if (!created.cell)
+        throw new Error("The goal tile could not be placed");
+    return created.cell;
+}
+export async function writeGoalContent(engine, goal, content) {
+    const result = await mutateNotebook(engine, goal.notebookId, "goal_plan", (document) => {
+        if (!findGoalCell(document, goal))
+            throw new Error(REMOVED_TILE_ERROR);
+        return {
+            ...document,
+            cells: document.cells.map((cell) => cell.id === goal.cellId
+                ? { ...cell, ...goalCellText(content), inputs: goalCellInputs(goal.goalId, content) }
+                : cell),
+        };
+    }, { goalId: goal.goalId });
+    if (!result.ok)
+        throw new Error(result.error.message);
+}