@milenyumai/film-kit 2.3.0 → 2.3.2

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

@@ -44,16 +44,22 @@ export class Seedance20PromptAdapter extends BaseVideoModelPromptAdapter {
     }
     buildPrompt(input) {
         const audioPlan = buildAudioPlan(input);
+        const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
+        const storyboardToken = storyboardEntry?.token ?? "@Image2";
         const continuityInstruction = input.continuityMode === "continuous-shot"
             ? "No scene cuts throughout, one continuous shot."
-            : "Use only the planned storyboard phase transitions below; do not add unplanned cuts, extra scene jumps, or new locations.";
+            : `Follow the generated storyboard panels in ${storyboardToken} left-to-right, top-to-bottom as the exact visual beat order. Do not reinterpret actions, poses, camera angles, emotional progression, frame variety, or the final pose. Compress the planned sequence into the full duration as concise motion snapshots; use only storyboard-motivated cuts, match cuts, whip transitions, or camera moves, and do not add unplanned cuts, extra scene jumps, or new locations.`;
         const characterEntries = this.getMappingEntries(input, "character_identity");
-        const storyboardEntry = this.getMappingEntries(input, "storyboard_plan")[0];
         const characterTokenText = characterEntries.map(entry => entry.token).join(", ") || "@Image1";
-        const storyboardToken = storyboardEntry?.token ?? "@Image2";
         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]
@@ -63,7 +69,7 @@ ${input.request.brief}
 ${formatPhaseLines(input.interpretation.phases)}
 
 [GPT IMAGE 2 STORYBOARD SOURCE]
-Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source.
+Use the generated storyboard image from ${input.storyboardImagePrompt.outputPath} as ${storyboardToken}. It has ${input.storyboardImagePrompt.panelCount} panel(s), follows the shot handoff, and is not an identity source. Treat colored arrows, panel labels, and lens notes as planning annotations only; never render arrows, notes, labels, timestamps, or storyboard text into the video.
 
 [CAMERA]
 ${input.interpretation.cameraPlan.framing}, ${input.interpretation.cameraPlan.movement}, ${input.interpretation.cameraPlan.lens}, ${input.interpretation.cameraPlan.stabilization}. Preserve ${input.interpretation.cameraPlan.screenDirection}.
@@ -78,9 +84,9 @@ Ambience: ${audioPlan.ambience.join(", ")}.
 Music: NONE.
 
 [CONTINUITY]
-Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources.
+Identity reference stays locked to ${characterTokenText}. Storyboard ${storyboardToken} controls staging, shot order, pose logic, camera variety, emotional progression, and visual rhythm only. Character design, wardrobe, accessories, and visible props cannot be inherited from the storyboard. Storyboard text, panel borders, arrows, colored marks, lens notes, watermark, logo, and alternate character design are never identity sources and must not appear in the rendered video.
 
-Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
+Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders, colored arrows, annotation marks, lens notes, timestamps, watermark, logo, distorted hands, rubbery motion, flicker, unnatural camera jumps.`;
         const output = {
             model: this.model,
             displayName: getDisplayName(this.model),
@@ -115,10 +121,18 @@ Avoid: identity drift, face drift, outfit drift, storyboard text, panel borders,
                 && characterTokens.every(token => output.promptText.includes(token))
                 && /exact character identity reference/i.test(output.promptText),
             usesStoryboardToken: output.promptText.includes(storyboardToken) && /shot storyboard reference/i.test(output.promptText),
-            blocksStoryboardIdentitySources: /Storyboard text, panel borders, watermark, logo, and alternate character design are never identity sources/i.test(output.promptText),
+            followsStoryboardOrder: continuityMode === "continuous-shot"
+                ? 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;
 }
@@ -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.`
         };
     });
 }
@@ -117,18 +139,40 @@ function buildStoryboardImagePrompt(input) {
     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: "realistic-production-storyboard",
+        style: "professional-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.`
+        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.
+
+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. 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) {
@@ -293,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);
@@ -347,6 +396,7 @@ export function buildStoryboardReferencePromptBundles(input) {
             assetRoles: assets.assetRoles,
             continuityMode,
             phaseBudget,
+            providerFileLimits,
             handoffNote,
             storyboardImagePrompt,
             referenceAssetRequirements,
@@ -354,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: {
@@ -368,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

@@ -128,7 +128,7 @@ export interface StoryboardImagePrompt {
     provider: "gpt-image-2";
     aspectRatio: "16:9";
     panelCount: number;
-    style: "realistic-production-storyboard";
+    style: "professional-production-storyboard";
     characterSheetIds: string[];
     externalStoryboardGuideIds: string[];
     previousShotHandoff: string;
@@ -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(" ")}`);
+    }
+}