videobook 0.0.0-stage → 0.2.0

package/dist/goal-plan-v3.js

@@ -0,0 +1,273 @@
+import { z } from "zod";
+import { notebookGridTag } from "videobook-engine/notebook-grid";
+import { goalPromptWords } from "./goal-prompt-budget.js";
+import { LIGHTNING_COLD_OPEN_SECONDS, LIGHTNING_SCENE_ASPECT_RATIO, LIGHTNING_SCENE_MODEL, LIGHTNING_SCENE_OUTPUT_FORMAT, LIGHTNING_SCENE_PROMPT_WORDS, LIGHTNING_SCENE_RESOLUTION, LIGHTNING_VIDEO_DURATION_SECONDS, LIGHTNING_VIDEO_GENERATE_AUDIO, LIGHTNING_VIDEO_OUTPUT_FORMAT, LIGHTNING_VIDEO_PROMPT_WORDS, LIGHTNING_VIDEO_RESOLUTION, LIGHTNING_VIDEO_MODEL, LIGHTNING_WATERMARK_PROFILE, preservedPrompt, } from "./lightning-defaults.js";
+const IMAGE_LIMIT = 30;
+const VIDEO_LIMIT = 10;
+export const goalMediaRefSchema = z.object({
+    kind: z.enum(["image", "video"]),
+    artifactId: z.string().min(1),
+    cellId: z.string().min(1),
+    address: z.string().min(1),
+    label: z.string(),
+    objectHash: z.string().min(1),
+    slot: z.string().regex(/^@(?:image|video)\d+$/u),
+}).strict();
+export const goalPlanV3Schema = z.object({
+    version: z.literal(3),
+    title: z.string().trim().min(1).max(120),
+    aspectRatio: z.enum(["16:9", "9:16", "1:1"]),
+    scene: z.object({
+        prompt: z.string().trim().min(1).max(4000),
+        tool: z.literal("generate_image"),
+        model: z.literal(LIGHTNING_SCENE_MODEL),
+        aspectRatio: z.enum(["16:9", "9:16", "1:1"]),
+        resolution: z.literal(LIGHTNING_SCENE_RESOLUTION),
+        outputFormat: z.literal(LIGHTNING_SCENE_OUTPUT_FORMAT),
+        imageRefs: z.array(goalMediaRefSchema).max(IMAGE_LIMIT),
+    }).strict(),
+    video: z.object({
+        prompt: z.string().trim().min(1).max(4000),
+        tool: z.literal("generate_video"),
+        model: z.literal(LIGHTNING_VIDEO_MODEL),
+        aspectRatio: z.enum(["16:9", "9:16", "1:1", "adaptive"]),
+        resolution: z.literal(LIGHTNING_VIDEO_RESOLUTION),
+        durationSeconds: z.number().int().min(4).max(30),
+        generateAudio: z.literal(true),
+        outputFormat: z.literal(LIGHTNING_VIDEO_OUTPUT_FORMAT),
+        imageRefs: z.array(goalMediaRefSchema).max(IMAGE_LIMIT),
+        videoRefs: z.array(goalMediaRefSchema).max(VIDEO_LIMIT),
+    }).strict(),
+    references: z.array(goalMediaRefSchema).min(1),
+    sampledFrames: z.array(z.object({
+        artifactId: z.string().min(1),
+        objectHash: z.string().min(1),
+        seconds: z.number().nonnegative(),
+    }).strict()),
+    finish: z.object({
+        suggestedColdOpenSeconds: z.number().positive(),
+        watermark: z.object({
+            platform: z.literal("tiktok"),
+            handle: z.string().min(1),
+            profileUrl: z.string().min(1),
+            mode: z.literal("burn"),
+            handleEndSeconds: z.number().nullable(),
+            qrLeadSeconds: z.number().nullable(),
+            handleOpacity: z.number(),
+            qrOpacity: z.number(),
+            fadeSeconds: z.number(),
+        }).strict(),
+    }).strict(),
+}).strict();
+export function isGoalPlanV3(plan) {
+    return plan?.version === 3;
+}
+export function closestGoalAspectRatio(width, height) {
+    const ratio = Math.log(width / height);
+    const candidates = [["16:9", 16 / 9], ["9:16", 9 / 16], ["1:1", 1]];
+    return candidates.reduce((best, candidate) => Math.abs(ratio - Math.log(candidate[1])) < Math.abs(ratio - Math.log(best[1])) ? candidate : best)[0];
+}
+function goalV3Timing(brief, fallbackAspectRatio = LIGHTNING_SCENE_ASPECT_RATIO) {
+    const aspectRatio = /\b(?:9:16|portrait|vertical)\b/iu.test(brief) ? "9:16"
+        : /\b(?:1:1|square)\b/iu.test(brief) ? "1:1"
+            : /\b(?:16:9|landscape|horizontal)\b/iu.test(brief) ? "16:9"
+                : fallbackAspectRatio;
+    const match = /(?:^|\s)(\d+)[ -]*(?:s|secs?|seconds?)\b/iu.exec(brief);
+    const parsed = match ? Number(match[1]) : Number.NaN;
+    const durationSeconds = Number.isInteger(parsed) && parsed >= 4 && parsed <= 30
+        ? parsed
+        : LIGHTNING_VIDEO_DURATION_SECONDS;
+    return { aspectRatio, durationSeconds };
+}
+function briefProse(brief) {
+    return brief.replace(/@[a-z0-9]+/giu, " ").replace(/\s+/gu, " ").trim();
+}
+function quoted(brief, label) {
+    const specific = new RegExp(`(?:^|\\s)${label}\\s*:\\s*["“]([^"”]+)["”]`, "iu").exec(brief);
+    return specific?.[1]?.trim() || null;
+}
+function authoredCopy(brief) {
+    const generic = /["“]([^"”]+)["”]/u.exec(brief)?.[1]?.trim() || null;
+    return {
+        scene: quoted(brief, "scene") ?? quoted(brief, "image") ?? generic,
+        video: quoted(brief, "video") ?? quoted(brief, "clip") ?? generic,
+    };
+}
+function limitedWords(value, maxWords, authored) {
+    if (authored)
+        return preservedPrompt(value, maxWords, true);
+    if (maxWords < 1)
+        return "";
+    return preservedPrompt(value, maxWords, false);
+}
+function promptWithSlots(body, slots, maxWords, authored) {
+    const kept = limitedWords(body, authored ? maxWords : Math.max(0, maxWords - slots.length), authored);
+    const prompt = [kept, ...slots].filter(part => part.length > 0).join(" ").trim();
+    if (!authored && goalPromptWords(prompt) > maxWords) {
+        return [...slots].join(" ");
+    }
+    return prompt.length > 0 ? prompt : slots.join(" ");
+}
+function framePrompt(body, characterSlots, authored) {
+    const instruction = characterSlots.length > 0
+        ? `Place ${characterSlots.join(" and ")} into @image1, keeping its framing, setting and light.`
+        : "Edit @image1, keeping its framing, setting and light.";
+    const kept = limitedWords(body, LIGHTNING_SCENE_PROMPT_WORDS - goalPromptWords(instruction), authored);
+    return [instruction, kept].filter(part => part.length > 0).join(" ");
+}
+function sceneImageRefs(images, frame) {
+    if (!frame)
+        return images.slice(0, IMAGE_LIMIT);
+    return [frame.reference, ...images].slice(0, IMAGE_LIMIT).map((reference, index) => ({ ...reference, slot: `@image${index + 1}` }));
+}
+function titleFrom(body) {
+    const title = body.split(/\s+/u).filter(Boolean).slice(0, 6).join(" ").slice(0, 80).trim();
+    return title.length > 0 ? title : "Video";
+}
+function assignSlots(references) {
+    let images = 0;
+    let videos = 0;
+    return references.map(reference => {
+        const slot = reference.kind === "video" ? `@video${++videos}` : `@image${++images}`;
+        return { ...reference, slot };
+    });
+}
+export function buildGoalPlanV3(input) {
+    const references = assignSlots(input.references);
+    const images = references.filter(reference => reference.kind === "image");
+    const videos = references.filter(reference => reference.kind === "video");
+    const timing = goalV3Timing(input.brief, input.frame?.aspectRatio);
+    const copy = authoredCopy(input.brief);
+    const prose = briefProse(input.brief);
+    const sceneBody = copy.scene ?? prose;
+    const videoBody = copy.video ?? prose;
+    const sceneRefs = sceneImageRefs(images, input.frame);
+    const videoSlots = [...images.slice(0, IMAGE_LIMIT), ...videos.slice(0, VIDEO_LIMIT)].map(reference => reference.slot);
+    const scenePrompt = input.frame
+        ? framePrompt(sceneBody, sceneRefs.slice(1).map(reference => reference.slot), copy.scene !== null)
+        : promptWithSlots(sceneBody, sceneRefs.map(reference => reference.slot), LIGHTNING_SCENE_PROMPT_WORDS, copy.scene !== null);
+    const videoPrompt = promptWithSlots(videoBody, videoSlots, LIGHTNING_VIDEO_PROMPT_WORDS, copy.video !== null);
+    const profile = LIGHTNING_WATERMARK_PROFILE;
+    return goalPlanV3Schema.parse({
+        version: 3,
+        title: titleFrom(sceneBody || videoBody),
+        aspectRatio: timing.aspectRatio,
+        scene: {
+            prompt: scenePrompt,
+            tool: "generate_image",
+            model: LIGHTNING_SCENE_MODEL,
+            aspectRatio: timing.aspectRatio,
+            resolution: LIGHTNING_SCENE_RESOLUTION,
+            outputFormat: LIGHTNING_SCENE_OUTPUT_FORMAT,
+            imageRefs: sceneRefs,
+        },
+        video: {
+            prompt: videoPrompt,
+            tool: "generate_video",
+            model: LIGHTNING_VIDEO_MODEL,
+            aspectRatio: timing.aspectRatio,
+            resolution: LIGHTNING_VIDEO_RESOLUTION,
+            durationSeconds: timing.durationSeconds,
+            generateAudio: LIGHTNING_VIDEO_GENERATE_AUDIO,
+            outputFormat: LIGHTNING_VIDEO_OUTPUT_FORMAT,
+            imageRefs: images.slice(0, IMAGE_LIMIT),
+            videoRefs: videos.slice(0, VIDEO_LIMIT),
+        },
+        references,
+        sampledFrames: input.frame
+            ? [{ artifactId: input.frame.reference.artifactId, objectHash: input.frame.reference.objectHash, seconds: input.frame.seconds }]
+            : [],
+        finish: {
+            suggestedColdOpenSeconds: LIGHTNING_COLD_OPEN_SECONDS,
+            watermark: {
+                platform: "tiktok",
+                handle: profile.handle,
+                profileUrl: profile.profileUrl,
+                mode: "burn",
+                handleEndSeconds: profile.handleEndSeconds,
+                qrLeadSeconds: profile.qrLeadSeconds,
+                handleOpacity: profile.handleOpacity,
+                qrOpacity: profile.qrOpacity,
+                fadeSeconds: profile.fadeSeconds,
+            },
+        },
+    });
+}
+function liveAddress(document, reference) {
+    const cell = document.cells.find(candidate => candidate.id === reference.cellId);
+    return cell ? { ...reference, address: notebookGridTag(cell.slot) } : reference;
+}
+export function refreshGoalPlanV3(plan, document) {
+    const map = (reference) => liveAddress(document, reference);
+    return {
+        ...plan,
+        references: plan.references.map(map),
+        scene: { ...plan.scene, imageRefs: plan.scene.imageRefs.map(map) },
+        video: {
+            ...plan.video,
+            imageRefs: plan.video.imageRefs.map(map),
+            videoRefs: plan.video.videoRefs.map(map),
+        },
+    };
+}
+function refList(params, role) {
+    const refs = params.refs;
+    const list = refs?.[role];
+    return Array.isArray(list) ? list.filter((entry) => typeof entry === "string") : [];
+}
+function withRefs(params, images, videos) {
+    const refs = {
+        ...(images.length > 0 ? { image: [...images] } : {}),
+        ...(videos.length > 0 ? { video: [...videos] } : {}),
+    };
+    const { refs: _previous, mode: _mode, ...rest } = params;
+    return Object.keys(refs).length > 0 ? { ...rest, refs, ...(params.mode ? { mode: params.mode } : {}) } : rest;
+}
+export function compileGoalV3Approval(plan, stage, sceneAddress) {
+    const [scene, video] = compileGoalV3Steps(plan);
+    if (stage === "frame")
+        return { ...scene, params: withRefs(scene.params, refList(scene.params, "image"), []) };
+    const imageRefs = [...new Set([...(sceneAddress ? [sceneAddress] : []), ...refList(video.params, "image")])];
+    return { ...video, params: withRefs(video.params, imageRefs, refList(video.params, "video")) };
+}
+export function compileGoalV3Steps(plan) {
+    const sceneRefs = plan.scene.imageRefs.slice(0, IMAGE_LIMIT);
+    const videoImages = plan.video.imageRefs.slice(0, IMAGE_LIMIT);
+    const videoRefs = plan.video.videoRefs.slice(0, VIDEO_LIMIT);
+    return [
+        {
+            id: "scene",
+            tool: plan.scene.tool,
+            params: {
+                model: plan.scene.model,
+                prompt: plan.scene.prompt,
+                refs: { image: sceneRefs.map(reference => reference.address) },
+                options: {
+                    aspect_ratio: plan.scene.aspectRatio,
+                    resolution: plan.scene.resolution,
+                    output_format: plan.scene.outputFormat,
+                },
+            },
+        },
+        {
+            id: "video",
+            tool: plan.video.tool,
+            params: {
+                model: plan.video.model,
+                prompt: plan.video.prompt,
+                refs: {
+                    image: videoImages.map(reference => reference.address),
+                    video: videoRefs.map(reference => reference.address),
+                },
+                ...(videoImages.length + videoRefs.length > 0 ? { mode: "r2v" } : {}),
+                options: {
+                    aspect_ratio: plan.video.aspectRatio,
+                    resolution: plan.video.resolution,
+                    duration: plan.video.durationSeconds,
+                    generate_audio: plan.video.generateAudio,
+                    output_format: plan.video.outputFormat,
+                },
+            },
+        },
+    ];
+}

package/dist/goal-plan.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { LIGHTNING_VIDEO_MODEL } from "./lightning-defaults.js";
+import { GOAL_PROMPT_BUDGET, goalPromptWords } from "./goal-prompt-budget.js";
+import { GOAL_STYLE_IDS, goalStyleFragment, resolveGoalStyleOptions } from "./goal-styles.js";
+export { compileGoalV3Approval, compileGoalV3Steps, goalMediaRefSchema, goalPlanV3Schema, isGoalPlanV3, refreshGoalPlanV3 } from "./goal-plan-v3.js";
+export { GOAL_PROMPT_BUDGET, goalPromptWords } from "./goal-prompt-budget.js";
+export const GOAL_VIDEO_TOOL = "generate_video";
+export const GOAL_VIDEO_MODEL = LIGHTNING_VIDEO_MODEL;
+const GOAL_IMAGE_MODELS = {
+    "nano-banana-2-1": { text: "kie:nano-banana-2-1", edit: "kie:nano-banana-2-1" },
+    sunburst: { text: "kie:gpt-image-2-5-sunburst-text-to-image", edit: "kie:gpt-image-2-5-sunburst-image-to-image" },
+    flare: { text: "kie:gpt-image-2-5-flare-text-to-image", edit: "kie:gpt-image-2-5-flare-image-to-image" },
+};
+const GOAL_MAX_SHOTS = 8;
+const goalPrompt = (limit) => z.string().trim().min(1).max(limit)
+    .regex(/^[^@]*$/u, "Use Reference 1, Reference 2 and plain text in plan prompts; input references are added automatically");
+export const goalStyleSchema = z.object({
+    id: z.enum(GOAL_STYLE_IDS), options: z.record(z.string(), z.string()),
+}).strict().superRefine((style, context) => {
+    try {
+        resolveGoalStyleOptions(style.id, style.options);
+    }
+    catch (error) {
+        context.addIssue({ code: "custom", path: ["options"], message: error instanceof Error ? error.message : String(error), fatal: true });
+    }
+}).overwrite(style => ({ ...style, options: resolveGoalStyleOptions(style.id, style.options) }));
+export const legacyGoalPlanSchema = z.object({
+    title: z.string().trim().min(1).max(120),
+    continuity: z.string().trim().min(1).max(3000),
+    aspectRatio: z.enum(["16:9", "9:16", "1:1"]),
+    shots: z.array(z.object({
+        title: z.string().trim().min(1).max(120),
+        prompt: z.string().trim().min(1).max(6000),
+        durationSeconds: z.number().int().min(4).max(30),
+    })).min(1).max(GOAL_MAX_SHOTS),
+}).strict();
+export const goalPlanSchema = legacyGoalPlanSchema.extend({
+    version: z.literal(2),
+    style: goalStyleSchema.default({ id: "cinematic", options: {} }),
+    title: goalPrompt(120),
+    continuity: goalPrompt(3000),
+    imageModel: z.enum(["sunburst", "flare", "nano-banana-2-1"]).default("sunburst"),
+    storyboardLayout: z.enum(["four-panel", "six-panel"]).optional(),
+    referenceRoles: z.array(z.enum(["scene", "character", "prop", "reference"])).max(8).optional(),
+    imageResolution: z.enum(["1K", "2K"]).default("2K"),
+    videoResolution: z.enum(["480p", "720p"]).default("720p"),
+    frameContinuity: z.boolean().default(false),
+    frame: z.object({ prompt: goalPrompt(6000) }).strict(),
+    shots: z.array(z.object({
+        title: goalPrompt(120),
+        storyboardPrompt: goalPrompt(6000),
+        endingPrompt: goalPrompt(6000).nullable().default(null),
+        videoPrompt: goalPrompt(6000),
+        durationSeconds: z.number().int().min(4).max(30),
+    }).strict()).min(1).max(GOAL_MAX_SHOTS),
+}).strict();
+export const goalPlannerResponseSchema = goalPlanSchema.extend({
+    storyboardLayout: z.enum(["four-panel", "six-panel"]).default("six-panel"),
+    referenceRoles: z.array(z.enum(["scene", "character", "prop", "reference"])).max(8).default([]),
+    title: goalPrompt(80),
+    continuity: goalPrompt(600),
+    frame: z.object({ prompt: goalPrompt(400) }).strict(),
+    shots: z.array(goalPlanSchema.shape.shots.element.extend({
+        title: goalPrompt(80),
+        storyboardPrompt: goalPrompt(500),
+        endingPrompt: goalPrompt(250).nullable().default(null),
+        videoPrompt: goalPrompt(400),
+    })).min(1).max(GOAL_MAX_SHOTS),
+});
+export function goalPromptBudgetIssues(plan) {
+    const fields = [
+        ["Title", plan.title, GOAL_PROMPT_BUDGET.title],
+        ["Continuity", plan.continuity, GOAL_PROMPT_BUDGET.continuity],
+        ["Frame", plan.frame.prompt, GOAL_PROMPT_BUDGET.frame],
+        ...plan.shots.flatMap((shot, index) => [
+            [`Shot ${index + 1} title`, shot.title, GOAL_PROMPT_BUDGET.title],
+            [`Storyboard ${index + 1}`, shot.storyboardPrompt, plan.storyboardLayout === "six-panel" ? 48 : GOAL_PROMPT_BUDGET.storyboard],
+            [`Ending ${index + 1}`, shot.endingPrompt ?? "", GOAL_PROMPT_BUDGET.ending],
+            [`Video ${index + 1}`, shot.videoPrompt, GOAL_PROMPT_BUDGET.video],
+        ]),
+    ];
+    return fields.flatMap(([label, value, limit]) => {
+        const words = goalPromptWords(value);
+        return words > limit ? [`${label}: ${words} words; limit ${limit}.`] : [];
+    });
+}
+export function goalBriefConstraints(brief) {
+    const words = {
+        one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8,
+        nine: 9, ten: 10, eleven: 11, twelve: 12,
+    };
+    const modifiers = "(?:(?:short|funny|comedic|cinematic|animated|portrait|vertical|square|landscape|horizontal)[ -]+){0,3}";
+    const count = new RegExp(`\\b(\\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\\s+${modifiers}(?:\\d+(?:\\.\\d+)?[ -]*(?:s|secs?|seconds?)[ -]*)?${modifiers}(?:clips?|videos?)\\b`, "iu").exec(brief);
+    const multiplier = /\b(\d+)\s*[x×]\s*(\d+)\s*(?:s|secs?|seconds?)\b/iu.exec(brief);
+    const clipDuration = /\b(\d+(?:\.\d+)?)[ -]*(?:s|secs?|seconds?)[ -]*(?:clips?|shots?|scenes?|each)\b/iu.exec(brief)
+        ?? /\b(?:clips?|shots?|scenes?)\s+(?:of\s+)?(\d+(?:\.\d+)?)[ -]*(?:s|secs?|seconds?)\b/iu.exec(brief);
+    const duration = /\b(\d+(?:\.\d+)?)[ -]*(?:s|secs?|seconds?)\b/iu.exec(brief);
+    const shotCount = count ? words[count[1].toLowerCase()] ?? Number(count[1])
+        : multiplier ? Number(multiplier[1]) : 1;
+    const durationSeconds = multiplier ? Number(multiplier[2]) : clipDuration ? Number(clipDuration[1]) : duration ? Number(duration[1]) : shotCount === 1 ? 20 : 10;
+    if (!Number.isInteger(shotCount) || shotCount < 1 || shotCount > GOAL_MAX_SHOTS) {
+        throw new Error(`A goal supports 1–${GOAL_MAX_SHOTS} clips. Choose a smaller shot count.`);
+    }
+    if (!Number.isInteger(durationSeconds) || durationSeconds < 4 || durationSeconds > 30) {
+        throw new Error("Each goal clip must be a whole number of seconds from 4 to 30.");
+    }
+    const aspectRatio = /\b(?:16:9|landscape|horizontal|widescreen)\b/iu.test(brief) ? "16:9"
+        : /\b(?:1:1|square)\b/iu.test(brief) ? "1:1" : "9:16";
+    return { shotCount, durationSeconds, aspectRatio };
+}
+function styledGoalPrompt(plan, stage, text) {
+    const fragment = goalStyleFragment(plan.style, stage);
+    return fragment ? `${text}\n\n${fragment}` : text;
+}
+function goalReferenceName(plan, index) {
+    return plan.storyboardLayout === "six-panel" ? `Reference ${index + 1} (${plan.referenceRoles?.[index] ?? "reference"})` : `Character ${index + 1}`;
+}
+function goalReferenceLegend(plan, characters, frame = null) {
+    return `${[...(frame ? [plan.storyboardLayout === "six-panel" ? "@image1 approved scene: keep clothes, props, place" : "@image1 full frame: keep clothes, props"] : []), ...characters.map((_, index) => `@image${index + (frame ? 2 : 1)} ${goalReferenceName(plan, index)}`)].join("; ")}.`;
+}
+function goalImageStep(id, plan, prompt, references) {
+    const models = GOAL_IMAGE_MODELS[plan.imageModel];
+    return {
+        id,
+        tool: "generate_image",
+        params: {
+            model: references.length > 0 ? models.edit : models.text,
+            prompt,
+            refs: { image: [...references] },
+            options: {
+                aspect_ratio: plan.aspectRatio,
+                resolution: plan.imageResolution,
+                ...(plan.imageModel === "nano-banana-2-1" ? { output_format: "png" } : { background: "opaque" }),
+            },
+        },
+    };
+}
+export function compileFrameSteps(plan, characters) {
+    return [goalImageStep("frame", plan, `${styledGoalPrompt(plan, "frame", `${plan.continuity}\n\n${plan.frame.prompt}`)}\n\n${goalReferenceLegend(plan, characters)}`, characters.map(character => character.address))];
+}
+function storyboardLayoutPrompt(plan, index) {
+    const six = plan.storyboardLayout === "six-panel";
+    const beat = plan.shots[index].durationSeconds / (six ? 6 : 4);
+    const time = (value) => six ? Number(value.toFixed(1)) : value;
+    const times = Array.from({ length: six ? 6 : 4 }, (_, position) => `${time(position * beat)}–${time((position + 1) * beat)}s`);
+    return `${six ? "2 columns by 3 rows, six-panel" : "2x2"} storyboard. Each ${plan.aspectRatio}. Left-right, top-bottom: ${six ? "hook; setup; action; escalation; reaction; payoff" : "setup; action; reaction; ending"}. Below pictures: timing + action/camera notes. Times: ${times.join("; ")}. Pictures text-free.`;
+}
+export function compileStoryboardSteps(plan, characters, frame, indexes = plan.shots.map((_, index) => index)) {
+    const frames = [...indexes.map(index => ({ index, ending: false })), ...(plan.frameContinuity ? indexes.map(index => ({ index, ending: true })) : [])];
+    return frames.map(({ index, ending }) => goalImageStep(`storyboard${index + 1 + (ending ? plan.shots.length : 0)}`, plan, `${styledGoalPrompt(plan, ending ? "ending" : "storyboard", ending ? `Ending frame. ${goalEndingPrompt(plan, index)}` : `${storyboardLayoutPrompt(plan, index)}\n\n${goalStillPrompt(plan, "storyboards", index)}`)}\n\n${goalReferenceLegend(plan, characters, "full")}`, [frame, ...characters.map(character => character.address)]));
+}
+function goalEndingPrompt(plan, index) {
+    const shot = plan.shots[index];
+    return shot.endingPrompt ?? `Final moment: ${shot.videoPrompt}`;
+}
+export function goalStillPrompt(plan, stage, index) {
+    if (stage === "frame" && index === 0)
+        return plan.frame.prompt;
+    if (stage === "storyboards" && index >= 0 && index < plan.shots.length) {
+        const shot = plan.shots[index];
+        return `Shot ${index + 1}: ${shot.title} (${shot.durationSeconds}s). ${shot.storyboardPrompt}${plan.storyboardLayout === "six-panel" ? "" : `\nAction: ${shot.videoPrompt}`}`;
+    }
+    if (stage === "storyboards" && plan.frameContinuity && index >= plan.shots.length && index < plan.shots.length * 2)
+        return goalEndingPrompt(plan, index - plan.shots.length);
+    throw new Error("There is no still at this stage and index");
+}
+export function compileReviseStillStep(plan, characters, stage, index, current, feedback, frame) {
+    const basePrompt = goalStillPrompt(plan, stage, index);
+    const storyboard = stage === "storyboards" && index < plan.shots.length;
+    if (stage === "storyboards" && !frame)
+        throw new Error("Choose a full frame before revising storyboards");
+    const references = ["@image1: previous version", ...(frame ? ["@image2: full frame"] : []),
+        ...characters.map((_, position) => `@image${position + (frame ? 3 : 2)}: ${goalReferenceName(plan, position)}`)];
+    return goalImageStep(stage === "frame" ? "frame" : `storyboard${index + 1}`, plan, `${styledGoalPrompt(plan, "revise", `${storyboard ? `${storyboardLayoutPrompt(plan, index)}\n\n` : ""}${basePrompt}\n\nChange @image1: ${feedback.replace(/[.!?]+$/u, "")}. Keep rest.${storyboard ? plan.storyboardLayout === "six-panel" ? " Six distinct moments." : " Four distinct moments." : ""}`)}\n\n${references.join("; ")}.`, [current, ...(frame ? [frame] : []), ...characters.map(character => character.address)]);
+}
+function goalShotParams(plan, index, storyboard, ending, options) {
+    const shot = plan.shots[index];
+    const fragment = goalStyleFragment(plan.style, "video");
+    const six = plan.storyboardLayout === "six-panel";
+    const references = [storyboard, ...(ending ? [ending] : []), ...(six && options.frame ? [options.frame] : []), ...(six ? (options.characters ?? []).map(character => character.address) : [])];
+    const sceneSlot = ending ? 3 : 2;
+    const legend = six ? [options.frame ? `@image${sceneSlot} approved scene` : "", ...(options.characters ?? []).map((_, position) => `@image${sceneSlot + (options.frame ? 1 : 0) + position} ${goalReferenceName(plan, position)}`)].filter(Boolean).join("; ") : "";
+    return {
+        model: GOAL_VIDEO_MODEL,
+        prompt: `${shot.videoPrompt}${options.feedback ? `\nRevision: ${options.feedback}` : ""}\n\n@image1 storyboard. ${six ? "Six beats in reading order, follow its timestamps" : `Four beats in order, ${shot.durationSeconds / 4}s each`}. Same people, place. Full-screen.${fragment ? ` ${fragment}` : ""}${ending ? " @image2 ending pose." : ""}${legend ? ` ${legend}.` : ""} No grid, borders, notes, text. No music.`,
+        refs: { image: references },
+        mode: "r2v",
+        options: {
+            duration: shot.durationSeconds,
+            aspect_ratio: plan.aspectRatio,
+            resolution: plan.videoResolution,
+            generate_audio: true,
+        },
+    };
+}
+export function compileVideoSteps(goalId, plan, storyboards, endings = [], options = {}) {
+    if (storyboards.length !== plan.shots.length)
+        throw new Error("Approve a storyboard for every shot before generating videos");
+    if (plan.frameContinuity && endings.length !== plan.shots.length)
+        throw new Error("Approve an ending frame for every shot before generating videos");
+    const steps = [
+        ...(options.indexes ?? plan.shots.map((_, index) => index)).map(index => ({
+            id: `shot${index + 1}`,
+            tool: GOAL_VIDEO_TOOL,
+            params: goalShotParams(plan, index, storyboards[index], plan.frameContinuity ? endings[index] : undefined, options),
+        })),
+    ];
+    if (plan.shots.length > 1 && options.assemble !== false)
+        steps.push({
+            id: "assemble",
+            tool: "assemble_goal",
+            params: {
+                goal_id: goalId,
+                artifact_ids: plan.shots.map((_, index) => ({
+                    $ref: { step_id: `shot${index + 1}`, output: "asset_id" },
+                })),
+            },
+        });
+    return steps;
+}

package/dist/goal-planner-prompt.js

@@ -0,0 +1,28 @@
+import { GOAL_PROMPT_BUDGET, goalBriefConstraints } from "./goal-plan.js";
+import { goalStyle, goalStyleSummary, resolveGoalStyleOptions } from "./goal-styles.js";
+const cinematicInstructions = `Plan video. Return version 2 JSON. Barebones prompts: short noun/verb fragments, present tense. No filler, prose, jargon lists or stacked adjectives. Name inputs Reference 1, Reference 2. Infer referenceRoles in input order: scene, character, prop or reference; use actual pixels and the brief. Continuity: identity, props, place, style once. Frame: the edited scene with the requested characters and props. storyboardLayout: six-panel. Storyboard: six semicolon-separated action/camera notes, hook/setup/action/escalation/reaction/payoff; 2 columns by 3 rows with timestamps and shot notes below pictures. Let the storyboard guide the video. videoPrompt: only essential motion and sound; do not retell the panels. Sound: ambience or speech. No music. Opening, escalation, payoff. Word ceilings, not targets: title ${GOAL_PROMPT_BUDGET.title}, continuity ${GOAL_PROMPT_BUDGET.continuity}, frame ${GOAL_PROMPT_BUDGET.frame}, storyboard 48, ending ${GOAL_PROMPT_BUDGET.ending}, video ${GOAL_PROMPT_BUDGET.video}. Match shot count, seconds and aspect ratio. Portrait default; centre subjects, leave headroom. Nano Banana 2.1, 2K, Seedance 2.5 720p unless specified. One continuous 20-second video by default; create multiple clips only when explicitly requested. frameContinuity false; endingPrompt null. No @tokens, tools, invented assets or continuity promises.`;
+export function goalPlannerInstructions(selection, constraints) {
+    const style = goalStyle(selection.id);
+    if (!style.planner)
+        return cinematicInstructions;
+    const options = resolveGoalStyleOptions(selection.id, selection.options);
+    const beats = style.options.find(option => option.key === "format")?.choices.find(choice => choice.value === options.format)?.beats;
+    return `${cinematicInstructions}\n\n${style.planner} Selected style: ${goalStyleSummary(selection)}.${beats ? ` Content arc: ${beats}; expand to six beats.` : ""} Use ${constraints.aspectRatio} throughout.`;
+}
+export function constrainGoalPlannerPlan(plan, brief, selection) {
+    const constraints = goalBriefConstraints(brief);
+    if (plan.shots.length !== constraints.shotCount)
+        throw new Error("The planner returned a different shot count. Try planning again.");
+    const defaults = goalStyle(selection.id).defaults;
+    const imageModel = /\b(flare|sunburst)\b/iu.exec(brief)?.[1]?.toLowerCase();
+    const imageResolution = /\b(1k|2k)\b/iu.exec(brief)?.[1]?.toUpperCase();
+    const videoResolution = /\b(480p|720p)\b/iu.exec(brief)?.[1]?.toLowerCase();
+    return {
+        ...plan, style: { id: selection.id, options: resolveGoalStyleOptions(selection.id, selection.options) },
+        aspectRatio: constraints.aspectRatio, frameContinuity: false, storyboardLayout: "six-panel",
+        imageModel: imageModel ?? "nano-banana-2-1",
+        imageResolution: imageResolution ?? defaults.imageResolution ?? "2K",
+        videoResolution: videoResolution ?? defaults.videoResolution ?? "720p",
+        shots: plan.shots.map(shot => ({ ...shot, durationSeconds: constraints.durationSeconds, endingPrompt: null })),
+    };
+}

package/dist/goal-prompt-budget.js

@@ -0,0 +1,4 @@
+export const GOAL_PROMPT_BUDGET = { title: 6, continuity: 30, frame: 20, storyboard: 32, ending: 12, video: 12 };
+export function goalPromptWords(value) {
+    return value.trim().split(/\s+/u).filter(Boolean).length;
+}

package/dist/goal-reference-images.js

@@ -0,0 +1,25 @@
+import { findPrimaryMediaFile } from "videobook-engine";
+import { mimeForImageFilename } from "./jobs/describe-image.js";
+export async function goalPlannerImages(engine, references) {
+    return Promise.all(references.map(async (reference, index) => {
+        const manifest = await engine.files.manifest(reference.artifactId);
+        const file = manifest.ok ? findPrimaryMediaFile(manifest.value.files, "image") : null;
+        if (!file)
+            throw new Error(`Reference ${index + 1} has no readable image`);
+        const bytes = await engine.files.read(reference.artifactId, file.name);
+        if (!bytes.ok)
+            throw new Error(bytes.error.message);
+        return [
+            { type: "input_text", text: `Reference ${index + 1}: ${reference.label}` },
+            { type: "input_image", image_url: `data:${mimeForImageFilename(file.name)};base64,${bytes.value.toString("base64")}`, detail: "high" },
+        ];
+    })).then(images => images.flat());
+}
+export async function goalReferenceHashes(engine, artifactIds) {
+    return Promise.all(artifactIds.map(async (artifactId) => {
+        const artifact = engine.artifacts.get(artifactId);
+        const manifest = await engine.files.manifest(artifactId);
+        const file = artifact.ok && manifest.ok ? findPrimaryMediaFile(manifest.value.files, artifact.value.kind) : null;
+        return { artifactId, objectHash: file?.objectHash ?? null };
+    }));
+}