@sogni-ai/sogni-intelligence-client 2.4.3 → 3.0.0-alpha.10

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

@@ -99,6 +99,7 @@ exports.inferDefaultVideoSteps = inferDefaultVideoSteps;
 exports.resolveVideoSteps = resolveVideoSteps;
 exports.sanitizeBatchPrompt = sanitizeBatchPrompt;
 const index_js_1 = require("../contracts/data/index.js");
+const turnPolicy_js_1 = require("../contracts/turnPolicy.js");
 function isLtxWorkflow(workflow) {
     return workflow === 't2v' || workflow === 'i2v' || workflow === 'ia2v' || workflow === 'a2v' || workflow === 'v2v';
 }
@@ -185,9 +186,18 @@ function createPublicSkillDefaultContractRuntime(input = {}) {
         ],
     });
 }
+const PUBLIC_SKILL_ADVISORY_SIGNAL_SOURCES = new Set(['regex', 'fact_extractor']);
+function normalizePublicSkillSignal(signal) {
+    const source = (0, turnPolicy_js_1.normalizeSignalSource)(String(signal.source));
+    if (source === signal.source)
+        return signal;
+    return { ...signal, source };
+}
 function publicSkillSignalSourcesByKind(signals) {
     const sourcesByKind = new Map();
     for (const signal of signals) {
+        if (PUBLIC_SKILL_ADVISORY_SIGNAL_SOURCES.has(signal.source))
+            continue;
         const sources = sourcesByKind.get(signal.kind) ?? new Set();
         sources.add(signal.source);
         sourcesByKind.set(signal.kind, sources);
@@ -226,7 +236,7 @@ function classifyPublicSkillTurn(input) {
     const signals = [
         ...(input.signals ?? []),
         ...publicSkillSessionSignals(input.sessionState),
-    ];
+    ].map(normalizePublicSkillSignal);
     const sourcesByKind = publicSkillSignalSourcesByKind(signals);
     const forbidden = new Set();
     const required = new Set();
@@ -654,10 +664,10 @@ exports.IMAGE_GENERATION_SKILL = {
 exports.IMAGE_EDITING_SKILL = {
     id: 'image_editing',
     name: 'Image editing',
-    description: 'Edit, restore, restyle, refine, or change the camera angle of an existing image. Includes persona-conditioned edits — persona images must always be produced with edit_image and reference photos, never via text-to-image.',
+    description: 'Edit, restore, restyle, refine, or change the camera angle of an existing image. Includes persona-conditioned edits — persona images should use edit_image and reference photos rather than text-to-image.',
     toolNames: ['edit_image', 'restore_photo', 'apply_style', 'change_angle', 'refine_result'],
     constraints: [
-        'Persona images must always be produced with edit_image and a reference photo — never invoke generate_image for persona output.',
+        'For persona image output, use edit_image with a reference photo rather than generate_image.',
         'refine_result acts on a prior generation in the session; do not call it before any image has been produced or uploaded.',
     ],
 };
@@ -667,7 +677,7 @@ exports.VIDEO_GENERATION_SKILL = {
     description: 'Text-to-video synthesis (LTX-2). Use when the user wants a new video clip generated from a prompt with no source image, audio, or clip.',
     toolNames: ['generate_video'],
     constraints: [
-        'Persona-driven video requests must always go through image_editing first to produce a conditioned image; never go straight to text-to-video for personas.',
+        'For My Personas video requests, default to image_editing first to produce a conditioned scene image before animation. Use direct video only when the user explicitly asks to animate an existing persona image/reference or no source image is available for a voice-only request.',
     ],
 };
 exports.VIDEO_EDITING_SKILL = {
@@ -687,7 +697,7 @@ exports.VIDEO_EDITING_SKILL = {
         'add_subtitles',
     ],
     constraints: [
-        'Per-clip retry and the batch progress contract are sacred — never collapse a multi-clip render down to a single waterfall call.',
+        'Preserve per-clip retry and batch progress semantics. Use one Dynamic Prompt project for prompt-only fan-out, and avoid serial waterfall calls for independent clips.',
         'animate_photo errors with all_failed must surface to the user; do not auto-retry from inside the chat loop.',
     ],
 };
@@ -709,7 +719,7 @@ exports.PERSONA_MANAGEMENT_SKILL = {
     description: "Resolve named personas to their reference photos and read/write the user's long-term creative memory (preferences, named subjects, ongoing projects).",
     toolNames: ['resolve_personas', 'manage_memory'],
     constraints: [
-        'A persona-driven request must call resolve_personas before any image_editing or video_editing tool — never assume a name resolves on its own.',
+        'For clear My Personas references, call resolve_personas before persona-conditioned image or video tools; do not rely on name text alone for identity.',
     ],
 };
 exports.APP_SETTINGS_SKILL = {
@@ -787,33 +797,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}`),
@@ -2748,8 +2773,8 @@ const STORYBOARD_COUNT_WORDS = {
 };
 const DEFAULT_STORYBOARD_TIMING_RULES = {
     normalWordsPerSecondMin: 2.0,
-    normalWordsPerSecondMax: 3.3,
-    fastWordsPerSecondMax: 4.0,
+    normalWordsPerSecondMax: 2.5,
+    fastWordsPerSecondMax: 3.0,
     minEndCardHoldSec: 2.0,
     minPunchlineSec: 0.5,
     toleranceSec: 0.25,
@@ -2942,10 +2967,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) {
@@ -2955,10 +2983,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) {
@@ -3073,13 +3104,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('; '),
         };
     }
@@ -3089,7 +3123,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('; '),
     };
 }
@@ -3473,6 +3507,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'), '')
@@ -3580,6 +3624,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) {
@@ -3637,6 +3726,12 @@ function extractStoryboardRequiredText(text) {
         const isProductionDirectionField = /\b(?:action|motion|camera|transition|audio|sfx|fx|foley|sound|music|dialogue|vo|voiceover|voice-over|narration|speech|lighting|style|performance|beat)\b/i.test(fieldLabel)
             && !visibleTextContextPattern.test(fieldLabel);
         const hasExplicitVisibleTextContext = visibleTextContextPattern.test(line);
+        const precedingCue = compactStoryboardLine([
+            precedingText ?? '',
+            line.slice(0, Math.max(0, matchIndex - lineStart)),
+        ].join(' ')).slice(-180);
+        const spokenTextCue = /\b(?:dialogue|vo|v\.o\.|voiceover|voice-over|voice\s*over|narration|speech|spoken(?:\s+line)?|audio\s*\/\s*dialogue)\b/i.test(precedingCue)
+            || /\b(?:narrator|speaker|actor|character|person|subject|host|mascot|performer|he|she|they)\b[^"“`]{0,80}\b(?:says?|speaks?|whispers?|shouts?|asks?|replies?)\b/i.test(precedingCue);
         const isRestrictionOnlyTextInstruction = visibleTextContextPattern.test(fieldLabel || line)
             && visibleTextRestrictionPattern.test(value)
             && !/["“”`]/.test(value);
@@ -3668,6 +3763,9 @@ function extractStoryboardRequiredText(text) {
         if ((isProductionDirectionField || looksLikeActionOrSfxCallout) && !hasExplicitVisibleTextContext) {
             return true;
         }
+        if (spokenTextCue && !/\b(?:visible|on[-\s]?screen|in[-\s]?frame|text|copy|cta|tagline|headline|title\s+card|caption|subtitle|super|wordmark|slogan|sign|poster|banner|label|placard|sticker|screen)\b/i.test(precedingCue)) {
+            return true;
+        }
         if (looksLikeAssetHandle
             && /\b(?:asset|reference|image|photo|upload|file|filename|logo|brand)\b/i.test(line)) {
             return true;
@@ -3743,7 +3841,7 @@ 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 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);
@@ -3782,9 +3880,10 @@ function extractStoryboardRequiredText(text) {
     for (const match of text.matchAll(exactTextPattern)) {
         const fullMatch = match[0];
         const quoteOpenInMatch = fullMatch.search(/["“`]/);
-        const precedingInMatch = quoteOpenInMatch >= 0 ? fullMatch.slice(0, quoteOpenInMatch) : fullMatch;
+        const quoteAbsIndex = (match.index ?? 0) + Math.max(0, quoteOpenInMatch);
+        const lineStart = text.lastIndexOf('\n', quoteAbsIndex) + 1;
         addRequiredText(match[1] ?? match[2] ?? match[3], match.index ?? 0, {
-            precedingText: precedingInMatch,
+            precedingText: text.slice(lineStart, quoteAbsIndex),
         });
     }
     const labeledTextPattern = /\b(?:on[-\s]?screen\s+text|visible\s+text|text\s+only|text|end\s+card\s+text|final\s+text|tagline|cta|headline|title\s+card|copy)\s*:\s*([^\n]{1,260})/gi;
@@ -4243,6 +4342,26 @@ function storyboardTableRowLooksLikeCountedBeat(cells, headers) {
     const candidate = compactStoryboardLine(cells[Math.max(0, headerIndex)] || cells[0] || '');
     return /^(?:beat|scene|shot|panel|frame)?\s*(?:#\s*)?0?\d{1,2}\b/i.test(candidate);
 }
+function normalizeStoryboardTableCellsToHeaders(cells, headers) {
+    if (!headers || cells.length <= headers.length)
+        return cells;
+    const overflow = cells.length - headers.length;
+    const combinedAudioDialogueIndex = headers.findIndex(header => /\baudio\b/i.test(header)
+        && /\b(?:dialogue|vo|v\.o\.|voiceover|speech|narration)\b/i.test(header));
+    if (combinedAudioDialogueIndex < 0)
+        return cells;
+    const mergeEnd = combinedAudioDialogueIndex + overflow;
+    if (mergeEnd >= cells.length)
+        return cells;
+    const overflowCells = cells.slice(combinedAudioDialogueIndex, mergeEnd + 1);
+    if (!overflowCells.some(cell => storyboardTableCellLooksLikeUnlabeledSpeech(cell)))
+        return cells;
+    return [
+        ...cells.slice(0, combinedAudioDialogueIndex),
+        overflowCells.join('\n'),
+        ...cells.slice(mergeEnd + 1),
+    ];
+}
 function storyboardTableCellWithoutDialogue(cell, dialogue) {
     const normalizedDialogue = compactStoryboardLine(dialogue).toLowerCase();
     return cell
@@ -4300,13 +4419,14 @@ function splitStoryboardTableSections(text) {
     const sections = [];
     let headers = null;
     for (const line of text.split(/\r?\n/)) {
-        const cells = storyboardMarkdownTableCells(line);
-        if (cells.length < 3)
+        const rawCells = storyboardMarkdownTableCells(line);
+        if (rawCells.length < 3)
             continue;
-        if (looksLikeStoryboardTableHeader(cells)) {
-            headers = cells;
+        if (looksLikeStoryboardTableHeader(rawCells)) {
+            headers = rawCells;
             continue;
         }
+        const cells = normalizeStoryboardTableCellsToHeaders(rawCells, headers);
         const timingCellIndex = cells.findIndex(cell => extractStoryboardTimingMarker(cell) !== null);
         if (timingCellIndex < 0)
             continue;
@@ -5047,10 +5167,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;
@@ -5073,13 +5193,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;
@@ -5251,6 +5380,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()
@@ -5301,6 +5451,7 @@ 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),
@@ -5324,7 +5475,7 @@ 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
@@ -5355,21 +5506,25 @@ 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) {
@@ -5599,67 +5754,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) {
@@ -5794,32 +5899,36 @@ 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
@@ -5827,7 +5936,7 @@ 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),
@@ -5846,27 +5955,28 @@ function ensureCompiledVideoStoryboardPromptPreservesSourceBrief(compiledPrompt,
 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})`)) {
@@ -5937,7 +6047,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) {