@milenyumai/film-kit 2.2.0 → 2.3.0

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,243 @@ 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.";
+    return {
+        shotId,
+        outputPath: `${request.outputDir}/storyboard-prompts/${shotId}-GPT-IMAGE-2-STORYBOARD.md`,
+        provider: "gpt-image-2",
+        aspectRatio: "16:9",
+        panelCount: interpretation.panelCount,
+        style: "realistic-production-storyboard",
+        characterSheetIds,
+        externalStoryboardGuideIds,
+        previousShotHandoff: input.previousShotHandoff,
+        nextShotHandoff: input.nextShotHandoff,
+        promptText: `Create a professional 16:9 realistic production storyboard image for ${shotId} with exactly ${interpretation.panelCount} readable 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} The scene brief is: ${request.brief}. Continue from the previous handoff: ${input.previousShotHandoff}. End on the next handoff: ${input.nextShotHandoff}. Show the camera plan clearly: ${interpretation.cameraPlan.framing}, ${interpretation.cameraPlan.movement}, ${interpretation.cameraPlan.lens}, preserving ${interpretation.cameraPlan.screenDirection}. Maintain the same environment, lighting, atmosphere, color grade, foreground, midground, and background continuity: ${interpretation.visualWorld.environment}; ${interpretation.visualWorld.lighting}; ${interpretation.visualWorld.atmosphere}. Each panel must show only the phase action needed for the shot, with clean blocking, motivated eyelines, stable scale, readable silhouettes, and practical production-board detail. Do not create final render polish, alternate character designs, text, captions, labels, panel numbers, watermarks, logos, decorative borders, extra scene cuts, or new locations.`
+    };
+}
+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 +292,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 +305,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 +367,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: "realistic-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 {