@sogni-ai/sogni-intelligence-client 3.0.0-alpha.9 → 3.0.2

package/dist-esm/public-skill-runtime/index.js

@@ -696,33 +696,48 @@ function compileStoryboardImagePromptFromProject(project) {
         : `Overall storyboard canvas aspect ratio: ${layout.boardAspectRatio}.`;
     return [
         'CREATE:',
-        `Create exactly ${frameCount} sequential video storyboard frames as one composite storyboard image.`,
-        `Project title: ${project.title}.`,
-        project.durationSec !== null ? `Target duration: ${project.durationSec} seconds.` : 'Target duration: unspecified in source brief.',
-        '',
-        ...compileStoryboardCountContractSection(project, layout),
+        `Create exactly ${frameCount} sequential video storyboard frames as one production storyboard sheet.`,
         '',
-        ...compileStoryboardReferenceSection(project),
+        'PROJECT:',
+        `Title: ${project.title}.`,
+        `Format: ${layout.targetVideoAspectRatio} video storyboard.`,
+        project.durationSec !== null ? `Target duration: ${project.durationSec} seconds.` : 'Target duration: unspecified in source brief.',
         '',
-        'CANVAS / LAYOUT:',
+        'LAYOUT CONTRACT:',
+        `Create exactly ${frameCount} numbered storyboard panels; do not render fewer or more panels.`,
+        `Arrange panels in reading order, left-to-right then top-to-bottom: ${Array.from({ length: frameCount }, (_, index) => {
+            const scene = project.scenes[index];
+            return `[${index + 1}] ${scene?.id.toUpperCase() ?? `SCENE_${String(index + 1).padStart(2, '0')}`}`;
+        }).join(', ')}.`,
         boardSizeLine,
         `Individual scene-cell/frame aspect ratio: ${layout.cellAspectRatio}.`,
         `Target final video aspect ratio: ${layout.targetVideoAspectRatio}.`,
         `Layout preset: ${layout.layoutKind} - ${layout.layoutDescription}.`,
+        `Each panel must contain one distinct ${layout.cellAspectRatio} cinematic video-frame rectangle with compact notes outside the frame.`,
+        'Keep scene numbers, timecodes, titles, dialogue/VO, audio notes, and production notes outside the video-frame rectangles.',
+        'Do not merge panels, create inset thumbnails, make panels square, or overlay storyboard metadata inside the artwork frames.',
         '',
-        ...compileStoryboardStoryContinuitySection(project),
+        ...compileStoryboardReferenceSection(project),
+        '',
+        'STYLE:',
+        `${project.creativeBrief.visualQualityBar} with cinematic shot language, coherent art direction, readable labels, and consistent reference usage.`,
+        'Reference-driven personality: before drawing, infer concrete visual and behavioral cues from uploaded/reference images, including character attitude, materials, props, palette, brand tone, typography style, and implied world. Let those cues make this storyboard specific to the supplied subject instead of a generic reusable template.',
+        'Vary composition within the required grid: keep the exact scene count, layout, and cell geometry, and make each panel intentionally staged with distinct shot scale, pose/action, camera angle, lighting beat, transition idea, and character-specific detail.',
         '',
-        'GLOBAL STYLE:',
-        project.creativeBrief.visualQualityBar,
+        ...compileStoryboardStoryContinuitySection(project),
         '',
         'CRITICAL REQUIREMENTS:',
         ...compileStoryboardCriticalRequirements().map((item, index) => `${index + 1}. ${item}`),
+        ...project.references
+            .filter(ref => ref.preservePriority === 'critical')
+            .map((ref, index) => `${compileStoryboardCriticalRequirements().length + index + 1}. Critical reference lock: ${ref.id} (${ref.kind}) must remain bound to its assigned usage scope: ${ref.usageScope}.`),
         '',
         ...compileStoryboardScenesSection(project),
-        'TEXT RENDERING:',
-        'Keep production labels outside video-frame artwork. Only user-required diegetic or brand text belongs inside a frame.',
+        'TEXT RULES:',
+        'Place scene number, timing, scene title, beat title, and compact production labels outside each video frame in a clearly associated header, footer strip, side rail, or table. Do not overlay scene numbers, timecodes, production notes, Dialogue/VO labels, Audio/SFX text, or SFX/action callout words such as Whoosh!, Impact!, Boom!, Thud!, Slash!, Crack!, or Pop! on top of the video-frame artwork. Also do not overlay scene/beat titles on top of the video-frame artwork. Project titles are metadata, not in-frame text. Only listed diegetic or brand text belongs inside a frame. Quote and spell any required visible text exactly.',
         'Visible text listed on a scene belongs only in that scene; repeat visible text only on scenes that list it.',
         ...storyboardRequiredVisibleText(project).map(formatStoryboardRequiredVisibleTextLine),
+        project.endCard.logoUsage ? `Logo usage: ${project.endCard.logoUsage}` : '',
         '',
         'NEGATIVE / AVOID:',
         ...compileStoryboardAvoidSection(project.creativeBrief.concept).map(item => `- ${item}`),
@@ -1558,7 +1573,7 @@ export function suggestedDurationForDialogue(prompt, currentDuration) {
     const baseDuration = currentDuration ?? 0;
     if (words <= 0)
         return baseDuration;
-    const speechSeconds = Math.ceil(words / 2.5) + 2;
+    const speechSeconds = Math.ceil(words / 3) + 2;
     return Math.max(baseDuration, Math.min(20, speechSeconds));
 }
 export function formatAudioIdPrompt(prompt, voiceName) {
@@ -2656,8 +2671,8 @@ const STORYBOARD_COUNT_WORDS = {
 };
 const DEFAULT_STORYBOARD_TIMING_RULES = {
     normalWordsPerSecondMin: 2.0,
-    normalWordsPerSecondMax: 3.3,
-    fastWordsPerSecondMax: 4.0,
+    normalWordsPerSecondMax: 3.0,
+    fastWordsPerSecondMax: 3.75,
     minEndCardHoldSec: 2.0,
     minPunchlineSec: 0.5,
     toleranceSec: 0.25,
@@ -2850,10 +2865,13 @@ function describePortraitLetterboxCellArrangement(frameCount, cellAspectRatio) {
     }
     const columns = frameCount <= 8 ? 2 : frameCount <= 15 ? 3 : 4;
     const rows = Math.ceil(frameCount / columns);
+    const unusedSlotNote = columns * rows > frameCount
+        ? ['use unused grid slots as margin/notes space only']
+        : [];
     return [
         `${frameCount} numbered scene slots arranged as a ${columns}-column x ${rows}-row grid inside a portrait sheet`,
         `each slot contains one ${frameShape} with compact labels outside the rectangle`,
-        'use unused grid slots as margin/notes space only',
+        ...unusedSlotNote,
     ].join('; ');
 }
 function describeLandscapePortraitCellArrangement(frameCount, cellAspectRatio) {
@@ -2863,10 +2881,13 @@ function describeLandscapePortraitCellArrangement(frameCount, cellAspectRatio) {
     }
     const rows = frameCount <= 8 ? 2 : frameCount <= 15 ? 3 : 4;
     const columns = Math.ceil(frameCount / rows);
+    const unusedSlotNote = columns * rows > frameCount
+        ? ['use unused grid slots as margin/notes space only']
+        : [];
     return [
         `${frameCount} numbered scene slots arranged as a ${rows}-row x ${columns}-column grid inside a landscape board`,
         `each slot contains one ${frameShape} with compact labels outside the rectangle`,
-        'use unused grid slots as margin/notes space only',
+        ...unusedSlotNote,
     ].join('; ');
 }
 function parseAspectRatioPair(aspectRatio) {
@@ -2981,13 +3002,16 @@ function describeSingleOrientationStoryboardArrangement(boardAspectRatio, cellAs
     const slotGrid = pickBalancedSlotGrid(frameCount);
     const cols = cellOrientation === 'landscape' ? slotGrid.minor : slotGrid.major;
     const rows = cellOrientation === 'landscape' ? slotGrid.major : slotGrid.minor;
+    const unusedSlotNote = cols * rows > frameCount
+        ? ['use unused grid slots as margin/notes space only']
+        : [];
     if (boardOrientation === 'portrait') {
         return {
             layoutKind: 'portrait_grid',
             layoutDescription: [
                 `${frameCount} numbered scene slots arranged as a ${cols}-column x ${rows}-row grid inside a portrait storyboard sheet`,
                 `each slot contains one ${frameShape} with compact labels outside the rectangle`,
-                'use unused grid slots as margin/notes space only',
+                ...unusedSlotNote,
             ].join('; '),
         };
     }
@@ -2997,7 +3021,7 @@ function describeSingleOrientationStoryboardArrangement(boardAspectRatio, cellAs
         layoutDescription: [
             `${frameCount} numbered scene slots arranged as a ${rows}-row x ${cols}-column grid inside a ${boardLabel}`,
             `each slot contains one ${frameShape} with compact labels outside the rectangle`,
-            'use unused grid slots as margin/notes space only',
+            ...unusedSlotNote,
         ].join('; '),
     };
 }
@@ -3381,6 +3405,16 @@ function cleanStoryboardReferenceSubjectHint(context, index) {
     const explicitSubject = cleanExplicitStoryboardReferenceSubject(source, index);
     if (explicitSubject)
         return explicitSubject;
+    const inlineReference = new RegExp(String.raw `\b(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\b\s*(?:is|=|:|-)?\s*([^.;,\n]{2,120})`, 'i').exec(source);
+    if (inlineReference?.[1]) {
+        const inlineSubject = compactStoryboardLine(stripStoryboardMarkup(inlineReference[1]))
+            .replace(/\b(?:use|usage|preserve|reference|asset)\b[\s\S]*$/i, '')
+            .replace(/[.\s]+$/g, '')
+            .trim();
+        if (inlineSubject && !/^(?:logo|brand|character|mascot|asset|reference|image|photo|picture)$/i.test(inlineSubject)) {
+            return inlineSubject.slice(0, 180).replace(/\s+\S*$/, match => inlineSubject.length > 180 ? '' : match).trim();
+        }
+    }
     const cleaned = source
         .replace(new RegExp(String.raw `^(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\s*(?:\([^)]*\))?\s*:?\s*`, 'i'), '')
         .replace(new RegExp(String.raw `^(?:uploaded|attached|provided|reference|source|input)\s+(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\s*:?\s*`, 'i'), '')
@@ -3488,6 +3522,51 @@ function buildStoryboardReferenceAssets(userIntentText, prompt) {
         preservePriority: storyboardPreservePriorityFromRole(role),
     }));
 }
+function storyboardReferenceIndexFromText(value) {
+    const normalized = value.trim();
+    if (!normalized)
+        return null;
+    const match = normalized.match(/^(?:@?\s*)?(?:image|photo|picture|asset|uploaded\s+asset|uploaded\s+image)[\s_#-]*(\d{1,2})$/i)
+        ?? normalized.match(/^image_(\d{1,2})$/i);
+    if (!match)
+        return null;
+    const index = Number(match[1]);
+    return Number.isInteger(index) && index > 0 ? index : null;
+}
+function looksLikeUnknownIndexedStoryboardReference(value) {
+    return /^(?:@?\s*)?(?:image|photo|picture|asset|uploaded\s+asset|uploaded\s+image)[\s_#-]*\d{1,2}$/i.test(value.trim())
+        || /^image_\d{1,2}$/i.test(value.trim());
+}
+function normalizeStoryboardSceneReferenceUsage(referenceUsage, references) {
+    if (referenceUsage.length === 0 || references.length === 0)
+        return [];
+    const knownById = new Map(references.map(ref => [ref.id.toLowerCase(), ref.id]));
+    const knownByIndex = new Map(references
+        .filter(ref => typeof ref.index === 'number')
+        .map(ref => [ref.index, ref.id]));
+    const normalized = [];
+    for (const raw of referenceUsage) {
+        const value = raw.trim();
+        if (!value)
+            continue;
+        const knownId = knownById.get(value.toLowerCase());
+        if (knownId) {
+            normalized.push(knownId);
+            continue;
+        }
+        const index = storyboardReferenceIndexFromText(value);
+        if (index !== null) {
+            const id = knownByIndex.get(index);
+            if (id)
+                normalized.push(id);
+            continue;
+        }
+        if (looksLikeUnknownIndexedStoryboardReference(value))
+            continue;
+        normalized.push(value);
+    }
+    return uniqueStoryboardStrings(normalized);
+}
 function compileStoryboardReferenceSection(project) {
     const refs = project.references;
     if (refs.length <= 0) {
@@ -3535,6 +3614,31 @@ function extractStoryboardRequiredText(text) {
     const visibleTextContextPattern = /\b(?:visible|on[-\s]?screen|in[-\s]?frame|text|copy|cta|tagline|headline|title\s+card|caption|subtitle|super|wordmark|spell(?:ed)?|read(?:s)?|slogan)\b/i;
     const sceneHeadingPattern = /^\s*(?:[-*+]\s*)?(?:#{1,6}\s*)?(?:[*_]{1,3})?\s*(?:Scene|Shot|Beat|Panel|Frame)[\s_#-]*\d{1,2}\b/i;
     const visibleTextRestrictionPattern = /\b(?:only\s+(?:text|copy|words?)|no\s+(?:captions?|subtitles?|overlays?|watermarks?|added\s+logos?|extra\s+logos?|logos?|text|copy)|without\s+(?:captions?|subtitles?|overlays?|watermarks?|added\s+logos?|extra\s+logos?|logos?|text|copy)|do\s+not\s+(?:add|include|render|show|write)\s+(?:captions?|subtitles?|overlays?|watermarks?|logos?|text|copy|words?))\b/i;
+    const storyboardTextCandidateLooksLikeConversationInstruction = (candidate) => {
+        const raw = compactStoryboardLine(stripStoryboardMarkup(candidate))
+            .replace(/^["“”'`]+|["“”'`]+$/g, '')
+            .trim();
+        if (!raw)
+            return false;
+        if (/^\[(?:uploaded|attached|provided)\s+(?:images?|files?|videos?|audio)\s*:/i.test(raw))
+            return true;
+        if (/^(?:yes|no|approved?|looks?\s+good|ok(?:ay)?|sure)[.!?]?$/i.test(raw))
+            return true;
+        const value = raw.toLowerCase();
+        const workflowTerm = /\b(?:script|prompt|story\s*board|storyboard|take|version|again|redo|retry|regenerate|re-generate|revise|revision|approve|approval|proceed|generate|render|run|do\s+it|best\s+judg(?:e)?ment)\b/i;
+        if (/^use\s+your\s+best\s+judg(?:e)?ment\b/i.test(raw))
+            return true;
+        if (/^(?:try\s+another|another\s+take|regenerate|re-generate|redo|retry|revise)\b/i.test(raw))
+            return true;
+        if (/^(?:go\s+ahead|can\s+you|please)\b/i.test(raw) && workflowTerm.test(value))
+            return true;
+        if (/^let'?s\b|^lets\b/i.test(raw)) {
+            return /\b(?:script|prompt|story\s*board|storyboard|take|version|again|redo|retry|regenerate|re-generate|revise|revision)\b/i.test(value)
+                || /\b(?:generate|render|create|do|run)\s+it\b/i.test(value)
+                || /\buse\s+your\s+best\s+judg(?:e)?ment\b/i.test(value);
+        }
+        return false;
+    };
     const shouldIgnoreRequiredText = (value, matchIndex, precedingText) => {
         const lineStart = text.lastIndexOf('\n', matchIndex) + 1;
         const nextLineBreak = text.indexOf('\n', matchIndex);
@@ -3570,6 +3674,9 @@ function extractStoryboardRequiredText(text) {
         if (storyboardTextCandidateLooksLikeGenericProductionLabel(value)) {
             return true;
         }
+        if (storyboardTextCandidateLooksLikeConversationInstruction(value)) {
+            return true;
+        }
         if (isNestedSceneHeadingField) {
             return true;
         }
@@ -3644,6 +3751,8 @@ function extractStoryboardRequiredText(text) {
             return false;
         if (storyboardTextCandidateLooksLikeGenericProductionLabel(value))
             return false;
+        if (storyboardTextCandidateLooksLikeConversationInstruction(value))
+            return false;
         const contextNamesText = /\b(?:slogans?|taglines?|cta|copy|text|words?|wordmark|brand|logo|end\s+card|final\s+card|end\s+scene|final\s+scene|closing\s+card)\b/i
             .test(context);
         if (!contextNamesText)
@@ -3660,7 +3769,10 @@ function extractStoryboardRequiredText(text) {
             || /^(?:powered|made|built|created|generated|rendered|presented)\s+by\b/i.test(value);
         return !productionDirection || copyOverridesProduction;
     };
-    const endCardLabelPattern = /^\s*(?:[-*+]\s*)?(?:end|final|closing)\s+(?:scene|card|frame|shot|cta|logo(?:\s+lockup)?)\s*:\s*([^\n]*)$/gim;
+    const endCardFollowingLineLooksLikeContinuationInstruction = (line) => {
+        return storyboardTextCandidateLooksLikeConversationInstruction(line);
+    };
+    const endCardLabelPattern = /^\s*(?:[-*+]\s*)?(?:(?:end|final|closing)\s+(?:scene|card|frame|shot|cta|logo(?:\s+lockup)?)|(?:scene|shot|beat|panel|frame)\s*\d{1,2}\s+(?:visible\s+text|on[-\s]?screen\s+text|onscreen\s+text|text|copy|cta)(?:\s+must\s+be\s+exactly)?)\s*:\s*([^\n]*)$/gim;
     for (const match of text.matchAll(endCardLabelPattern)) {
         const matchIndex = match.index ?? 0;
         const lineEnd = text.indexOf('\n', matchIndex);
@@ -3672,6 +3784,8 @@ function extractStoryboardRequiredText(text) {
                 break;
             if (/^(?:#{1,6}\s+|\|\s*|(?:Scene|Shot|Beat|Panel|Frame)\s*\d{1,2}\b)/i.test(trimmed))
                 break;
+            if (endCardFollowingLineLooksLikeContinuationInstruction(trimmed))
+                break;
             if (followingLines.length >= 5)
                 break;
             followingLines.push(trimmed);
@@ -4986,10 +5100,10 @@ function alignAssistantStoryboardDialogueWithUserSource(scenes, userIntentText,
         return { scenes, shouldRetime: false };
     return { scenes: repaired, shouldRetime: true };
 }
-function minimumStoryboardSceneDurationForDialogue(scene, rules) {
+function minimumStoryboardSceneDurationForDialogue(scene, rules, wordsPerSecondMax = rules.normalWordsPerSecondMax) {
     const dialogueWords = countWords(scene.dialogue);
     let minDuration = dialogueWords > 0
-        ? dialogueWords / rules.normalWordsPerSecondMax
+        ? dialogueWords / wordsPerSecondMax
         : 0.5;
     const sceneContext = `${scene.title}\n${scene.visual}\n${scene.textInImage.join(' ')}`;
     const hasReadableText = scene.textInImage.length > 0;
@@ -5012,13 +5126,22 @@ function retimeStoryboardScenesForDialogue(scenes, targetDurationSec, rules = DE
     const needsRetiming = scenes.some((scene, index) => (scene.durationSec ?? 0) + rules.toleranceSec < minimumDurations[index]);
     if (!needsRetiming)
         return scenes;
-    const minimumTotal = Math.round(minimumDurations.reduce((sum, duration) => sum + duration, 0) * 100) / 100;
+    let requiredDurations = minimumDurations;
+    let minimumTotal = Math.round(requiredDurations.reduce((sum, duration) => sum + duration, 0) * 100) / 100;
+    if (minimumTotal > targetDurationSec + rules.toleranceSec && rules.fastWordsPerSecondMax > rules.normalWordsPerSecondMax) {
+        const fastDurations = scenes.map(scene => minimumStoryboardSceneDurationForDialogue(scene, rules, rules.fastWordsPerSecondMax));
+        const fastTotal = Math.round(fastDurations.reduce((sum, duration) => sum + duration, 0) * 100) / 100;
+        if (fastTotal <= targetDurationSec + rules.toleranceSec) {
+            requiredDurations = fastDurations;
+            minimumTotal = fastTotal;
+        }
+    }
     if (minimumTotal > targetDurationSec + rules.toleranceSec)
         return scenes;
     const extraDuration = Math.max(0, targetDurationSec - minimumTotal);
     const originalDurations = scenes.map(scene => scene.durationSec ?? 0);
     const weightTotal = originalDurations.reduce((sum, duration) => sum + Math.max(0.01, duration), 0);
-    const unroundedDurations = minimumDurations.map((minimum, index) => (minimum + (extraDuration * Math.max(0.01, originalDurations[index]) / weightTotal)));
+    const unroundedDurations = requiredDurations.map((minimum, index) => (minimum + (extraDuration * Math.max(0.01, originalDurations[index]) / weightTotal)));
     const timelineStartSec = scenes[0].startSec ?? 0;
     const timelineEndSec = Math.round((timelineStartSec + targetDurationSec) * 100) / 100;
     let cursor = timelineStartSec;
@@ -5190,6 +5313,27 @@ function finalStoryboardSceneVisibleText(scenes) {
     }
     return [];
 }
+function applyStoryboardEndCardTextToScenes(scenes, endCardText) {
+    if (scenes.length === 0 || endCardText.length === 0)
+        return scenes;
+    const finalSceneIndex = scenes.length - 1;
+    const explicitEndCardIndex = (() => {
+        for (let index = scenes.length - 1; index >= 0; index -= 1) {
+            if (storyboardSceneLooksLikeEndCard(scenes[index]))
+                return index;
+        }
+        return finalSceneIndex;
+    })();
+    return scenes.map((scene, index) => index === explicitEndCardIndex
+        ? {
+            ...scene,
+            textInImage: uniqueStoryboardStrings([
+                ...scene.textInImage,
+                ...endCardText,
+            ]),
+        }
+        : scene);
+}
 function storyboardRequiredTextKey(value) {
     return compactStoryboardLine(value)
         .toLowerCase()
@@ -5240,6 +5384,7 @@ export function buildStoryboardProject(options) {
     const userIntentText = canonicalStoryboardScriptContext(rawUserIntentText) || rawUserIntentText;
     const narrativeUserIntentText = cleanStoryboardNarrativeSourceText(userIntentText);
     const approvedScriptContext = cleanStoryboardNarrativeSourceText(canonicalStoryboardScriptContext(options.approvedScriptContext));
+    const referencePromptContext = cleanStoryboardNarrativeSourceText(canonicalStoryboardScriptContext(prompt) || prompt);
     const primarySourceBrief = selectStoryboardSourceBriefForCompile(options, userIntentText);
     const sourceText = stripGenericStoryboardVisibleTextMetadata(sanitizeStoryboardExternalAudioReferences([
         cleanStoryboardNarrativeSourceText(primarySourceBrief),
@@ -5263,7 +5408,7 @@ export function buildStoryboardProject(options) {
     const requestedDurationSec = inferRequestedTotalVideoDurationSeconds(userIntentText);
     const durationSec = requestedDurationSec ?? inferRequestedTotalVideoDurationSeconds(sourceText);
     const references = buildStoryboardReferenceAssets(userIntentText, [
-        prompt,
+        referencePromptContext,
         approvedScriptContext,
     ].filter(Boolean).join('\n\n'));
     const approvedSections = approvedScriptContext
@@ -5294,21 +5439,25 @@ export function buildStoryboardProject(options) {
             return buildSceneFromSection(section, references, null, storyboardScenePlanningContractForIndex(options.planningContract, section.number));
         })
         : [];
-    const scenes = parsedScenes;
+    const scenes = parsedScenes.map(scene => ({
+        ...scene,
+        referenceUsage: normalizeStoryboardSceneReferenceUsage(scene.referenceUsage, references),
+    }));
     const timingNormalizedScenes = normalizeAssistantStoryboardSceneTiming(scenes, durationSec, options.promptAuthorship);
     const dialogueAlignment = alignAssistantStoryboardDialogueWithUserSource(timingNormalizedScenes, userIntentText, options.promptAuthorship);
-    const normalizedScenes = dialogueAlignment.shouldRetime
+    const dialogueTimedScenes = (options.promptAuthorship === 'assistant' || dialogueAlignment.shouldRetime)
         ? retimeStoryboardScenesForDialogue(dialogueAlignment.scenes, durationSec)
         : dialogueAlignment.scenes;
     const userConstraintSource = buildStoryboardUserConstraintSource(narrativeUserIntentText, cleanStoryboardNarrativeSourceText(primarySourceBrief), options);
-    const { mustIncludeText, endCardText } = storyboardRequiredTextForProject(options, userConstraintSource, normalizedScenes);
+    const { mustIncludeText, endCardText } = storyboardRequiredTextForProject(options, userConstraintSource, dialogueTimedScenes);
+    const normalizedScenes = retimeStoryboardScenesForDialogue(applyStoryboardEndCardTextToScenes(dialogueTimedScenes, endCardText), durationSec);
     const voiceLines = assignVoiceLinesToScenes(normalizedScenes, sourceText);
     const storySpineFallback = approvedScriptContext
         || (options.promptAuthorship === 'assistant' ? narrativeUserIntentText : cleanStoryboardNarrativeSourceText(primarySourceBrief))
         || prompt
         || narrativeUserIntentText;
     const storySpine = inferStoryboardStorySpine(allText, storySpineFallback);
-    const productFeatureMap = inferStoryboardProductFeatureMap(allText, scenes);
+    const productFeatureMap = inferStoryboardProductFeatureMap(allText, normalizedScenes);
     const beatMarkerScripts = [approvedScriptContext, sourceText];
     let directBeatMarkerCount = 0;
     for (const text of beatMarkerScripts) {
@@ -5538,67 +5687,17 @@ function compileStoryboardStoryContinuitySection(project) {
         'Keep product/feature/brand meaning in the associated notes. Do not force long product explanations or the whole script into tiny in-frame text.',
     ];
 }
-function compileStoryboardCountContractSection(project, layout, expectedFrameCount = project.scenes.length) {
-    if (expectedFrameCount <= 0)
-        return [];
-    const sceneSlots = Array.from({ length: expectedFrameCount }, (_, index) => {
-        const scene = project.scenes[index];
-        return `[${index + 1}] ${scene?.id.toUpperCase() ?? `SCENE_${String(index + 1).padStart(2, '0')}`}`;
-    })
-        .join(', ');
-    return [
-        'COUNT / GRID CONTRACT:',
-        `Required scene count: exactly ${expectedFrameCount} numbered storyboard scene slots; do not render fewer slots and do not add extra scene slots.`,
-        `Allocate the full ${expectedFrameCount}-slot storyboard grid before drawing details. Fill slots in reading order, left-to-right then top-to-bottom: ${sceneSlots}.`,
-        `Each allocated scene slot gets one distinct ${layout.cellAspectRatio} cinematic video-frame rectangle plus its own compact notes outside that rectangle. Do not merge adjacent scenes, combine two beats into one slot, duplicate slots, or place thumbnail/inset panels inside a slot.`,
-        `Layout preset: ${layout.layoutKind} - ${layout.layoutDescription}. The final sheet should be visibly countable as ${expectedFrameCount} numbered scene slots at a glance.`,
-    ];
-}
-function compileStoryboardFrameGeometrySection(layout) {
-    const cellOrientation = parseAspectRatioOrientation(layout.cellAspectRatio);
-    if (cellOrientation === 'portrait') {
-        return [
-            'PORTRAIT FRAME GEOMETRY:',
-            'Treat each numbered scene slot as a container, not as the artwork shape.',
-            `Inside every numbered scene slot, draw one identical upright ${layout.cellAspectRatio} video-frame rectangle whose height is visibly greater than its width.`,
-            `Keep all scene numbers, timing, titles, notes, headers, footers, and production labels outside the ${layout.cellAspectRatio} video-frame rectangles.`,
-            `Do not make the numbered scene slots, frame artwork areas, or thumbnails square. Square cells violate the requested ${layout.cellAspectRatio} final video format.`,
-            'Unused grid slots must remain blank margin/notes space only; do not stretch or square off the portrait frame rectangles to fill the grid.',
-        ];
-    }
-    if (cellOrientation === 'landscape') {
-        return [
-            'LANDSCAPE FRAME GEOMETRY:',
-            'Treat each numbered scene slot as a container, not as the artwork shape.',
-            `Inside every numbered scene slot, draw one identical wide ${layout.cellAspectRatio} video-frame rectangle whose width is visibly greater than its height.`,
-            `Keep all scene numbers, timing, titles, notes, headers, footers, and production labels outside the ${layout.cellAspectRatio} video-frame rectangles.`,
-            `Do not make the numbered scene slots, frame artwork areas, or thumbnails square. Square cells violate the requested ${layout.cellAspectRatio} final video format.`,
-            'Unused grid slots must remain blank margin/notes space only; do not stretch or square off the landscape frame rectangles to fill the grid.',
-        ];
-    }
-    if (cellOrientation === 'square') {
-        return [
-            'SQUARE FRAME GEOMETRY:',
-            'Treat each numbered scene slot as a container, not as the artwork shape.',
-            `Inside every numbered scene slot, draw one identical square ${layout.cellAspectRatio} video-frame area plus compact notes outside that square.`,
-            `Do not stretch square frame artwork areas into portrait, landscape, full-board, or any aspect ratio other than ${layout.cellAspectRatio}.`,
-        ];
-    }
-    return [
-        'FRAME GEOMETRY:',
-        `Inside every numbered scene slot, draw one identical ${layout.cellAspectRatio} video-frame rectangle plus compact notes outside that rectangle.`,
-        `Do not let frame artwork areas drift to square, full-board, or any aspect ratio other than ${layout.cellAspectRatio}.`,
-    ];
-}
 function promptReferenceUsageForScene(referenceUsage, references, modelId) {
     if (referenceUsage.length === 0)
         return '';
     const referenceById = new Map(references.map((ref, index) => [ref.id, { ref, index }]));
-    return uniqueStoryboardStrings(referenceUsage.map(value => {
+    return uniqueStoryboardStrings(referenceUsage.flatMap(value => {
         const found = referenceById.get(value);
-        if (!found)
-            return value;
-        return formatModelRef(modelId, found.ref.index ?? found.index + 1, 'image');
+        if (found)
+            return [formatModelRef(modelId, found.ref.index ?? found.index + 1, 'image')];
+        if (looksLikeUnknownIndexedStoryboardReference(value))
+            return [];
+        return [value];
     })).join(', ');
 }
 function storyboardMetadataLabelAliases(labels) {
@@ -5733,32 +5832,36 @@ export function compileVideoStoryboardImagePrompt(options) {
         : `Overall storyboard canvas aspect ratio: ${layout.boardAspectRatio}.`;
     return [
         'CREATE:',
-        `Create exactly ${compiledFrameCount} sequential video storyboard frames as one composite storyboard image.`,
-        `Project title: ${project.title}.`,
-        project.durationSec !== null ? `Target duration: ${project.durationSec} seconds.` : 'Target duration: unspecified in source brief.',
-        '',
-        ...compileStoryboardCountContractSection(project, layout, compiledFrameCount),
+        `Create exactly ${compiledFrameCount} sequential video storyboard frames as one production storyboard sheet.`,
         '',
-        ...compileStoryboardReferenceSection(project),
+        'PROJECT:',
+        `Title: ${project.title}.`,
+        `Format: ${layout.targetVideoAspectRatio} video storyboard.`,
+        project.durationSec !== null ? `Target duration: ${project.durationSec} seconds.` : 'Target duration: unspecified in source brief.',
         '',
-        'CANVAS / LAYOUT:',
+        'LAYOUT CONTRACT:',
+        `Create exactly ${compiledFrameCount} numbered storyboard panels; do not render fewer or more panels.`,
+        `Arrange panels in reading order, left-to-right then top-to-bottom: ${Array.from({ length: compiledFrameCount }, (_, index) => {
+            const scene = project.scenes[index];
+            return `[${index + 1}] ${scene?.id.toUpperCase() ?? `SCENE_${String(index + 1).padStart(2, '0')}`}`;
+        }).join(', ')}.`,
         boardSizeLine,
         `Individual scene-cell/frame aspect ratio: ${layout.cellAspectRatio}.`,
         `Target final video aspect ratio: ${layout.targetVideoAspectRatio}.`,
         `Layout preset: ${layout.layoutKind} - ${layout.layoutDescription}.`,
-        `Every cinematic frame artwork area inside every scene cell must preserve ${layout.cellAspectRatio}; do not let any individual frame drift to square, full-board, or a different portrait/landscape ratio.`,
-        'Keep margins, gutters, outside-frame numbering, note strips, and typography consistent across the full board.',
-        'Each scene cell must make the frame-to-notes relationship clear while keeping production labels outside the actual video-frame artwork.',
+        `Each panel must contain one distinct ${layout.cellAspectRatio} cinematic video-frame rectangle with compact notes outside the frame.`,
+        'Keep scene numbers, timecodes, titles, dialogue/VO, audio notes, and production notes outside the video-frame rectangles.',
+        'Do not merge panels, create inset thumbnails, make panels square, or overlay storyboard metadata inside the artwork frames.',
         '',
-        ...compileStoryboardFrameGeometrySection(layout),
-        '',
-        ...compileStoryboardStoryContinuitySection(project),
+        ...compileStoryboardReferenceSection(project),
         '',
-        'GLOBAL STYLE:',
+        'STYLE:',
         `${project.creativeBrief.visualQualityBar} with cinematic shot language, coherent art direction, readable labels, and consistent reference usage.`,
         'Reference-driven personality: before drawing, infer concrete visual and behavioral cues from uploaded/reference images, including character attitude, materials, props, palette, brand tone, typography style, and implied world. Let those cues make this storyboard specific to the supplied subject instead of a generic reusable template.',
         'Vary composition within the required grid: keep the exact scene count, layout, and cell geometry, and make each panel intentionally staged with distinct shot scale, pose/action, camera angle, lighting beat, transition idea, and character-specific detail.',
         '',
+        ...compileStoryboardStoryContinuitySection(project),
+        '',
         'CRITICAL REQUIREMENTS:',
         ...compileStoryboardCriticalRequirements().map((item, index) => `${index + 1}. ${item}`),
         ...project.references
@@ -5766,7 +5869,7 @@ export function compileVideoStoryboardImagePrompt(options) {
             .map((ref, index) => `${compileStoryboardCriticalRequirements().length + index + 1}. Critical reference lock: ${ref.id} (${ref.kind}) must remain bound to its assigned usage scope: ${ref.usageScope}.`),
         '',
         ...compileStoryboardScenesSection(project),
-        'TEXT RENDERING:',
+        'TEXT RULES:',
         'Place scene number, timing, scene title, beat title, and compact production labels outside each video frame in a clearly associated header, footer strip, side rail, or table. Do not overlay scene numbers, timecodes, production notes, Dialogue/VO labels, Audio/SFX text, or SFX/action callout words such as Whoosh!, Impact!, Boom!, Thud!, Slash!, Crack!, or Pop! on top of the video-frame artwork. Also do not overlay scene/beat titles on top of the video-frame artwork. Project titles are metadata, not in-frame text. Only listed diegetic or brand text belongs inside a frame. Quote and spell any required visible text exactly.',
         'Visible text listed on a scene belongs only in that scene; repeat visible text only on scenes that list it.',
         ...storyboardRequiredVisibleText(project).map(formatStoryboardRequiredVisibleTextLine),
@@ -5785,27 +5888,28 @@ export function ensureCompiledVideoStoryboardPromptPreservesSourceBrief(compiled
 export function lintStoryboardImagePrompt(prompt, layout, project) {
     const errors = [];
     const warnings = [];
+    const hasConsolidatedLayoutContract = /LAYOUT CONTRACT:/i.test(prompt);
     if (!/CREATE:/i.test(prompt))
         errors.push('missing CREATE section');
-    if (!/COUNT \/ GRID CONTRACT:/i.test(prompt))
+    if (!hasConsolidatedLayoutContract && !/COUNT \/ GRID CONTRACT:/i.test(prompt))
         errors.push('missing COUNT / GRID CONTRACT section');
     if (!/REFERENCE IMAGES:/i.test(prompt))
         errors.push('missing REFERENCE IMAGES section');
-    if (!/CANVAS \/ LAYOUT:/i.test(prompt))
+    if (!hasConsolidatedLayoutContract && !/CANVAS \/ LAYOUT:/i.test(prompt))
         errors.push('missing CANVAS / LAYOUT section');
-    if (!/FRAME GEOMETRY:/i.test(prompt))
+    if (!hasConsolidatedLayoutContract && !/FRAME GEOMETRY:/i.test(prompt))
         errors.push('missing FRAME GEOMETRY section');
     const cellOrientation = parseAspectRatioOrientation(layout.cellAspectRatio);
-    if (cellOrientation === 'portrait' && !/PORTRAIT FRAME GEOMETRY:/i.test(prompt)) {
+    if (!hasConsolidatedLayoutContract && cellOrientation === 'portrait' && !/PORTRAIT FRAME GEOMETRY:/i.test(prompt)) {
         errors.push('missing PORTRAIT FRAME GEOMETRY section');
     }
-    if (cellOrientation === 'landscape' && !/LANDSCAPE FRAME GEOMETRY:/i.test(prompt)) {
+    if (!hasConsolidatedLayoutContract && cellOrientation === 'landscape' && !/LANDSCAPE FRAME GEOMETRY:/i.test(prompt)) {
         errors.push('missing LANDSCAPE FRAME GEOMETRY section');
     }
-    if (cellOrientation === 'square' && !/SQUARE FRAME GEOMETRY:/i.test(prompt)) {
+    if (!hasConsolidatedLayoutContract && cellOrientation === 'square' && !/SQUARE FRAME GEOMETRY:/i.test(prompt)) {
         errors.push('missing SQUARE FRAME GEOMETRY section');
     }
-    if (!/TEXT RENDERING:/i.test(prompt))
+    if (!/(?:TEXT RENDERING|TEXT RULES):/i.test(prompt))
         errors.push('missing TEXT RENDERING section');
     if (!prompt.includes(`Overall storyboard canvas aspect ratio: ${layout.boardAspectRatio}`)
         && !prompt.includes(`(${layout.boardAspectRatio})`)) {
@@ -5876,7 +5980,7 @@ function inferCompiledStoryboardPromptAspectRatio(prompt, labelPattern) {
     return normalizeAspectRatio(match?.[1]);
 }
 function extractCompiledStoryboardScenesBlock(prompt) {
-    const match = prompt.match(/\nSCENES:\s*\n([\s\S]*?)(?:\nTEXT RENDERING:|\nSOURCE BRIEF TO FOLLOW:|\nNEGATIVE \/ AVOID:|$)/i);
+    const match = prompt.match(/\nSCENES:\s*\n([\s\S]*?)(?:\nTEXT RENDERING:|\nTEXT RULES:|\nSOURCE BRIEF TO FOLLOW:|\nNEGATIVE \/ AVOID:|$)/i);
     return match?.[1] ?? '';
 }
 function parseCompiledStoryboardHeadingTiming(heading) {