@milenyumai/film-kit 2.3.1 → 2.3.2

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

@@ -3,5 +3,5 @@ export { normalizeVideoPromptRequest } from "./request-normalizer.js";
 export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
-export { assertSafeStoryboardReferenceRequest, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.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";

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

@@ -3,4 +3,4 @@ export { normalizeVideoPromptRequest } from "./request-normalizer.js";
 export { resolveAssetRoles } from "./asset-role-resolver.js";
 export { interpretStoryboard } from "./storyboard-interpreter.js";
 export { renderShotMarkdown, writeStoryboardReferenceOutputs } from "./output-writer.js";
-export { assertSafeStoryboardReferenceRequest, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";
+export { assertSafeStoryboardReferenceRequest, assertStoryboardReferenceBuildPass, validateModelPromptOutput, validatePromptBundle, validateResolvedAssetRoles } from "./validators.js";

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

@@ -1,5 +1,6 @@
 import { resolve, join } from "node:path";
 import { writeText } from "../fs.js";
+import { assertStoryboardReferenceBuildPass } from "./validators.js";
 function getAudioPlan(bundle) {
     return Object.values(bundle.modelPrompts).find(Boolean)?.audioPlan;
 }
@@ -180,6 +181,7 @@ ${issues.length === 0 ? "- None" : "- Resolve FAIL items before render automatio
 `;
 }
 export async function writeStoryboardReferenceOutputs(result, rootDir = process.cwd()) {
+    assertStoryboardReferenceBuildPass(result);
     const outputRoot = resolve(rootDir, result.request.outputDir);
     const written = [];
     const planPath = join(outputRoot, "storyboard-reference-plan.json");
@@ -194,6 +196,7 @@ export async function writeStoryboardReferenceOutputs(result, rootDir = process.
 - Character sheet prompts: ${result.characterReferenceSheetPrompts.length}
 - External storyboard guides: ${result.assets.storyboards.length}
 - Generated shot storyboard prompts: ${result.bundles.length}
+- Voice cast entries: ${result.plan.voiceCast.length}
 - Target models: ${result.request.targetModels.join(", ")}
 - Safety context: ${result.request.safetyContext}
 `);

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

@@ -4,7 +4,7 @@ import { Seedance20PromptAdapter } from "./adapters/seedance20.js";
 import { Veo31PromptAdapter } from "./adapters/veo31.js";
 import { normalizeVideoPromptRequest } from "./request-normalizer.js";
 import { buildStoryboardPhaseBudget, inferContinuityMode, interpretStoryboard } from "./storyboard-interpreter.js";
-import { assertSafeStoryboardReferenceRequest, validateModelPromptOutput, validatePromptBundle } from "./validators.js";
+import { assertSafeStoryboardReferenceRequest, validateCharacterReferenceSheetPrompts, validateModelPromptOutput, validatePromptBundle } from "./validators.js";
 const ADAPTERS = {
     veo31: new Veo31PromptAdapter(),
     "seedance-2.0": new Seedance20PromptAdapter(),
@@ -74,6 +74,22 @@ function buildProviderFileLimitReport(request, generatedImageReferenceCount) {
     };
     return report;
 }
+function buildVoiceCast(request) {
+    const speakers = new Map();
+    for (const line of request.dialogue) {
+        const speakerKey = line.speaker.trim();
+        if (!speakerKey || speakers.has(speakerKey)) {
+            continue;
+        }
+        speakers.set(speakerKey, {
+            speakerKey,
+            displayName: speakerKey,
+            language: request.language,
+            voiceIdentityPrompt: `Original fictional voice for ${speakerKey}; keep the same age impression, accent family, breath texture, pacing, and emotional baseline across all storyboard-reference shots.`
+        });
+    }
+    return Array.from(speakers.values());
+}
 function buildShotHandoffNote(input) {
     const firstPhase = input.storyboardInterpretation.phases[0];
     const lastPhase = input.storyboardInterpretation.phases.at(-1);
@@ -103,7 +119,13 @@ function buildCharacterReferenceSheetPrompts(assets, outputDir) {
             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."}`
+            promptText: `REFERENCE LOCK: Use ${character.token} (${sourceLabel}) as the immutable identity source for this original fictional character. This generated sheet becomes the identity reference for all later shot storyboards.
+
+Keep same: exact face, skull shape, hair, skin texture, body proportions, wardrobe, accessories, visible props, material behavior, silhouette, and natural asymmetry. Do not beautify, redesign, age-shift, stylize, or change brand-free clothing.
+
+Change only: convert the source reference into one 16:9 realistic production storyboard character reference sheet. 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. 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.${index === 0 ? "" : " Match visual finish to the earlier character sheets."}
+
+Avoid: text, labels, arrows, captions, panel numbers, watermarks, logos, extra characters, alternate outfits, alternate character designs, background story elements, celebrity resemblance, public-figure likeness, brand marks, beauty filter, cartoon style, anime style, CGI look, final-render polish, distorted face, inconsistent identity between cells, bad anatomy, extra limbs, extra fingers, deformed hands, waxy skin, plastic skin.`
         };
     });
 }
@@ -134,7 +156,11 @@ function buildStoryboardImagePrompt(input) {
         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}
+        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.
+
+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}
 
 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.
 
@@ -144,7 +170,9 @@ Camera and staging: show ${interpretation.cameraPlan.framing}, ${interpretation.
 
 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.`
+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.
+
+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.`
     };
 }
 function isImageReference(asset) {
@@ -309,6 +337,11 @@ export function buildStoryboardReferencePromptBundles(input) {
     assertSafeStoryboardReferenceRequest(request);
     const assets = resolveAssetRoles(request.characterRefs, request.storyboardRefs, request.additionalRefs);
     const characterReferenceSheetPrompts = buildCharacterReferenceSheetPrompts(assets, request.outputDir);
+    const characterPromptIssues = validateCharacterReferenceSheetPrompts(characterReferenceSheetPrompts);
+    if (characterPromptIssues.length > 0) {
+        throw new Error(`Invalid character sheet prompt contract: ${characterPromptIssues.join("; ")}`);
+    }
+    const voiceCast = buildVoiceCast(request);
     const phaseBudget = buildStoryboardPhaseBudget(request.durationSeconds, request.storyboardReferenceMode.maxStoryboardPhases);
     const providerFileLimits = buildProviderFileLimitReport(request, characterReferenceSheetPrompts.length + 1);
     const panelCount = getStoryboardPanelCount(request, phaseBudget);
@@ -363,6 +396,7 @@ export function buildStoryboardReferencePromptBundles(input) {
             assetRoles: assets.assetRoles,
             continuityMode,
             phaseBudget,
+            providerFileLimits,
             handoffNote,
             storyboardImagePrompt,
             referenceAssetRequirements,
@@ -370,11 +404,15 @@ export function buildStoryboardReferencePromptBundles(input) {
             qa: { verdict: "pass", checks: {}, issues: [], splitRequired },
             generatedAt
         };
-        bundle.qa = validatePromptBundle(bundle, assets);
+        bundle.qa = validatePromptBundle(bundle, assets, voiceCast);
         bundles.push(bundle);
         previousShotHandoff = handoffNote.exitHandoff;
     });
     const providerReferenceTokens = buildProviderReferenceTokens(bundles[0]?.providerAssetMapping ?? {});
+    const visualWorld = bundles[0]?.storyboardInterpretation.visualWorld;
+    if (!visualWorld) {
+        throw new Error("Missing visual_world continuity contract for storyboard-reference plan.");
+    }
     const policy = buildStoryboardReferencePolicy(request, phaseBudget, providerFileLimits, bundles, providerReferenceTokens, maxPhases, splitRequired);
     return {
         plan: {
@@ -384,6 +422,8 @@ export function buildStoryboardReferencePromptBundles(input) {
             splitRequired,
             assetRoles: assets.assetRoles,
             characterReferenceSheetPrompts,
+            voiceCast,
+            visual_world: visualWorld,
             policy,
             generatedAt
         },

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

@@ -251,6 +251,7 @@ export interface PromptBundle {
     assetRoles: ResolvedAssetRoles["assetRoles"];
     continuityMode: SeedanceContinuityMode;
     phaseBudget: StoryboardPhaseBudget;
+    providerFileLimits: ProviderFileLimitReport;
     handoffNote: ShotHandoffNote;
     storyboardImagePrompt: StoryboardImagePrompt;
     referenceAssetRequirements: ReferenceAssetRequirement[];
@@ -326,6 +327,8 @@ export interface StoryboardReferencePlan {
     splitRequired: boolean;
     assetRoles: ResolvedAssetRoles["assetRoles"];
     characterReferenceSheetPrompts: CharacterReferenceSheetPrompt[];
+    voiceCast: VoiceCastEntry[];
+    visual_world: VisualWorld;
     policy: StoryboardReferencePolicy;
     generatedAt: string;
 }

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

@@ -1,5 +1,7 @@
-import type { ModelPromptOutput, ModelPromptQa, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ResolvedAssetRoles } from "./types.js";
+import type { CharacterReferenceSheetPrompt, ModelPromptOutput, ModelPromptQa, NormalizedVideoPromptRequest, PromptBundle, PromptBundleQa, ResolvedAssetRoles, StoryboardReferenceBuildResult, VoiceCastEntry } from "./types.js";
 export declare function assertSafeStoryboardReferenceRequest(request: NormalizedVideoPromptRequest): void;
+export declare function validateCharacterReferenceSheetPrompts(prompts: CharacterReferenceSheetPrompt[]): string[];
 export declare function validateResolvedAssetRoles(assets: ResolvedAssetRoles): string[];
 export declare function validateModelPromptOutput(output: ModelPromptOutput): ModelPromptQa;
-export declare function validatePromptBundle(bundle: PromptBundle, assets: ResolvedAssetRoles): PromptBundleQa;
+export declare function validatePromptBundle(bundle: PromptBundle, assets: ResolvedAssetRoles, voiceCast?: VoiceCastEntry[]): PromptBundleQa;
+export declare function assertStoryboardReferenceBuildPass(result: StoryboardReferenceBuildResult): void;

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

@@ -1,28 +1,63 @@
-const BLOCKED_REAL_PERSON_TERMS = [
-    "atatürk",
-    "mustafa kemal",
-    "elon musk",
-    "taylor swift",
-    "beyonce",
-    "messi",
-    "ronaldo"
+const BLOCKED_PUBLIC_FIGURE_OR_BRAND_TERMS = [
+    { term: "atatürk", reason: "real person/public figure" },
+    { term: "mustafa kemal", reason: "real person/public figure" },
+    { term: "elon musk", reason: "real person/public figure" },
+    { term: "taylor swift", reason: "real person/public figure" },
+    { term: "beyonce", reason: "real person/public figure" },
+    { term: "messi", reason: "real person/public figure" },
+    { term: "ronaldo", reason: "real person/public figure" },
+    { term: "nike", reason: "trademark/brand" },
+    { term: "adidas", reason: "trademark/brand" },
+    { term: "coca-cola", reason: "trademark/brand" },
+    { term: "mcdonald", reason: "trademark/brand" },
+    { term: "starbucks", reason: "trademark/brand" },
+    { term: "iphone", reason: "trademark/brand" },
+    { term: "apple logo", reason: "trademark/brand" },
+    { term: "disney", reason: "trademark/brand" },
+    { term: "marvel", reason: "trademark/brand" }
 ];
-function includesBlockedRealPersonTerm(text) {
+function includesBlockedReferenceTerm(text) {
     const normalized = text.toLowerCase();
-    return BLOCKED_REAL_PERSON_TERMS.find(term => normalized.includes(term));
+    return BLOCKED_PUBLIC_FIGURE_OR_BRAND_TERMS.find(entry => normalized.includes(entry.term));
+}
+function hasAvoidOrNegativePrompt(text) {
+    return /Avoid:|\[NEGATIVE PROMPT\]/i.test(text);
+}
+function hasGptImageStillPromptContract(text) {
+    return /REFERENCE LOCK:/i.test(text)
+        && /Keep same:/i.test(text)
+        && /Change only:/i.test(text)
+        && hasAvoidOrNegativePrompt(text);
 }
 export function assertSafeStoryboardReferenceRequest(request) {
     const checkedText = [
         request.brief,
         request.styleIntent,
         request.safetyContext,
-        ...request.characterRefs.map(ref => `${ref.label ?? ""} ${ref.notes ?? ""}`),
-        ...request.storyboardRefs.map(ref => `${ref.label ?? ""} ${ref.notes ?? ""}`)
+        ...request.characterRefs.map(ref => `${ref.id} ${ref.label ?? ""} ${ref.notes ?? ""}`),
+        ...request.storyboardRefs.map(ref => `${ref.id} ${ref.label ?? ""} ${ref.notes ?? ""}`),
+        ...request.additionalRefs.map(ref => `${ref.id} ${ref.label ?? ""} ${ref.notes ?? ""}`),
+        ...request.dialogue.map(line => `${line.speaker}: ${line.text}`)
     ].join("\n");
-    const blocked = includesBlockedRealPersonTerm(checkedText);
+    const blocked = includesBlockedReferenceTerm(checkedText);
     if (blocked) {
-        throw new Error(`Blocked storyboard-reference request: real person/public figure reference '${blocked}' must be removed or safely anonymized before prompt generation.`);
+        throw new Error(`Blocked storyboard-reference request: ${blocked.reason} reference '${blocked.term}' must be removed or safely anonymized before prompt generation.`);
+    }
+}
+export function validateCharacterReferenceSheetPrompts(prompts) {
+    const issues = [];
+    if (prompts.length === 0) {
+        issues.push("Missing character sheet prompt.");
+    }
+    for (const prompt of prompts) {
+        if (!prompt.promptText.trim()) {
+            issues.push(`${prompt.id} is missing prompt text.`);
+        }
+        if (!hasGptImageStillPromptContract(prompt.promptText)) {
+            issues.push(`${prompt.id} must include REFERENCE LOCK / Keep same / Change only / Avoid.`);
+        }
     }
+    return issues;
 }
 export function validateResolvedAssetRoles(assets) {
     const issues = [];
@@ -48,7 +83,7 @@ export function validateModelPromptOutput(output) {
     const prompt = output.promptText;
     const checks = {
         hasPromptText: prompt.trim().length > 0,
-        hasAvoidOrNegative: /Avoid:|\[NEGATIVE PROMPT\]/i.test(prompt),
+        hasAvoidOrNegative: hasAvoidOrNegativePrompt(prompt),
         separatesStoryboardRole: /storyboard/i.test(prompt) && /identity|character reference|@image1/i.test(prompt),
         blocksStoryboardTextCopy: /Do not copy storyboard text|storyboard text|on-screen text/i.test(prompt),
         musicNone: /Music: NONE|Music NONE/i.test(prompt)
@@ -62,17 +97,27 @@ export function validateModelPromptOutput(output) {
         issues
     };
 }
-export function validatePromptBundle(bundle, assets) {
+export function validatePromptBundle(bundle, assets, voiceCast = []) {
     const roleIssues = validateResolvedAssetRoles(assets);
     const modelIssues = Object.values(bundle.modelPrompts)
         .flatMap(output => output?.qa.issues ?? []);
+    const voiceCastKeys = new Set(voiceCast.map(entry => entry.speakerKey));
+    const audioPlans = Object.values(bundle.modelPrompts)
+        .map(output => output?.audioPlan)
+        .filter((plan) => Boolean(plan));
     const checks = {
         hasCharacterReference: assets.characters.length >= 1,
         hasStoryboardReference: assets.storyboards.length >= 1 || Boolean(bundle.storyboardImagePrompt),
+        hasStoryboardImagePrompt: Boolean(bundle.storyboardImagePrompt?.promptText.trim()),
+        storyboardPromptHasReferenceLockStructure: hasGptImageStillPromptContract(bundle.storyboardImagePrompt?.promptText ?? ""),
         hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output?.qa.checks.hasAvoidLine ?? output?.qa.checks.hasAvoidOrNegative)),
+        storyboardPromptHasAvoidLine: hasAvoidOrNegativePrompt(bundle.storyboardImagePrompt?.promptText ?? ""),
         modelGrammarPasses: Object.values(bundle.modelPrompts).every(output => output?.qa.verdict === "pass"),
         storyboardDoesNotOverrideIdentity: Object.values(bundle.modelPrompts).every(output => /storyboard.*staging|storyboard.*planning|storyboard.*composition|storyboard.*only/i.test(output?.promptText ?? "")),
-        audioPlanPresent: Object.values(bundle.modelPrompts).every(output => Boolean(output?.audioPlan))
+        audioPlanPresent: Object.values(bundle.modelPrompts).every(output => Boolean(output?.audioPlan)),
+        speakingAudioPlansHaveActiveSpeaker: audioPlans.every(plan => plan.dialogueTranscript === "NONE" || Boolean(plan.activeSpeakerKey)),
+        activeSpeakerResolvesToVoiceCast: audioPlans.every(plan => !plan.activeSpeakerKey || voiceCastKeys.has(plan.activeSpeakerKey)),
+        providerFilesWithinLimits: bundle.providerFileLimits.withinLimits
     };
     const failedChecks = Object.entries(checks)
         .filter(([, passed]) => !passed)
@@ -85,3 +130,15 @@ export function validatePromptBundle(bundle, assets) {
         splitRequired: bundle.storyboardInterpretation.riskFlags.includes("split-required")
     };
 }
+export function assertStoryboardReferenceBuildPass(result) {
+    const failedBundles = result.bundles.filter(bundle => bundle.qa.verdict !== "pass");
+    const issues = failedBundles.flatMap(bundle => (bundle.qa.issues.length > 0
+        ? bundle.qa.issues.map(issue => `${bundle.shotId}: ${issue}`)
+        : [`${bundle.shotId}: bundle QA failed without a detailed issue.`]));
+    if (result.bundles.length === 0) {
+        issues.push("No storyboard-reference prompt bundles were generated.");
+    }
+    if (issues.length > 0) {
+        throw new Error(`Storyboard-reference QA failed. Refusing to write render-ready outputs. ${issues.join(" ")}`);
+    }
+}