@milenyumai/film-kit 2.2.1 → 2.3.1

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

@@ -3,19 +3,29 @@ import { Kling30PromptAdapter } from "./adapters/kling30.js";
 import { Seedance20PromptAdapter } from "./adapters/seedance20.js";
 import { Veo31PromptAdapter } from "./adapters/veo31.js";
 import { normalizeVideoPromptRequest } from "./request-normalizer.js";
-import { interpretStoryboard } from "./storyboard-interpreter.js";
+import { buildStoryboardPhaseBudget, inferContinuityMode, interpretStoryboard } from "./storyboard-interpreter.js";
 import { assertSafeStoryboardReferenceRequest, validateModelPromptOutput, validatePromptBundle } from "./validators.js";
 const ADAPTERS = {
     veo31: new Veo31PromptAdapter(),
     "seedance-2.0": new Seedance20PromptAdapter(),
     "kling-3.0": new Kling30PromptAdapter()
 };
-function getStoryboardPanelCount(request) {
-    return request.storyboardPanelCountHint ?? request.shotCountHint ?? Math.min(3, request.storyboardReferenceMode.maxStoryboardPhases);
+function getStoryboardPanelCount(request, phaseBudget) {
+    return request.storyboardPanelCountHint
+        ?? request.shotCountHint
+        ?? phaseBudget.recommendedMaxPhases;
 }
 function buildShotId(index) {
     return `SHOT${String(index + 1).padStart(2, "0")}`;
 }
+function safeFileId(value) {
+    const normalized = value
+        .trim()
+        .replace(/[^a-z0-9_-]+/gi, "-")
+        .replace(/^-+|-+$/g, "")
+        .toUpperCase();
+    return normalized || "REFERENCE";
+}
 function getSplitPhaseCounts(panelCount, maxPhases) {
     const counts = [];
     let remaining = panelCount;
@@ -26,6 +36,259 @@ function getSplitPhaseCounts(panelCount, maxPhases) {
     }
     return counts.length > 0 ? counts : [1];
 }
+function detectProviderFileKind(pathOrUrl) {
+    const cleanPath = pathOrUrl.toLowerCase().split("?")[0] ?? "";
+    if (/\.(png|jpe?g|webp|gif|avif|heic|heif)$/.test(cleanPath))
+        return "image";
+    if (/\.(mp4|mov|webm|m4v|avi|mkv)$/.test(cleanPath))
+        return "video";
+    if (/\.(mp3|wav|m4a|aac|ogg|flac|aiff?)$/.test(cleanPath))
+        return "audio";
+    return "unknown";
+}
+function buildProviderFileLimitReport(request, generatedImageReferenceCount) {
+    const counts = {
+        image: generatedImageReferenceCount,
+        video: 0,
+        audio: 0,
+        unknown: 0
+    };
+    for (const asset of request.additionalRefs) {
+        counts[detectProviderFileKind(asset.pathOrUrl)] += 1;
+    }
+    const observedTotalFiles = generatedImageReferenceCount + request.additionalRefs.length;
+    const report = {
+        maxImages: 9,
+        maxVideos: 3,
+        maxAudio: 3,
+        maxTotalFiles: 12,
+        observedImages: counts.image,
+        observedVideos: counts.video,
+        observedAudio: counts.audio,
+        observedUnknown: counts.unknown,
+        observedTotalFiles,
+        withinLimits: counts.image <= 9
+            && counts.video <= 3
+            && counts.audio <= 3
+            && observedTotalFiles <= 12
+    };
+    return report;
+}
+function buildShotHandoffNote(input) {
+    const firstPhase = input.storyboardInterpretation.phases[0];
+    const lastPhase = input.storyboardInterpretation.phases.at(-1);
+    return {
+        shotId: input.shotId,
+        continuityMode: input.continuityMode,
+        phaseCount: input.storyboardInterpretation.phases.length,
+        entryHandoff: firstPhase
+            ? `${firstPhase.timeRange}: ${firstPhase.subjectAction}`
+            : "No storyboard phase entry available.",
+        exitHandoff: lastPhase
+            ? `${lastPhase.timeRange}: ${lastPhase.handoffTrigger ?? lastPhase.subjectAction}`
+            : "No storyboard phase exit available."
+    };
+}
+function buildCharacterReferenceSheetPrompts(assets, outputDir) {
+    return assets.characters.map((character, index) => {
+        const id = `character-sheet-${character.asset.id}`;
+        const sourceLabel = character.asset.label ?? character.asset.id;
+        const outputPath = `${outputDir}/reference-prep/CHARACTER-SHEET-${safeFileId(character.asset.id)}.md`;
+        return {
+            id,
+            characterAssetId: character.asset.id,
+            sourceToken: character.token,
+            outputPath,
+            provider: "gpt-image-2",
+            aspectRatio: "16:9",
+            cellCount: 6,
+            generatedOnce: true,
+            promptText: `Create one 16:9 realistic production storyboard character reference sheet from ${character.token} (${sourceLabel}). Use the uploaded reference only as the identity source. Preserve the exact face, skull shape, hair, skin texture, body proportions, wardrobe, accessories, and visible props; do not beautify, redesign, age-shift, or stylize the character. Arrange six clean storyboard cells in a single widescreen sheet: front full body, back full body, left profile, right profile, three-quarter full body, and close-up face. Keep the same wardrobe and props in every cell. Use neutral studio lighting, consistent scale, uncluttered pale gray background, readable silhouette, realistic pencil-and-wash production storyboard finish, subtle tonal shading, and no dramatic lens distortion. No text, labels, arrows, captions, panel numbers, watermarks, logos, extra characters, alternate outfits, or background story elements. This sheet is generated once and becomes the identity reference for all later shot storyboards.${index === 0 ? "" : " Match visual finish to the earlier character sheets."}`
+        };
+    });
+}
+function buildStoryboardImagePrompt(input) {
+    const { request, assets, shotId, interpretation, characterReferenceSheetPrompts } = input;
+    const characterSheetIds = characterReferenceSheetPrompts.map(prompt => prompt.id);
+    const externalStoryboardGuideIds = assets.storyboards.map(storyboard => storyboard.asset.id);
+    const sheetRefs = characterReferenceSheetPrompts
+        .map((prompt, index) => `${prompt.id} as character ${index + 1}`)
+        .join(", ");
+    const externalGuideText = assets.storyboards.length > 0
+        ? `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}.`)
+        .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.";
+    return {
+        shotId,
+        outputPath: `${request.outputDir}/storyboard-prompts/${shotId}-GPT-IMAGE-2-STORYBOARD.md`,
+        provider: "gpt-image-2",
+        aspectRatio: "16:9",
+        panelCount: interpretation.panelCount,
+        style: "professional-production-storyboard",
+        characterSheetIds,
+        externalStoryboardGuideIds,
+        previousShotHandoff: input.previousShotHandoff,
+        nextShotHandoff: input.nextShotHandoff,
+        promptText: `Create a professional 16:9 production storyboard page for ${shotId} with exactly ${interpretation.panelCount} cinematic panel${interpretation.panelCount === 1 ? "" : "s"}. Use the generated character sheet reference${characterReferenceSheetPrompts.length === 1 ? "" : "s"} (${sheetRefs}) as the only source for character identity, face, body proportions, wardrobe, accessories, and visible props. ${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.
+
+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}.
+
+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. Avoid static standing poses unless the brief requires a deliberately held beat. Keep the location minimal and readable; do not add new characters, new locations, alternate wardrobe, alternate identity, logos, watermarks, decorative borders, final-render polish, or photorealistic video frames.`
+    };
+}
+function isImageReference(asset) {
+    return detectProviderFileKind(asset.asset.pathOrUrl) === "image";
+}
+function buildProviderAssetMapping(assets, characterReferenceSheetPrompts, storyboardImagePrompt) {
+    const mapping = {};
+    characterReferenceSheetPrompts.forEach((sheet, index) => {
+        const token = `@Image${index + 1}`;
+        mapping[token] = {
+            token,
+            legacyAlias: `@image${index + 1}`,
+            sourceToken: sheet.sourceToken,
+            sourceAssetId: sheet.id,
+            role: "character_identity",
+            description: "Generated character sheet: identity, face, body proportions, wardrobe, accessories, and visible props only.",
+            generatedPromptPath: sheet.outputPath
+        };
+    });
+    const storyboardIndex = characterReferenceSheetPrompts.length + 1;
+    const storyboardToken = `@Image${storyboardIndex}`;
+    mapping[storyboardToken] = {
+        token: storyboardToken,
+        legacyAlias: `@image${storyboardIndex}`,
+        sourceToken: `@${storyboardImagePrompt.shotId.toLowerCase()}Storyboard`,
+        sourceAssetId: `${storyboardImagePrompt.shotId}-storyboard-image`,
+        role: "storyboard_plan",
+        description: "Generated shot storyboard: composition, blocking, camera direction, timing, action rhythm, and phase order only.",
+        generatedPromptPath: storyboardImagePrompt.outputPath
+    };
+    let nextImageIndex = storyboardIndex + 1;
+    for (const ref of assets.additional.filter(isImageReference)) {
+        const token = `@Image${nextImageIndex}`;
+        mapping[token] = {
+            token,
+            legacyAlias: `@image${nextImageIndex}`,
+            sourceToken: ref.token,
+            sourceAssetId: ref.asset.id,
+            role: ref.asset.role,
+            description: "Additional image reference; keep below character identity and generated storyboard authority."
+        };
+        nextImageIndex += 1;
+    }
+    return mapping;
+}
+function buildReferenceAssetRequirements(providerAssetMapping) {
+    return Object.values(providerAssetMapping).map(entry => {
+        const source = entry.role === "character_identity"
+            ? "character-sheet"
+            : entry.role === "storyboard_plan"
+                ? "shot-storyboard"
+                : "additional-reference";
+        const requirement = {
+            token: entry.token,
+            source,
+            assetId: entry.sourceAssetId,
+            role: entry.role,
+            required: entry.role === "character_identity" || entry.role === "storyboard_plan",
+            notes: entry.description
+        };
+        if (entry.legacyAlias)
+            requirement.legacyAlias = entry.legacyAlias;
+        if (entry.generatedPromptPath)
+            requirement.generatedPromptPath = entry.generatedPromptPath;
+        return requirement;
+    });
+}
+function buildProviderReferenceTokens(providerAssetMapping) {
+    const characterIdentities = Object.values(providerAssetMapping)
+        .filter(entry => entry.role === "character_identity")
+        .map(entry => entry.token);
+    const storyboardReference = Object.values(providerAssetMapping)
+        .find(entry => entry.role === "storyboard_plan")?.token ?? "@Image2";
+    return {
+        characterIdentity: characterIdentities[0] ?? "@Image1",
+        characterIdentities,
+        storyboardReference,
+        legacyAliases: {
+            characterIdentity: characterIdentities[0]?.replace("@Image", "@image") ?? "@image1",
+            characterIdentities: characterIdentities.map(token => token.replace("@Image", "@image")),
+            storyboardReference: storyboardReference.replace("@Image", "@image")
+        },
+        videoReference: "@video1",
+        audioReference: "@audio1"
+    };
+}
+function buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits, bundles, providerReferenceTokens, maxPhases, splitRequired) {
+    const continuityModes = Array.from(new Set(bundles.map(bundle => bundle.continuityMode)));
+    return {
+        project: {
+            reference_mode: "storyboard-reference"
+        },
+        storyboard_reference: {
+            enabled: true,
+            max_storyboard_phases: maxPhases,
+            recommended_phase_budget: phaseBudget,
+            provider_reference_tokens: providerReferenceTokens,
+            continuity_mode: continuityModes.length === 1
+                ? continuityModes[0] ?? "multi-shot-storyboard"
+                : "mixed",
+            provider_file_limits: providerFileLimits,
+            character_reference_sheets: {
+                enabled: true,
+                provider: "gpt-image-2",
+                generated_once_per_character: true,
+                aspect_ratio: "16:9",
+                required_views: [
+                    "front full body",
+                    "back full body",
+                    "left profile",
+                    "right profile",
+                    "three-quarter full body",
+                    "close-up face"
+                ]
+            },
+            storyboard_prompt_policy: {
+                enabled: true,
+                provider: "gpt-image-2",
+                generated_per_shot: true,
+                aspect_ratio: "16:9",
+                max_panels_per_shot: maxPhases,
+                panel_budget: phaseBudget.policy,
+                professional_prompt_target_words: "160-240 words per shot storyboard prompt"
+            },
+            role_separation: {
+                character_identity: `${providerReferenceTokens.characterIdentities.join(", ")} control identity, face, hair, body proportions, wardrobe, accessories, and visible props.`,
+                storyboard_reference: `${providerReferenceTokens.storyboardReference} controls composition, blocking, camera direction, timing, action rhythm, and phase order only.`,
+                storyboard_never_identity_source: [
+                    "storyboard text",
+                    "panel borders",
+                    "watermarks",
+                    "logos",
+                    "alternate character designs"
+                ]
+            },
+            split_policy: {
+                split_storyboard_overload: request.storyboardReferenceMode.splitStoryboardOverload,
+                split_at_phase_count: splitRequired ? maxPhases + 1 : phaseBudget.splitAtPhaseCount,
+                split_target: "SHOTNN.md"
+            }
+        },
+        shot_handoff_notes: bundles.map(bundle => bundle.handoffNote)
+    };
+}
 function buildModelPrompts(request, bundleInput) {
     const modelPrompts = {};
     for (const model of request.targetModels) {
@@ -45,8 +308,11 @@ export function buildStoryboardReferencePromptBundles(input) {
     const request = normalizeVideoPromptRequest(input);
     assertSafeStoryboardReferenceRequest(request);
     const assets = resolveAssetRoles(request.characterRefs, request.storyboardRefs, request.additionalRefs);
-    const panelCount = getStoryboardPanelCount(request);
-    const maxPhases = request.storyboardReferenceMode.maxStoryboardPhases;
+    const characterReferenceSheetPrompts = buildCharacterReferenceSheetPrompts(assets, request.outputDir);
+    const phaseBudget = buildStoryboardPhaseBudget(request.durationSeconds, request.storyboardReferenceMode.maxStoryboardPhases);
+    const providerFileLimits = buildProviderFileLimitReport(request, characterReferenceSheetPrompts.length + 1);
+    const panelCount = getStoryboardPanelCount(request, phaseBudget);
+    const maxPhases = phaseBudget.effectiveMaxStoryboardPhases;
     const splitRequired = panelCount > maxPhases;
     if (splitRequired && !request.storyboardReferenceMode.splitStoryboardOverload) {
         throw new Error(`Storyboard has ${panelCount} phases, which exceeds maxStoryboardPhases=${maxPhases}. Enable splitStoryboardOverload or split the storyboard manually.`);
@@ -55,27 +321,61 @@ export function buildStoryboardReferencePromptBundles(input) {
         ? getSplitPhaseCounts(panelCount, maxPhases)
         : [Math.min(panelCount, maxPhases)];
     const generatedAt = new Date().toISOString();
-    const bundles = phaseCounts.map((phaseCount, index) => {
+    const bundles = [];
+    let previousShotHandoff = "Project opening: start from the screenplay's first visual beat.";
+    phaseCounts.forEach((phaseCount, index) => {
+        const shotId = buildShotId(index);
         const interpretation = interpretStoryboard(request, assets, phaseCount, splitRequired);
+        const continuityMode = inferContinuityMode(interpretation.phases);
+        const handoffNote = buildShotHandoffNote({
+            shotId,
+            continuityMode,
+            storyboardInterpretation: interpretation
+        });
+        const storyboardImagePrompt = buildStoryboardImagePrompt({
+            request,
+            assets,
+            shotId,
+            interpretation,
+            characterReferenceSheetPrompts,
+            previousShotHandoff,
+            nextShotHandoff: handoffNote.exitHandoff
+        });
+        const providerAssetMapping = buildProviderAssetMapping(assets, characterReferenceSheetPrompts, storyboardImagePrompt);
+        const referenceAssetRequirements = buildReferenceAssetRequirements(providerAssetMapping);
         const modelPrompts = buildModelPrompts(request, {
             assets,
             interpretation,
+            continuityMode,
+            phaseBudget,
+            providerFileLimits,
+            storyboardImagePrompt,
+            providerAssetMapping,
             visualWorld: interpretation.visualWorld
         });
         const bundle = {
-            shotId: buildShotId(index),
+            shotId,
             mode: "storyboard-reference",
             durationSeconds: request.durationSeconds,
             aspectRatio: request.aspectRatio,
             modelPrompts,
             storyboardInterpretation: interpretation,
             assetRoles: assets.assetRoles,
+            continuityMode,
+            phaseBudget,
+            handoffNote,
+            storyboardImagePrompt,
+            referenceAssetRequirements,
+            providerAssetMapping,
             qa: { verdict: "pass", checks: {}, issues: [], splitRequired },
             generatedAt
         };
         bundle.qa = validatePromptBundle(bundle, assets);
-        return bundle;
+        bundles.push(bundle);
+        previousShotHandoff = handoffNote.exitHandoff;
     });
+    const providerReferenceTokens = buildProviderReferenceTokens(bundles[0]?.providerAssetMapping ?? {});
+    const policy = buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits, bundles, providerReferenceTokens, maxPhases, splitRequired);
     return {
         plan: {
             mode: "storyboard-reference",
@@ -83,10 +383,13 @@ export function buildStoryboardReferencePromptBundles(input) {
             shotCount: bundles.length,
             splitRequired,
             assetRoles: assets.assetRoles,
+            characterReferenceSheetPrompts,
+            policy,
             generatedAt
         },
         request,
         assets,
+        characterReferenceSheetPrompts,
         bundles
     };
 }

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

@@ -25,8 +25,11 @@ function assertAspectRatio(aspectRatio) {
     }
     return aspectRatio;
 }
-function assertReferenceAssets(assets, fieldName) {
-    if (assets.length === 0) {
+function assertReferenceAssets(assets, fieldName, options) {
+    if (!assets || assets.length === 0) {
+        if (!options.required) {
+            return;
+        }
         throw new Error(`storyboard-reference mode requires at least one ${fieldName}.`);
     }
     for (const asset of assets) {
@@ -42,8 +45,8 @@ export function normalizeVideoPromptRequest(input) {
     if (!input.brief.trim()) {
         throw new Error("storyboard-reference mode requires a non-empty brief.");
     }
-    assertReferenceAssets(input.characterRefs, "character reference");
-    assertReferenceAssets(input.storyboardRefs, "storyboard reference");
+    assertReferenceAssets(input.characterRefs, "character reference", { required: true });
+    assertReferenceAssets(input.storyboardRefs, "storyboard reference", { required: false });
     const storyboardReferenceMode = resolveStoryboardReferenceRuntime(input.storyboardReferenceMode);
     if (!storyboardReferenceMode.enabled) {
         throw new Error("storyboard-reference mode is disabled by storyboardReferenceMode.enabled=false.");
@@ -51,6 +54,7 @@ export function normalizeVideoPromptRequest(input) {
     const normalized = {
         ...input,
         targetModels: assertSupportedModels(input.targetModels),
+        storyboardRefs: input.storyboardRefs ?? [],
         durationSeconds: normalizePositiveInteger(input.durationSeconds, DEFAULT_STORYBOARD_DURATION_SECONDS, "durationSeconds"),
         aspectRatio: assertAspectRatio(input.aspectRatio ?? DEFAULT_STORYBOARD_ASPECT_RATIO),
         language: input.language?.trim() || DEFAULT_STORYBOARD_LANGUAGE,

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

@@ -1,2 +1,4 @@
-import type { NormalizedVideoPromptRequest, ResolvedAssetRoles, StoryboardInterpretation } from "./types.js";
+import type { NormalizedVideoPromptRequest, ResolvedAssetRoles, SeedanceContinuityMode, StoryboardInterpretation, StoryboardPhaseBudget, StoryboardPhase } from "./types.js";
+export declare function buildStoryboardPhaseBudget(durationSeconds: number, configuredMaxStoryboardPhases: number): StoryboardPhaseBudget;
+export declare function inferContinuityMode(phases: StoryboardPhase[]): SeedanceContinuityMode;
 export declare function interpretStoryboard(request: NormalizedVideoPromptRequest, assets: ResolvedAssetRoles, phaseCount: number, splitRequired: boolean): StoryboardInterpretation;

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

@@ -36,6 +36,26 @@ function formatTimeRange(index, phaseCount, durationSeconds) {
     const end = (durationSeconds * (index + 1)) / phaseCount;
     return `${start.toFixed(1)}s-${end.toFixed(1)}s`;
 }
+export function buildStoryboardPhaseBudget(durationSeconds, configuredMaxStoryboardPhases) {
+    const durationPolicy = durationSeconds <= 6
+        ? { min: 1, max: 2, policy: "4-6s:1-2" }
+        : durationSeconds <= 10
+            ? { min: 2, max: 3, policy: "7-10s:2-3" }
+            : { min: 3, max: 4, policy: "11-15s:3-4" };
+    const effectiveMaxStoryboardPhases = Math.max(1, Math.min(configuredMaxStoryboardPhases, durationPolicy.max));
+    return {
+        durationSeconds,
+        providerDurationRangeSeconds: { min: 4, max: 15 },
+        recommendedMinPhases: durationPolicy.min,
+        recommendedMaxPhases: durationPolicy.max,
+        effectiveMaxStoryboardPhases,
+        splitAtPhaseCount: effectiveMaxStoryboardPhases + 1,
+        policy: durationPolicy.policy
+    };
+}
+export function inferContinuityMode(phases) {
+    return phases.length <= 1 ? "continuous-shot" : "multi-shot-storyboard";
+}
 function buildPhases(request, phaseCount) {
     return Array.from({ length: phaseCount }, (_, index) => {
         const job = PHASE_JOBS[Math.min(index, PHASE_JOBS.length - 1)] ?? "handoff";
@@ -63,7 +83,7 @@ export function interpretStoryboard(request, assets, phaseCount, splitRequired)
         riskFlags.push("dialogue-needs-voice-cast");
     }
     return {
-        storyboardAssetId: assets.storyboards[0]?.asset.id ?? "storyboard1",
+        storyboardAssetId: assets.storyboards[0]?.asset.id ?? "generated-shot-storyboard",
         panelCount: phaseCount,
         phases: buildPhases(request, phaseCount),
         editorialFunction: inferEditorialFunction(request.brief),

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

@@ -24,7 +24,7 @@ export interface VideoPromptRequest {
     targetModels: SupportedModel[];
     brief: string;
     characterRefs: ReferenceAsset[];
-    storyboardRefs: ReferenceAsset[];
+    storyboardRefs?: ReferenceAsset[];
     additionalRefs?: ReferenceAsset[];
     durationSeconds?: number;
     aspectRatio?: HybridAspectRatio;
@@ -39,6 +39,7 @@ export interface VideoPromptRequest {
     storyboardReferenceMode?: Partial<StoryboardReferenceConfig>;
 }
 export interface NormalizedVideoPromptRequest extends VideoPromptRequest {
+    storyboardRefs: ReferenceAsset[];
     durationSeconds: number;
     aspectRatio: HybridAspectRatio;
     language: string;
@@ -66,6 +67,94 @@ export interface ResolvedAssetRoles {
         label?: string;
     }>;
 }
+export type SeedanceContinuityMode = "continuous-shot" | "multi-shot-storyboard";
+export interface StoryboardPhaseBudget {
+    durationSeconds: number;
+    providerDurationRangeSeconds: {
+        min: 4;
+        max: 15;
+    };
+    recommendedMinPhases: number;
+    recommendedMaxPhases: number;
+    effectiveMaxStoryboardPhases: number;
+    splitAtPhaseCount: number;
+    policy: "4-6s:1-2" | "7-10s:2-3" | "11-15s:3-4";
+}
+export interface ProviderFileLimitReport {
+    maxImages: 9;
+    maxVideos: 3;
+    maxAudio: 3;
+    maxTotalFiles: 12;
+    observedImages: number;
+    observedVideos: number;
+    observedAudio: number;
+    observedUnknown: number;
+    observedTotalFiles: number;
+    withinLimits: boolean;
+}
+export interface ProviderReferenceTokenPolicy {
+    characterIdentity: string;
+    characterIdentities: string[];
+    storyboardReference: string;
+    legacyAliases: {
+        characterIdentity: string;
+        characterIdentities: string[];
+        storyboardReference: string;
+    };
+    videoReference: "@video1";
+    audioReference: "@audio1";
+}
+export interface ShotHandoffNote {
+    shotId: string;
+    continuityMode: SeedanceContinuityMode;
+    phaseCount: number;
+    entryHandoff: string;
+    exitHandoff: string;
+}
+export interface CharacterReferenceSheetPrompt {
+    id: string;
+    characterAssetId: string;
+    sourceToken: string;
+    outputPath: string;
+    provider: "gpt-image-2";
+    aspectRatio: "16:9";
+    cellCount: 6;
+    generatedOnce: true;
+    promptText: string;
+}
+export interface StoryboardImagePrompt {
+    shotId: string;
+    outputPath: string;
+    provider: "gpt-image-2";
+    aspectRatio: "16:9";
+    panelCount: number;
+    style: "professional-production-storyboard";
+    characterSheetIds: string[];
+    externalStoryboardGuideIds: string[];
+    previousShotHandoff: string;
+    nextShotHandoff: string;
+    promptText: string;
+}
+export type ProviderAssetMappingRole = "character_identity" | "storyboard_plan" | "style_reference" | "camera_reference" | "action_reference" | "prop_reference";
+export interface ProviderAssetMappingEntry {
+    token: string;
+    sourceToken: string;
+    sourceAssetId: string;
+    role: ProviderAssetMappingRole;
+    description: string;
+    legacyAlias?: string;
+    generatedPromptPath?: string;
+}
+export interface ReferenceAssetRequirement {
+    token: string;
+    legacyAlias?: string;
+    source: "character-sheet" | "shot-storyboard" | "additional-reference";
+    assetId: string;
+    role: ProviderAssetMappingRole;
+    required: boolean;
+    generatedPromptPath?: string;
+    notes: string;
+}
 export interface StoryboardPhase {
     index: number;
     timeRange: string;
@@ -131,10 +220,16 @@ export interface ModelPromptQa {
     checks: Record<string, boolean>;
     issues: string[];
 }
+export interface ModelRouteMetadata extends Record<string, unknown> {
+    continuityMode?: SeedanceContinuityMode;
+    providerAssetMapping?: Record<string, ProviderAssetMappingEntry>;
+    phaseBudget?: StoryboardPhaseBudget;
+    providerFileLimits?: ProviderFileLimitReport;
+}
 export interface ModelPromptOutput {
     model: SupportedModel;
     displayName: string;
-    routeMetadata: Record<string, unknown>;
+    routeMetadata: ModelRouteMetadata;
     promptText: string;
     audioPlan?: AudioPlan;
     warnings: string[];
@@ -154,6 +249,12 @@ export interface PromptBundle {
     modelPrompts: Partial<Record<SupportedModel, ModelPromptOutput>>;
     storyboardInterpretation: StoryboardInterpretation;
     assetRoles: ResolvedAssetRoles["assetRoles"];
+    continuityMode: SeedanceContinuityMode;
+    phaseBudget: StoryboardPhaseBudget;
+    handoffNote: ShotHandoffNote;
+    storyboardImagePrompt: StoryboardImagePrompt;
+    referenceAssetRequirements: ReferenceAssetRequirement[];
+    providerAssetMapping: Record<string, ProviderAssetMappingEntry>;
     qa: PromptBundleQa;
     generatedAt: string;
 }
@@ -161,6 +262,11 @@ export interface AdapterInput {
     request: NormalizedVideoPromptRequest;
     assets: ResolvedAssetRoles;
     interpretation: StoryboardInterpretation;
+    continuityMode: SeedanceContinuityMode;
+    phaseBudget: StoryboardPhaseBudget;
+    providerFileLimits: ProviderFileLimitReport;
+    storyboardImagePrompt: StoryboardImagePrompt;
+    providerAssetMapping: Record<string, ProviderAssetMappingEntry>;
     voiceCast?: VoiceCastEntry[];
     visualWorld: VisualWorld;
 }
@@ -173,18 +279,61 @@ export interface VideoModelPromptAdapter {
     buildPrompt(input: AdapterInput): ModelPromptOutput;
     validate(output: ModelPromptOutput): ModelPromptQa;
 }
+export interface StoryboardReferencePolicy {
+    project: {
+        reference_mode: "storyboard-reference";
+    };
+    storyboard_reference: {
+        enabled: true;
+        max_storyboard_phases: number;
+        recommended_phase_budget: StoryboardPhaseBudget;
+        provider_reference_tokens: ProviderReferenceTokenPolicy;
+        continuity_mode: SeedanceContinuityMode | "mixed";
+        provider_file_limits: ProviderFileLimitReport;
+        character_reference_sheets: {
+            enabled: true;
+            provider: "gpt-image-2";
+            generated_once_per_character: true;
+            aspect_ratio: "16:9";
+            required_views: string[];
+        };
+        storyboard_prompt_policy: {
+            enabled: true;
+            provider: "gpt-image-2";
+            generated_per_shot: true;
+            aspect_ratio: "16:9";
+            max_panels_per_shot: number;
+            panel_budget: string;
+            professional_prompt_target_words: string;
+        };
+        role_separation: {
+            character_identity: string;
+            storyboard_reference: string;
+            storyboard_never_identity_source: string[];
+        };
+        split_policy: {
+            split_storyboard_overload: boolean;
+            split_at_phase_count: number;
+            split_target: "SHOTNN.md";
+        };
+    };
+    shot_handoff_notes: ShotHandoffNote[];
+}
 export interface StoryboardReferencePlan {
     mode: "storyboard-reference";
     targetModels: SupportedModel[];
     shotCount: number;
     splitRequired: boolean;
     assetRoles: ResolvedAssetRoles["assetRoles"];
+    characterReferenceSheetPrompts: CharacterReferenceSheetPrompt[];
+    policy: StoryboardReferencePolicy;
     generatedAt: string;
 }
 export interface StoryboardReferenceBuildResult {
     plan: StoryboardReferencePlan;
     request: NormalizedVideoPromptRequest;
     assets: ResolvedAssetRoles;
+    characterReferenceSheetPrompts: CharacterReferenceSheetPrompt[];
     bundles: PromptBundle[];
 }
 export interface StoryboardReferenceWriteResult {