@milenyumai/film-kit 2.3.1 → 2.3.3

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

@@ -54,6 +54,12 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
         const promptText = `${this.formatCharacterRoleLine(input)}
 ${this.formatStoryboardRoleLine(input)}
 
+[REFERENCE ROLES]
+- Identity reference: ${characterTokenText} locks face, hair, body proportions, wardrobe, accessories, visible props, and material continuity.
+- Camera reference: ${storyboardToken} controls composition, camera direction, framing, screen direction, shot order, and lens rhythm only.
+- Action reference: ${storyboardToken} controls blocking, pose logic, timing, action rhythm, phase order, and emotional progression only.
+- Audio reference: use the Audio Plan text below for dialogue, SFX, ambience, and music intent; do not infer audio from storyboard annotations unless explicitly requested.
+
 ${continuityInstruction}
 
 [CORE INTENT]
@@ -119,10 +125,14 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
                 ? hasNoCutsRule
                 : /left-to-right, top-to-bottom/i.test(output.promptText)
                     && /Do not reinterpret actions, poses, camera angles, emotional progression/i.test(output.promptText),
+            separatesReferenceRoles: /Identity reference:/i.test(output.promptText)
+                && /Camera reference:/i.test(output.promptText)
+                && /Action reference:/i.test(output.promptText)
+                && /Audio reference:/i.test(output.promptText),
             blocksStoryboardIdentitySources: /Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
             continuityMode: continuityMode === "continuous-shot"
                 ? hasNoCutsRule
-                : !hasNoCutsRule && /planned storyboard phase transitions/i.test(output.promptText),
+                : !hasNoCutsRule && /storyboard-motivated cuts/i.test(output.promptText),
             musicNone: /Music: NONE/i.test(output.promptText)
         };
         const issues = [

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;
 }
@@ -40,6 +41,37 @@ function formatProviderTokens(bundle) {
     })
         .join("\n");
 }
+function getProviderToken(bundle, role, fallback) {
+    return Object.values(bundle.providerAssetMapping)
+        .find(entry => entry.role === role)?.token ?? fallback;
+}
+function formatCoverageReferences(bundle) {
+    const interpretation = bundle.storyboardInterpretation;
+    const characterTokens = Object.values(bundle.providerAssetMapping)
+        .filter(entry => entry.role === "character_identity")
+        .map(entry => entry.token)
+        .join(", ") || "@Image1";
+    const storyboardToken = getProviderToken(bundle, "storyboard_plan", "@Image2");
+    const visualWorld = interpretation.visualWorld;
+    const camera = interpretation.cameraPlan;
+    const firstPhase = interpretation.phases[0];
+    const lastPhase = interpretation.phases.at(-1) ?? firstPhase;
+    return `## Coverage References In Same File
+
+Coverage is standalone editorial material for this shot only. Do not chain coverage into the next main shot. Keep the same generated character identity, wardrobe, props, lighting direction, environment, screen direction, and visual_world.
+
+### ${bundle.shotId}A - ECU Reaction | 3s
+
+\`\`\`text
+Use ${characterTokens} as the exact identity source and ${storyboardToken} only for scene continuity. Extreme close-up reaction coverage during ${firstPhase?.timeRange ?? "the opening beat"}: ${firstPhase?.subjectAction ?? "the character registers the story beat"}. Keep ${visualWorld.lighting}, ${visualWorld.atmosphere}, and ${camera.screenDirection}. Static or barely drifting camera, shallow depth of field, natural skin texture, visible breath or eye tension, no new action beat, no new identity. Audio: close breath, subtle clothing sound, matched ambience, Music: NONE. Avoid: identity drift, face drift, wardrobe drift, beauty filter, plastic skin, distorted eyes, flicker, warping, on-screen text, watermark, logo.
+\`\`\`
+
+### ${bundle.shotId}B - Insert / Environmental Detail | 3s
+
+\`\`\`text
+Use ${storyboardToken} only for composition and environment continuity; do not introduce a new character identity. Tight insert coverage tied to ${lastPhase?.timeRange ?? "the final beat"}: ${lastPhase?.subjectAction ?? "the action resolves into a clear visual detail"}. Show a physically plausible detail from the same visual world: foreground texture, prop contact, reflection, light spill, hand tension, fabric motion, or environment response. Keep ${visualWorld.environment}; ${visualWorld.foreground}; ${visualWorld.background}; ${visualWorld.lighting}. Audio: matched practical SFX and ambience, no dialogue unless explicitly present in the main Audio Plan, Music: NONE. Avoid: new location, new character, clear logo, readable text, impossible physics, wrong reflection angle, identity override, flicker, warping, cartoon style, CGI look.
+\`\`\``;
+}
 export function renderShotMarkdown(bundle) {
     const interpretation = bundle.storyboardInterpretation;
     const audioPlan = getAudioPlan(bundle);
@@ -103,6 +135,8 @@ ${JSON.stringify(audioPlan ?? null, null, 2)}
 
 ${modelPrompts}
 
+${formatCoverageReferences(bundle)}
+
 ## QA
 ${formatQa(bundle)}
 `;
@@ -180,6 +214,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 +229,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,32 @@ export function validateModelPromptOutput(output) {
         issues
     };
 }
-export function validatePromptBundle(bundle, assets) {
+export function validatePromptBundle(bundle, assets, voiceCast = []) {
     const roleIssues = validateResolvedAssetRoles(assets);
+    const modelValidationResults = Object.values(bundle.modelPrompts)
+        .filter((output) => Boolean(output))
+        .map(validateModelPromptOutput);
     const modelIssues = Object.values(bundle.modelPrompts)
-        .flatMap(output => output?.qa.issues ?? []);
+        .flatMap(output => output?.qa.issues ?? [])
+        .concat(modelValidationResults.flatMap(result => result.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),
-        hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output?.qa.checks.hasAvoidLine ?? output?.qa.checks.hasAvoidOrNegative)),
-        modelGrammarPasses: Object.values(bundle.modelPrompts).every(output => output?.qa.verdict === "pass"),
+        hasStoryboardImagePrompt: Boolean(bundle.storyboardImagePrompt?.promptText.trim()),
+        storyboardPromptHasReferenceLockStructure: hasGptImageStillPromptContract(bundle.storyboardImagePrompt?.promptText ?? ""),
+        hasAvoidLineEverywhere: Object.values(bundle.modelPrompts).every(output => Boolean(output) && hasAvoidOrNegativePrompt(output.promptText)),
+        storyboardPromptHasAvoidLine: hasAvoidOrNegativePrompt(bundle.storyboardImagePrompt?.promptText ?? ""),
+        modelGrammarPasses: Object.values(bundle.modelPrompts).every(output => output?.qa.verdict === "pass")
+            && modelValidationResults.every(result => result.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 +135,25 @@ export function validatePromptBundle(bundle, assets) {
         splitRequired: bundle.storyboardInterpretation.riskFlags.includes("split-required")
     };
 }
+export function assertStoryboardReferenceBuildPass(result) {
+    const issues = validateCharacterReferenceSheetPrompts(result.characterReferenceSheetPrompts)
+        .map(issue => `character-sheet: ${issue}`);
+    for (const bundle of result.bundles) {
+        const currentQa = validatePromptBundle(bundle, result.assets, result.plan.voiceCast);
+        if (bundle.qa.verdict !== "pass" || currentQa.verdict !== "pass") {
+            const bundleIssues = [
+                ...bundle.qa.issues,
+                ...currentQa.issues
+            ];
+            issues.push(...(bundleIssues.length > 0
+                ? bundleIssues.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(" ")}`);
+    }
+}

package/build/lib/storyboard-reference/visual-world-builder.js

@@ -11,7 +11,7 @@ export function buildCameraPlan(request) {
         lens: wideShot ? "35mm lens feel" : closeShot ? "85mm lens feel" : "50mm lens feel",
         framing: wideShot ? "layered wide composition" : closeShot ? "eye-level close framing" : "stable mid-shot framing",
         stabilization: "tripod-stable with minimal organic drift",
-        screenDirection: "preserve the storyboard's screen direction and eyeline relationships"
+        screenDirection: "storyboard screen direction and eyeline relationships"
     };
 }
 export function buildVisualWorld(request) {