@milenyumai/film-kit 2.3.3 → 2.3.5

package/build/lib/storyboard-reference/adapters/seedance20.js

@@ -47,8 +47,8 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const continuityInstruction = input.continuityMode === "continuous-shot"
-            ? "No scene cuts throughout, one continuous shot."
-            : `Follow the generated storyboard panels in ${storyboardToken} left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, or the final pose. Compress the planned sequence into the full duration as concise motion snapshots; use only storyboard-motivated cuts, match cuts, whip transitions, or camera moves, and do not add unplanned cuts, extra scene jumps, or new locations.`;
+            ? `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow the single storyboard beat exactly. No scene cuts throughout, one continuous shot.`
+            : `Use the generated storyboard reference ${storyboardToken} as the complete visual, action, camera, and choreography source for this ${input.request.durationSeconds}-second video. Follow all ${input.storyboardImagePrompt.panelCount} beats sequentially from left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, movement logic, shot order, or the final pose. Compress the full ${input.storyboardImagePrompt.panelCount}-beat sequence into the full duration as fast readable motion snapshots, not full-length actions. Use urgent rhythm, storyboard-motivated cuts, quick cuts, match cuts, whip transitions, or motivated camera moves only when the storyboard supports them. Do not add unplanned cuts, extra scene jumps, duplicate performers, or new locations.`;
         const characterEntries = this.getMappingEntries(input, "character_identity");
         const characterTokenText = characterEntries.map(entry => entry.token).join(", ") || "@Image1";
         const promptText = `${this.formatCharacterRoleLine(input)}
@@ -69,13 +69,13 @@ ${input.request.brief}
 ${formatPhaseLines(input.interpretation.phases)}
 
 [GPT IMAGE 2 STORYBOARD SOURCE]
-Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, and lens notes as planning annotations only; never render arrows, notes, labels, timestamps, or storyboard text into the video.
+Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, lens notes, and framing marks as planning annotations only; never render arrows, annotation marks, notes, labels, timestamps, panel borders, or storyboard text into the video.
 
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
 
 [PERFORMANCE]
-Visible acting stays concrete and restrained: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing identity.
+Keep the same performer identity from ${characterTokenText}; do not duplicate the character. Visible performance must include breath, mouth movement when dialogue or singing is present, body strain, fabric motion, floor or prop contact, and emotional escalation while preserving exact identity. Acting stays concrete and physically grounded: gaze, breathing, posture, hand behavior, and facial tension evolve from the brief without changing wardrobe or body design.
 
 [AUDIO]
 Dialogue: ${buildDialogueTranscript(input)}.
@@ -86,7 +86,7 @@ Music: NONE.
 [CONTINUITY]
 Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, emotional progression, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
 
-Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
+Avoid: identity drift, face drift, outfit drift, duplicated performer, storyboard text, annotations, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps. No text, no annotations, no timestamps, no watermark.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),

package/build/lib/storyboard-reference/defaults.js

@@ -1,9 +1,10 @@
+import { listActiveVideoModelIds } from "../model-registry/index.js";
 export const STORYBOARD_REFERENCE_MODE = "storyboard-reference";
 export const DEFAULT_STORYBOARD_DURATION_SECONDS = 8;
 export const DEFAULT_STORYBOARD_ASPECT_RATIO = "16:9";
 export const DEFAULT_STORYBOARD_LANGUAGE = "NONE";
 export const DEFAULT_STORYBOARD_OUTPUT_DIR = "./outputs";
-export const DEFAULT_STORYBOARD_TARGET_MODELS = ["veo31", "seedance-2.0", "kling-3.0"];
+export const DEFAULT_STORYBOARD_TARGET_MODELS = listActiveVideoModelIds();
 export const DEFAULT_STORYBOARD_REFERENCE_RUNTIME = {
     enabled: true,
     maxStoryboardPhases: 4,

package/build/lib/storyboard-reference/index.d.ts

@@ -4,4 +4,4 @@ export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
 export { assertSafeStoryboardReferenceRequest, assertStoryboardReferenceBuildPass, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";
-export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";
+export type { AdapterInput, AudioPlan, CameraPlan, CharacterReferenceSheetPrompt, ContinuityAnchors, DialogueLine, ModelPromptOutput, ModelPromptQa, ModelRouteMetadata, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ProviderAssetMappingEntry, ProviderFileLimitReport, ProviderReferenceTokenPolicy, ReferenceAsset, ReferenceAssetRequirement, ReferenceAssetRole, ReferenceLockStrength, ResolvedAssetRoles, SeedanceContinuityMode, ShotHandoffNote, StoryboardCreationMetadata, StoryboardImagePrompt, StoryboardInterpretation, StoryboardPhase, StoryboardPhaseBudget, StoryboardReferenceBuildResult, StoryboardReferencePlan, StoryboardReferencePolicy, StoryboardReferenceWriteResult, VideoModelPromptAdapter, VideoPromptRequest, VisualWorld, VoiceCastEntry } from "./types.js";

package/build/lib/storyboard-reference/output-writer.js

@@ -169,6 +169,9 @@ ${bundle.storyboardImagePrompt.promptText}
 \`\`\`
 `;
 }
+function renderStoryboardPromptAlias(result) {
+    return result.bundles.map(renderStoryboardPromptFile).join("\n---\n\n");
+}
 function renderQaReport(result) {
     const models = result.request.targetModels.join(", ");
     const rows = result.bundles
@@ -219,6 +222,7 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
     const written = [];
     const planPath = join(outputRoot, "storyboard-reference-plan.json");
     const projectInfoPath = join(outputRoot, "project-info.md");
+    const storyboardPromptAliasPath = join(outputRoot, "storyboard-prompt.md");
     const qaPath = join(outputRoot, "reports", "STORYBOARD-REFERENCE-QA.md");
     await writeText(planPath, `${JSON.stringify(result.plan, null, 2)}\n`);
     written.push(planPath);
@@ -234,6 +238,8 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
 - Safety context: ${result.request.safetyContext}
 `);
     written.push(projectInfoPath);
+    await writeText(storyboardPromptAliasPath, renderStoryboardPromptAlias(result));
+    written.push(storyboardPromptAliasPath);
     for (const prompt of result.characterReferenceSheetPrompts) {
         const promptPath = resolve(rootDir, prompt.outputPath);
         await writeText(promptPath, renderCharacterSheetPrompt(prompt));

package/build/lib/storyboard-reference/prompt-bundle-builder.js

@@ -1,19 +1,57 @@
 import { resolveAssetRoles } from "./asset-role-resolver.js";
+import { GenericPromptAdapter } from "./adapters/generic.js";
 import { Kling30PromptAdapter } from "./adapters/kling30.js";
 import { Seedance20PromptAdapter } from "./adapters/seedance20.js";
 import { Veo31PromptAdapter } from "./adapters/veo31.js";
+import { getModelAdapterKey, requireModel } from "../model-registry/index.js";
 import { normalizeVideoPromptRequest } from "./request-normalizer.js";
 import { buildStoryboardPhaseBudget, inferContinuityMode, interpretStoryboard } from "./storyboard-interpreter.js";
 import { assertSafeStoryboardReferenceRequest, validateCharacterReferenceSheetPrompts, validateModelPromptOutput, validatePromptBundle } from "./validators.js";
 const ADAPTERS = {
     veo31: new Veo31PromptAdapter(),
-    "seedance-2.0": new Seedance20PromptAdapter(),
-    "kling-3.0": new Kling30PromptAdapter()
+    seedance20: new Seedance20PromptAdapter(),
+    kling30: new Kling30PromptAdapter()
 };
-function getStoryboardPanelCount(request, phaseBudget) {
-    return request.storyboardPanelCountHint
-        ?? request.shotCountHint
-        ?? phaseBudget.recommendedMaxPhases;
+function buildGenericCapabilities(model) {
+    const registryModel = requireModel(model);
+    const capabilities = {
+        supportsImageReference: Boolean(registryModel.capabilities.characterReference),
+        supportsMultipleImageReferences: Boolean(registryModel.capabilities.multipleImageReferences),
+        supportsStoryboardReference: Boolean(registryModel.capabilities.storyboardReference),
+        supportsAudio: Boolean(registryModel.capabilities.audioPlan),
+        supportsDialogue: Boolean(registryModel.capabilities.dialogue),
+        supportsCustomStoryboardPhases: Boolean(registryModel.capabilities.customStoryboardPhases),
+        preferredPromptShape: "natural-language"
+    };
+    if (registryModel.durationRange?.maxSeconds !== undefined) {
+        capabilities.maxDurationSeconds = registryModel.durationRange.maxSeconds;
+    }
+    if (registryModel.capabilities.maxStoryboardPhases !== undefined) {
+        capabilities.maxStoryboardPhases = registryModel.capabilities.maxStoryboardPhases;
+    }
+    return capabilities;
+}
+function resolvePromptAdapter(model) {
+    const adapterKey = getModelAdapterKey(model);
+    if (adapterKey === "generic") {
+        return new GenericPromptAdapter(model, buildGenericCapabilities(model));
+    }
+    const adapter = ADAPTERS[adapterKey];
+    if (!adapter) {
+        throw new Error(`Model ${model} does not have a storyboard-reference video adapter.`);
+    }
+    return adapter;
+}
+const MAX_STORYBOARD_SHEET_PANELS = 12;
+function getStoryboardSheetPanelCount(request, phaseBudget) {
+    const panelCount = request.storyboardPanelCountHint ?? phaseBudget.recommendedMaxPhases;
+    if (panelCount > MAX_STORYBOARD_SHEET_PANELS) {
+        throw new Error(`Invalid storyboardPanelCountHint. Expected 1-${MAX_STORYBOARD_SHEET_PANELS} panels for one GPT Image 2 storyboard sheet.`);
+    }
+    return panelCount;
+}
+function getVideoPhaseCount(request, phaseBudget) {
+    return request.shotCountHint ?? phaseBudget.recommendedMaxPhases;
 }
 function buildShotId(index) {
     return `SHOT${String(index + 1).padStart(2, "0")}`;
@@ -140,37 +178,37 @@ function buildStoryboardImagePrompt(input) {
         ? `Use external storyboard guide tokens ${assets.storyboards.map(storyboard => storyboard.token).join(", ")} only for composition, blocking, camera direction, timing, and action rhythm.`
         : "No external storyboard guide is required; infer the board from the screenplay brief, continuity notes, and visual world.";
     const phaseDirection = interpretation.phases
-        .map(phase => `Panel ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
+        .map(phase => `Phase ${phase.index}: ${phase.job}; ${phase.subjectAction}; camera behavior: ${phase.cameraBehavior}; background behavior: ${phase.backgroundBehavior}.`)
         .join(" ");
     const continuityStyle = interpretation.phases.length <= 1
         ? "Because this is a single uninterrupted beat, show one decisive action moment with a clear entry pose, motion direction, and final body intention inside the same panel."
-        : "Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.";
+        : `Read panels left-to-right, top-to-bottom as a planned visual beat sequence. Create ${input.storyboardSheetPanelCount} distinct beat snapshot${input.storyboardSheetPanelCount === 1 ? "" : "s"} distributed across the video phases. Each panel must show a distinct body pose, camera size/angle, movement logic, and emotional escalation, not decorative micro-poses.`;
     return {
         shotId,
         outputPath: `${request.outputDir}/storyboard-prompts/${shotId}-GPT-IMAGE-2-STORYBOARD.md`,
         provider: "gpt-image-2",
         aspectRatio: "16:9",
-        panelCount: interpretation.panelCount,
+        panelCount: input.storyboardSheetPanelCount,
         style: "professional-production-storyboard",
         characterSheetIds,
         externalStoryboardGuideIds,
         previousShotHandoff: input.previousShotHandoff,
         nextShotHandoff: input.nextShotHandoff,
-        promptText: `REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, body proportions, wardrobe, accessories, material behavior, and visible props.
+        promptText: `REFERENCE LOCK: Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, hair, skin texture, body proportions, wardrobe, accessories, material behavior, and visible props.
 
 Keep same: every character identity detail from the character sheet${characterReferenceSheetPrompts.length === 1 ? "" : "s"}, the declared visual world, screen direction, environmental continuity, lighting direction, prop continuity, and shot handoff logic. Storyboard text, arrows, labels, panel borders, watermarks, logos, and alternate character designs are never identity sources.
 
-Change only: create a professional 16:9 production storyboard page for ${shotId} with exactly ${interpretation.panelCount} cinematic panel${interpretation.panelCount === 1 ? "" : "s"}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
+Change only: create a raw cinematic storyboard sheet for ${shotId}. 16:9 storyboard sheet, exactly ${input.storyboardSheetPanelCount} cinematic panel${input.storyboardSheetPanelCount === 1 ? "" : "s"}. The storyboard controls composition, blocking, camera direction, timing, phase order, action rhythm, and emotional progression only. ${externalGuideText}
 
-Storyboard drawing style: raw contemporary film storyboard, black-and-white rough pencil linework for the artwork only, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished choreography-previsualization feel, not polished concept art or final render.
+Storyboard drawing style: raw contemporary film storyboard with black-and-white rough pencil linework. The actual storyboard drawings must be black-and-white only: rough pencil lines, minimal detail, fast gesture drawing energy, simple anatomy construction, strong silhouette readability, lightweight unfinished choreography previs, not polished concept art or final render.
 
 Panel direction: ${continuityStyle} The scene brief is: ${request.brief} Previous handoff: ${input.previousShotHandoff}. Next handoff: ${input.nextShotHandoff}. Planned panel actions: ${phaseDirection}
 
-Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic camera variety only when motivated by the beat: handheld energy, push-in, orbit, overhead, low angle, side silhouette, insert, aggressive close-up, long-lens compression, or extreme negative space. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
+Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}; preserve ${interpretation.cameraPlan.screenDirection}. Use cinematic arthouse camerawork with handheld energy, whip pans, orbit movement, overhead shots, low angles, side silhouettes, aggressive close-ups, long lens compression, inserts, and extreme negative space whenever motivated by the beat. Maintain the same environment, lighting, atmosphere, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.foreground}; ${interpretation.visualWorld.midground}; ${interpretation.visualWorld.background}; ${interpretation.visualWorld.atmosphere}.
 
 Annotation color system: red arrows for body movement, blue arrows for camera movement, green marks for framing/composition, orange marks for lighting direction, purple marks for vocal or emotional emphasis when relevant, black text only for very short lens notes and panel labels. No timestamps.
 
-Every panel must contain visible momentum or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, or a readable pose transition. Keep the location minimal and readable.
+Every panel must contain visible momentum. Every panel must contain visible motion, strong body momentum, or clear behavioral change: gaze shift, breath, weight transfer, contact with ground/prop, fabric motion, hand tension, floor contact, hair or clothing motion, or a readable pose transition. Avoid static standing poses unless explicitly required by the beat. Keep the location minimal and readable. End with one overwhelming final readable movement pose or composition that preserves the shot's emotional endpoint.
 
 Avoid: identity drift, face drift, hair drift, wardrobe drift, prop drift, material drift, alternate character design, static standing poses unless explicitly required by the beat, timestamps, long text notes, storyboard text becoming scene text, new characters, new locations, logos, watermarks, decorative borders, broken perspective, impossible contact or weight, inconsistent screen direction, inconsistent light direction, photorealistic final-render polish, cartoon style, anime style, CGI look, unsafe public-figure likeness, trademarked branding.`
     };
@@ -259,6 +297,45 @@ function buildProviderReferenceTokens(providerAssetMapping) {
         audioReference: "@audio1"
     };
 }
+function buildStoryboardCreationMetadata(request, storyboardImagePrompt, providerAssetMapping) {
+    const storyboardEntry = Object.values(providerAssetMapping)
+        .find(entry => entry.role === "storyboard_plan");
+    return {
+        provider: "gpt-image-2",
+        prompt_path: storyboardImagePrompt.outputPath,
+        alias_path: `${request.outputDir}/storyboard-prompt.md`,
+        source_mode: storyboardImagePrompt.externalStoryboardGuideIds.length > 0
+            ? "generated-with-external-guide"
+            : "generated",
+        panel_count: storyboardImagePrompt.panelCount,
+        reading_order: "left-to-right, top-to-bottom",
+        character_sheet_ids: storyboardImagePrompt.characterSheetIds,
+        external_storyboard_guide_ids: storyboardImagePrompt.externalStoryboardGuideIds,
+        seedance_token: storyboardEntry?.token ?? "@Image2",
+        annotation_policy: {
+            rendered_in_video: false,
+            color_system: {
+                red: "body movement",
+                blue: "camera movement",
+                green: "framing / composition",
+                orange: "lighting direction",
+                purple: "vocal / emotional emphasis",
+                black: "short lens notes and panel labels"
+            },
+            forbidden_in_video: [
+                "arrows",
+                "annotation marks",
+                "lens notes",
+                "panel labels",
+                "timestamps",
+                "panel borders",
+                "watermark",
+                "logo"
+            ]
+        },
+        prompt_text: storyboardImagePrompt.promptText
+    };
+}
 function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits, bundles, providerReferenceTokens, maxPhases, splitRequired) {
     const continuityModes = Array.from(new Set(bundles.map(bundle => bundle.continuityMode)));
     return {
@@ -293,9 +370,9 @@ function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits
                 provider: "gpt-image-2",
                 generated_per_shot: true,
                 aspect_ratio: "16:9",
-                max_panels_per_shot: maxPhases,
+                max_panels_per_shot: MAX_STORYBOARD_SHEET_PANELS,
                 panel_budget: phaseBudget.policy,
-                professional_prompt_target_words: "160-240 words per shot storyboard prompt"
+                professional_prompt_target_words: "240-420 words per shot storyboard prompt"
             },
             role_separation: {
                 character_identity: `${providerReferenceTokens.characterIdentities.join(", ")} control identity, face, hair, body proportions, wardrobe, accessories, and visible props.`,
@@ -320,7 +397,7 @@ function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits
 function buildModelPrompts(request, bundleInput) {
     const modelPrompts = {};
     for (const model of request.targetModels) {
-        const adapter = ADAPTERS[model];
+        const adapter = resolvePromptAdapter(model);
         const output = adapter.buildPrompt({ ...bundleInput, request });
         const validatorQa = validateModelPromptOutput(output);
         output.qa = {
@@ -344,15 +421,16 @@ export function buildStoryboardReferencePromptBundles(input) {
     const voiceCast = buildVoiceCast(request);
     const phaseBudget = buildStoryboardPhaseBudget(request.durationSeconds, request.storyboardReferenceMode.maxStoryboardPhases);
     const providerFileLimits = buildProviderFileLimitReport(request, characterReferenceSheetPrompts.length + 1);
-    const panelCount = getStoryboardPanelCount(request, phaseBudget);
+    const storyboardSheetPanelCount = getStoryboardSheetPanelCount(request, phaseBudget);
+    const videoPhaseCount = getVideoPhaseCount(request, phaseBudget);
     const maxPhases = phaseBudget.effectiveMaxStoryboardPhases;
-    const splitRequired = panelCount > maxPhases;
+    const splitRequired = videoPhaseCount > maxPhases;
     if (splitRequired && !request.storyboardReferenceMode.splitStoryboardOverload) {
-        throw new Error(`Storyboard has ${panelCount} phases, which exceeds maxStoryboardPhases=${maxPhases}. Enable splitStoryboardOverload or split the storyboard manually.`);
+        throw new Error(`Storyboard has ${videoPhaseCount} video phases, which exceeds maxStoryboardPhases=${maxPhases}. Enable splitStoryboardOverload or split the storyboard manually.`);
     }
     const phaseCounts = splitRequired && request.storyboardReferenceMode.splitStoryboardOverload
-        ? getSplitPhaseCounts(panelCount, maxPhases)
-        : [Math.min(panelCount, maxPhases)];
+        ? getSplitPhaseCounts(videoPhaseCount, maxPhases)
+        : [Math.min(videoPhaseCount, maxPhases)];
     const generatedAt = new Date().toISOString();
     const bundles = [];
     let previousShotHandoff = "Project opening: start from the screenplay's first visual beat.";
@@ -370,11 +448,13 @@ export function buildStoryboardReferencePromptBundles(input) {
             assets,
             shotId,
             interpretation,
+            storyboardSheetPanelCount,
             characterReferenceSheetPrompts,
             previousShotHandoff,
             nextShotHandoff: handoffNote.exitHandoff
         });
         const providerAssetMapping = buildProviderAssetMapping(assets, characterReferenceSheetPrompts, storyboardImagePrompt);
+        const storyboard_creation = buildStoryboardCreationMetadata(request, storyboardImagePrompt, providerAssetMapping);
         const referenceAssetRequirements = buildReferenceAssetRequirements(providerAssetMapping);
         const modelPrompts = buildModelPrompts(request, {
             assets,
@@ -399,6 +479,7 @@ export function buildStoryboardReferencePromptBundles(input) {
             providerFileLimits,
             handoffNote,
             storyboardImagePrompt,
+            storyboard_creation,
             referenceAssetRequirements,
             providerAssetMapping,
             qa: { verdict: "pass", checks: {}, issues: [], splitRequired },

package/build/lib/storyboard-reference/request-normalizer.js

@@ -1,5 +1,5 @@
+import { validateModelAllowed } from "../model-registry/index.js";
 import { DEFAULT_STORYBOARD_ASPECT_RATIO, DEFAULT_STORYBOARD_DURATION_SECONDS, DEFAULT_STORYBOARD_LANGUAGE, DEFAULT_STORYBOARD_OUTPUT_DIR, DEFAULT_STORYBOARD_TARGET_MODELS, STORYBOARD_REFERENCE_MODE, resolveStoryboardReferenceRuntime } from "./defaults.js";
-const SUPPORTED_MODELS = ["veo31", "seedance-2.0", "kling-3.0"];
 const SUPPORTED_ASPECT_RATIOS = ["16:9", "9:16", "1:1"];
 function normalizePositiveInteger(value, fallback, fieldName) {
     const normalized = value ?? fallback;
@@ -13,9 +13,11 @@ function assertSupportedModels(models) {
         return DEFAULT_STORYBOARD_TARGET_MODELS.slice();
     }
     for (const model of models) {
-        if (!SUPPORTED_MODELS.includes(model)) {
-            throw new Error(`Unsupported target model: ${model}. Supported: ${SUPPORTED_MODELS.join(", ")}`);
-        }
+        validateModelAllowed(model, {
+            requiredModalities: ["video"],
+            referenceMode: STORYBOARD_REFERENCE_MODE,
+            usage: "storyboard target"
+        });
     }
     return Array.from(new Set(models));
 }

package/build/lib/storyboard-reference/types.d.ts

@@ -135,6 +135,30 @@ export interface StoryboardImagePrompt {
     nextShotHandoff: string;
     promptText: string;
 }
+export interface StoryboardCreationMetadata {
+    provider: "gpt-image-2";
+    prompt_path: string;
+    alias_path: string;
+    source_mode: "generated" | "generated-with-external-guide";
+    panel_count: number;
+    reading_order: "left-to-right, top-to-bottom";
+    character_sheet_ids: string[];
+    external_storyboard_guide_ids: string[];
+    seedance_token: string;
+    annotation_policy: {
+        rendered_in_video: false;
+        color_system: {
+            red: "body movement";
+            blue: "camera movement";
+            green: "framing / composition";
+            orange: "lighting direction";
+            purple: "vocal / emotional emphasis";
+            black: "short lens notes and panel labels";
+        };
+        forbidden_in_video: string[];
+    };
+    prompt_text: string;
+}
 export type ProviderAssetMappingRole = "character_identity" | "storyboard_plan" | "style_reference" | "camera_reference" | "action_reference" | "prop_reference";
 export interface ProviderAssetMappingEntry {
     token: string;
@@ -254,6 +278,7 @@ export interface PromptBundle {
     providerFileLimits: ProviderFileLimitReport;
     handoffNote: ShotHandoffNote;
     storyboardImagePrompt: StoryboardImagePrompt;
+    storyboard_creation: StoryboardCreationMetadata;
     referenceAssetRequirements: ReferenceAssetRequirement[];
     providerAssetMapping: Record<string, ProviderAssetMappingEntry>;
     qa: PromptBundleQa;

package/build/lib/storyboard-reference/validators.js

@@ -113,6 +113,10 @@ export function validatePromptBundle(bundle, assets, voiceCast = []) {
         hasCharacterReference: assets.characters.length >= 1,
         hasStoryboardReference: assets.storyboards.length >= 1 || Boolean(bundle.storyboardImagePrompt),
         hasStoryboardImagePrompt: Boolean(bundle.storyboardImagePrompt?.promptText.trim()),
+        hasStoryboardCreationMetadata: Boolean(bundle.storyboard_creation?.prompt_text.trim())
+            && bundle.storyboard_creation?.prompt_path === bundle.storyboardImagePrompt.outputPath
+            && bundle.storyboard_creation?.panel_count === bundle.storyboardImagePrompt.panelCount
+            && bundle.storyboard_creation?.annotation_policy.rendered_in_video === false,
         storyboardPromptHasReferenceLockStructure: hasGptImageStillPromptContract(bundle.storyboardImagePrompt?.promptText ?? ""),
         hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output) && hasAvoidOrNegativePrompt(output.promptText)),
         storyboardPromptHasAvoidLine: hasAvoidOrNegativePrompt(bundle.storyboardImagePrompt?.promptText ?? ""),

package/build/lib/templates.js

@@ -35,7 +35,7 @@ function buildStoryboardPlatformGuard(config) {
 - Do not generate main-shot \`ILK FRAME\`, \`İLK FRAME\`, or \`SON FRAME\` sections.
 - Do not use exact first-frame reuse instructions, \`SHOTNN_START\`, \`SHOTNN_END\`, or mandatory Start+End transition fields.
 - If no character reference is available through the user, an in-context image, \`--character-ref\`, or \`refs/character.png\`, stop and request one.
-- Required storyboard outputs: \`${config.outputDir}/storyboard-reference-plan.json\`, \`${config.outputDir}/reference-prep/\`, \`${config.outputDir}/storyboard-prompts/\`, \`${config.outputDir}/prompt-bundles/\`, \`${config.outputDir}/shots/SHOTNN.md\`, and \`${config.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
+- Required storyboard outputs: \`${config.outputDir}/storyboard-reference-plan.json\`, \`${config.outputDir}/storyboard-prompt.md\`, \`${config.outputDir}/reference-prep/\`, \`${config.outputDir}/storyboard-prompts/\`, \`${config.outputDir}/prompt-bundles/\`, \`${config.outputDir}/shots/SHOTNN.md\`, and \`${config.outputDir}/reports/STORYBOARD-REFERENCE-QA.md\`.
 `;
 }
 function buildSeedanceProfile(active, storyboardReferenceActive = false, maxStoryboardPhases = 4) {

package/build/lib/types.d.ts

@@ -1,5 +1,6 @@
+import type { VideoModelId } from "./model-registry/index.js";
 export type SupportedPlatform = "cursor" | "claude" | "copilot" | "antigravity" | "codex";
-export type SupportedModel = "veo31" | "kling-3.0" | "seedance-2.0";
+export type SupportedModel = VideoModelId;
 export type KlingPreset = "ultra-realism" | "balanced" | "custom";
 export type FilmKitPreset = "single" | "multi" | "hybrid" | "hybrid-smart" | "gpt-image-smart" | "studio";
 export type ReferenceMode = "start-end" | "storyboard-reference" | "hybrid";

package/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milenyumai/film-kit",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "Single-package Film-Kit distribution with preset-driven cinematic runtime setup for OpenAI Codex App, Claude Code, Cursor, Copilot, and Antigravity.",
   "type": "module",
   "main": "./build/index.js",
@@ -36,6 +36,7 @@
     "packages/gpt-image-smart/content",
     "packages/studio/content",
     "content",
+    "MODEL_REGISTRY.md",
     "README.md",
     "LICENSE"
   ],

package/packages/gpt-image-smart/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json

package/packages/gpt-image-smart/content/workflows/generate-storyboard.md

@@ -33,11 +33,12 @@ description: Generate character sheet prompts, per-shot GPT Image 2 storyboard p
    - exact identity, wardrobe, accessories, and visible props
    - no labels, text, logos, watermarks, alternate designs, or extra characters
 3. Confirm target models: `veo31`, `seedance-2.0`, `kling-3.0`, or a user-provided subset.
-4. Select shot storyboard panel budget:
-   - 4-6 seconds: 1-2 panels/phases
-   - 7-10 seconds: 2-3 panels/phases
-   - 11-15 seconds: 3-4 panels/phases
-   - 5+ distinct phases: split into multiple `SHOTNN.md` files
+4. Select video phase budget and storyboard sheet panel count:
+   - 4-6 seconds: 1-2 video phases
+   - 7-10 seconds: 2-3 video phases
+   - 11-15 seconds: 3-4 video phases
+   - GPT Image 2 storyboard sheet may contain 1-12 panels
+   - 5+ distinct real video phases, scene changes, or location/action blocks: split into multiple `SHOTNN.md` files
 5. Build `visual_world`:
    - environment
    - lighting
@@ -89,7 +90,7 @@ npx @milenyumai/film-kit generate-storyboard \
 - Missing character reference: stop and request a valid reference.
 - Empty brief: stop and request a brief.
 - Public figure / real-person likeness / trademark risk: stop or safely anonymize before prompt generation.
-- 5+ storyboard phases: do not compress into one prompt; split shots.
+- 5+ real video phases: do not compress into one prompt; split shots. 5-12 storyboard sheet panels alone do not force a split.
 - Missing GPT Image 2 character sheet prompt: output is invalid.
 - Missing GPT Image 2 per-shot storyboard prompt: output is invalid.
 - Missing `Avoid` / negative prompt: output is invalid.

package/packages/hybrid/content/skills/storyboard-reference/SKILL.md

@@ -13,7 +13,7 @@ Use this skill when the user provides:
 - a video brief or scenario text
 - optional external storyboard guide images
 
-The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. The generated shot storyboard is the staging reference for the final video model prompt.
+The output is a production workflow, not only a video prompt. First create one reusable GPT Image 2 character sheet prompt per reference character. Then create one GPT Image 2 storyboard prompt per `SHOTNN.md`. If no external storyboard image is supplied, this generated prompt is the mandatory storyboard bootstrap step. The generated shot storyboard is the staging reference for the final video model prompt.
 
 ## Reference Prep
 
@@ -36,9 +36,10 @@ For each shot, generate a professional GPT Image 2 storyboard prompt:
 
 - provider: `gpt-image-2`
 - aspect ratio: `16:9`
-- panel budget: 4-6s = 1-2 panels, 7-10s = 2-3 panels, 11-15s = 3-4 panels
-- hard cap: max 4 panels/phases per shot unless the configured project cap is lower
-- split policy: 5+ distinct phases must become separate chained `SHOTNN.md` files
+- storyboard sheet panel budget: default follows the duration-aware phase budget, but an explicit storyboard panel hint may request 1-12 panels in one GPT Image 2 storyboard sheet
+- video phase budget: 4-6s = 1-2 phases, 7-10s = 2-3 phases, 11-15s = 3-4 phases
+- hard cap: max 4 video phases per shot unless the configured project cap is lower
+- split policy: 5+ distinct real video phases, scene changes, or location/action blocks must become separate chained `SHOTNN.md` files; 5-12 storyboard sheet panels alone do not force a split
 - target detail: dense professional storyboard direction, concrete blocking and camera language, no decorative prose
 - storyboard art grammar: black-and-white rough pencil drawings, minimal detail, rapid gesture energy, simple anatomy construction, strong silhouette readability, unfinished previsualization feel
 - annotation grammar: red arrows = body movement, blue arrows = camera movement, green marks = framing/composition, orange marks = lighting direction, purple marks = vocal/emotional emphasis, black text = very short lens notes and panel labels
@@ -108,6 +109,7 @@ Each shot file contains:
 - provider reference tokens
 - GPT Image 2 storyboard prompt
 - storyboard interpretation
+- storyboard_creation metadata in `SHOTNN.bundle.json`
 - audio plan
 - prompt bundle for requested models
 - QA verdict
@@ -116,6 +118,7 @@ Generated files:
 
 ```text
 $OUTPUT_DIR/storyboard-reference-plan.json
+$OUTPUT_DIR/storyboard-prompt.md
 $OUTPUT_DIR/reference-prep/CHARACTER-SHEET-*.md
 $OUTPUT_DIR/storyboard-prompts/SHOTNN-GPT-IMAGE-2-STORYBOARD.md
 $OUTPUT_DIR/prompt-bundles/SHOTNN.bundle.json