videobook 0.0.0-stage → 0.1.0

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);
+}

package/dist/goal-styles.js

@@ -0,0 +1,144 @@
+export const GOAL_STYLE_IDS = ["source", "cinematic", "ig-influencer"];
+const styles = {
+    source: {
+        id: "source", label: "Match source", summary: "Keep the look, camera and lighting of the source screenshot.",
+        briefKeywords: [], defaults: { imageModel: "nano-banana-2-1", imageResolution: "2K", videoResolution: "720p" },
+        planner: "Infer the visual style, framing, lighting and camera from the scene reference. Preserve that look. Identify the scene screenshot, character references and prop references from the actual images and brief. Reference images are not necessarily people. Remove social-media interface overlays from generated pictures.",
+        fragments: {
+            frame: "Match the source scene's framing, lighting and visual style; remove interface overlays",
+            storyboard: "Keep the approved scene's visual style, people and props",
+            ending: "Keep the approved scene's visual style",
+            video: "Match the approved scene's camera and lighting; natural ambient sound",
+            revise: "Preserve the selected image's visual style",
+        },
+        banned: [], options: [],
+    },
+    cinematic: {
+        id: "cinematic", label: "Cinematic", summary: "Photographic live-action with natural proportions, textures and motion.",
+        briefKeywords: ["cinematic"], defaults: {},
+        planner: "Photographic live-action. Natural proportions, real skin and material textures, practical light. Restrained expressions and plausible motion. Comedy comes from situations and timing; avoid cartoon rendering, caricature, rubbery movement and exaggerated features.",
+        fragments: {
+            frame: "Photographic live-action, natural proportions, real textures",
+            storyboard: "Photographic live-action, natural proportions, real textures",
+            ending: "Photographic live-action, natural proportions, real textures",
+            video: "Live-action, natural motion, restrained expressions",
+            revise: "Photographic live-action, natural proportions, real textures",
+        },
+        banned: [], options: [],
+    },
+    "ig-influencer": {
+        id: "ig-influencer", label: "IG Influencer", summary: "Hyper-realistic, candid iPhone footage with natural skin and light.",
+        briefKeywords: ["ig influencer", "instagram influencer", "influencer", "insta reel", "instagram reel"],
+        defaults: { aspectRatio: "9:16", imageModel: "sunburst", imageResolution: "2K", videoResolution: "720p" },
+        planner: "Use a hyper-realistic Instagram phone-camera register: real-world activity in present tense, one location per shot, candid framing with slight imperfection, light grain, unretouched skin with visible pores and texture. Use the selected iPhone camera and lighting; natural daylight or soft indoor light by default. No HDR crunch or beautify. No captions or on-screen text inside pictures or video; storyboard notes go below pictures. Avoid cinematic, masterpiece, editorial, Portra, Cinestill and all film-stock vocabulary. Match the delivery: address the camera for selfies, be caught mid-action when filmed by a friend, hold framing steady on a tripod, or show the reflection for a mirror shot. Make the selected content format explicit in the four beats. Sound is ambient room or street sound with an optional short spoken line.",
+        fragments: {
+            frame: "hyper-realistic, skin pores, light grain",
+            storyboard: "hyper-realistic, skin pores, light grain",
+            ending: "hyper-realistic, skin pores",
+            video: "hyper-realistic skin pores, natural motion, handheld micro-shake, ambient sound",
+            revise: "hyper-realistic, skin pores",
+        },
+        banned: ["cinematic", "masterpiece", "editorial", "Portra", "Cinestill"],
+        options: [
+            {
+                key: "format", label: "Content format", default: "day-in-the-life",
+                choices: [
+                    { value: "grwm", label: "GRWM", prompt: "GRWM", briefKeywords: ["grwm", "get ready with me"], beats: "skincare, outfit, final look, mirror check" },
+                    { value: "ootd", label: "OOTD", prompt: "OOTD", briefKeywords: ["ootd", "outfit of the day"], beats: "reveal, details, walk, turn" },
+                    { value: "day-in-the-life", label: "Day in the life", prompt: "day-in-the-life", briefKeywords: ["day in the life", "vlog"], beats: "arrive, begin activity, react, finish" },
+                    { value: "travel-reel", label: "Travel reel", prompt: "travel", briefKeywords: ["travel reel"], beats: "arrive, explore, discover, farewell" },
+                    { value: "cafe", label: "Café", prompt: "café", briefKeywords: ["brunch", "cafe", "café"], beats: "order, receive drink, taste, smile" },
+                    { value: "gym", label: "Gym", prompt: "gym", briefKeywords: ["gym"], beats: "warm up, exercise, effort, recover" },
+                    { value: "skincare", label: "Skincare", prompt: "skincare", briefKeywords: ["skincare"], beats: "cleanse, apply, massage, reveal" },
+                    { value: "haul", label: "Haul", prompt: "haul", briefKeywords: ["haul"], beats: "unpack, show item, try on, react" },
+                    { value: "storytime", label: "Storytime", prompt: "storytime", briefKeywords: ["storytime"], beats: "hook, explain, react, conclude" },
+                ],
+            },
+            {
+                key: "delivery", label: "Delivery", default: "selfie-to-camera",
+                choices: [
+                    { value: "selfie-to-camera", label: "Selfie to camera", prompt: "selfie", briefKeywords: ["selfie", "front camera"] },
+                    { value: "filmed-by-friend", label: "Filmed by a friend", prompt: "friend-filmed", briefKeywords: ["filmed by"] },
+                    { value: "tripod", label: "Tripod", prompt: "tripod", briefKeywords: ["tripod"] },
+                    { value: "mirror", label: "Mirror", prompt: "mirror", briefKeywords: ["mirror"] },
+                ],
+            },
+            {
+                key: "camera", label: "Camera", default: "iphone-front",
+                choices: [
+                    { value: "iphone-front", label: "iPhone front camera", prompt: "iPhone front", briefKeywords: ["front camera", "iphone front"] },
+                    { value: "iphone-main", label: "iPhone main camera", prompt: "iPhone main", briefKeywords: ["main camera", "iphone main"] },
+                ],
+            },
+            {
+                key: "light", label: "Light", default: "soft-daylight",
+                choices: [
+                    { value: "soft-daylight", label: "Soft daylight", prompt: "soft daylight", briefKeywords: ["soft daylight", "natural daylight"] },
+                    { value: "golden-hour", label: "Golden hour", prompt: "golden hour", briefKeywords: ["golden hour"] },
+                    { value: "indoor-warm", label: "Warm indoor light", prompt: "warm indoor", briefKeywords: ["warm indoor", "indoor warm"] },
+                    { value: "night-flash", label: "Night flash", prompt: "night flash", briefKeywords: ["night out", "flash"] },
+                ],
+            },
+        ],
+    },
+};
+export function goalStyle(id) {
+    return styles[id];
+}
+export function resolveGoalStyleOptions(id, partial = {}) {
+    const style = goalStyle(id);
+    for (const key of Object.keys(partial)) {
+        if (!style.options.some(option => option.key === key))
+            throw new Error(`Unknown ${style.label} option: ${key}`);
+    }
+    const resolved = {};
+    for (const option of style.options) {
+        const fallback = option.key === "camera" && resolved.delivery !== "selfie-to-camera" ? "iphone-main" : option.default;
+        const value = partial[option.key] ?? fallback;
+        if (!option.choices.some(choice => choice.value === value)) {
+            throw new Error(`Invalid ${style.label} ${option.label}: ${value}. Choose ${option.choices.map(choice => choice.value).join(", ")}.`);
+        }
+        resolved[option.key] = value;
+    }
+    return resolved;
+}
+export function goalStyleFragment(selection, stage) {
+    const style = goalStyle(selection.id);
+    const options = resolveGoalStyleOptions(selection.id, selection.options);
+    let fragment = style.fragments[stage];
+    if (!fragment)
+        return "";
+    if (stage === "video" && options.delivery === "tripod")
+        fragment = fragment.replace("handheld micro-shake", "steady framing");
+    const pieces = style.options.map(option => option.choices.find(choice => choice.value === options[option.key]).prompt);
+    return `${pieces.length ? `${pieces.join(", ")}: ` : ""}${fragment}.`;
+}
+export function goalStyleSummary(selection) {
+    const style = goalStyle(selection.id);
+    const options = resolveGoalStyleOptions(selection.id, selection.options);
+    return [style.label, ...style.options.map(option => option.choices.find(choice => choice.value === options[option.key]).label)].join(" · ");
+}
+export function goalStylesEqual(left, right) {
+    if (left.id !== right.id)
+        return false;
+    const a = resolveGoalStyleOptions(left.id, left.options);
+    const b = resolveGoalStyleOptions(right.id, right.options);
+    return Object.keys(a).every(key => a[key] === b[key]);
+}
+function firstKeyword(brief, keywords) {
+    return Math.min(...keywords.map(keyword => {
+        const pattern = keyword.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&").replace(/[ -]+/gu, "[\\s-]+");
+        const match = new RegExp(`(^|[^\\p{L}\\p{N}_-])${pattern}(?=$|[^\\p{L}\\p{N}_-])`, "iu").exec(brief);
+        return match ? match.index + match[1].length : Infinity;
+    }));
+}
+export function goalBriefStyle(brief) {
+    const style = GOAL_STYLE_IDS.map(id => ({ style: goalStyle(id), index: firstKeyword(brief, goalStyle(id).briefKeywords) }))
+        .filter(match => Number.isFinite(match.index)).sort((left, right) => left.index - right.index)[0]?.style ?? goalStyle("source");
+    const partial = Object.fromEntries(style.options.flatMap(option => {
+        const choice = option.choices.map(candidate => ({ value: candidate.value, index: firstKeyword(brief, candidate.briefKeywords) }))
+            .filter(match => Number.isFinite(match.index)).sort((left, right) => left.index - right.index)[0];
+        return choice ? [[option.key, choice.value]] : [];
+    }));
+    return { id: style.id, options: resolveGoalStyleOptions(style.id, partial) };
+}

package/dist/goal-v3-runtime.js

@@ -0,0 +1,157 @@
+import { join } from "node:path";
+import { v7 as uuidv7 } from "uuid";
+import { findPrimaryMediaFile, nextHorizontalSlotFrom } from "videobook-engine";
+import { notebookGridTag, notebookOccupiedSlots } from "videobook-engine/notebook-grid";
+import { scanNotebookMentions } from "videobook-engine/notebook-mentions";
+import { probeVideo } from "./ffmpeg.js";
+import { closestGoalAspectRatio, compileGoalV3Steps } from "./goal-plan-v3.js";
+import { captureFrame } from "./notebook-media-ops.js";
+import { EXTRACT_FRAME_OUTPUT_ROLE } from "./notebook-cell-outputs.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { slotRight } from "./notebook-placement.js";
+import { notebookCellFingerprint } from "./jobs/run-notebook.js";
+import { queue } from "./queue.js";
+import { resolveNotebookPromptReferences } from "./notebook-reference-resolver.js";
+import { assessToolCallEstimate } from "./jobs/cost-estimate-assessment.js";
+const GOAL_MEDIA_HELP = "Mention the reference images or videos in the brief, for example /goal @a1 @a2 as ...";
+function mediaKind(kind, cellType) {
+    if (kind === "image" || cellType === "image" || cellType === "generate_image")
+        return "image";
+    if (kind === "video" || kind === "final" || ["video", "generate_video", "concat", "splice", "split_video"].includes(cellType))
+        return "video";
+    return null;
+}
+export async function resolveGoalMediaReferences(engine, document, brief) {
+    if (scanNotebookMentions(brief).length === 0)
+        throw new Error(GOAL_MEDIA_HELP);
+    const resolved = resolveNotebookPromptReferences({ engine, document, prompt: brief, requireMedia: true });
+    if (resolved.unresolved.length > 0)
+        throw new Error(resolved.unresolved[0].message);
+    const references = [];
+    const seen = new Set();
+    for (const reference of resolved.resolved) {
+        if (seen.has(reference.artifactId))
+            continue;
+        const artifact = engine.artifacts.get(reference.artifactId);
+        const cell = document.cells.find(candidate => candidate.id === reference.cellId);
+        const kind = artifact.ok && cell ? mediaKind(artifact.value.kind, cell.type) : null;
+        if (!artifact.ok || !cell || !kind)
+            throw new Error(`${reference.mention} is not an image or video`);
+        const manifest = await engine.files.manifest(reference.artifactId);
+        const file = manifest.ok ? findPrimaryMediaFile(manifest.value.files, kind === "image" ? "image" : "video") : null;
+        if (!manifest.ok || !file)
+            throw new Error(`${reference.mention} has no readable media`);
+        seen.add(reference.artifactId);
+        references.push({
+            kind,
+            artifactId: reference.artifactId,
+            cellId: cell.id,
+            address: notebookGridTag(cell.slot),
+            label: artifact.value.label || cell.label || reference.mention,
+            objectHash: file.objectHash,
+        });
+    }
+    if (references.length === 0)
+        throw new Error(GOAL_MEDIA_HELP);
+    return references;
+}
+async function frameImageFile(engine, artifactId) {
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const file = findPrimaryMediaFile(manifest.value.files, "image");
+    if (!file)
+        throw new Error("The scene frame has no image file");
+    return { path: join(manifest.value.path, file.name), objectHash: file.objectHash };
+}
+async function insertSceneFrameCell(engine, notebookId, video, artifactId, atSeconds) {
+    const placed = { cell: null };
+    const runId = uuidv7();
+    const result = await mutateNotebook(engine, notebookId, "goal_scene_frame", (notebook) => {
+        const anchor = notebook.cells.find(cell => cell.id === video.cellId);
+        if (!anchor)
+            throw new Error(`${video.address} was removed`);
+        const cell = engine.notebooks.createCell({
+            type: "image",
+            label: `Frame at ${atSeconds}s`,
+            slot: nextHorizontalSlotFrom(slotRight(anchor.slot), notebookOccupiedSlots(notebook.cells)),
+            outputArtifactId: artifactId,
+            inputs: { mediaRole: EXTRACT_FRAME_OUTPUT_ROLE, frameMode: "time", timestampSeconds: atSeconds, atSeconds, sourceCellId: anchor.id, state: "completed" },
+        });
+        placed.cell = cell;
+        const completedAt = new Date().toISOString();
+        return {
+            ...notebook,
+            cells: [...notebook.cells, cell],
+            edges: [...notebook.edges, engine.notebooks.createEdge({ source: anchor.id, target: cell.id, targetInput: "segment" })],
+            execution: {
+                ...(notebook.execution ?? {}),
+                [cell.id]: { fingerprint: notebookCellFingerprint(notebook, cell), status: "completed", runId, outputArtifactId: artifactId, completedAt, updatedAt: completedAt, tool: "ffmpeg" },
+            },
+        };
+    }, { sourceCellId: video.cellId, runId }, { artifactId });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    if (!placed.cell)
+        throw new Error("The scene frame could not be placed");
+    return placed.cell;
+}
+export async function captureGoalSceneFrame(engine, notebookId, references) {
+    const video = references.find(reference => reference.kind === "video");
+    if (!video)
+        return null;
+    const captured = await captureFrame(engine, video.artifactId, { role: "time", timestampSeconds: 1, title: `${video.address} · scene frame` });
+    const file = await frameImageFile(engine, captured.artifactId);
+    const probe = await probeVideo(file.path);
+    await queue.enqueue(`process-image-${captured.artifactId}`, {
+        type: "process_image", assetId: captured.artifactId, bookId: engine.book.get().bookId, extension: ".jpg",
+        provenance: { origin: "extract_frame", sourceArtifactId: video.artifactId, frameMode: "time", atSeconds: captured.atSeconds },
+    });
+    const cell = await insertSceneFrameCell(engine, notebookId, video, captured.artifactId, captured.atSeconds);
+    return {
+        reference: {
+            kind: "image", artifactId: captured.artifactId, cellId: cell.id, address: notebookGridTag(cell.slot),
+            label: cell.label ?? "Scene frame", objectHash: file.objectHash,
+        },
+        seconds: captured.atSeconds,
+        aspectRatio: closestGoalAspectRatio(probe.width, probe.height),
+    };
+}
+function estimateInput(engine, plan, step) {
+    const images = (step.id === "video" ? plan.video.imageRefs : plan.scene.imageRefs).map(reference => reference.artifactId);
+    const videos = step.id === "video" ? plan.video.videoRefs.map(reference => reference.artifactId) : [];
+    return {
+        book_id: engine.book.get().bookId,
+        ...step.params,
+        refs: { image: images, video: videos },
+        ...(step.id === "video" && images.length + videos.length > 0 ? { mode: "r2v" } : {}),
+    };
+}
+export async function estimateGoalV3(engine, plan) {
+    const [scene, video] = compileGoalV3Steps(plan);
+    const priced = await Promise.all([scene, video].map(async (step) => {
+        const estimate = await assessToolCallEstimate(engine, step.tool, estimateInput(engine, plan, step));
+        return { usd: estimate.available ? estimate.usd ?? null : null, warnings: estimate.warnings };
+    }));
+    const frame = priced[0];
+    const videos = priced[1];
+    const storyboards = { usd: 0, warnings: [] };
+    const parts = [frame, storyboards, videos];
+    return {
+        frame,
+        storyboards,
+        videos,
+        total: {
+            usd: parts.every(part => part.usd !== null) ? parts.reduce((sum, part) => sum + (part.usd ?? 0), 0) : null,
+            warnings: [...new Set(parts.flatMap(part => part.warnings))],
+        },
+    };
+}
+export function goalMediaCharacters(references) {
+    return references.filter(reference => reference.kind === "image").map(reference => ({
+        artifactId: reference.artifactId,
+        cellId: reference.cellId,
+        address: reference.address,
+        label: reference.label,
+    }));
+}