@sogni-ai/sogni-creative-agent-skill 2.1.3 → 2.2.0

package/generated/creative-agent-runtime.mjs

@@ -4,8 +4,357 @@
 function isLtxWorkflow(workflow) {
     return workflow === 't2v' || workflow === 'i2v' || workflow === 'ia2v' || workflow === 'a2v' || workflow === 'v2v';
 }
-export const SKILL_RUNTIME_VERSION = '2026-05-04.1';
-export const SEEDANCE_STORYBOARD_REFERENCE_PROMPT = 'Turn the video storyboard in @Image1 into a video by following the thumbnails and script for each segment in the image.';
+export const SKILL_RUNTIME_VERSION = '2026-05-12.1';
+const SEEDANCE_MODEL_REF_FORMAT = {
+    format(index, type) {
+        if (type === 'video')
+            return `@Video${index}`;
+        if (type === 'audio')
+            return `@Audio${index}`;
+        return `@Image${index}`;
+    },
+    parse(token) {
+        const m = /^@(Image|Video|Audio)(\d+)$/.exec(token.trim());
+        if (!m)
+            return null;
+        const index = Number.parseInt(m[2], 10);
+        if (!Number.isFinite(index) || index < 1)
+            return null;
+        return {
+            index,
+            type: m[1] === 'Video' ? 'video' : m[1] === 'Audio' ? 'audio' : 'image',
+        };
+    },
+    scanRegex: /@(?:Image|Video|Audio)\d+/g,
+};
+const GPT_IMAGE_MODEL_REF_FORMAT = {
+    format(index, type) {
+        if (type === 'video')
+            return `Video ${index}`;
+        if (type === 'audio')
+            return `Audio ${index}`;
+        return `Image ${index}`;
+    },
+    parse(token) {
+        const m = /^(?:\[(Image|Video|Audio)\s+(\d+)\]|(Image|Video|Audio)\s+(\d+))$/.exec(token.trim());
+        if (!m)
+            return null;
+        const kind = m[1] ?? m[3];
+        const index = Number.parseInt(m[2] ?? m[4], 10);
+        if (!Number.isFinite(index) || index < 1)
+            return null;
+        return {
+            index,
+            type: kind === 'Video' ? 'video' : kind === 'Audio' ? 'audio' : 'image',
+        };
+    },
+    scanRegex: /(?<!@)(?<!\b[Gg][Pp][Tt]\s)(?:\[(?:Image|Video|Audio)\s+\d+\]|\b(?:Image|Video|Audio)\s+\d+\b)/g,
+};
+const CONTEXT_MODEL_REF_FORMAT = {
+    format(index, type) {
+        const slot = Math.max(0, index - 1);
+        if (type === 'video')
+            return `context_video_${slot}`;
+        if (type === 'audio')
+            return `context_audio_${slot}`;
+        return `context_image_${slot}`;
+    },
+    parse(token) {
+        const m = /^context_(image|video|audio)_(\d+)$/.exec(token.trim());
+        if (!m)
+            return null;
+        const slot = Number.parseInt(m[2], 10);
+        if (!Number.isFinite(slot) || slot < 0)
+            return null;
+        return { index: slot + 1, type: m[1] };
+    },
+    scanRegex: /context_(?:image|video|audio)_\d+/g,
+};
+export function getModelRefFormat(modelId) {
+    const trimmed = modelId.trim().toLowerCase();
+    if (trimmed.startsWith('seedance'))
+        return SEEDANCE_MODEL_REF_FORMAT;
+    if (trimmed.startsWith('gpt-image') || trimmed.startsWith('flux'))
+        return GPT_IMAGE_MODEL_REF_FORMAT;
+    if (trimmed.startsWith('ltx') || trimmed.startsWith('wan') || trimmed.startsWith('qwen-image'))
+        return CONTEXT_MODEL_REF_FORMAT;
+    console.warn(`[SOGNI RUNTIME] Unknown model_id "${modelId}" fell back to GPT Image model_ref format.`);
+    return GPT_IMAGE_MODEL_REF_FORMAT;
+}
+export function formatModelRef(modelId, index, type) {
+    return getModelRefFormat(modelId).format(index, type);
+}
+export const SESSION_CONTROL_SKILL = {
+    id: 'session_control',
+    name: 'Session control',
+    description: 'Turn-control markers that end the current turn cleanly.',
+    toolNames: ['ask_clarifying_question', 'finalize_response'],
+    alwaysLoaded: true,
+    constraints: ['ask_clarifying_question and finalize_response both end the turn.'],
+};
+export const ASSET_REFERENCE_MANAGEMENT_SKILL = {
+    id: 'asset_reference_management',
+    name: 'Asset reference management',
+    description: 'Translate between asset_id, user_label, and per-model model_ref tokens.',
+    toolNames: ['create_asset_manifest', 'inspect_asset', 'label_asset', 'map_assets_for_model', 'validate_asset_references'],
+    alwaysLoaded: true,
+    constraints: ['Use formatModelRef/map assets helpers instead of hand-formatting model reference tokens.'],
+};
+export const QUALITY_AUDIT_SKILL = {
+    id: 'quality_audit',
+    name: 'Quality audit',
+    description: 'Pre-dispatch and post-generation audits that catch parameter / asset / model-range / persona-flow issues before burning a worker round. Findings come back as structured fatal/minor issues with a recommended_action (accept | refine | regenerate | ask_user). Always loaded — cannot be unloaded.',
+    toolNames: [],
+    alwaysLoaded: true,
+    constraints: [
+        'When the audit returns recommended_action="ask_user", surface the fatal_issues to the user and wait — do not retry the tool call.',
+        'When recommended_action="refine", apply the fix_hint(s) on the next attempt rather than repeating the same call.',
+    ],
+};
+export const IMAGE_GENERATION_SKILL = {
+    id: 'image_generation',
+    name: 'Image generation',
+    description: 'Text-to-image synthesis (Flux). Use when the user wants a new image generated from a prompt with no source asset.',
+    toolNames: ['generate_image'],
+    constraints: [
+        'For persona-driven requests, defer to image_editing — personas must be conditioned on reference photos, never generated from scratch.',
+    ],
+};
+export const 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.',
+    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.',
+        'refine_result acts on a prior generation in the session; do not call it before any image has been produced or uploaded.',
+    ],
+};
+export const VIDEO_GENERATION_SKILL = {
+    id: 'video_generation',
+    name: 'Video generation',
+    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.',
+    ],
+};
+export const VIDEO_EDITING_SKILL = {
+    id: 'video_editing',
+    name: 'Video editing',
+    description: 'Convert a still image, audio track, or existing clip into video, plus stitching, orbits, dance-montage compositions, segment extend/replace, and pure-ffmpeg post-production (overlay, subtitles).',
+    toolNames: [
+        'animate_photo',
+        'sound_to_video',
+        'video_to_video',
+        'stitch_video',
+        'orbit_video',
+        'dance_montage',
+        'extend_video',
+        'replace_video_segment',
+        'overlay_video',
+        '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.',
+        'animate_photo errors with all_failed must surface to the user; do not auto-retry from inside the chat loop.',
+    ],
+};
+export const MUSIC_GENERATION_SKILL = {
+    id: 'music_generation',
+    name: 'Music generation',
+    description: 'Compose music with optional lyrics, BPM, key, and structural hints (Sonic Logos).',
+    toolNames: ['generate_music'],
+};
+export const MEDIA_ANALYSIS_SKILL = {
+    id: 'media_analysis',
+    name: 'Media analysis',
+    description: 'Vision analysis of uploaded images / videos and structured extraction of generation metadata from previously rendered results.',
+    toolNames: ['analyze_image', 'analyze_video', 'extract_metadata'],
+};
+export const PERSONA_MANAGEMENT_SKILL = {
+    id: 'persona_management',
+    name: 'Persona & memory',
+    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.',
+    ],
+};
+export const APP_SETTINGS_SKILL = {
+    id: 'app_settings',
+    name: 'App settings',
+    description: 'Toggle user-visible app preferences such as the safe-content filter. Only invoke when the user has explicitly asked to change a setting.',
+    toolNames: ['set_content_filter'],
+};
+export const ALL_BUILT_IN_SKILLS = [
+    QUALITY_AUDIT_SKILL,
+    SESSION_CONTROL_SKILL,
+    ASSET_REFERENCE_MANAGEMENT_SKILL,
+    IMAGE_GENERATION_SKILL,
+    IMAGE_EDITING_SKILL,
+    VIDEO_GENERATION_SKILL,
+    VIDEO_EDITING_SKILL,
+    MUSIC_GENERATION_SKILL,
+    MEDIA_ANALYSIS_SKILL,
+    PERSONA_MANAGEMENT_SKILL,
+    APP_SETTINGS_SKILL,
+];
+export function toolOk(fields) {
+    return { ok: true, status: 'completed', output_assets: [], ...fields };
+}
+export function toolErr(fields) {
+    return { ok: false, ...fields };
+}
+export function isToolResultOk(result) {
+    return result.ok === true;
+}
+export function isToolResultErr(result) {
+    return result.ok === false;
+}
+// ---------------------------------------------------------------------------
+// Storyboard adapter prompt-guidance composer (wraps the per-adapter strings)
+// ---------------------------------------------------------------------------
+/**
+ * Returns the concatenated per-adapter system-prompt guidance block.
+ * Public-skill consumers append this to their chat system prompt so the
+ * model sees the same per-model rules the chat product injects. The
+ * adapter `compile()` runtime is intentionally not bundled here — public
+ * skill callers that need real per-model prompt compilation should
+ * import directly from `@sogni/creative-agent` rather than the
+ * single-file runtime bundle.
+ *
+ * NOTE: The rich adapter `compile()` logic (Seedance / GPT Image 2 /
+ * LTX-2.3 / WAN) is not inlined into this bundle yet. Pull it in from
+ * `@sogni/creative-agent/storyboard` when a downstream consumer needs
+ * `compileForModel()` to do real prompt compilation rather than the
+ * registry stub above.
+ */
+export function composeAdapterPromptGuidance() {
+    // The hand-curated bundle currently exposes adapter stubs only, so the
+    // composer returns an empty block. Real compile() + getSystemPromptGuidance
+    // for each adapter lives in `@sogni/creative-agent/storyboard/adapters`.
+    return '';
+}
+export class SkillRegistry {
+    manifests = new Map();
+    loaded = new Set();
+    register(manifest) {
+        this.manifests.set(manifest.id, manifest);
+        if (manifest.alwaysLoaded)
+            this.loaded.add(manifest.id);
+    }
+    load(id) {
+        if (!this.manifests.has(id))
+            return false;
+        this.loaded.add(id);
+        return true;
+    }
+    unload(id) {
+        const manifest = this.manifests.get(id);
+        if (!manifest || manifest.alwaysLoaded)
+            return false;
+        return this.loaded.delete(id);
+    }
+    getActiveToolNames() {
+        const names = new Set();
+        for (const id of this.loaded) {
+            const manifest = this.manifests.get(id);
+            if (!manifest)
+                continue;
+            for (const name of manifest.toolNames)
+                names.add(name);
+        }
+        return [...names];
+    }
+    getActiveSkills() {
+        return [...this.loaded].map((id) => this.manifests.get(id)).filter(Boolean);
+    }
+}
+export const storyboardAdapterRegistry = {
+    getAdapter(modelId) {
+        const trimmed = modelId.trim().toLowerCase();
+        if (trimmed.startsWith('seedance'))
+            return { modelId: 'seedance' };
+        if (trimmed.startsWith('gpt-image'))
+            return { modelId: 'gpt-image-2' };
+        if (trimmed.startsWith('ltx'))
+            return { modelId: 'ltx23' };
+        if (trimmed.startsWith('wan'))
+            return { modelId: 'wan' };
+        return null;
+    },
+};
+export function compileForModel(modelId) {
+    const adapter = storyboardAdapterRegistry.getAdapter(modelId);
+    if (!adapter)
+        throw new Error(`No storyboard adapter registered for model_id "${modelId}".`);
+    return { adapterModelId: adapter.modelId };
+}
+const PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF = formatModelRef('seedance', 1, 'image');
+export const SEEDANCE_STORYBOARD_REFERENCE_PROMPT = `Create a full-screen cinematic video from the storyboard in ${PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF}. Treat ${PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF} as the controlling source for shot order and intent, and as a source layout reference: use the thumbnails, timing, Dialogue/VO, Audio/SFX, timecodes, camera/motion notes, transitions, and scene order as instructions, not as a visual board to reproduce. Do not display the storyboard grid, borders, caption bars, storyboard title/footer text, panel numbers, section labels, slide titles, headings, or transcribed narration. Convert the ordered thumbnails into full-screen chronological beats; do not reuse only one or two motifs while skipping panels. When the board has panel titles, captions, section numbers, slide titles, or headings but no formal Dialogue/VO labels, treat those labels as short audio-only narration/voiceover or key-message beats in order unless they are clearly visual-only metadata. Voice each label as its own brief phrase with a pause; do not concatenate labels into run-on sentences and do not speak panel numbers. Show storyboard labels as visible text only when the user explicitly asks for visible text, subtitles, a title card, lower third, signage, or CTA. Preserve the story spine, character/product/reference continuity, and cause-and-effect progression between beats. Treat transitions as motion instructions, not unrelated hard cuts unless the storyboard explicitly asks for hard cuts. Use brand color, lighting, product imagery, and composition instead of invented typography. Keep visible text limited to exact copy the user or storyboard explicitly marks as on-screen text, CTA, signage, or end-card text. Use a music/SFX arc that follows the storyboard audio notes and lands the final brand/CTA hit. Keep unrelated UI, extra logos, microtext, subtitles, and extra scenes out of the frame.`;
+export const SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS = 15;
+function asciiAt(data, start, length) {
+    if (data.length < start + length)
+        return '';
+    let value = '';
+    for (let index = start; index < start + length; index += 1) {
+        value += String.fromCharCode(data[index]);
+    }
+    return value;
+}
+export function normalizeReferenceAudioMimeType(mimeType) {
+    const trimmed = mimeType?.split(';')[0]?.trim().toLowerCase();
+    return trimmed || 'application/octet-stream';
+}
+export function detectReferenceAudioFormat(data, mimeType) {
+    const normalizedMimeType = normalizeReferenceAudioMimeType(mimeType);
+    if (normalizedMimeType === 'audio/mpeg' || normalizedMimeType === 'audio/mp3') {
+        return 'mp3';
+    }
+    if (normalizedMimeType === 'audio/mp4'
+        || normalizedMimeType === 'audio/m4a'
+        || normalizedMimeType === 'audio/x-m4a') {
+        return 'm4a';
+    }
+    if (normalizedMimeType === 'audio/wav' || normalizedMimeType === 'audio/x-wav') {
+        return 'wav';
+    }
+    if (normalizedMimeType === 'audio/ogg' || normalizedMimeType === 'application/ogg') {
+        return 'ogg';
+    }
+    if (data.length >= 3 && asciiAt(data, 0, 3) === 'ID3')
+        return 'mp3';
+    if (data.length >= 2 && data[0] === 0xff && (data[1] & 0xe0) === 0xe0)
+        return 'mp3';
+    if (data.length >= 12 && asciiAt(data, 4, 4) === 'ftyp')
+        return 'm4a';
+    if (data.length >= 12 && asciiAt(data, 0, 4) === 'RIFF' && asciiAt(data, 8, 4) === 'WAVE')
+        return 'wav';
+    if (data.length >= 4 && asciiAt(data, 0, 4) === 'OggS')
+        return 'ogg';
+    return 'unknown';
+}
+function finiteNonNegativeMediaValue(value, fallback = 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? Math.max(0, parsed) : fallback;
+}
+export function shouldTrimSeedanceV2VSourceVideo({ sourceDurationSeconds, requestedDurationSeconds, startOffsetSeconds = 0, maxDurationSeconds = SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS, }) {
+    const maxDuration = finiteNonNegativeMediaValue(maxDurationSeconds, SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS)
+        || SEEDANCE_V2V_REFERENCE_MAX_DURATION_SECONDS;
+    const sourceDuration = finiteNonNegativeMediaValue(sourceDurationSeconds, Number.NaN);
+    const requestedDuration = finiteNonNegativeMediaValue(requestedDurationSeconds, maxDuration);
+    const startOffset = finiteNonNegativeMediaValue(startOffsetSeconds, 0);
+    if (startOffset > 0)
+        return true;
+    const effectiveDuration = Math.min(requestedDuration || maxDuration, maxDuration);
+    return Number.isFinite(sourceDuration) && sourceDuration > effectiveDuration + 0.15;
+}
+export const GPT_IMAGE_STORYBOARD_DEFAULTS = {
+    storyboardLandscape: { width: 2560, height: 1440, aspectRatio: '2560x1440' },
+    storyboardPortrait: { width: 1440, height: 2560, aspectRatio: '1440x2560' },
+};
+export const DEFAULT_STORYBOARD_CANVAS_HINT_MARKER = 'DEFAULT STORYBOARD PAGE LAYOUT:';
 export const LTX23_WORKFLOW_MODELS = Object.freeze({
     t2v: 'ltx23-22b-fp8_t2v_distilled',
     i2v: 'ltx23-22b-fp8_i2v_distilled',
@@ -13,6 +362,18 @@ export const LTX23_WORKFLOW_MODELS = Object.freeze({
     a2v: 'ltx23-22b-fp8_a2v_distilled',
     v2v: 'ltx23-22b-fp8_v2v_distilled'
 });
+export const LTX23_DEV_WORKFLOW_MODELS = Object.freeze({
+    t2v: 'ltx23-22b-fp8_t2v_dev',
+    i2v: 'ltx23-22b-fp8_i2v_dev',
+    ia2v: 'ltx23-22b-fp8_ia2v_dev',
+    a2v: 'ltx23-22b-fp8_a2v_dev'
+});
+export function resolveLtx23WorkflowModelForQuality(workflow, qualityTier) {
+    if (qualityTier === 'pro' && workflow !== 'v2v') {
+        return LTX23_DEV_WORKFLOW_MODELS[workflow];
+    }
+    return LTX23_WORKFLOW_MODELS[workflow];
+}
 export const SEEDANCE_WORKFLOW_MODELS = Object.freeze({
     t2v: 'seedance-2-0',
     t2vFast: 'seedance-2-0-fast',
@@ -233,6 +594,15 @@ export const VIDEO_MODEL_REGISTRY = Object.freeze({
 });
 export const EXPANDED_VIDEO_MODEL_REGISTRY = (() => {
     const registry = { ...VIDEO_MODEL_REGISTRY };
+    for (const workflow of ['t2v', 'i2v', 'ia2v', 'a2v']) {
+        const base = registry[LTX23_WORKFLOW_MODELS[workflow]];
+        if (!base)
+            continue;
+        registry[LTX23_DEV_WORKFLOW_MODELS[workflow]] = {
+            ...base,
+            steps: 20
+        };
+    }
     for (const workflow of ['t2v', 'i2v', 'ia2v', 'a2v', 'v2v']) {
         const ltx2Distilled = 'ltx2-19b-fp8_' + workflow + '_distilled';
         const ltx2Quality = 'ltx2-19b-fp8_' + workflow;
@@ -506,17 +876,18 @@ export function formatAudioIdPrompt(prompt, voiceName) {
     const dialogue = extractQuotedDialogueSegments(prompt);
     const speechLines = dialogue.length > 0
         ? dialogue.map((line, index) => (voiceName || 'SPEAKER_' + (index + 1)) + ': "' + line + '"').join('\n')
-        : 'No spoken dialogue unless exact quoted words are present in the visual prompt.';
-    return [
+        : '';
+    const sections = [
         '[VISUAL]',
         prompt.trim(),
         '',
         '[SPEECH]',
-        speechLines,
-        '',
-        '[SOUNDS]',
-        'Use natural ambient sound that matches the scene unless the prompt specifies silence.'
-    ].join('\n');
+    ];
+    if (speechLines) {
+        sections.push(speechLines);
+    }
+    sections.push('', '[SOUNDS]', 'Use natural ambient sound that matches the scene unless the prompt specifies silence.');
+    return sections.join('\n');
 }
 export function getVideoPromptGuardrailPlan({ prompt, duration, frames, fps, durationExplicit, referenceAudioIdentity, voiceName } = {}) {
     let nextPrompt = prompt || '';
@@ -600,15 +971,15 @@ export function selectDefaultVideoModel(workflow, opts = {}, config) {
     if (configured)
         return resolveVideoModelAlias(configured, workflow) || null;
     if (workflow === 'ia2v')
-        return LTX23_WORKFLOW_MODELS.ia2v;
+        return resolveLtx23WorkflowModelForQuality('ia2v', opts.quality);
     if (workflow === 'a2v')
-        return LTX23_WORKFLOW_MODELS.a2v;
+        return resolveLtx23WorkflowModelForQuality('a2v', opts.quality);
     if (workflow === 'v2v')
         return LTX23_WORKFLOW_MODELS.v2v;
     if (workflow === 't2v')
-        return LTX23_WORKFLOW_MODELS.t2v;
+        return resolveLtx23WorkflowModelForQuality('t2v', opts.quality);
     if (workflow === 'i2v' && (opts.referenceAudioIdentity || promptNeedsLtxNativeAudio(opts.prompt) || opts.quality === 'hq' || opts.quality === 'pro')) {
-        return LTX23_WORKFLOW_MODELS.i2v;
+        return resolveLtx23WorkflowModelForQuality('i2v', opts.quality);
     }
     return VIDEO_WORKFLOW_DEFAULT_MODELS[workflow] || null;
 }
@@ -626,8 +997,11 @@ export function dimensionsWithShortSide(width, height, shortSide) {
         height: Math.round(h * scale)
     };
 }
+function textMentionsPortraitSocialFormat(text) {
+    return /\b(?:tiktok|tik\s*tok|reels?|shorts|story)\b/i.test(text);
+}
 function hasPortraitResolutionHint(text) {
-    return /\b(portrait|vertical|reels?|tiktok|shorts?|story)\b/i.test(text);
+    return /\b(?:portrait|vertical)\b/i.test(text) || textMentionsPortraitSocialFormat(text);
 }
 function hasLandscapeResolutionHint(text) {
     return /\b(landscape|horizontal|wide(?:screen)?|cinematic|youtube)\b/i.test(text);
@@ -649,6 +1023,18 @@ export function inferNamedVideoResolutionShortSideFromText(text) {
     const namedResolution = compact.match(/\b(480|720|1080|1440|2160)\s*p\b/i);
     return namedResolution ? Number(namedResolution[1]) : null;
 }
+export function inferRequestedVideoResolutionShortSideFromText(text) {
+    const standardResolution = inferNamedVideoResolutionShortSideFromText(text);
+    if (standardResolution)
+        return standardResolution;
+    const match = text.match(/\b([1-9]\d{2,3})\s*p\b/i);
+    if (!match)
+        return null;
+    const parsed = Number(match[1]);
+    if (!Number.isInteger(parsed) || parsed < 100 || parsed > 4320)
+        return null;
+    return parsed;
+}
 export function inferExplicitPixelDimensionsFromText(text) {
     const compact = text.replace(/,/g, '');
     const exactPair = compact.match(/\b(\d{1,5})\s*(x|by)\s*(\d{1,5})\s*(px|pixels?)?\b/i);
@@ -715,7 +1101,11 @@ export function inferExplicitAspectRatioFromText(text) {
     }
     const index = match.index ?? 0;
     const context = text.slice(Math.max(0, index - 48), Math.min(text.length, index + match[0].length + 48));
-    if (/\b(?:ratio|aspect|format|portrait|landscape|vertical|horizontal|widescreen|frame|video|output)\b/i.test(context)) {
+    const hasExplicitRatioContext = /\b(?:aspect|ratio|format|resolution|size|dimensions?|portrait|landscape|widescreen|horizontal|vertical)\b/i.test(context);
+    if (!hasExplicitRatioContext && width <= 3 && height >= 10 && height < 60) {
+        return null;
+    }
+    if (/\b(?:ratio|aspect|format|resolution|size|dimensions?|portrait|landscape|vertical|horizontal|widescreen|frame|image|photo|picture|video|clip|ad|advert|commercial|promo|story\s*board|storyboard|tiktok|tik\s*tok|reels?|shorts?|instagram|output)\b/i.test(context)) {
         return { width, height, text: match[0] };
     }
     return null;
@@ -723,15 +1113,28 @@ export function inferExplicitAspectRatioFromText(text) {
 export function inferRequestedTotalVideoDurationSeconds(text) {
     const durations = [];
     for (const match of text.matchAll(/\b(\d{1,3}(?:\.\d+)?)\s*(?:minutes?|mins?)\b/gi)) {
+        if (match.index !== undefined && text[match.index - 1] === '%')
+            continue;
         const minutes = Number(match[1]);
         if (Number.isFinite(minutes) && minutes > 0)
             durations.push(Math.ceil(minutes * 60));
     }
-    for (const match of text.matchAll(/\b(\d{1,3})\s*(?:s|sec|secs|seconds?)\b/gi)) {
+    for (const match of text.matchAll(/\b(\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)\b/gi)) {
+        if (match.index !== undefined && text[match.index - 1] === '%')
+            continue;
         const seconds = Number(match[1]);
         if (Number.isFinite(seconds) && seconds > 0)
             durations.push(seconds);
     }
+    for (const match of text.matchAll(/\b(\d{1,2}):([0-5]\d)(?:\.\d+)?\s*(?:-|–|—|\bto\b)\s*(\d{1,2}):([0-5]\d)(?:\.\d+)?\b/gi)) {
+        if (match.index !== undefined && text[match.index - 1] === '%')
+            continue;
+        const start = (Number(match[1]) * 60) + Number(match[2]);
+        const end = (Number(match[3]) * 60) + Number(match[4]);
+        if (Number.isFinite(start) && Number.isFinite(end) && end > start && end <= 600) {
+            durations.push(end);
+        }
+    }
     return durations.length > 0 ? Math.max(...durations) : null;
 }
 export function textProvidesLiteralVideoPrompt(text) {
@@ -789,15 +1192,94 @@ export function extractLiteralVideoPrompt(text) {
     return extracted.length >= 3 ? extracted : null;
 }
 export function textMentionsStoryboardReference(text) {
-    return /\b(?:story\s*board|storyboard|video\s+sequence|sequence\s+sheet|shot\s+sheet|thumbnail\s+sequence|panel\s+sequence)\b/i.test(text);
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return false;
+    if (/\b(?:video\s+sequence|sequence\s+sheet|shot\s+sheet|thumbnail\s+sequence|panel\s+sequence)\b/i.test(normalized)) {
+        return true;
+    }
+    const rejectsStoryboardPanelOutput = /\b(?:no|without)\s+(?:extra\s+|random\s+|visible\s+|generated\s+|output\s+)?(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\b(?:avoid|exclude|never|don't|do\s+not)\b[\s\S]{0,80}\b(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\bnot\s+(?:a\s+|the\s+|as\s+)?(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\b(?:story\s*board|storyboard)\s+panels?\b[\s\S]{0,80}\b(?:not\s+(?:needed|required|wanted)|without|avoid|exclude|never)\b/i.test(normalized);
+    const contextualStoryboardReference = /\b(?:uploading|uploaded|attached|provided|reference|source|input)\b[\s\S]{0,80}\b(?:story\s*board|storyboard)\b/i.test(normalized)
+        || /\b(?:story\s*board|storyboard)\b[\s\S]{0,80}\b(?:uploaded|attached|provided|reference|source|input|image|sheet|grid|layout|page|board|panels?|frames?|sequence|timecodes?)\b/i.test(normalized)
+        || /\b(?:use|using|with|from|based\s+on|following|follow|turn|convert|transform|animate)\b[\s\S]{0,100}\b(?:story\s*board|storyboard)\b/i.test(normalized)
+        || /\b(?:story\s*board|storyboard)\b[\s\S]{0,100}\b(?:into|to|as)\s+(?:a\s+|the\s+)?(?:videos?|clips?|animations?|movies?|films?)\b/i.test(normalized);
+    return contextualStoryboardReference && !rejectsStoryboardPanelOutput;
+}
+export function textExplicitlyRequestsSeedanceFastModel(text) {
+    const mentionsSeedance = /\b(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\b/i.test(text);
+    return /\b(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\s+fast\b/i.test(text)
+        || /\bfast\s+(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\b/i.test(text)
+        || /\b(?:(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\s+)?fast\s+(?:version|variant)\b/i.test(text)
+        || /\b(?:version|variant)\s+(?:should\s+be\s+|is\s+|as\s+)?(?:(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\s+)?fast\b/i.test(text)
+        || (mentionsSeedance && /\bdraft\b/i.test(text))
+        || (mentionsSeedance
+            && /\b(?:use|using|choose|select|set|switch\s+to|with|via)\b[\s\S]{0,40}\bfast\s+model\b/i.test(text));
+}
+export function textExplicitlyRequestsNonSeedanceVideoModel(text) {
+    return /\b(?:ltx(?:\s*2(?:\.3)?)?|wan(?:\s*2(?:\.2)?)?|another\s+video\s+model|different\s+video\s+model|non[-\s]?seedance)\b/i.test(text)
+        && !/\b(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\b/i.test(text);
+}
+export function textTreatsAudioAsLooseReference(text) {
+    return /@?audio\d*\b[\s\S]{0,100}\b(?:loose|rough|mood|vibe|background|ambient|style|play\s+under)\b[\s\S]{0,40}\b(?:references?|guide|under|track|shot|clip)\b/i.test(text)
+        || /\baudio\b[\s\S]{0,80}\bloose\s+references?\b/i.test(text)
+        || /\bloose\s+references?\b[\s\S]{0,80}\baudio\b/i.test(text)
+        || /\breference\s+audio\b[\s\S]{0,100}\b(?:loose|mood|background|play\s+under|under)\b/i.test(text)
+        || /\baudio\b[\s\S]{0,100}\b(?:mood|background|ambient|style)\s+references?\b/i.test(text)
+        || /\baudio\b[\s\S]{0,80}\bplay\s+under\b/i.test(text)
+        || /\bplay\s+under\b[\s\S]{0,80}\baudio\b/i.test(text)
+        || /\baudio\b[\s\S]{0,80}\b(?:as\s+(?:a\s+)?(?:rough\s+)?(?:reference|guide)|for\s+(?:the\s+)?(?:mood|vibe|tone|feel|inspiration|style)|mood\s+reference|vibe\s+reference)\b/i.test(text)
+        || /\b(?:use|take|treat)\b[\s\S]{0,80}\b(?:audio|song|track|music)\b[\s\S]{0,80}\b(?:as\s+(?:a\s+)?(?:rough\s+)?(?:reference|guide)|for\s+(?:the\s+)?(?:mood|vibe|tone|feel|inspiration|style))\b/i.test(text)
+        || /\b(?:mood|vibe|tone|feel|style)\b[\s\S]{0,80}\b(?:from|of)\b[\s\S]{0,80}\b(?:audio|song|track|music)\b/i.test(text)
+        || /\b(?:inspired\s+by|based\s+on)\b[\s\S]{0,80}\b(?:audio|song|track|music)\b[\s\S]{0,80}\b(?:mood|vibe|tone|feel|style)?\b/i.test(text);
+}
+export function textRequestsPrimaryAudioSyncVideo(text) {
+    if (textTreatsAudioAsLooseReference(text)) {
+        return false;
+    }
+    if (/\b(?:do\s+not|don't|dont|no|not|without)\b[\s\S]{0,50}\b(?:sync|synced|synchroni[sz]e|synchronized|match|lip[-\s]*sync)\b[\s\S]{0,50}\b(?:audio|sound|song|track|beat|rhythm|music|voice|dialogue|speech|words)\b/i.test(text)
+        || /\b(?:audio|sound|song|track|beat|rhythm|music|voice|dialogue|speech|words)\b[\s\S]{0,50}\b(?:do\s+not|don't|dont|no|not|without)\b[\s\S]{0,50}\b(?:sync|synced|synchroni[sz]e|synchronized|match|lip[-\s]*sync)\b/i.test(text)) {
+        return false;
+    }
+    return /\bsound[-_\s]*to[-_\s]*video\b/i.test(text)
+        || /\baudio[-_\s]*(?:sync|synced|synchronized|synchroni[sz]ed)\b/i.test(text)
+        || /\b(?:sync|synced|synchroni[sz]e|synchroni[sz]ed|match)\b[\s\S]{0,80}\b(?:audio|sound|song|track|beat|rhythm|music|voice|dialogue|speech|words)\b/i.test(text)
+        || /\b(?:saying|speaking|lip[-\s]*sync(?:ing)?|mouth(?:ing)?)\b[\s\S]{0,100}\b(?:audio|sound|words|dialogue|speech|voice)\b/i.test(text)
+        || /\b(?:audio|sound|song|track|beat|rhythm|music|voice|dialogue|speech|words)\b[\s\S]{0,100}\b(?:drive|drives|driving|primary|sync|synced|synchronized|synchroni[sz]ed|lip[-\s]*sync)\b/i.test(text)
+        || /\b(?:audio\s+(?:voice\s+)?recording|voice\s+(?:recording|clip|track|file)|wav\s+file|uploaded\s+(?:audio|voice|wav)|audio\s+file)\b[\s\S]{0,160}\b(?:image|photo|picture|portrait|face|person|man|woman|character)\b[\s\S]{0,160}\b(?:make|create|generate|render|animate|turn|convert|transform)\b[\s\S]{0,120}\b(?:sing|sinc|since|sync|speak|speaking|say|saying|talk|talking|lip[-\s]*sync|dance|dancing)\b/i.test(text)
+        || /\b(?:image|photo|picture|portrait|face|person|man|woman|character)\b[\s\S]{0,160}\b(?:audio\s+(?:voice\s+)?recording|voice\s+(?:recording|clip|track|file)|wav\s+file|uploaded\s+(?:audio|voice|wav)|audio\s+file)\b[\s\S]{0,160}\b(?:make|create|generate|render|animate|turn|convert|transform)\b[\s\S]{0,120}\b(?:sing|sinc|since|sync|speak|speaking|say|saying|talk|talking|lip[-\s]*sync|dance|dancing)\b/i.test(text);
+}
+export function seedanceRequestUsesStoryboardReferenceForModelDefault(input) {
+    if (input.storyboardDetected === true)
+        return true;
+    const promptText = typeof input.promptText === 'string'
+        ? input.promptText.trim()
+        : '';
+    if (promptText === SEEDANCE_STORYBOARD_REFERENCE_PROMPT)
+        return true;
+    if (!input.hasImageReference)
+        return false;
+    const combinedText = `${input.userIntentText}\n${promptText}`;
+    if (!textMentionsStoryboardReference(combinedText))
+        return false;
+    return /\b(?:seedance|videos?|clips?|animations?|movies?|films?|generate|create|make|render|produce|turn|animate|convert|transform)\b/i.test(combinedText);
 }
 export function textProvidesVideoScriptOrDetailedPrompt(text) {
-    const normalized = text.trim();
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .trim();
     if (!normalized)
         return false;
     if (textProvidesLiteralVideoPrompt(normalized))
         return true;
-    if (/\[\s*\d{1,2}(?:[:.]\d{2})?\s*(?:-|to)\s*\d{1,2}(?:[:.]\d{2})?\s*\]/i.test(normalized))
+    if (/\[\s*\d{1,2}(?:[:.]\d{2})?\s*(?:-|–|—|to)\s*\d{1,2}(?:[:.]\d{2})?\s*\]/i.test(normalized))
         return true;
     if (/^\s*(?:style|shot|scene|segment|camera|motion|audio|vo|v\.o\.|voiceover|sfx|fx|music|dialogue)\s*:/im.test(normalized))
         return true;
@@ -821,6 +1303,32 @@ export function textProvidesVideoScriptOrDetailedPrompt(text) {
 export function seedanceStoryboardFallbackAllowedForText(text) {
     return !textProvidesVideoScriptOrDetailedPrompt(text);
 }
+function textProvidesStructuredVideoScriptOrPrompt(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .trim();
+    if (!normalized)
+        return false;
+    if (textProvidesLiteralVideoPrompt(normalized))
+        return true;
+    if (/\[\s*\d{1,2}(?:[:.]\d{2})?\s*(?:-|–|—|to)\s*\d{1,2}(?:[:.]\d{2})?\s*\]/i.test(normalized))
+        return true;
+    if (/^\s*(?:scene|shot|segment)\s*\d{1,2}\b/im.test(normalized))
+        return true;
+    if (/^\s*(?:dialogue|vo|v\.o\.|voiceover)\s*:/im.test(normalized))
+        return true;
+    if ((normalized.match(/^\s*(?:shot|scene|segment|camera|motion|audio|vo|v\.o\.|voiceover|sfx|fx|music|dialogue)\s*:/gim) || []).length >= 2) {
+        return true;
+    }
+    if ((normalized.match(/\b(?:VO|SFX|camera|motion|audio|dialogue|shot|segment)\s*:/g) || []).length >= 3) {
+        return true;
+    }
+    return (normalized.match(/"[^"]{8,}"/g) || []).length >= 2;
+}
+export function seedanceStoryboardReferenceFallbackAllowedForVisualDetection(text) {
+    return !textProvidesStructuredVideoScriptOrPrompt(text);
+}
 function normalizeDurationSeconds(value) {
     const raw = typeof value === 'string'
         ? Number(value.trim().match(/^(\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?$/i)?.[1])
@@ -877,7 +1385,12 @@ function textExplicitlyRequestsGeneratedImageStage(text) {
 }
 function textRequestsAdjacentImageTransitions(text) {
     const lower = text.toLowerCase();
-    const mentionsTransition = /\b(?:transition|transitions|transitioning|link|links|linking|connect|connecting|morph)\b/.test(lower)
+    const sequenceNouns = String.raw `(?:images?|photos?|pictures?|keyframes?|frames?|versions?|variations?|scenes?)`;
+    const transitionVerbs = String.raw `(?:transition|transitions|transitioning|link|links|linking|connect|connecting|morph|morphs|morphing)`;
+    const transitionVerbTargetsSequence = new RegExp(String.raw `\b${transitionVerbs}\b\s+(?:the\s+|all\s+|each\s+|every\s+|these\s+|those\s+)?${sequenceNouns}\b`, 'i').test(lower)
+        || new RegExp(String.raw `\b${transitionVerbs}\b[\s\S]{0,40}\b(?:between|from|to|into|across)\b[\s\S]{0,40}\b(?:the\s+)?${sequenceNouns}\b`, 'i').test(lower)
+        || new RegExp(String.raw `\b(?:each|every|all|these|those|generated|uploaded|source|end|first|last|previous|next)\s+(?:story\s*board\s+|storyboard\s+|generated\s+|uploaded\s+)?${sequenceNouns}\b[\s\S]{0,80}\b${transitionVerbs}\b`, 'i').test(lower);
+    const mentionsTransition = transitionVerbTargetsSequence
         || /\bbetween\s+(?:the\s+)?(?:images?|photos?|pictures?|keyframes?|frames?|versions?|variations?|scenes?)\b/.test(lower)
         || /(?:->)/.test(text);
     if (!mentionsTransition)
@@ -887,13 +1400,171 @@ function textRequestsAdjacentImageTransitions(text) {
     const mentionsVideoOutput = /\b(?:video|videos|clips?|segments?|stitch|stitched|stitching|montage)\b/.test(lower);
     return mentionsGeneratedSequence && mentionsVideoOutput;
 }
+export function textRequestsProfessionalCharacterSheetImage(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return false;
+    const generationVerb = String.raw `(?:generate|create|make|render|produce|design|build|develop|draw)`;
+    const characterSubject = String.raw `(?:character|mascot|brand\s+mascot|creature|avatar|persona|toon|cartoon\s+character)`;
+    const sheetArtifact = String.raw `(?:character\s+sheet|mascot\s+sheet|model\s+sheet|reference\s+(?:sheet|board)|design\s+sheet|turnaround(?:\s+(?:sheet|views?|board))?|expression\s+(?:sheet|row|board)|pose\s+(?:sheet|board))`;
+    const directCharacterSheet = new RegExp(String.raw `\b${characterSubject}\b[\s\S]{0,80}\b(?:sheet|reference\s+(?:sheet|board)|model\s+sheet|turnaround(?:\s+(?:sheet|views?|board))?|expression\s+(?:sheet|row|board)|pose\s+(?:sheet|board))\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b${sheetArtifact}\b[\s\S]{0,80}\b${characterSubject}\b`, 'i').test(normalized)
+        || /\breusable\s+character\s+sheet\b/i.test(normalized);
+    if (!directCharacterSheet)
+        return false;
+    return new RegExp(String.raw `\b${generationVerb}\b[\s\S]{0,180}\b${sheetArtifact}\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b${sheetArtifact}\b[\s\S]{0,120}\b(?:image|illustration|artwork|render|board|layout)\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b(?:need|want|would\s+like|looking\s+for|please|can\s+you|could\s+you)\b[\s\S]{0,120}\b${sheetArtifact}\b`, 'i').test(normalized);
+}
+export function textRequestsSingleCompositeImageOutput(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return false;
+    const generationVerbs = String.raw `(?:generate|create|make|render|produce|design|build|develop|draw)`;
+    const videoGenerationVerbs = String.raw `(?:generate|create|make|render|produce|turn|animate|convert|transform)`;
+    const imageOutputNouns = String.raw `(?:images?|photos?|pictures?|portraits?|posters?|artwork|illustrations?)`;
+    const videoOutputNouns = String.raw `(?:videos?|clips?|animations?|movies?|films?)`;
+    const compositeNouns = String.raw `(?:story\s*board|storyboard|collage|contact\s+sheet|mood\s*board|moodboard|grid|board)`;
+    const adCreativeNouns = String.raw `(?:ads?|advertisements?|banners?|flyers?|posters?|social\s+posts?|campaign\s+creative|marketing\s+(?:creative|graphic)|promo\s+graphic|product\s+graphic)`;
+    const characterSheetImageStage = textRequestsProfessionalCharacterSheetImage(normalized);
+    const directSeedanceVersionFromStoryboard = /\b(?:generate|create|make|render|produce|turn|animate|convert|transform)\b[\s\S]{0,120}\b(?:seedance|seeddance)(?:\s*2(?:\.0)?)?(?:\s+\w+){0,3}\s+(?:version|variant)\b[\s\S]{0,120}\b(?:story\s*board|storyboard)\b/i.test(normalized)
+        || /\b(?:generate|create|make|render|produce|turn|animate|convert|transform)\b[\s\S]{0,120}\b(?:version|variant)(?:\s+\w+){0,3}\s+(?:seedance|seeddance)(?:\s*2(?:\.0)?)?\b[\s\S]{0,120}\b(?:story\s*board|storyboard)\b/i.test(normalized);
+    if (directSeedanceVersionFromStoryboard)
+        return false;
+    const uploadedStoryboardPanelSource = /\b(?:upload(?:ing|ed)?|attach(?:ing|ed)?|provid(?:ing|ed)?)\b[\s\S]{0,140}\b(?:each|all|the)?\s*(?:of\s+)?(?:the\s+)?\d{1,2}\s+(?:story\s*board\s+|storyboard\s+)?(?:panels?|frames?|keyframes?)\b/i.test(normalized)
+        || /\b(?:these|uploaded|attached|provided)\s+(?:\d{1,2}\s+)?(?:story\s*board\s+|storyboard\s+)?(?:panels?|frames?|keyframes?)\b/i.test(normalized);
+    const directClipPerPanelRequest = /\b(?:generate|create|make|render|animate|produce)\b[\s\S]{0,120}\b(?:each|all|the)?\s*(?:clips?|videos?|segments?|animations?)\b[\s\S]{0,120}\b(?:per|from|using|with|based\s+on)\b[\s\S]{0,80}\b(?:panels?|frames?|keyframes?|story\s*board|storyboard)\b/i.test(normalized);
+    if (uploadedStoryboardPanelSource && directClipPerPanelRequest)
+        return false;
+    const directVideoFromStoryboard = new RegExp(String.raw `\b(?:generate|create|make|render|produce|turn|animate|convert|transform)\b[\s\S]{0,100}\b(?:videos?|clips?|animations?|movies?|films?)\b[\s\S]{0,140}\b(?:using|with|from|based\s+on|as|following)\b[\s\S]{0,100}\b(?:story\s*board|storyboard)(?:\s+(?:image|photo|picture|reference))?\b`, 'i').test(normalized)
+        || /\b(?:turn|convert|transform|animate)\b[\s\S]{0,120}\b(?:story\s*board|storyboard)\b[\s\S]{0,80}\b(?:into|to|as)\s+(?:a\s+|the\s+)?(?:videos?|clips?|animations?|movies?|films?)\b/i.test(normalized);
+    const noReferenceConnectorBeforeStoryboard = String.raw `(?:(?!\b(?:using|with|from|based\s+on|as|following)\b)[\s\S])`;
+    const explicitStoryboardImageOrSheetRequest = new RegExp(String.raw `\b(?:generate|create|make|render|produce|design|build|develop|draw)\b${noReferenceConnectorBeforeStoryboard}{0,180}\b(?:video\s+)?(?:story\s*board|storyboard)\s+(?:image|sheet|grid|layout|page|board)\b`, 'i').test(normalized)
+        || /\b(?:story\s*board|storyboard)\s+(?:image|sheet|grid|layout|page|board)\b[\s\S]{0,120}\b(?:for|of)\s+(?:a\s+|the\s+)?(?:videos?|clips?|animations?|movies?|films?|social\s+media\s+video)\b/i.test(normalized);
+    if (directVideoFromStoryboard
+        && !explicitStoryboardImageOrSheetRequest
+        && !/\b(?:story\s*board|storyboard)\b[\s\S]{0,60}\bfirst\b/i.test(normalized)) {
+        return false;
+    }
+    const directVideoOutput = new RegExp(String.raw `\b${videoGenerationVerbs}\b[\s\S]{0,140}\b${videoOutputNouns}\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b${videoOutputNouns}\b[\s\S]{0,140}\b${videoGenerationVerbs}\b`, 'i').test(normalized);
+    const rejectsStoryboardPanelOutput = /\b(?:no|without)\s+(?:extra\s+|random\s+|visible\s+|generated\s+|output\s+)?(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\b(?:avoid|exclude|never|don't|do\s+not)\b[\s\S]{0,80}\b(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\bnot\s+(?:a\s+|the\s+|as\s+)?(?:story\s*board|storyboard)\s+panels?\b/i.test(normalized)
+        || /\b(?:story\s*board|storyboard)\s+panels?\b[\s\S]{0,80}\b(?:not\s+(?:needed|required|wanted)|without|avoid|exclude|never)\b/i.test(normalized);
+    if (directVideoOutput && rejectsStoryboardPanelOutput && !explicitStoryboardImageOrSheetRequest) {
+        return false;
+    }
+    const explicitGeneratedImageOutput = new RegExp(String.raw `\b${generationVerbs}\b[\s\S]{0,180}\b(?:${imageOutputNouns}|${compositeNouns}\s+image|image\s+(?:story\s*board|storyboard|grid|collage|board))\b`, 'i').test(normalized);
+    const standaloneCompositeImageMention = new RegExp(String.raw `\b(?:story\s*board|storyboard|grid|collage|contact\s+sheet|mood\s*board|moodboard)\s+${imageOutputNouns}\b`, 'i').test(normalized);
+    const storyboardImageStage = new RegExp(String.raw `\b${generationVerbs}\b[\s\S]{0,180}\b(?:video\s+)?(?:story\s*board|storyboard)(?:\s+(?:sequence|sheet|layout|panel|panels|board))?\b`, 'i').test(normalized)
+        || /\b(?:turn|convert|transform)\b[\s\S]{0,80}\binto\b[\s\S]{0,120}\b(?:video\s+)?(?:story\s*board|storyboard)(?:\s+(?:sequence|sheet|layout|panel|panels|board))?\b/i.test(normalized)
+        || /\b(?:story\s*board|storyboard)\b[\s\S]{0,80}\bfirst\b/i.test(normalized)
+        || /\bfirst\b[\s\S]{0,80}\b(?:story\s*board|storyboard)\b/i.test(normalized);
+    const referenceGuidedAdCreative = new RegExp(String.raw `\b${generationVerbs}\b[\s\S]{0,140}\b${adCreativeNouns}\b`, 'i').test(normalized)
+        && /\b(?:referenc(?:e|es|ed|ing)|use|using|include|incorporate|based\s+on|guided\s+by|with)\b[\s\S]{0,120}\b(?:uploaded|attached|provided|reference|source|input|assets?|images?|photos?|pictures?)\b/i.test(normalized)
+        && !/\b(?:videos?|clips?|animations?|movies?|films?|commercials?)\b/i.test(normalized);
+    const storyboardImageMentionIsCaptionSource = standaloneCompositeImageMention
+        && /\b(?:voice\s*over|voiceover|captions?|text|copy|dialogue|lines?)\b[\s\S]{0,180}\b(?:read|shown|displayed|under|below|from|in|on)\b[\s\S]{0,120}\b(?:story\s*board|storyboard)\s+images?\b/i.test(normalized);
+    if (directVideoOutput
+        && storyboardImageMentionIsCaptionSource
+        && !explicitStoryboardImageOrSheetRequest
+        && !referenceGuidedAdCreative
+        && !characterSheetImageStage) {
+        return false;
+    }
+    if (directVideoOutput
+        && !explicitGeneratedImageOutput
+        && standaloneCompositeImageMention
+        && !storyboardImageStage
+        && !referenceGuidedAdCreative
+        && !characterSheetImageStage
+        && !explicitStoryboardImageOrSheetRequest) {
+        return false;
+    }
+    const explicitImageOutput = explicitGeneratedImageOutput || standaloneCompositeImageMention;
+    if (!explicitImageOutput && !storyboardImageStage && !referenceGuidedAdCreative && !characterSheetImageStage)
+        return false;
+    if (!referenceGuidedAdCreative
+        && !characterSheetImageStage
+        && !/\b(?:story\s*board|storyboard|panels?|grid|rows?|columns?|collage|contact\s+sheet|mood\s*board|moodboard|layout|board)\b/i.test(normalized)) {
+        return false;
+    }
+    const directVideoStoryboardReference = new RegExp(String.raw `\b${generationVerbs}\b[\s\S]{0,100}\b(?:videos?|clips?|animations?|movies?|films?)\b[\s\S]{0,140}\b(?:using|with|from|based\s+on|as)\b[\s\S]{0,100}\b(?:story\s*board|storyboard)(?:\s+(?:image|photo|picture|reference))?\b`, 'i').test(normalized);
+    if (directVideoStoryboardReference && !explicitStoryboardImageOrSheetRequest) {
+        return false;
+    }
+    const explicitSeparateOutputs = new RegExp(String.raw `\b${generationVerbs}\b[\s\S]{0,180}\b(?:separate|individual|distinct|different|multiple)\s+(?:images|photos|pictures|keyframes|frames|versions|variations|variants)\b`, 'i').test(normalized)
+        || /\b(?:let\s+me\s+see|show\s+me|give\s+me|i\s+want\s+to\s+see|want\s+to\s+see|need|make|generate|create|render|produce)\b[\s\S]{0,100}\b(?:\d{1,2}|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen)\s+(?:separate\s+|individual\s+|distinct\s+|different\s+|alternate\s+|new\s+)?(?:images|photos|pictures|keyframes|frames|versions|variations|variants|options|takes)\b/i.test(normalized)
+        || /\b(?:\d{1,2}|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen)\s+(?:separate\s+|individual\s+|distinct\s+|different\s+|alternate\s+|new\s+)?(?:images|photos|pictures|keyframes|frames|versions|variations|variants|options|takes)\b[\s\S]{0,100}\b(?:then|after|before|animate|animation|video|stitch|transition)\b/i.test(normalized);
+    return !explicitSeparateOutputs;
+}
+export function textRequestsDirectMediaAfterPreproduction(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return false;
+    return /\b(?:do\s+not|don't|dont|without|no\s+need\s+to)\b[\s\S]{0,80}\b(?:wait|ask|confirm|review|feedback|approval|approve)\b/i.test(normalized)
+        || /\b(?:skip|bypass)\b[\s\S]{0,80}\b(?:review|approval|confirmation|feedback)\b/i.test(normalized)
+        || /\b(?:generate|render|make|create|produce|complete|build|run)\b[\s\S]{0,140}\b(?:everything|all\s+stages|all\s+the\s+way|end\s*-?\s*to\s*-?\s*end|full\s+workflow|complete\s+workflow|the\s+(?:entire|whole)\s+(?:workflow|project|pipeline|thing))\b/i.test(normalized)
+        || /\b(?:go\s+ahead|proceed|run\s+it|do\s+it\s+now|generate\s+directly|render\s+directly|start\s+rendering|send\s+it)\b/i.test(normalized)
+        || /\b(?:after|then|next)\b[\s\S]{0,120}\b(?:immediately|directly|right\s+away|without\s+waiting|without\s+asking)\b[\s\S]{0,120}\b(?:generate|render|make|create|animate|produce)\b/i.test(normalized)
+        || /\b(?:generate|render|make|create|animate|produce)\b[\s\S]{0,120}\b(?:immediately|directly|right\s+away|without\s+waiting|without\s+asking)\b/i.test(normalized);
+}
+export function textRequestsPreproductionScriptStage(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!normalized)
+        return false;
+    const planningArtifactNoun = String.raw `(?:script|screenplay|story\s*board|storyboard|shot\s*list|beat\s*sheet|treatment)`;
+    const suppliedScript = new RegExp(String.raw `\b(?:here\s+is|here's|below\s+is|following\s+is)\b[\s\S]{0,80}\b${planningArtifactNoun}\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b(?:provided|supplied|included|existing|approved|final|attached|uploaded)\s+${planningArtifactNoun}\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b${planningArtifactNoun}\b\s*(?:is|was|has\s+been|already)?\s*(?:provided|supplied|included|attached|uploaded|pasted|below|approved|final)\b`, 'i').test(normalized)
+        || /\b(?:use|send|turn|convert|animate|generate|render|make|create)\b[\s\S]{0,120}\b(?:this|that|existing|approved|final|provided|supplied|included)\b[\s\S]{0,80}\b(?:script|screenplay|story\s*board|storyboard|shot\s*list|beat\s*sheet|treatment|storyboard\s+image)\b/i.test(normalized);
+    if (suppliedScript)
+        return false;
+    const explicitStoryboardImageOutput = /\b(?:story\s*board|storyboard)\s+(?:image|sheet|grid|layout|poster|board)\b/i.test(normalized)
+        || /\b(?:image|sheet|grid|layout|poster|board)\s+(?:story\s*board|storyboard)\b/i.test(normalized);
+    const mentionsWrittenPlanning = /\b(?:script|screenplay|shot\s*list|beat\s*sheet|treatment|story\s+beats?|video\s+plan|creative\s+brief)\b/i.test(normalized);
+    if (explicitStoryboardImageOutput && !mentionsWrittenPlanning)
+        return false;
+    const planningNoun = String.raw `(?:script|screenplay|story\s*board|storyboard|shot\s*list|beat\s*sheet|treatment|story\s+beats?|video\s+plan|creative\s+brief)`;
+    const planningVerb = String.raw `(?:write|draft|develop|create|make|generate|build|design|outline|plan|map\s*out|break\s*down)`;
+    const asksForPlanning = new RegExp(String.raw `\b${planningVerb}\b[\s\S]{0,140}\b${planningNoun}\b`, 'i').test(normalized)
+        || new RegExp(String.raw `\b${planningNoun}\b[\s\S]{0,120}\b(?:to\s+develop|for\s+review|for\s+approval|before|first|then|next|subsequent|subsequently|later)\b`, 'i').test(normalized)
+        || /\bnew\s+script\s+to\s+develop\b/i.test(normalized);
+    if (!asksForPlanning)
+        return false;
+    const downstreamMediaContext = /\b(?:video|clip|animation|movie|film|seedance|ltx|image|keyframe|storyboard\s+image|storyboard\s+sheet|model|generation|generate|render|animate)\b/i.test(normalized)
+        || /\b(?:used\s+by|enough\s+details?|production\s+ready|prompt-ready|model-ready)\b/i.test(normalized);
+    return downstreamMediaContext;
+}
 export function planSeedanceStoryboardFallback(input) {
     const userIntentText = input.userIntentText;
     const providesLiteralPrompt = input.providesLiteralPrompt
         ?? textProvidesLiteralVideoPrompt(userIntentText);
     if (providesLiteralPrompt)
         return null;
-    if (!seedanceStoryboardFallbackAllowedForText(userIntentText))
+    const storyboardReferenceMentioned = textMentionsStoryboardReference(userIntentText);
+    const storyboardVisuallyDetected = input.storyboardDetected === true;
+    const allowsStoryboardFallback = storyboardReferenceMentioned || storyboardVisuallyDetected
+        ? seedanceStoryboardReferenceFallbackAllowedForVisualDetection(userIntentText)
+        : seedanceStoryboardFallbackAllowedForText(userIntentText);
+    if (!allowsStoryboardFallback)
         return null;
     if (input.uploadedImageCount !== 1)
         return null;
@@ -903,11 +1574,13 @@ export function planSeedanceStoryboardFallback(input) {
         return null;
     if (textExplicitlyRequestsGeneratedImageStage(userIntentText))
         return null;
+    if (textRequestsSingleCompositeImageOutput(userIntentText))
+        return null;
     if (textRequestsAdjacentImageTransitions(userIntentText))
         return null;
-    const reason = textMentionsStoryboardReference(userIntentText)
+    const reason = storyboardReferenceMentioned
         ? 'text_mentions_storyboard'
-        : input.storyboardDetected
+        : storyboardVisuallyDetected
             ? 'vision_detected_storyboard'
             : null;
     if (!reason)
@@ -919,11 +1592,14 @@ export function planSeedanceStoryboardFallback(input) {
     const defaultDuration = input.defaultDurationSeconds ?? 5;
     const maxDuration = input.maxDurationSeconds ?? 15;
     const minDuration = input.minDurationSeconds ?? 4;
-    const intendedDuration = requestedDuration !== null && requestedDuration !== undefined
+    const userProvidedDuration = requestedDuration !== null && requestedDuration !== undefined;
+    const intendedDuration = userProvidedDuration
         ? requestedDuration
         : storyboardDuration ?? defaultDuration;
+    if (userProvidedDuration && intendedDuration > maxDuration)
+        return null;
     return {
-        prompt: SEEDANCE_STORYBOARD_REFERENCE_PROMPT,
+        prompt: buildSeedanceStoryboardReferencePrompt(userIntentText, reason),
         duration: Math.max(minDuration, Math.min(maxDuration, intendedDuration)),
         referenceImageIndices: input.referenceImageIndices ?? [-1],
         skipPromptProcessing: true,
@@ -932,6 +1608,16 @@ export function planSeedanceStoryboardFallback(input) {
         ...(storyboardAspectRatio ? { aspectRatio: storyboardAspectRatio } : {}),
     };
 }
+function buildSeedanceStoryboardReferencePrompt(userIntentText, reason) {
+    if (reason !== 'vision_detected_storyboard')
+        return SEEDANCE_STORYBOARD_REFERENCE_PROMPT;
+    const additionalDirection = userIntentText
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!additionalDirection)
+        return SEEDANCE_STORYBOARD_REFERENCE_PROMPT;
+    return `${SEEDANCE_STORYBOARD_REFERENCE_PROMPT} Additional user direction to honor while following the storyboard: ${additionalDirection}`;
+}
 function valuePresent(value) {
     return value !== undefined && value !== null && value !== '';
 }
@@ -984,6 +1670,7 @@ export function planCliVideoBrain(input) {
         plan.duration = inferredDuration;
     }
     if (!cliSet.width && !cliSet.height) {
+        const aspectRatio = inferExplicitAspectRatioFromText(text);
         const exactDimensions = inferExplicitPixelDimensionsFromText(text);
         if (exactDimensions) {
             plan.width = exactDimensions.width;
@@ -991,12 +1678,11 @@ export function planCliVideoBrain(input) {
             plan.dimensionSource = 'exact';
         }
         else if (!cliSet.targetResolution) {
-            const shortSide = inferNamedVideoResolutionShortSideFromText(text);
+            const shortSide = inferRequestedVideoResolutionShortSideFromText(text);
             if (shortSide !== null) {
                 plan.targetResolution = shortSide;
             }
             else {
-                const aspectRatio = inferExplicitAspectRatioFromText(text);
                 if (aspectRatio) {
                     const dimensions = dimensionsForAspectRatio(input.width ?? 1920, input.height ?? 1088, aspectRatio.text);
                     if (dimensions) {
@@ -1007,6 +1693,9 @@ export function planCliVideoBrain(input) {
                 }
             }
         }
+        if (aspectRatio && !exactDimensions) {
+            plan.aspectRatio = aspectRatio.text;
+        }
     }
     const uploadedImageCount = (valuePresent(input.refImage) ? 1 : 0) +
         (valuePresent(input.refImageEnd) ? 1 : 0);
@@ -1045,6 +1734,3049 @@ export function planCliVideoBrain(input) {
     }
     return plan;
 }
+export const STORYBOARD_PLANNING_CONTRACT_SCHEMA_VERSION = 'storyboard-planning-contract/v1';
+export const STORYBOARD_PLANNING_CONTRACT_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        schemaVersion: {
+            type: 'string',
+            const: STORYBOARD_PLANNING_CONTRACT_SCHEMA_VERSION,
+        },
+        source: {
+            type: 'string',
+            enum: ['llm_schema', 'assistant_metadata', 'user_schema', 'fallback_text'],
+        },
+        layout: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: {
+                    type: 'string',
+                    enum: ['llm_schema', 'assistant_metadata', 'user_schema', 'fallback_text'],
+                },
+                storyboardCanvasAspectRatio: { type: 'string' },
+                storyboardCellAspectRatio: { type: 'string' },
+                targetVideoAspectRatio: { type: 'string' },
+                boardDimensions: { type: 'string' },
+            },
+            required: [
+                'source',
+                'storyboardCanvasAspectRatio',
+                'storyboardCellAspectRatio',
+                'targetVideoAspectRatio',
+                'boardDimensions',
+            ],
+        },
+        scenes: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string' },
+                    index: { type: 'integer', minimum: 1, maximum: 24 },
+                    visibleText: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    metadataLabels: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    referenceUsage: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                required: ['id', 'index', 'visibleText', 'metadataLabels', 'referenceUsage'],
+            },
+        },
+        endCard: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                visibleText: {
+                    type: 'array',
+                    items: { type: 'string' },
+                },
+                metadataLabels: {
+                    type: 'array',
+                    items: { type: 'string' },
+                },
+            },
+            required: ['visibleText', 'metadataLabels'],
+        },
+        metadataLabels: {
+            type: 'array',
+            items: { type: 'string' },
+        },
+    },
+    required: ['schemaVersion', 'source', 'layout', 'scenes', 'endCard', 'metadataLabels'],
+};
+export function buildStoryboardPlanningResponseFormat(name = 'preproduction_storyboard_planning') {
+    return {
+        type: 'json_schema',
+        json_schema: {
+            name,
+            strict: true,
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    notes: { type: 'string' },
+                    storyboardPlanningContract: STORYBOARD_PLANNING_CONTRACT_JSON_SCHEMA,
+                },
+                required: ['notes', 'storyboardPlanningContract'],
+            },
+        },
+    };
+}
+export const STORYBOARD_DEFAULT_MIN_FRAMES = 4;
+export const STORYBOARD_DEFAULT_MAX_FRAMES = 12;
+const STORYBOARD_COUNT_WORDS = {
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+    seven: 7,
+    eight: 8,
+    nine: 9,
+    ten: 10,
+    eleven: 11,
+    twelve: 12,
+    thirteen: 13,
+    fourteen: 14,
+    fifteen: 15,
+    sixteen: 16,
+    seventeen: 17,
+    eighteen: 18,
+    nineteen: 19,
+    twenty: 20,
+    twentyone: 21,
+    twentytwo: 22,
+    twentythree: 23,
+    twentyfour: 24,
+};
+const DEFAULT_STORYBOARD_TIMING_RULES = {
+    normalWordsPerSecondMin: 2.0,
+    normalWordsPerSecondMax: 3.3,
+    fastWordsPerSecondMax: 4.0,
+    minEndCardHoldSec: 2.0,
+    minPunchlineSec: 0.5,
+    toleranceSec: 0.25,
+};
+function storyboardGcd(a, b) {
+    let x = Math.abs(a);
+    let y = Math.abs(b);
+    while (y > 0) {
+        const next = x % y;
+        x = y;
+        y = next;
+    }
+    return x || 1;
+}
+function formatStoryboardRatio(width, height) {
+    const divisor = storyboardGcd(width, height);
+    return `${width / divisor}:${height / divisor}`;
+}
+function ratioFromStoryboardAspectWords(value) {
+    if (/^(?:portrait|vertical|9\s*:\s*16)$/i.test(value.trim()))
+        return '9:16';
+    if (/^(?:landscape|horizontal|widescreen|16\s*:\s*9)$/i.test(value.trim()))
+        return '16:9';
+    const match = value.match(/(\d{1,4})\s*:\s*(\d{1,4})/);
+    if (!match)
+        return value;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        return '';
+    }
+    return `${width}:${height}`;
+}
+function inferStoryboardBoardAspectDirective(text) {
+    const aspectToken = String.raw `(?:portrait|vertical|landscape|horizontal|widescreen|\d{1,4}\s*:\s*\d{1,4})`;
+    const patterns = [
+        /\bStoryboard layout target\s*:\s*board\s+([^\n;,]+)/i,
+        /\bStoryboard layout\s*:[^\n]*\bboard\s+([^\n;,]+)/i,
+        /\bDEFAULT STORYBOARD PAGE LAYOUT\s*:\s*Use a\s+([^\n.]+?)\s+storyboard\s+canvas\/page\b/i,
+        /\bOverall storyboard canvas(?:\s+aspect ratio)?\s*:\s*(?:\d{3,5}\s*x\s*\d{3,5}\s+pixels\s*\()?([^\n.)]+)/i,
+        new RegExp(String.raw `\b(${aspectToken})(?:\s*\([^)]{0,80}\))?[^\n]{0,120}\b(?:video\s+)?(?:story\s*board|storyboard)\s+(?:image|sheet|layout|page|board|canvas)\b`, 'i'),
+        new RegExp(String.raw `\b(?:story\s*board|storyboard)?\s*(?:board|canvas|page|sheet)\b[^\n]{0,80}\b(?:must|should|use|be|is|as|at)\b[^\n]{0,80}\b(${aspectToken})\b`, 'i'),
+    ];
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (!match)
+            continue;
+        const ratio = ratioFromStoryboardAspectWords(match[1]);
+        if (ratio)
+            return ratio;
+    }
+    return null;
+}
+function inferStoryboardAspectNearUnit(text, unitPattern, rejectBetweenPattern) {
+    const aspectPattern = /\b(portrait|vertical|landscape|horizontal|widescreen|\d{1,4}\s*:\s*\d{1,4})\b/gi;
+    const unit = new RegExp(String.raw `\b(?:${unitPattern})\b`, 'i');
+    const candidates = [];
+    for (const match of text.matchAll(aspectPattern)) {
+        const aspect = match[1];
+        const ratio = ratioFromStoryboardAspectWords(aspect);
+        if (!ratio)
+            continue;
+        const specificity = /\d/.test(aspect) ? 0 : 1;
+        const start = match.index ?? 0;
+        const end = start + match[0].length;
+        const after = text.slice(end, Math.min(text.length, end + 80));
+        const afterUnit = after.match(unit);
+        if (afterUnit?.index !== undefined) {
+            const between = after.slice(0, afterUnit.index);
+            if (!rejectBetweenPattern.test(between)) {
+                candidates.push({ ratio, distance: between.length, specificity });
+            }
+        }
+        const before = text.slice(Math.max(0, start - 80), start);
+        const beforeUnitMatches = Array.from(before.matchAll(new RegExp(String.raw `\b(?:${unitPattern})\b`, 'gi')));
+        const beforeUnit = beforeUnitMatches[beforeUnitMatches.length - 1];
+        if (beforeUnit?.index !== undefined) {
+            const between = before.slice(beforeUnit.index + beforeUnit[0].length);
+            if (!rejectBetweenPattern.test(between)) {
+                candidates.push({ ratio, distance: between.length, specificity });
+            }
+        }
+    }
+    candidates.sort((a, b) => a.specificity - b.specificity || a.distance - b.distance);
+    return candidates[0]?.ratio ?? null;
+}
+function inferStoryboardBoardAspectRatio(text) {
+    const boardDirective = inferStoryboardBoardAspectDirective(text);
+    if (boardDirective)
+        return boardDirective;
+    const explicitPixels = inferExplicitPixelDimensionsFromText(text);
+    if (explicitPixels) {
+        return formatStoryboardRatio(explicitPixels.width, explicitPixels.height);
+    }
+    const boardAspect = inferStoryboardAspectNearUnit(text, String.raw `board|canvas|image|poster|sheet|layout|story\s*board|storyboard|output`, /\b(?:cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots|video)\b/i);
+    if (boardAspect)
+        return boardAspect;
+    const explicitRatio = inferExplicitAspectRatioFromText(text);
+    if (explicitRatio)
+        return `${explicitRatio.width}:${explicitRatio.height}`;
+    if (textMentionsPortraitSocialFormat(text))
+        return '9:16';
+    return '16:9';
+}
+function inferExplicitStoryboardTargetVideoAspectRatio(text) {
+    const storyboardLayoutTarget = text.match(/\bStoryboard layout(?: target)?\s*:[^\n]*\bvideo\s+(\d{1,4})\s*:\s*(\d{1,4})\b/i);
+    if (storyboardLayoutTarget) {
+        const width = Number(storyboardLayoutTarget[1]);
+        const height = Number(storyboardLayoutTarget[2]);
+        if (width > 0 && height > 0)
+            return `${width}:${height}`;
+    }
+    const videoOutputAspect = inferStoryboardAspectNearUnit(text, String.raw `target\s+video|final\s+video|output\s+video|video\s+output|actual\s+video|seedance\s+video`, /\b(?:story\s*board|storyboard|board|canvas|page|sheet|poster)\b/i);
+    if (videoOutputAspect)
+        return videoOutputAspect;
+    const explicitTargetPattern = /\b(?:target|final|output|actual|seedance|video|clip|film|commercial|promo)\b([\s\S]{0,80}?)\b(\d{1,4})\s*:\s*(\d{1,4})\b/gi;
+    for (const explicitTarget of text.matchAll(explicitTargetPattern)) {
+        const between = explicitTarget[1] ?? '';
+        if (/\b(?:story\s*board|storyboard|board|canvas|page|sheet|poster)\b/i.test(between))
+            continue;
+        const width = Number(explicitTarget[2]);
+        const height = Number(explicitTarget[3]);
+        if (width > 0 && height > 0)
+            return `${width}:${height}`;
+    }
+    return null;
+}
+function inferStoryboardTargetVideoAspectRatio(text, boardAspectRatio) {
+    const explicitTarget = inferExplicitStoryboardTargetVideoAspectRatio(text);
+    if (explicitTarget)
+        return explicitTarget;
+    if (/\b(?:portrait|vertical|9\s*:\s*16)\b/i.test(text) || textMentionsPortraitSocialFormat(text)) {
+        return '9:16';
+    }
+    if (/\b(?:landscape|horizontal|widescreen|16\s*:\s*9|youtube)\b/i.test(text)) {
+        return '16:9';
+    }
+    return boardAspectRatio;
+}
+function inferStoryboardCellAspectRatio(text, targetVideoAspectRatio) {
+    const explicitCell = inferStoryboardAspectNearUnit(text, String.raw `cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots`, /\b(?:board|canvas|image|poster|sheet|layout|story\s*board|storyboard|output|format)\b/i);
+    if (explicitCell) {
+        return explicitCell;
+    }
+    if (/\b(?:portrait|vertical|9\s*:\s*16)\b[\s\S]{0,80}\b(?:cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots)\b/i.test(text)) {
+        return '9:16';
+    }
+    if (/\b(?:cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots)\b[\s\S]{0,80}\b(?:portrait|vertical|9\s*:\s*16)\b/i.test(text)) {
+        return '9:16';
+    }
+    if (/\b(?:landscape|horizontal|widescreen|letterbox|16\s*:\s*9)\b[\s\S]{0,80}\b(?:cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots)\b/i.test(text)) {
+        return '16:9';
+    }
+    if (/\b(?:cell|cells|frame|frames|panel|panels|still|stills|thumbnail|thumbnails|shot|shots)\b[\s\S]{0,80}\b(?:landscape|horizontal|widescreen|letterbox|16\s*:\s*9)\b/i.test(text)) {
+        return '16:9';
+    }
+    return targetVideoAspectRatio;
+}
+function describeVideoFrameShape(cellAspectRatio) {
+    const cellOrientation = parseAspectRatioOrientation(cellAspectRatio);
+    if (cellOrientation === 'portrait')
+        return `tall ${cellAspectRatio} portrait video-frame rectangle`;
+    if (cellOrientation === 'landscape')
+        return `wide ${cellAspectRatio} landscape video-frame rectangle`;
+    if (cellOrientation === 'square')
+        return `square ${cellAspectRatio} video-frame area`;
+    return `${cellAspectRatio} video-frame rectangle`;
+}
+function describePortraitLetterboxCellArrangement(frameCount, cellAspectRatio) {
+    const frameShape = describeVideoFrameShape(cellAspectRatio);
+    if (frameCount <= 4) {
+        return `${frameCount} numbered scene slots, each containing one ${frameShape}, stacked in a portrait sheet with compact labels outside the rectangles`;
+    }
+    const columns = frameCount <= 8 ? 2 : frameCount <= 15 ? 3 : 4;
+    const rows = Math.ceil(frameCount / columns);
+    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',
+    ].join('; ');
+}
+function describeLandscapePortraitCellArrangement(frameCount, cellAspectRatio) {
+    const frameShape = describeVideoFrameShape(cellAspectRatio);
+    if (frameCount <= 4) {
+        return `${frameCount} numbered scene slots, each containing one ${frameShape}, arranged cleanly inside a landscape board with compact labels outside the rectangles`;
+    }
+    const rows = frameCount <= 8 ? 2 : frameCount <= 15 ? 3 : 4;
+    const columns = Math.ceil(frameCount / rows);
+    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',
+    ].join('; ');
+}
+function describeSingleOrientationStoryboardArrangement(boardAspectRatio, cellAspectRatio, frameCount) {
+    const boardOrientation = parseAspectRatioOrientation(boardAspectRatio);
+    const frameShape = describeVideoFrameShape(cellAspectRatio);
+    if (boardOrientation === 'portrait') {
+        return {
+            layoutKind: 'portrait_grid',
+            layoutDescription: `${frameCount} numbered scene slots arranged in a clean vertical storyboard grid; each slot contains one ${frameShape} with compact labels outside the rectangle`,
+        };
+    }
+    const boardLabel = boardOrientation === 'square' ? 'square board' : 'landscape board';
+    return {
+        layoutKind: 'landscape_grid',
+        layoutDescription: frameCount === 6 && boardOrientation !== 'square'
+            ? `2 rows x 3 columns of numbered scene slots inside a ${boardLabel}; each slot contains one ${frameShape} with compact labels outside the rectangle`
+            : `${frameCount} numbered scene slots in a balanced ${boardLabel} storyboard grid; each slot contains one ${frameShape} with compact labels outside the rectangle`,
+    };
+}
+function describeStoryboardLayout(boardAspectRatio, cellAspectRatio, frameCount) {
+    const boardOrientation = parseAspectRatioOrientation(boardAspectRatio);
+    const cellOrientation = parseAspectRatioOrientation(cellAspectRatio);
+    if (boardOrientation === 'portrait' && cellOrientation === 'landscape') {
+        return {
+            layoutKind: 'portrait_letterbox_cells',
+            layoutDescription: describePortraitLetterboxCellArrangement(frameCount, cellAspectRatio),
+        };
+    }
+    if (boardOrientation === 'landscape' && cellOrientation === 'portrait') {
+        return {
+            layoutKind: 'landscape_portrait_cells',
+            layoutDescription: describeLandscapePortraitCellArrangement(frameCount, cellAspectRatio),
+        };
+    }
+    return describeSingleOrientationStoryboardArrangement(boardAspectRatio, cellAspectRatio, frameCount);
+}
+function normalizeStoryboardBoardDimensions(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = value.trim().match(/\b(\d{3,5})\s*[x:]\s*(\d{3,5})\b/i);
+    if (!match)
+        return null;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+        return null;
+    return `${Math.trunc(width)}x${Math.trunc(height)}`;
+}
+function storyboardPlanningSourceFromContract(contract) {
+    return contract?.layout?.source ?? contract?.source ?? 'fallback_text';
+}
+function applyStoryboardPlanningLayoutContract(fallback, contract, frameCount) {
+    const layoutContract = contract?.layout;
+    if (!layoutContract)
+        return fallback;
+    const boardAspectRatio = normalizeAspectRatio(layoutContract.storyboardCanvasAspectRatio)
+        ?? fallback.boardAspectRatio;
+    const cellAspectRatio = normalizeAspectRatio(layoutContract.storyboardCellAspectRatio)
+        ?? fallback.cellAspectRatio;
+    const targetVideoAspectRatio = normalizeAspectRatio(layoutContract.targetVideoAspectRatio)
+        ?? cellAspectRatio
+        ?? fallback.targetVideoAspectRatio;
+    const layout = describeStoryboardLayout(boardAspectRatio, cellAspectRatio, frameCount);
+    const boardDimensions = normalizeStoryboardBoardDimensions(layoutContract.boardDimensions)
+        ?? fallback.boardDimensions;
+    return {
+        boardAspectRatio,
+        cellAspectRatio,
+        targetVideoAspectRatio,
+        ...layout,
+        ...(boardDimensions ? { boardDimensions } : {}),
+    };
+}
+export function inferStoryboardLayoutSpec(userIntentText, frameCount, planningContract) {
+    const explicitPixels = inferExplicitPixelDimensionsFromText(userIntentText);
+    const boardAspectRatio = inferStoryboardBoardAspectRatio(userIntentText);
+    const explicitTargetVideoAspectRatio = inferExplicitStoryboardTargetVideoAspectRatio(userIntentText);
+    const inferredTargetVideoAspectRatio = explicitTargetVideoAspectRatio
+        ?? inferStoryboardTargetVideoAspectRatio(userIntentText, boardAspectRatio);
+    const cellAspectRatio = inferStoryboardCellAspectRatio(userIntentText, inferredTargetVideoAspectRatio);
+    const targetVideoAspectRatio = explicitTargetVideoAspectRatio ?? cellAspectRatio;
+    const layout = describeStoryboardLayout(boardAspectRatio, cellAspectRatio, frameCount);
+    const fallback = {
+        boardAspectRatio,
+        cellAspectRatio,
+        targetVideoAspectRatio,
+        ...layout,
+        ...(explicitPixels ? { boardDimensions: `${explicitPixels.width}x${explicitPixels.height}` } : {}),
+    };
+    return applyStoryboardPlanningLayoutContract(fallback, planningContract, frameCount);
+}
+function clampStoryboardDefaultFrameCount(value) {
+    return Math.max(STORYBOARD_DEFAULT_MIN_FRAMES, Math.min(STORYBOARD_DEFAULT_MAX_FRAMES, Math.round(value)));
+}
+function normalizeStoryboardCountToken(value) {
+    if (!value)
+        return null;
+    const normalized = value.toLowerCase().replace(/[\s-]/g, '');
+    const parsed = /^\d+$/.test(normalized)
+        ? Number(normalized)
+        : STORYBOARD_COUNT_WORDS[normalized];
+    return Number.isInteger(parsed) && parsed >= 1 && parsed <= 24 ? parsed : null;
+}
+export function inferExplicitStoryboardFrameCountFromText(text) {
+    const normalized = text
+        .replace(/[“”]/g, '"')
+        .replace(/[’]/g, "'")
+        .trim();
+    if (!normalized)
+        return null;
+    const countToken = String.raw `(?:\d{1,2}|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty(?:[-\s]?(?:one|two|three|four))?)`;
+    const countModifiers = String.raw `(?:(?:timed|timecoded|time-coded|sequential|distinct|separate|individual|video|storyboard|story-board|key|scene|shot|clean|polished|portrait|landscape|widescreen)\s+){0,5}`;
+    const storyboardUnits = String.raw `(?:panels?|frames?|storyboard\s+frames?|shots?|keyframes?|beats?|cells?|stills?|thumbnails?)`;
+    const candidates = [];
+    const patterns = [
+        new RegExp(String.raw `\b(${countToken})\s*[- ]?\s*${countModifiers}${storyboardUnits}\b`, 'gi'),
+        new RegExp(String.raw `\b${storyboardUnits}\s*(?:count|total)?\s*[:=]\s*(${countToken})\b`, 'gi'),
+    ];
+    for (const pattern of patterns) {
+        for (const match of normalized.matchAll(pattern)) {
+            const count = normalizeStoryboardCountToken(match[1]);
+            if (count !== null)
+                candidates.push(count);
+        }
+    }
+    return candidates.length > 0 ? Math.max(...candidates) : null;
+}
+function inferMarkdownStoryboardTableFrameCount(text) {
+    const count = text
+        .split(/\r?\n/)
+        .filter(line => {
+        if (!line.trim().startsWith('|'))
+            return false;
+        return /\b(?:\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?\s*(?:-|to|\u2013|\u2014)\s*(?:\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\b/i.test(line);
+    })
+        .length;
+    return count >= 1 && count <= 24 ? count : null;
+}
+export function inferStoryboardFrameCountFromScriptText(text) {
+    if (!text)
+        return null;
+    const canonicalText = canonicalStoryboardScriptContext(text) || text;
+    const tableCount = inferMarkdownStoryboardTableFrameCount(canonicalText);
+    if (tableCount)
+        return tableCount;
+    const sections = splitStoryboardSections(canonicalText);
+    if (sections.length >= 1 && sections.length <= 24)
+        return sections.length;
+    return inferExplicitStoryboardFrameCountFromText(canonicalText);
+}
+function storyboardComplexityScore(text) {
+    let score = 0;
+    const normalized = text.toLowerCase();
+    const signals = [
+        /\b(?:dialogue|voice\s*over|voiceover|vo|spoken|says?|speaker|character\s+lines?)\b/i,
+        /\b(?:audio|sfx|foley|sound\s*effects?|music|score|ambience)\b/i,
+        /\b(?:brand|logo|product|launch|commercial|ad|campaign|cta|end\s*card|title\s*card)\b/i,
+        /\b(?:cast|characters?|mascot|protagonist|hero|villain|host|customer|crowd|people)\b/i,
+        /\b(?:transform|transformation|journey|arc|storyline|narrative|beginning|middle|ending|reveal|twist)\b/i,
+        /\b(?:uploaded|attached|provided|reference|image\s+\d|asset\s+\d)\b/i,
+        /\b(?:transition|montage|sequence|timecoded|shot\s*list|beat\s*sheet)\b/i,
+    ];
+    for (const signal of signals) {
+        if (signal.test(normalized))
+            score += 1;
+    }
+    const sentenceCount = (text.match(/[.!?]\s+|\n{2,}/g) || []).length + 1;
+    if (sentenceCount >= 5)
+        score += 1;
+    if (sentenceCount >= 9)
+        score += 1;
+    return score;
+}
+function storyboardWordCount(text) {
+    const words = text.match(/\b[\w']+\b/g);
+    return words ? words.length : 0;
+}
+export function inferDefaultStoryboardFrameCountFromText(text) {
+    const canonicalText = canonicalStoryboardScriptContext(text) || text;
+    const scriptCount = inferStoryboardFrameCountFromScriptText(canonicalText);
+    if (scriptCount)
+        return clampStoryboardDefaultFrameCount(scriptCount);
+    const duration = inferRequestedTotalVideoDurationSeconds(canonicalText);
+    const words = storyboardWordCount(canonicalText);
+    const complexity = storyboardComplexityScore(canonicalText);
+    let count = duration !== null
+        ? duration <= 8
+            ? 4
+            : duration <= 15
+                ? 5
+                : duration <= 20
+                    ? 6
+                    : duration <= 30
+                        ? 8
+                        : duration <= 45
+                            ? 10
+                            : 12
+        : words <= 28
+            ? 4
+            : words <= 70
+                ? 5
+                : words <= 130
+                    ? 7
+                    : 9;
+    if (complexity >= 6) {
+        count += 2;
+    }
+    else if (complexity >= 3) {
+        count += 1;
+    }
+    if (duration === null && words > 180)
+        count += 1;
+    return clampStoryboardDefaultFrameCount(count);
+}
+function inferReferencedStoryboardImageCount(text) {
+    let maxIndex = 0;
+    for (const match of text.matchAll(/\b(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?(\d{1,2})\b/gi)) {
+        if (match.index !== undefined && isStoryboardModelNameReference(text, match.index, match.index + match[0].length)) {
+            continue;
+        }
+        maxIndex = Math.max(maxIndex, Number(match[1]));
+    }
+    return maxIndex;
+}
+function isStoryboardModelNameReference(text, start, end) {
+    const matched = text.slice(start, end).toLowerCase();
+    if (!/\bimage\s*(?:#|number\s*)?2\b/.test(matched))
+        return false;
+    const before = text.slice(Math.max(0, start - 24), start).toLowerCase();
+    const after = text.slice(end, Math.min(text.length, end + 36)).toLowerCase();
+    const compactContext = `${before}${matched}${after}`;
+    return /\bgpt\s+image\s*2\b/.test(compactContext)
+        || /\b(?:gpt[-\s]*)?image\s*2\s+(?:image\s+)?models?\b/.test(compactContext)
+        || /\bimage\s*2\s+image[-\s]?to[-\s]?image\b/.test(compactContext);
+}
+function contextAroundStoryboardReference(text, index) {
+    const referenceWithSubjectInParens = new RegExp(String.raw `(?:^|[\n,;:*_\-\s])(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\s*\(\s*([^\)\n]{2,120}?)\s*\)\s*[:*_ -]*\s*([^\n]{0,160})`, 'gi');
+    for (const match of text.matchAll(referenceWithSubjectInParens)) {
+        if (match.index === undefined)
+            continue;
+        if (isStoryboardModelNameReference(text, match.index, match.index + match[0].length))
+            continue;
+        const subject = compactStoryboardLine(stripStoryboardMarkup(match[1]));
+        const tail = compactStoryboardLine(stripStoryboardMarkup(match[2] || ''));
+        if (subject)
+            return `${subject} (asset ${index})${tail ? ` ${tail}` : ''}`;
+    }
+    const parentheticalReferencePattern = new RegExp(String.raw `(?:^|[\n,;:])\s*([^,\n;()]{2,120}?)\s*\(\s*(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\s*\)`, 'gi');
+    for (const match of text.matchAll(parentheticalReferencePattern)) {
+        if (match.index === undefined)
+            continue;
+        if (isStoryboardModelNameReference(text, match.index, match.index + match[0].length))
+            continue;
+        const subject = compactStoryboardLine(stripStoryboardMarkup(match[1]))
+            .replace(/^(?:reference\s+assets?|uploaded\s+(?:images?|assets?)|attached\s+(?:images?|assets?)|provided\s+(?:images?|assets?)|assets?)\s*:\s*/i, '')
+            .trim();
+        if (subject)
+            return `${subject} (asset ${index})`;
+    }
+    const patterns = [
+        new RegExp(String.raw `\b(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?${index}\b`, 'i'),
+        new RegExp(String.raw `\b${index}\b`, 'i'),
+    ];
+    for (const pattern of patterns) {
+        const matches = Array.from(text.matchAll(new RegExp(pattern.source, 'gi')));
+        for (const match of matches) {
+            if (match.index === undefined)
+                continue;
+            if (isStoryboardModelNameReference(text, match.index, match.index + match[0].length))
+                continue;
+            const lineStart = text.lastIndexOf('\n', match.index) + 1;
+            const nextLineBreak = text.indexOf('\n', match.index);
+            const lineEnd = nextLineBreak >= 0 ? nextLineBreak : text.length;
+            const start = Math.max(0, lineStart);
+            let end = Math.min(lineEnd, match.index + match[0].length + 140);
+            const afterMatch = text.slice(match.index + match[0].length, end);
+            const nextReference = afterMatch.search(/\b(?:uploaded|attached|provided|reference|source|input)?\s*(?:image|photo|picture|asset)\s*(?:#|number\s*)?\d{1,2}\b/i);
+            if (nextReference >= 0) {
+                end = match.index + match[0].length + nextReference;
+            }
+            const afterCurrentReference = text.slice(match.index + match[0].length, end);
+            const nextSentence = afterCurrentReference.search(/[.!?]\s+\S/);
+            if (nextSentence >= 0) {
+                end = Math.min(end, match.index + match[0].length + nextSentence + 1);
+            }
+            return text.slice(start, end);
+        }
+    }
+    return text;
+}
+function cleanExplicitStoryboardReferenceSubject(value, index) {
+    const subjectMarkers = Array.from(value.matchAll(/\bSubject:\s*/gi));
+    const lastSubjectMarker = subjectMarkers[subjectMarkers.length - 1];
+    if (!lastSubjectMarker || lastSubjectMarker.index === undefined)
+        return '';
+    const subjectStart = lastSubjectMarker.index + lastSubjectMarker[0].length;
+    const tail = value.slice(subjectStart);
+    const nextField = tail.search(/\s+(?:Usage|Preserve):/i);
+    const rawSubject = nextField >= 0 ? tail.slice(0, nextField) : tail;
+    const cleaned = compactStoryboardLine(stripStoryboardMarkup(rawSubject))
+        .replace(new RegExp(String.raw `\s*\(\s*asset\s*${index}\s*\)\s*`, 'i'), ' ')
+        .replace(/^(?:character\/source subject|logo\/brand|product\/object|style\/environment|reference asset|character|logo|brand|product|style|environment|other)\s+references?\b\.?\s*/i, '')
+        .replace(/[.\s]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!cleaned)
+        return '';
+    if (/^(?:logo|brand|character|mascot|asset|reference|image|photo|picture)$/i.test(cleaned))
+        return '';
+    return cleaned.slice(0, 180).replace(/\s+\S*$/, match => cleaned.length > 180 ? '' : match).trim();
+}
+function cleanStoryboardReferenceSubjectHint(context, index) {
+    const source = compactStoryboardLine(stripStoryboardMarkup(context));
+    const explicitSubject = cleanExplicitStoryboardReferenceSubject(source, index);
+    if (explicitSubject)
+        return explicitSubject;
+    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'), '')
+        .replace(/\b(?:use|using|for|as|with|from|featuring|feature)\b\s*$/i, '')
+        .replace(/[.\s]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!cleaned)
+        return '';
+    if (/^(?:logo|brand|character|mascot|asset|reference|image|photo|picture)$/i.test(cleaned))
+        return '';
+    return cleaned.slice(0, 180).replace(/\s+\S*$/, match => cleaned.length > 180 ? '' : match).trim();
+}
+function inferStoryboardReferenceRole(index, text) {
+    const context = contextAroundStoryboardReference(text, index);
+    const lower = context.toLowerCase();
+    const subjectHint = cleanStoryboardReferenceSubjectHint(context, index);
+    if (/\b(?:logo|wordmark|brand|mark|icon)\b/.test(lower)) {
+        return {
+            index,
+            role: 'logo/brand reference',
+            subjectHint,
+            usage: /\b(?:end|final|card|cta|tagline|logo\s+reveal|brand\s+reveal)\b/.test(lower)
+                ? 'end card only unless the approved script says otherwise'
+                : 'brand moments and any explicitly assigned scenes',
+            preserve: 'preserve the visible logo shape, typography, spacing, color relationships, and spelling as closely as possible',
+        };
+    }
+    if (/\b(?:character|mascot|person|people|face|actor|host|protagonist|subject|hero|doll|toy|figure|avatar|girl|boy|woman|man)\b/.test(lower)) {
+        return {
+            index,
+            role: 'character/source subject reference',
+            subjectHint,
+            usage: 'all scenes where that subject appears',
+            preserve: 'preserve the visible identity, proportions, colors, outfit cues, expression, and recognizable silhouette',
+        };
+    }
+    if (/\b(?:product|package|device|object|item)\b/.test(lower)) {
+        return {
+            index,
+            role: 'product/object reference',
+            subjectHint,
+            usage: 'all scenes where that product or object appears',
+            preserve: 'preserve the visible shape, materials, markings, proportions, and recognizable details',
+        };
+    }
+    if (/\b(?:style|mood|look|palette|lighting|texture|background|environment|setting)\b/.test(lower)) {
+        return {
+            index,
+            role: 'style/environment reference',
+            subjectHint,
+            usage: 'style, lighting, palette, or environment guidance where the approved brief calls for it',
+            preserve: 'preserve the requested visual direction without copying unrelated content into every scene',
+        };
+    }
+    return {
+        index,
+        role: 'reference asset',
+        subjectHint,
+        usage: 'use only where assigned by the approved brief',
+        preserve: 'preserve visible details that the brief identifies as important',
+    };
+}
+function storyboardReferenceKindFromRole(role) {
+    const lower = role.role.toLowerCase();
+    if (lower.includes('character') || lower.includes('subject'))
+        return 'character';
+    if (lower.includes('logo') || lower.includes('brand'))
+        return 'logo';
+    if (lower.includes('product') || lower.includes('object'))
+        return 'product';
+    if (lower.includes('style'))
+        return 'style';
+    if (lower.includes('environment') || lower.includes('background'))
+        return 'background';
+    return 'other';
+}
+function storyboardUsageScopeFromRole(role) {
+    const usage = role.usage.toLowerCase();
+    if (/\b(?:end|final|card|cta)\b/.test(usage))
+        return 'end_card_only';
+    if (/\b(?:assigned|specific|explicit)\b/.test(usage))
+        return 'specific_scenes';
+    return 'global';
+}
+function storyboardPreservePriorityFromRole(role) {
+    const kind = storyboardReferenceKindFromRole(role);
+    if (kind === 'logo' || kind === 'character' || kind === 'product')
+        return 'critical';
+    if (kind === 'style' || kind === 'background')
+        return 'high';
+    return 'medium';
+}
+function inferStoryboardReferenceRoles(text) {
+    const count = inferReferencedStoryboardImageCount(text);
+    return Array.from({ length: count }, (_, index) => inferStoryboardReferenceRole(index + 1, text));
+}
+function buildStoryboardReferenceAssets(userIntentText, prompt) {
+    return inferStoryboardReferenceRoles(`${userIntentText}\n${prompt}`).map(role => ({
+        id: `image_${role.index}`,
+        index: role.index,
+        kind: storyboardReferenceKindFromRole(role),
+        description: `${role.role}. ${role.subjectHint ? `Subject: ${role.subjectHint}. ` : ''}Usage: ${role.usage}. Preserve: ${role.preserve}.`,
+        usageScope: storyboardUsageScopeFromRole(role),
+        preservePriority: storyboardPreservePriorityFromRole(role),
+    }));
+}
+function compileStoryboardReferenceSection(project) {
+    const refs = project.references;
+    if (refs.length <= 0) {
+        return [
+            'REFERENCE IMAGES:',
+            'Uploaded or supplied references: preserve any provided subject, product, logo, style, or background roles from the approved brief. If no reference assets are attached, ignore this section.',
+        ];
+    }
+    return [
+        'REFERENCE IMAGES:',
+        ...refs.map((ref, index) => {
+            const modelRef = formatModelRef('gpt-image-2', ref.index ?? index + 1, 'image');
+            return `${modelRef}: ${ref.description} Usage scope: ${ref.usageScope}. Preserve priority: ${ref.preservePriority}.`;
+        }),
+    ];
+}
+function extractStoryboardAvoidConstraints(text) {
+    const constraints = [];
+    for (const match of text.matchAll(/\b(?:avoid|do not include|don't include|without|less)\b[\s\S]{0,220}(?:\.|$)/gi)) {
+        const value = match[0].trim();
+        if (value && !constraints.includes(value))
+            constraints.push(value);
+    }
+    return constraints;
+}
+function extractStoryboardRequiredText(text) {
+    const required = new Set();
+    const inlineProductionLabelPattern = /\b(?:SFX|FX|Audio(?:\s*\/\s*SFX)?|Sound(?:s)?|Music|Foley|Camera(?:\s*\/\s*Motion)?|Motion|Lighting(?:\s*\/\s*Style)?|Style|Transition|Action(?:\s*\/\s*Motion)?|Performance|Beat)\s*:\s*[^a-z0-9]{0,4}$/i;
+    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 shouldIgnoreRequiredText = (value, matchIndex, precedingText) => {
+        const lineStart = text.lastIndexOf('\n', matchIndex) + 1;
+        const nextLineBreak = text.indexOf('\n', matchIndex);
+        const lineEnd = nextLineBreak >= 0 ? nextLineBreak : text.length;
+        const line = text.slice(lineStart, lineEnd);
+        const looksLikeAssetHandle = /\.\.\.|(?:^|[./_-])(?:png|jpe?g|webp|gif|svg)$|[a-f0-9]{8}-[a-f0-9-]{8,}/i.test(value);
+        const fieldLabel = line.match(/^\s*(?:[-*+]\s*)?(?:[*_]{1,3})?\s*([^:\n]{1,60})\s*:/)?.[1] ?? '';
+        const isProductionDirectionField = /\b(?:action|motion|camera|transition|audio|sfx|fx|foley|sound|music|lighting|style|performance|beat)\b/i.test(fieldLabel)
+            && !visibleTextContextPattern.test(fieldLabel);
+        const hasExplicitVisibleTextContext = visibleTextContextPattern.test(line);
+        const looksLikeActionOrSfxCallout = /^[a-z][a-z-]{1,24}[!?.]?$/i.test(value.trim())
+            && /\b(?:action|motion|transition|audio|sfx|fx|foley|sound|music|camera|performance|beat|pop(?:s|ped|ping)?|snap(?:s|ped|ping)?|whoosh(?:es)?|thud(?:s|ded|ding)?|ding(?:s|ed|ing)?|boom(?:s|ed|ing)?|impact(?:s|ed|ing)?|hit(?:s|ting)?|slam(?:s|med|ming)?|wipe(?:s|d|ing)?|glitch(?:es|ed|ing)?|morph(?:s|ed|ing)?|bounce(?:s|d|ing)?|zoom(?:s|ed|ing)?)\b/i.test(line);
+        const precedingTail = (precedingText ?? '').slice(-80);
+        const hasInlineProductionLabel = !!precedingTail
+            && inlineProductionLabelPattern.test(precedingTail)
+            && !visibleTextContextPattern.test(precedingTail);
+        if (/\b(?:working\s+title|project\s+title)\b/i.test(line)
+            && !/\b(?:title\s+card|on[-\s]?screen|visible|text|copy|cta|headline|tagline)\b/i.test(line)) {
+            return true;
+        }
+        if (storyboardTextCandidateLooksLikeGenericProductionLabel(value)) {
+            return true;
+        }
+        if (hasInlineProductionLabel) {
+            return true;
+        }
+        if ((isProductionDirectionField || looksLikeActionOrSfxCallout) && !hasExplicitVisibleTextContext) {
+            return true;
+        }
+        if (looksLikeAssetHandle
+            && /\b(?:asset|reference|image|photo|upload|file|filename|logo|brand)\b/i.test(line)) {
+            return true;
+        }
+        return false;
+    };
+    const addRequiredText = (rawValue, matchIndex = 0, options = {}) => {
+        const value = compactStoryboardLine(stripStoryboardMarkup(rawValue || ''))
+            .replace(/\\"/g, '"')
+            .replace(/^\|+|\|+$/g, '')
+            .replace(/^[*_]+|[*_]+$/g, '')
+            .replace(/^["“”'`]+|["“”'`]+$/g, '')
+            .trim();
+        if (value && shouldIgnoreRequiredText(value, matchIndex, options.precedingText))
+            return;
+        if (/^visible\s+text\b/i.test(value) && (extractStoryboardTiming(value) || /^visible\s+text\.?$/i.test(value)))
+            return;
+        if (options.splitUnquotedList && value.includes(';')) {
+            const parts = value
+                .split(/\s*;\s*/)
+                .map(part => part.trim())
+                .filter(Boolean);
+            if (parts.length > 1 && parts.every(part => part.length <= 160)) {
+                for (const part of parts)
+                    addRequiredText(part, matchIndex, { precedingText: options.precedingText });
+                return;
+            }
+        }
+        if (value)
+            required.add(value);
+    };
+    const exactTextPattern = /\b(?:render|show|include|text|copy|cta|tagline|headline|title|brand|logo|wordmark|words?|say(?:s)?|spell(?:ed)?)\b[^"“`\n]{0,120}(?:"([^"]{1,160})"|“([^”]{1,160})”|`([^`]{1,160})`)/gi;
+    for (const match of text.matchAll(exactTextPattern)) {
+        const fullMatch = match[0];
+        const quoteOpenInMatch = fullMatch.search(/["“`]/);
+        const precedingInMatch = quoteOpenInMatch >= 0 ? fullMatch.slice(0, quoteOpenInMatch) : fullMatch;
+        addRequiredText(match[1] ?? match[2] ?? match[3], match.index ?? 0, {
+            precedingText: precedingInMatch,
+        });
+    }
+    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;
+    for (const match of text.matchAll(labeledTextPattern)) {
+        const value = match[1] || '';
+        const matchStartInText = match.index ?? 0;
+        const valueStartInMatch = match[0].indexOf(value);
+        const valueStartInText = valueStartInMatch >= 0 ? matchStartInText + valueStartInMatch : matchStartInText;
+        let addedQuotedText = false;
+        for (const quote of value.matchAll(/"([^"]{1,160})"|“([^”]{1,160})”|`([^`]{1,160})`/g)) {
+            const innerStartInValue = quote.index ?? 0;
+            const precedingInValue = value.slice(0, innerStartInValue);
+            const quoteAbsIndex = valueStartInText + innerStartInValue;
+            addRequiredText(quote[1] ?? quote[2] ?? quote[3], quoteAbsIndex, {
+                precedingText: precedingInValue,
+            });
+            addedQuotedText = true;
+        }
+        if (!addedQuotedText) {
+            const unquoted = value
+                .split('|')[0]
+                .replace(/\s+\b(?:Dialogue\/VO|VO\/Dialogue|V\.O\.|VO|Voiceover|Voice-over|Speech|Narration|Audio\/SFX|Audio|SFX|FX|Foley|Sound|Sounds|Music|Camera\/Motion|Camera|Lighting\/Style|Lighting|Style|Look|Action\/Motion|Action|Motion)\s*:[\s\S]*$/i, '')
+                .replace(/\b(?:none|no\s+(?:visible\s+)?text|n\/a|not\s+specified)\b\.?$/i, '')
+                .trim();
+            addRequiredText(unquoted, matchStartInText, { splitUnquotedList: true });
+        }
+    }
+    const renderThesePattern = /\b(?:exact words|exact text|required text|final cta|end card text)\b[\s\S]{0,320}/gi;
+    for (const block of text.matchAll(renderThesePattern)) {
+        for (const quote of extractQuotedDialogueSegments(block[0])) {
+            addRequiredText(quote, block.index ?? 0);
+        }
+    }
+    return [...required];
+}
+function inferStoryboardTitle(text) {
+    const cleanTitle = (rawValue) => compactStoryboardLine(stripStoryboardMarkup(rawValue)
+        .replace(/^["“”'`*_\s]+|["“”'`*_\s.]+$/g, ''));
+    const titleMatch = text.match(/\b(?:title|working title)\s*:\s*([^\n]{1,120})/i);
+    if (titleMatch?.[1]?.trim())
+        return cleanTitle(titleMatch[1]);
+    const quotedTitle = text.match(/\b(?:titled|called)\s+"([^"]{1,120})"/i);
+    if (quotedTitle?.[1]?.trim())
+        return cleanTitle(quotedTitle[1]);
+    return 'Video Storyboard';
+}
+function compactStoryboardLine(value, fallback = '') {
+    return String(value || fallback).replace(/\s+/g, ' ').trim();
+}
+function stripStoryboardExpansionInstruction(value) {
+    return value
+        .replace(/\s*If the source text contains fewer (?:panel|frame) descriptions, expand those beats into exactly \d{1,2} timecoded frames; do not create (?:a\s+)?(?:\d{1,2}|four|six)[^.]*?or split the storyboard into separate images\./gi, '')
+        .replace(/\s*If the source text contains fewer (?:panel|frame) descriptions, expand those beats into exactly \d{1,2} timecoded frames; keep all frames in one composite storyboard image and do not split the storyboard into separate images\./gi, '')
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function normalizeStoryboardBriefKey(value) {
+    return stripStoryboardExpansionInstruction(value)
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}:]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function textHasStoryboardBriefSubstance(value) {
+    const text = stripStoryboardExpansionInstruction(value);
+    if (text.length < 40)
+        return false;
+    return /\b(?:story\s*board|storyboard|video|seedance|commercial|promo|teaser|ad|scene|shot|beat|panel|frame|duration|logo|reference|audio|sfx|foley)\b/i.test(text)
+        || extractStoryboardTiming(text) !== null;
+}
+function isTerseStoryboardRetryInstruction(value) {
+    const text = stripStoryboardExpansionInstruction(value)
+        .toLowerCase()
+        .replace(/[.!?]+$/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!text || text.length > 90)
+        return false;
+    return /^(?:try again|retry|redo|rerun|run it again|do it again|go ahead|do it|continue|looks good|approved|approve|yes|yeah|yep|ok|okay|sure|please do|make it)$/.test(text)
+        || /\b(?:try again|retry|redo|do it again)\b/i.test(text);
+}
+function latestSubstantiveStoryboardUserBrief(userIntentText, promptCore) {
+    const promptKey = normalizeStoryboardBriefKey(promptCore);
+    const chunks = userIntentText
+        .split(/\n{1,}/)
+        .map(chunk => chunk.trim())
+        .filter(Boolean)
+        .filter(chunk => normalizeStoryboardBriefKey(chunk) !== promptKey)
+        .filter(textHasStoryboardBriefSubstance);
+    return chunks[chunks.length - 1] || '';
+}
+function selectStoryboardSourceBrief(prompt, userIntentText) {
+    const promptCore = stripStoryboardExpansionInstruction(prompt);
+    const priorBrief = latestSubstantiveStoryboardUserBrief(userIntentText, promptCore);
+    if (priorBrief && (!textHasStoryboardBriefSubstance(promptCore) || isTerseStoryboardRetryInstruction(promptCore))) {
+        return priorBrief;
+    }
+    return promptCore || priorBrief || userIntentText.trim();
+}
+function storyboardBriefContains(haystack, needle) {
+    const haystackKey = normalizeStoryboardBriefKey(haystack);
+    const needleKey = normalizeStoryboardBriefKey(needle);
+    return !!needleKey && haystackKey.includes(needleKey);
+}
+function buildStoryboardSourceBriefForPrompt(prompt, userIntentText, approvedScriptContext, promptAuthorship) {
+    const selectedBrief = selectStoryboardSourceBrief(prompt, userIntentText);
+    const originalBrief = latestSubstantiveStoryboardUserBrief(userIntentText, selectedBrief);
+    const canonicalApprovedScriptContext = canonicalStoryboardScriptContext(approvedScriptContext);
+    const includeSelectedBrief = selectedBrief && !(promptAuthorship === 'assistant' && canonicalApprovedScriptContext);
+    const includeOriginalBrief = originalBrief && !(promptAuthorship === 'assistant' && canonicalApprovedScriptContext);
+    const parts = [];
+    if (includeOriginalBrief && !storyboardBriefContains(selectedBrief, originalBrief)) {
+        parts.push(`ORIGINAL USER INTENT:\n${originalBrief}`);
+    }
+    if (includeSelectedBrief) {
+        parts.push(parts.length > 0 ? `STORYBOARD BRIEF:\n${selectedBrief}` : selectedBrief);
+    }
+    if (canonicalApprovedScriptContext) {
+        parts.push(`APPROVED STORYBOARD SCRIPT CONTEXT TO PRESERVE:\n${canonicalApprovedScriptContext}`);
+    }
+    return parts.filter(Boolean).join('\n\n');
+}
+function buildStoryboardUserConstraintSource(userIntentText, primarySourceBrief, options) {
+    const canonicalApprovedScriptContext = canonicalStoryboardScriptContext(options.approvedScriptContext);
+    return [
+        userIntentText,
+        canonicalApprovedScriptContext,
+        options.promptAuthorship === 'assistant' ? '' : primarySourceBrief,
+    ].filter(Boolean).join('\n\n');
+}
+function stripStoryboardMarkup(value) {
+    return value
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/?[^>]+>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&quot;/gi, '"')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/__([^_]+)__/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/`([^`]+)`/g, '$1')
+        .split(/\r?\n/)
+        .map(line => line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim())
+        .filter(Boolean)
+        .join('\n')
+        .trim();
+}
+function storyboardFieldLabelPattern(label) {
+    return label
+        .trim()
+        .split('/')
+        .map(part => part.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join(String.raw `\s*/\s*`);
+}
+function extractStoryboardField(section, labels) {
+    const normalizedSection = stripStoryboardMarkup(section)
+        .split(/\r?\n/)
+        .map(line => line.replace(/^\s*#{1,6}\s*/, '').trim())
+        .filter(Boolean)
+        .join('\n');
+    const labelPattern = labels.map(storyboardFieldLabelPattern).join('|');
+    const match = normalizedSection.match(new RegExp(String.raw `^\s*(?:${labelPattern})(?:\s*\([^)\n]{0,80}\))?\s*:\s*(.+)$`, 'im'));
+    return compactStoryboardLine(match?.[1]);
+}
+function removeStoryboardTimingText(value) {
+    return value
+        .replace(/\b\d{1,2}:\d{2}(?:\.\d+)?\s*(?:-|to|\u2013|\u2014)\s*\d{1,2}:\d{2}(?:\.\d+)?\b/gi, ' ')
+        .replace(/\b\d{1,3}(?:\.\d+)?\s*(?:s|sec|secs|seconds?)?\s*(?:-|to|\u2013|\u2014)\s*\d{1,3}(?:\.\d+)?\s*(?:s|sec|secs|seconds?)?\b/gi, ' ')
+        .replace(/\(\s*\)|\[\s*\]/g, ' ')
+        .replace(/\s*[|]\s*/g, ' ')
+        .replace(/^[-:.\s|]+|[-:.\s|]+$/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function storyboardTextCandidateLooksLikeGenericProductionLabel(value) {
+    const withoutTiming = removeStoryboardTimingText(value)
+        .replace(/^\(|\)$/g, '')
+        .replace(/^[-:.\s|]+|[-:.\s|]+$/g, '')
+        .trim();
+    return /^(?:visible\s+text|on[-\s]?screen\s+text|onscreen\s+text|text\s+overlay|title\s+card|caption|subtitle|super|copy|cta|tagline|headline)$/i.test(withoutTiming);
+}
+function normalizeStoryboardDialogue(value) {
+    const compact = compactStoryboardLine(value);
+    if (!compact)
+        return '';
+    if (/^[-\u2013\u2014]\.?$/.test(compact))
+        return '';
+    if (/^(?:[\[(]\s*)?(?:none|no\s+(?:spoken\s+)?(?:dialogue|vo|voiceover|voice-over|speech)|n\/a|not\s+specified|text\s+only|silence(?:\s*\/\s*beat)?|silent beat)(?:\s*[\])])?\.?$/i.test(compact)) {
+        return '';
+    }
+    const visibleTextField = compact.match(/^(?:visible\s+text|on[-\s]?screen\s+text|onscreen\s+text|text|cta|tagline|headline|title\s+card|copy)\s*:\s*(.+)$/i)?.[1];
+    if (visibleTextField !== undefined)
+        return '';
+    if (/^text\s+only\s*:/i.test(compact))
+        return '';
+    const quoted = extractQuotedDialogueSegments(compact)
+        .map(line => compactStoryboardLine(line))
+        .filter(Boolean);
+    if (quoted.length > 0)
+        return quoted.join(' ');
+    const nestedVo = compact.match(/\b(?:VO|V\.O\.|Voiceover|Voice-over|Dialogue|Speech|Narration)\b(?:\s*\([^)]*\))?\s*:\s*(.+)$/i)?.[1];
+    if (nestedVo && !/^(?:[\[(]\s*)?(?:none|no\s+(?:spoken\s+)?(?:dialogue|vo|voiceover|voice-over|speech)|n\/a|not\s+specified|text\s+only)(?:\s*[\])])?\.?$/i.test(nestedVo.trim())) {
+        return compactStoryboardLine(nestedVo);
+    }
+    return compact;
+}
+function parseStoryboardTimeValue(value) {
+    const trimmed = value.trim();
+    const timecode = trimmed.match(/^(\d{1,2}):(\d{2})(?:\.(\d+))?$/);
+    if (timecode) {
+        const minutes = Number(timecode[1]);
+        const seconds = Number(timecode[2]);
+        const fraction = timecode[3] ? Number(`0.${timecode[3]}`) : 0;
+        if (!Number.isFinite(minutes) || !Number.isFinite(seconds) || seconds >= 60)
+            return null;
+        return Math.round((minutes * 60 + seconds + fraction) * 100) / 100;
+    }
+    const numeric = Number(trimmed);
+    return Number.isFinite(numeric) ? numeric : null;
+}
+function extractStoryboardTiming(text) {
+    const match = text.match(/(\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?\s*(?:-|to|\u2013|\u2014)\s*(\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?/i);
+    if (!match)
+        return null;
+    const startSec = parseStoryboardTimeValue(match[1]);
+    const endSec = parseStoryboardTimeValue(match[2]);
+    if (startSec === null || endSec === null)
+        return null;
+    if (!Number.isFinite(startSec) || !Number.isFinite(endSec) || endSec <= startSec)
+        return null;
+    return {
+        startSec,
+        endSec,
+        durationSec: Math.round((endSec - startSec) * 100) / 100,
+    };
+}
+function extractStoryboardTimingMarker(text) {
+    const match = text.match(/(\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?\s*(?:-|to|\u2013|\u2014)\s*(\d{1,2}:\d{2}(?:\.\d+)?|\d{1,3}(?:\.\d+)?)\s*(?:s|sec|secs|seconds?)?/i);
+    if (!match)
+        return null;
+    const startSec = parseStoryboardTimeValue(match[1]);
+    const endSec = parseStoryboardTimeValue(match[2]);
+    if (startSec === null || endSec === null)
+        return null;
+    if (!Number.isFinite(startSec) || !Number.isFinite(endSec) || endSec < startSec)
+        return null;
+    return {
+        startSec,
+        endSec,
+        durationSec: Math.round((endSec - startSec) * 100) / 100,
+    };
+}
+function storyboardMarkdownTableCells(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return [];
+    const cells = trimmed
+        .replace(/^\|/, '')
+        .replace(/\|$/, '')
+        .split('|')
+        .map(cell => stripStoryboardMarkup(cell))
+        .map(cell => compactStoryboardLine(cell))
+        .filter(cell => cell.length > 0);
+    if (cells.length < 2)
+        return [];
+    if (cells.every(cell => /^:?-{3,}:?$/.test(cell.replace(/\s+/g, ''))))
+        return [];
+    return cells;
+}
+function splitStoryboardTitleDescription(value) {
+    const cleaned = stripStoryboardMarkup(value);
+    const fallbackTitleFromDescription = (description) => {
+        const withoutLeadingLabel = description.replace(/^(?:Visual|Visual Frame|Frame|Shot|Image|Action|Action\/Motion)\s*:\s*/i, '');
+        const titleSafe = withoutLeadingLabel
+            .replace(/"[^"]{1,240}"|“[^”]{1,240}”|`[^`]{1,240}`/g, '')
+            .replace(/\s+\b(?:Dialogue\/VO|VO\/Dialogue|V\.O\.|VO|Voiceover|Voice-over|Speech|Narration|Audio\/SFX|Audio|SFX|FX|Foley|Sound|Sounds|Music|Visible text|On-screen text|Onscreen text|Text|CTA|Camera\/Motion|Camera|Lighting\/Style|Lighting|Style|Look|Action\/Motion|Action|Motion)\s*:[\s\S]*$/i, '')
+            .replace(/\s*:\s*$/, '');
+        const firstClause = titleSafe.split(/(?<=[.!?])\s+|;\s+|\n/)[0] || titleSafe || withoutLeadingLabel;
+        return compactStoryboardLine(firstClause.slice(0, 80), 'Storyboard Beat');
+    };
+    const match = cleaned.match(/^([^:\n]{1,100})\s*:\s*([\s\S]+)$/);
+    if (!match) {
+        return {
+            title: fallbackTitleFromDescription(cleaned),
+            description: compactStoryboardLine(cleaned),
+        };
+    }
+    const rawPrefix = match[1];
+    const prefixContainsSentenceEnd = /[.!?]\s/.test(rawPrefix);
+    if (prefixContainsSentenceEnd) {
+        return {
+            title: fallbackTitleFromDescription(cleaned),
+            description: compactStoryboardLine(cleaned),
+        };
+    }
+    const title = compactStoryboardLine(rawPrefix, 'Storyboard Beat');
+    const description = compactStoryboardLine(match[2], cleaned);
+    if (/^(?:visual|visual frame|frame|shot|image|action|action\/motion|camera|audio|sfx|dialogue|vo)$/i.test(title)) {
+        return {
+            title: fallbackTitleFromDescription(description),
+            description,
+        };
+    }
+    return {
+        title,
+        description,
+    };
+}
+function storyboardTableCellWithFieldBreaks(value) {
+    return stripStoryboardMarkup(value)
+        .replace(/\s+\b(Dialogue\/VO|VO\/Dialogue|V\.O\.|VO|Voiceover|Voice-over|Speech|Narration|Audio\/SFX|Audio|SFX|FX|Foley|Sound|Sounds|Music|Visible text|On-screen text|Onscreen text|Text|CTA|Camera\/Motion|Camera|Lighting\/Style|Lighting|Style|Look|Action\/Motion|Action|Motion)\s*:/gi, '\n$1:')
+        .trim();
+}
+function storyboardTableHeaderMatches(header, pattern) {
+    return !!header && pattern.test(header);
+}
+function storyboardTableHeaderIndex(headers, pattern) {
+    if (!headers)
+        return -1;
+    return headers.findIndex(header => storyboardTableHeaderMatches(header, pattern));
+}
+function uniqueStoryboardTableIndices(indices) {
+    const seen = new Set();
+    return indices.filter(index => {
+        if (index < 0 || seen.has(index))
+            return false;
+        seen.add(index);
+        return true;
+    });
+}
+function looksLikeStoryboardTableHeader(cells) {
+    if (cells.some(cell => extractStoryboardTiming(cell)))
+        return false;
+    const joined = cells.join(' ');
+    return /\b(?:time|timecode|timing|duration)\b/i.test(joined)
+        && /\b(?:visual|action|frame|shot|camera|audio|dialogue|vo|voiceover|sfx)\b/i.test(joined);
+}
+function storyboardTableCellWithoutDialogue(cell, dialogue) {
+    const normalizedDialogue = compactStoryboardLine(dialogue).toLowerCase();
+    return cell
+        .split(/\r?\n/)
+        .map(line => {
+        const compact = compactStoryboardLine(dialogue ? line.replace(/"[^"]{1,800}"/g, ' ') : line);
+        if (normalizedDialogue && compact.toLowerCase() === normalizedDialogue) {
+            return '';
+        }
+        if (/^\s*(?:Dialogue\/VO|VO\/Dialogue|V\.O\.|VO|Voiceover|Voice-over|Speech|Narration)\s*:/i.test(compact)) {
+            return '';
+        }
+        if (/^\s*(?:Visible text|On-screen text|Onscreen text|Text|CTA)\s*:/i.test(compact)) {
+            return '';
+        }
+        return compact;
+    })
+        .filter(Boolean)
+        .join(' ')
+        .replace(/\b(?:none|no\s+(?:spoken\s+)?(?:dialogue|vo|voiceover|voice-over|speech)|n\/a|not\s+specified|text\s+only)\b\.?/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function storyboardTableCellHasExplicitVoiceField(cell) {
+    return cell
+        .split(/\r?\n/)
+        .some(line => /^\s*(?:Dialogue\/VO|VO\/Dialogue|Dialogue|VO|V\.O\.|Voiceover|Voice-over|Speech|Narration)\s*:/i.test(compactStoryboardLine(line)));
+}
+function storyboardTableCellIsAudioOnly(cell) {
+    const lines = cell
+        .split(/\r?\n/)
+        .map(line => compactStoryboardLine(line))
+        .filter(Boolean);
+    if (lines.length === 0)
+        return false;
+    if (storyboardTableCellHasExplicitVoiceField(cell))
+        return false;
+    return lines.every(line => /^\s*(?:Audio\/SFX|Audio|SFX|FX|Foley|Sound|Sounds|Music)\s*:/i.test(line));
+}
+function splitStoryboardTableSections(text) {
+    const sections = [];
+    let headers = null;
+    for (const line of text.split(/\r?\n/)) {
+        const cells = storyboardMarkdownTableCells(line);
+        if (cells.length < 3)
+            continue;
+        if (looksLikeStoryboardTableHeader(cells)) {
+            headers = cells;
+            continue;
+        }
+        const timingCellIndex = cells.findIndex(cell => extractStoryboardTimingMarker(cell) !== null);
+        if (timingCellIndex < 0)
+            continue;
+        const timing = extractStoryboardTimingMarker(cells[timingCellIndex]);
+        if (!timing)
+            continue;
+        const visualHeaderIndex = storyboardTableHeaderIndex(headers, /\b(?:visual|frame|shot|image|action)\b/i);
+        const cameraHeaderIndex = storyboardTableHeaderIndex(headers, /\b(?:camera|motion|fx|effect|lighting|style|look)\b/i);
+        const dialogueHeaderIndex = storyboardTableHeaderIndex(headers, /\b(?:dialogue|vo|v\.o\.|voiceover|speech|narration)\b/i);
+        const soundHeaderIndex = storyboardTableHeaderIndex(headers, /\b(?:audio|sfx|sound|foley|music)\b/i);
+        const visibleTextHeaderIndex = storyboardTableHeaderIndex(headers, /\b(?:visible\s+text|on[-\s]?screen\s+text|onscreen\s+text|text|copy|cta|tagline|headline|title\s+card|subtitle|caption)\b/i);
+        const beatHeaderIndex = headers
+            ? headers.findIndex(header => /\b(?:beat|scene|shot|panel|frame)\b/i.test(header)
+                && !/\b(?:visual|action|camera|audio|dialogue|vo|sfx)\b/i.test(header))
+            : -1;
+        const purposeHeaderIndex = headers
+            ? headers.findIndex(header => /\b(?:purpose|story\s*beat|story\s*purpose|beat\s*name|beat\s*title|narrative|name|title)\b/i.test(header)
+                && !/\b(?:visual|action|camera|audio|dialogue|vo|sfx|time|transition|scene)\b/i.test(header))
+            : -1;
+        const visualIndex = visualHeaderIndex >= 0
+            ? visualHeaderIndex
+            : timingCellIndex === 0
+                ? 1
+                : Math.min(timingCellIndex + 1, cells.length - 1);
+        if (visualIndex === timingCellIndex)
+            continue;
+        const visualHeader = headers?.[visualIndex] || '';
+        const visualCell = cells[visualIndex] || '';
+        const visualCellWithFieldBreaks = storyboardTableCellWithFieldBreaks(visualCell);
+        const visual = splitStoryboardTitleDescription(visualCell);
+        const explicitAction = extractStoryboardField(visualCellWithFieldBreaks, ['Action/Motion', 'Action', 'Motion', 'Performance']);
+        const action = explicitAction || (storyboardTableHeaderMatches(visualHeader, /\b(?:action|motion|performance)\b/i)
+            && !storyboardTableHeaderMatches(visualHeader, /\b(?:visual|frame|shot|image)\b/i)
+            ? visual.description || visual.title
+            : '');
+        const cameraLighting = cameraHeaderIndex >= 0
+            ? storyboardTableCellWithFieldBreaks(cells[cameraHeaderIndex] || '')
+            : '';
+        const dialogueCell = dialogueHeaderIndex >= 0
+            ? storyboardTableCellWithFieldBreaks(cells[dialogueHeaderIndex] || '')
+            : '';
+        const soundCell = soundHeaderIndex >= 0
+            ? storyboardTableCellWithFieldBreaks(cells[soundHeaderIndex] || '')
+            : '';
+        const visibleTextCell = visibleTextHeaderIndex >= 0
+            ? storyboardTableCellWithFieldBreaks(cells[visibleTextHeaderIndex] || '')
+            : '';
+        const audioCell = uniqueStoryboardTableIndices([dialogueHeaderIndex, soundHeaderIndex, visibleTextHeaderIndex])
+            .map(index => storyboardTableCellWithFieldBreaks(cells[index] || ''))
+            .filter(Boolean)
+            .join('\n');
+        const dialogueHeader = headers?.[dialogueHeaderIndex] || headers?.[soundHeaderIndex] || '';
+        const camera = extractStoryboardField(cameraLighting, ['Camera', 'Camera/Motion', 'Framing', 'Shot type']);
+        const lighting = extractStoryboardField(cameraLighting, ['Lighting', 'Style', 'Lighting/Style', 'Look']);
+        const explicitDialogue = extractStoryboardField(audioCell, [
+            'Dialogue/VO',
+            'VO/Dialogue',
+            'Dialogue',
+            'VO',
+            'V.O.',
+            'Voiceover',
+            'Voice-over',
+            'Speech',
+            'Narration',
+        ]);
+        const dialogue = explicitDialogue
+            ? normalizeStoryboardDialogue(explicitDialogue)
+            : storyboardTableCellIsAudioOnly(dialogueCell || audioCell)
+                ? ''
+                : storyboardTableHeaderMatches(dialogueHeader, /\b(?:dialogue|vo|v\.o\.|voiceover|speech|narration)\b/i)
+                    ? normalizeStoryboardDialogue(extractQuotedDialogueSegments(dialogueCell || audioCell)[0] || dialogueCell || audioCell)
+                    : '';
+        const visibleText = extractStoryboardField(audioCell, ['Visible text', 'On-screen text', 'Onscreen text', 'Text', 'CTA'])
+            || (visibleTextHeaderIndex >= 0 ? compactStoryboardLine(visibleTextCell) : '');
+        const audio = extractStoryboardField(audioCell, ['Audio/SFX', 'Audio', 'SFX', 'FX', 'Foley', 'Sound', 'Sounds'])
+            || storyboardTableCellWithoutDialogue(soundCell || audioCell, dialogue);
+        const number = sections.length + 1;
+        const beatLabel = beatHeaderIndex >= 0 && beatHeaderIndex !== timingCellIndex
+            ? compactStoryboardLine(cells[beatHeaderIndex])
+            : '';
+        const purposeLabel = purposeHeaderIndex >= 0
+            && purposeHeaderIndex !== timingCellIndex
+            && purposeHeaderIndex !== visualIndex
+            && purposeHeaderIndex !== beatHeaderIndex
+            && purposeHeaderIndex !== dialogueHeaderIndex
+            && purposeHeaderIndex !== soundHeaderIndex
+            && purposeHeaderIndex !== cameraHeaderIndex
+            && purposeHeaderIndex !== visibleTextHeaderIndex
+            ? compactStoryboardLine(cells[purposeHeaderIndex])
+            : '';
+        const beatTitleSource = purposeLabel && !/^\d{1,2}$/.test(purposeLabel)
+            ? purposeLabel
+            : beatLabel && !/^\d{1,2}$/.test(beatLabel)
+                ? beatLabel
+                : '';
+        const sceneTitle = beatTitleSource
+            ? `${beatTitleSource}: ${visual.title}`
+            : visual.title;
+        sections.push({
+            number,
+            heading: `Scene ${number} - ${sceneTitle} - ${formatStoryboardSeconds(timing.startSec)}-${formatStoryboardSeconds(timing.endSec)}`,
+            body: [
+                `Visual: ${visual.description || visual.title}`,
+                action ? `Action: ${action}` : '',
+                camera ? `Camera: ${camera}` : cameraLighting ? `Camera: ${compactStoryboardLine(cameraLighting)}` : '',
+                lighting ? `Lighting: ${lighting}` : '',
+                dialogue ? `Dialogue/VO: ${dialogue}` : '',
+                visibleText ? `Visible text: ${visibleText}` : '',
+                audio ? `Audio/SFX: ${audio}` : '',
+            ].filter(Boolean).join('\n'),
+        });
+    }
+    return sections;
+}
+function splitStoryboardSceneSections(text) {
+    const matches = Array.from(text.matchAll(/^\s*(?:[-*+]\s*)?(?:#{1,6}\s*)?(?:[*_]{1,3})?\s*(?:Scene|Shot|Beat|Panel|Frame)\s*(\d{1,2})\b\s*(?:[-:.)|]\s*)?([^\n]*)/gim));
+    if (matches.length === 0)
+        return [];
+    return matches.map((match, index) => {
+        const start = match.index ?? 0;
+        const nextStart = index + 1 < matches.length ? matches[index + 1].index ?? text.length : text.length;
+        return {
+            number: Number(match[1]),
+            heading: compactStoryboardLine(match[0]),
+            body: text.slice(start, nextStart).trim(),
+        };
+    }).filter(section => Number.isInteger(section.number) && section.number > 0);
+}
+function splitStoryboardSections(text) {
+    const sectionHeadings = splitStoryboardSceneSections(text);
+    const tableSections = splitStoryboardTableSections(text);
+    if (tableSections.length > 0 && tableSections.length >= sectionHeadings.length) {
+        return tableSections;
+    }
+    return sectionHeadings.length > 0 ? sectionHeadings : tableSections;
+}
+function storyboardSectionsHavePreservableExplicitTiming(sections) {
+    return sections.length > 1
+        && sections.some(section => extractStoryboardTiming(`${section.heading}\n${section.body}`) !== null);
+}
+function canonicalStoryboardScriptContext(text) {
+    const trimmed = String(text || '').trim();
+    if (!trimmed)
+        return '';
+    const cutoffPattern = /^\s*(?:[-*+]\s*)?(?:#{1,6}\s*)?(?:[*_]{1,3})?\s*(?:[^\w\n]{0,12}\s*)?(?:storyboard\s+image\s+brief|subsequent\s+video\s+brief|video\s+generation\s+stage|next\s+steps?)\b[^\n]*$/gim;
+    for (const match of trimmed.matchAll(cutoffPattern)) {
+        const before = trimmed.slice(0, match.index ?? 0).trim();
+        if (before && splitStoryboardSections(before).length > 0) {
+            return before;
+        }
+    }
+    return trimmed;
+}
+function escapeStoryboardRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function uniqueStoryboardStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values.map(item => compactStoryboardLine(item)).filter(Boolean)) {
+        const key = value.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(value);
+    }
+    return result;
+}
+function normalizeStoryboardContractTextArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return uniqueStoryboardStrings(value.filter((item) => typeof item === 'string'));
+}
+function storyboardScenePlanningContractForIndex(contract, sceneNumber) {
+    const scenes = Array.isArray(contract?.scenes) ? contract.scenes : [];
+    const id = `scene_${String(sceneNumber).padStart(2, '0')}`.toLowerCase();
+    return scenes.find(scene => typeof scene.id === 'string' && scene.id.toLowerCase() === id)
+        ?? scenes.find(scene => scene.index === sceneNumber)
+        ?? null;
+}
+function removeStoryboardMetadataLabelsFromVisibleText(visibleText, metadataLabels) {
+    if (metadataLabels.length === 0)
+        return visibleText;
+    const metadataKeys = new Set(metadataLabels.map(item => compactStoryboardLine(item).toLowerCase()));
+    return visibleText.filter(item => !metadataKeys.has(compactStoryboardLine(item).toLowerCase()));
+}
+function metadataLabelsFromPlanningContract(contract) {
+    return uniqueStoryboardStrings([
+        ...normalizeStoryboardContractTextArray(contract?.metadataLabels),
+        ...normalizeStoryboardContractTextArray(contract?.endCard?.metadataLabels),
+        ...(Array.isArray(contract?.scenes)
+            ? contract.scenes.flatMap(scene => normalizeStoryboardContractTextArray(scene.metadataLabels))
+            : []),
+    ]);
+}
+function storyboardReferenceSubjectTokens(ref) {
+    const subject = ref.description.match(/\bSubject:\s*([\s\S]*?)\s+Usage:/i)?.[1] || '';
+    if (!subject)
+        return [];
+    const stopWords = new Set([
+        'asset',
+        'image',
+        'photo',
+        'picture',
+        'reference',
+        'source',
+        'input',
+        'with',
+        'from',
+        'that',
+        'this',
+        'used',
+        'using',
+        'where',
+        'scene',
+        'scenes',
+        'final',
+        'card',
+        'only',
+        'unless',
+    ]);
+    return uniqueStoryboardStrings(subject
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(/\s+/)
+        .map(token => token.trim())
+        .filter(token => token.length >= 4 && !stopWords.has(token)));
+}
+function storyboardReferenceSubjectMatchesSection(ref, lowerSection) {
+    return storyboardReferenceSubjectTokens(ref).some(token => new RegExp(String.raw `\b${escapeStoryboardRegExp(token)}\b`, 'i').test(lowerSection));
+}
+function sceneReferencesFromSection(section, references) {
+    const used = references
+        .filter(ref => ref.index && new RegExp(String.raw `\b(?:image|photo|picture|asset)\s*(?:#|number\s*)?${ref.index}\b`, 'i').test(section))
+        .map(ref => ref.id);
+    if (used.length > 0)
+        return used;
+    const lower = section.toLowerCase();
+    const subjectMatches = references
+        .filter(ref => ref.kind !== 'logo')
+        .filter(ref => storyboardReferenceSubjectMatchesSection(ref, lower))
+        .map(ref => ref.id);
+    if (subjectMatches.length > 0)
+        return uniqueStoryboardStrings(subjectMatches);
+    const roleMatches = references
+        .filter(ref => {
+        if (ref.kind === 'logo')
+            return /\b(?:logo|wordmark|brand|brand\s+mark|end\s+card|cta|tagline)\b/i.test(lower);
+        if (ref.kind === 'style' || ref.kind === 'background')
+            return /\b(?:style|look|lighting|palette|background|environment|setting)\b/i.test(lower);
+        return false;
+    })
+        .map(ref => ref.id);
+    if (roleMatches.length > 0)
+        return uniqueStoryboardStrings(roleMatches);
+    return references
+        .filter(ref => ref.usageScope === 'global')
+        .filter(ref => {
+        if (ref.kind === 'character') {
+            return /\b(?:character|mascot|person|people|face|actor|host|protagonist|subject|hero|doll|toy|figure|avatar|girl|boy|woman|man|she|he|they|her|him)\b/i.test(lower);
+        }
+        if (ref.kind === 'product') {
+            return /\b(?:product|package|device|object|item|prototype|model|tool|app|platform|integration|feature)\b/i.test(lower);
+        }
+        return false;
+    })
+        .map(ref => ref.id);
+}
+function sceneTextRequirementsFromSection(section) {
+    const required = extractStoryboardRequiredText(section);
+    const visualCueContext = [
+        section.split(/\r?\n/, 1)[0] || '',
+        extractStoryboardField(section, ['Visual/Action', 'Visual Frame', 'Visual', 'Frame', 'Image', 'Shot']),
+        extractStoryboardField(section, ['Action/Motion', 'Action', 'Motion', 'Performance']),
+        extractStoryboardField(section, ['Product/Feature', 'Product feature', 'Feature mapping', 'Product meaning', 'Feature', 'Capability']),
+    ].filter(Boolean).join('\n');
+    const hasVisibleTextCue = /\b(?:visible\s+text|on[-\s]?screen\s+text|onscreen\s+text|text\s+overlay|title\s+card|end\s+card|cta|tagline|headline|slogan|copy|wordmark|text\s+(?:appears|changes|updates|fades|reads|below)|reads\s*:)\b/i.test(visualCueContext);
+    if (!hasVisibleTextCue) {
+        return required;
+    }
+    const quotedVisualText = extractQuotedDialogueSegments(visualCueContext)
+        .map(text => compactStoryboardLine(text))
+        .filter(Boolean)
+        .filter(text => !/^[-\u2013\u2014]\.?$/.test(text))
+        .filter(text => !/^(?:none|no\s+(?:visible\s+)?text|n\/a|not\s+specified)$/i.test(text));
+    return uniqueStoryboardStrings([...required, ...quotedVisualText]);
+}
+function isNoAudioPlaceholder(value) {
+    return /^(?:no\s+(?:audio|sound|sfx|audio\/sfx)(?:\s+specified)?|none|n\/a|not\s+specified)\.?$/i.test(value.trim());
+}
+function sanitizeStoryboardExternalAudioReferences(value) {
+    let sanitized = value;
+    sanitized = sanitized
+        .replace(/\b(?:trending|viral|popular)\s+(?:TikTok\s+)?(?:audio|sound|song|track)\b/gi, 'video-model-generated social-video music bed')
+        .replace(/\b(?:a\s+)?(?:trending|viral|popular)\s+(?:upbeat\s+)?(?:audio|sound|song|track)\b/gi, 'a video-model-generated upbeat social-video music bed')
+        .replace(/\b(?:existing|external|licensed|commercial)\s+(?:audio|sound|song|track|music)\b/gi, 'generated audio');
+    sanitized = sanitized.replace(/\b(?:all\s+)?(?:cuts?|edits?|transitions?)\s+(?:must\s+|should\s+)?(?:align|sync|cut)\s+(?:perfectly\s+|exactly\s+)?(?:with|to)\s+([^.!?\n]*(?:beat|beats|drop|drops|snare|hi[-/\s]?hat|kick|percussion)[^.!?\n]*)[.!?]?/gi, 'Cuts should follow a generated music bed, with percussion hits, beat drops, whooshes, and foley cues described for the video model.');
+    if (/\b(?:snare|hi-hat|beat drops?|cuts?)\b/i.test(sanitized) && /\bvideo-model-generated\b/i.test(sanitized)) {
+        sanitized = sanitized.replace(/\bperfectly\b/gi, 'clearly');
+    }
+    return sanitized;
+}
+function normalizeStoryboardAudioSfx(value) {
+    const compact = sanitizeStoryboardExternalAudioReferences(compactStoryboardLine(value));
+    if (!compact || isNoAudioPlaceholder(compact))
+        return [];
+    return compact
+        .split(/\s*,\s*|\s*;\s*/)
+        .map(item => item.trim())
+        .filter(Boolean);
+}
+function buildSceneFromSection(section, references, fallbackTiming, planningContract) {
+    const combined = `${section.heading}\n${section.body}`;
+    const timing = extractStoryboardTiming(combined) ?? fallbackTiming;
+    const normalizedHeading = stripStoryboardMarkup(section.heading)
+        .replace(/^\s*#{1,6}\s*/, '');
+    const title = compactStoryboardLine(removeStoryboardTimingText(normalizedHeading
+        .replace(/^\s*(?:Scene|Shot|Beat|Panel|Frame)\s*\d{1,2}\b\s*(?:[-:.)|]\s*)?/i, '')), `Scene ${String(section.number).padStart(2, '0')}`);
+    const dialogueField = extractStoryboardField(combined, [
+        'Dialogue/VO',
+        'VO/Dialogue',
+        'Dialogue',
+        'VO',
+        'V.O.',
+        'Voiceover',
+        'Voice-over',
+        'Speech',
+        'Narration',
+    ]);
+    const hasExplicitNoDialogueField = /\b(?:Dialogue\/VO|VO\/Dialogue|Dialogue|VO|V\.O\.|Voiceover|Voice-over|Speech|Narration)\s*:\s*(?:none|no\s+(?:spoken\s+)?(?:dialogue|vo|voiceover|voice-over|speech)|n\/a|not\s+specified|text\s+only)\b/i.test(combined);
+    const dialogue = dialogueField
+        ? normalizeStoryboardDialogue(dialogueField)
+        : hasExplicitNoDialogueField
+            ? ''
+            : /\b(?:VO|V\.O\.|voiceover|voice-over|dialogue|speech|narration|says?|speaks?|whispers?|shouts?)\b/i.test(combined)
+                ? extractQuotedDialogueSegments(combined)[0] || ''
+                : '';
+    const audio = extractStoryboardField(combined, ['Audio/SFX', 'Audio/Foley', 'Foley/SFX', 'Audio', 'SFX', 'FX', 'Foley', 'Sound', 'Sounds']);
+    const audioSfx = normalizeStoryboardAudioSfx(audio);
+    const metadataLabels = normalizeStoryboardContractTextArray(planningContract?.metadataLabels);
+    const hasTypedVisibleText = Array.isArray(planningContract?.visibleText);
+    const visibleText = hasTypedVisibleText
+        ? normalizeStoryboardContractTextArray(planningContract?.visibleText)
+        : sceneTextRequirementsFromSection(combined);
+    const referenceUsage = Array.isArray(planningContract?.referenceUsage)
+        ? uniqueStoryboardStrings(planningContract.referenceUsage)
+        : sceneReferencesFromSection(combined, references);
+    return {
+        id: `scene_${String(section.number).padStart(2, '0')}`,
+        title,
+        startSec: timing?.startSec ?? null,
+        endSec: timing?.endSec ?? null,
+        durationSec: timing?.durationSec ?? null,
+        purpose: extractStoryboardField(combined, ['Purpose', 'Story purpose', 'Narrative purpose', 'Beat purpose', 'Scene purpose', 'Why this beat exists']),
+        productFeature: extractStoryboardField(combined, ['Product/Feature', 'Product feature', 'Feature mapping', 'Product meaning', 'Product idea', 'Feature', 'Capability']),
+        visual: extractStoryboardField(combined, ['Visual/Action', 'Visual Frame', 'Visual', 'Frame', 'Image', 'Shot']) || compactStoryboardLine(section.body.slice(0, 240)),
+        action: extractStoryboardField(combined, ['Action/Motion', 'Action', 'Motion', 'Performance', 'Beat']),
+        camera: extractStoryboardField(combined, ['Camera/Motion', 'Camera', 'Framing', 'Shot type']),
+        lighting: extractStoryboardField(combined, ['Lighting/Style', 'Lighting', 'Style', 'Look']),
+        transitionIn: extractStoryboardField(combined, ['Transition in', 'Transition-in', 'In']),
+        transitionOut: extractStoryboardField(combined, ['Transition', 'Transition out', 'Transition-out', 'Edit']),
+        dialogue,
+        audioSfx,
+        music: sanitizeStoryboardExternalAudioReferences(extractStoryboardField(combined, ['Music', 'Score', 'Underscore'])),
+        referenceUsage,
+        textInImage: removeStoryboardMetadataLabelsFromVisibleText(visibleText, metadataLabels),
+        metadataLabels,
+        mustAvoid: extractStoryboardAvoidConstraints(combined),
+    };
+}
+function applyStoryboardScenePlanningContract(scene, planningContract) {
+    if (!planningContract)
+        return scene;
+    const metadataLabels = normalizeStoryboardContractTextArray(planningContract.metadataLabels);
+    const hasTypedVisibleText = Array.isArray(planningContract.visibleText);
+    const visibleText = hasTypedVisibleText
+        ? normalizeStoryboardContractTextArray(planningContract.visibleText)
+        : scene.textInImage;
+    const referenceUsage = Array.isArray(planningContract.referenceUsage)
+        ? uniqueStoryboardStrings(planningContract.referenceUsage)
+        : scene.referenceUsage;
+    return {
+        ...scene,
+        referenceUsage,
+        textInImage: removeStoryboardMetadataLabelsFromVisibleText(visibleText, metadataLabels),
+        metadataLabels,
+    };
+}
+function buildFallbackScenes(frameCount, durationSec, sourceText) {
+    const sceneDuration = durationSec && frameCount > 0
+        ? Math.round((durationSec / frameCount) * 100) / 100
+        : null;
+    return Array.from({ length: frameCount }, (_, index) => {
+        const startSec = sceneDuration !== null ? Math.round(index * sceneDuration * 100) / 100 : null;
+        const endSec = sceneDuration !== null
+            ? index === frameCount - 1 && durationSec !== null
+                ? durationSec
+                : Math.round(((index + 1) * sceneDuration) * 100) / 100
+            : null;
+        return {
+            id: `scene_${String(index + 1).padStart(2, '0')}`,
+            title: `Frame ${String(index + 1).padStart(2, '0')}`,
+            startSec,
+            endSec,
+            durationSec: startSec !== null && endSec !== null ? Math.round((endSec - startSec) * 100) / 100 : null,
+            purpose: index === 0
+                ? 'Establish the hook and the first clear story beat from the source brief.'
+                : 'Advance the same story spine with a distinct sequential beat.',
+            productFeature: '',
+            visual: index === 0 ? compactStoryboardLine(sourceText.slice(0, 260)) : 'Follow the approved source brief for this sequential storyboard beat.',
+            action: '',
+            camera: '',
+            lighting: '',
+            transitionIn: '',
+            transitionOut: '',
+            dialogue: '',
+            audioSfx: [],
+            music: '',
+            referenceUsage: [],
+            textInImage: [],
+            metadataLabels: [],
+            mustAvoid: [],
+        };
+    });
+}
+function normalizeAssistantStoryboardSceneTiming(scenes, targetDurationSec, promptAuthorship) {
+    if (promptAuthorship !== 'assistant' || targetDurationSec === null || scenes.length === 0) {
+        return scenes;
+    }
+    const timedScenes = scenes.filter(scene => scene.startSec !== null
+        && scene.endSec !== null
+        && scene.durationSec !== null
+        && scene.endSec > scene.startSec
+        && scene.durationSec > 0);
+    if (timedScenes.length !== scenes.length)
+        return scenes;
+    const totalSceneDurationSec = Math.round(scenes.reduce((sum, scene) => sum + (scene.durationSec ?? 0), 0) * 100) / 100;
+    if (totalSceneDurationSec <= 0)
+        return scenes;
+    const diff = Math.abs(totalSceneDurationSec - targetDurationSec);
+    if (diff <= DEFAULT_STORYBOARD_TIMING_RULES.toleranceSec)
+        return scenes;
+    const scale = targetDurationSec / totalSceneDurationSec;
+    const timelineStartSec = scenes[0].startSec ?? 0;
+    const timelineEndSec = Math.round((timelineStartSec + targetDurationSec) * 100) / 100;
+    let cursor = timelineStartSec;
+    return scenes.map((scene, index) => {
+        const isLast = index === scenes.length - 1;
+        const startLimit = isLast ? timelineEndSec - 0.01 : cursor;
+        const startSec = Math.round(Math.min(cursor, startLimit) * 100) / 100;
+        const endSec = isLast
+            ? timelineEndSec
+            : Math.round((startSec + Math.max(0.01, (scene.durationSec ?? 0) * scale)) * 100) / 100;
+        const durationSec = Math.round((endSec - startSec) * 100) / 100;
+        cursor = endSec;
+        return {
+            ...scene,
+            startSec,
+            endSec,
+            durationSec,
+        };
+    });
+}
+function normalizeStoryboardDialogueToken(value) {
+    return value
+        .toLowerCase()
+        .replace(/[‘’]/g, "'")
+        .replace(/^'+|'+$/g, '');
+}
+function storyboardDialogueWordSpans(text) {
+    const spans = [];
+    const pattern = /[\p{L}\p{N}]+(?:[’'][\p{L}\p{N}]+)?/gu;
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+        spans.push({
+            token: normalizeStoryboardDialogueToken(match[0]),
+            start: match.index,
+            end: match.index + match[0].length,
+        });
+    }
+    return spans;
+}
+function storyboardDialogueCoverage(sourceDialogue, currentDialogue) {
+    const sourceTokens = storyboardDialogueWordSpans(sourceDialogue).map(span => span.token);
+    const currentTokens = storyboardDialogueWordSpans(currentDialogue).map(span => span.token);
+    if (sourceTokens.length === 0)
+        return 1;
+    if (currentTokens.length === 0)
+        return 0;
+    let cursor = 0;
+    let matched = 0;
+    for (const token of sourceTokens) {
+        const foundIndex = currentTokens.indexOf(token, cursor);
+        if (foundIndex < 0)
+            continue;
+        matched += 1;
+        cursor = foundIndex + 1;
+    }
+    return matched / sourceTokens.length;
+}
+function sourceQuotedStoryboardDialogueSegments(userIntentText) {
+    const text = normalizeScreenplayDialogueQuotes(userIntentText.replace(/[“”]/g, '"')) || '';
+    const segments = [];
+    const pattern = /"([^"]{1,800})"/g;
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+        const index = match.index;
+        const before = text.slice(Math.max(0, index - 180), index);
+        const after = text.slice(pattern.lastIndex, Math.min(text.length, pattern.lastIndex + 120));
+        const context = `${before} ${after}`;
+        const lineStart = text.lastIndexOf('\n', Math.max(0, index - 1)) + 1;
+        const nextLineBreak = text.indexOf('\n', pattern.lastIndex);
+        const lineEnd = nextLineBreak >= 0 ? nextLineBreak : text.length;
+        const lineContext = text.slice(lineStart, lineEnd);
+        const speechContext = /\b(?:dialogue|vo|v\.o\.|voiceover|voice-over|speech|spoken|monologue|narration|line|lines|say|says|said|speak|speaks|speaking|script)\b/i.test(context);
+        const lineSpeechContext = /\b(?:dialogue|vo|v\.o\.|voiceover|voice-over|speech|spoken|monologue|narration|say|says|said|speak|speaks|speaking)\b/i.test(lineContext);
+        const lineVisibleTextOnly = /\b(?:visible|on[-\s]?screen|onscreen|text|copy|cta|tagline|headline|title\s+card|logo|wordmark|spell(?:ed)?|read(?:s)?|end\s+card|slogan)\b/i.test(lineContext)
+            && !lineSpeechContext;
+        const lineNonVoiceMetadata = /\b(?:working\s+title|title|format|duration|aspect(?:\s+ratio)?|reference\s+assets?)\s*:/i.test(lineContext)
+            && !lineSpeechContext;
+        const value = compactStoryboardLine(match[1]);
+        if (value && speechContext && !lineVisibleTextOnly && !lineNonVoiceMetadata)
+            segments.push(value);
+    }
+    return segments;
+}
+function findStoryboardDialogueStartIndex(sourceSpans, dialogue, cursor) {
+    const dialogueTokens = storyboardDialogueWordSpans(dialogue).map(span => span.token);
+    if (dialogueTokens.length === 0)
+        return null;
+    const maxNeedleLength = Math.min(3, dialogueTokens.length);
+    for (let needleLength = maxNeedleLength; needleLength >= 1; needleLength -= 1) {
+        const needle = dialogueTokens.slice(0, needleLength);
+        for (let index = cursor; index <= sourceSpans.length - needleLength; index += 1) {
+            const matches = needle.every((token, offset) => sourceSpans[index + offset]?.token === token);
+            if (matches)
+                return index;
+        }
+    }
+    return null;
+}
+function sourceDialogueSliceForWordRange(sourceDialogue, sourceSpans, startIndex, endExclusive) {
+    const start = sourceSpans[startIndex]?.start ?? 0;
+    const lastSpan = sourceSpans[Math.max(startIndex, endExclusive - 1)];
+    if (!lastSpan)
+        return '';
+    const nextStart = sourceSpans[endExclusive]?.start ?? sourceDialogue.length;
+    const trailing = sourceDialogue.slice(lastSpan.end, nextStart).match(/^[\s.,!?;:…'"’”)}\]-]*/)?.[0] ?? '';
+    return sourceDialogue.slice(start, lastSpan.end + trailing.length).trim();
+}
+function matchSourceDialogueSceneStarts(scenes, sourceSpans) {
+    const dialogueScenes = scenes
+        .map((scene, index) => ({ scene, index }))
+        .filter(({ scene }) => scene.dialogue.trim().length > 0);
+    if (sourceSpans.length === 0 || dialogueScenes.length === 0)
+        return null;
+    const matches = [];
+    let cursor = 0;
+    for (const { scene, index } of dialogueScenes) {
+        const start = findStoryboardDialogueStartIndex(sourceSpans, scene.dialogue, cursor);
+        if (start === null)
+            return null;
+        matches.push({ sceneIndex: index, startIndex: start });
+        cursor = start + 1;
+    }
+    return matches;
+}
+function redistributeSourceDialogueAcrossMatchedScenes(scenes, sourceDialogue, matches) {
+    const sourceSpans = storyboardDialogueWordSpans(sourceDialogue);
+    if (sourceSpans.length === 0 || matches.length === 0)
+        return null;
+    const repaired = scenes.slice();
+    for (let index = 0; index < matches.length; index += 1) {
+        const sceneIndex = matches[index].sceneIndex;
+        const start = matches[index].startIndex;
+        const end = matches[index + 1]?.startIndex ?? sourceSpans.length;
+        if (end <= start)
+            return null;
+        const dialogue = sourceDialogueSliceForWordRange(sourceDialogue, sourceSpans, start, end);
+        if (!dialogue)
+            return null;
+        repaired[sceneIndex] = {
+            ...repaired[sceneIndex],
+            dialogue,
+        };
+    }
+    return repaired;
+}
+function alignAssistantStoryboardDialogueWithUserSource(scenes, userIntentText, promptAuthorship) {
+    if (promptAuthorship !== 'assistant')
+        return { scenes, shouldRetime: false };
+    const sourceDialogue = sourceQuotedStoryboardDialogueSegments(userIntentText).join(' ');
+    if (!sourceDialogue)
+        return { scenes, shouldRetime: false };
+    const sourceSpans = storyboardDialogueWordSpans(sourceDialogue);
+    const matches = matchSourceDialogueSceneStarts(scenes, sourceSpans);
+    if (!matches)
+        return { scenes, shouldRetime: false };
+    const currentDialogue = scenes.map(scene => scene.dialogue).filter(Boolean).join(' ');
+    if (storyboardDialogueCoverage(sourceDialogue, currentDialogue) >= 1) {
+        return { scenes, shouldRetime: true };
+    }
+    const repaired = redistributeSourceDialogueAcrossMatchedScenes(scenes, sourceDialogue, matches);
+    if (!repaired)
+        return { scenes, shouldRetime: false };
+    return { scenes: repaired, shouldRetime: true };
+}
+function minimumStoryboardSceneDurationForDialogue(scene, rules) {
+    const dialogueWords = countWords(scene.dialogue);
+    let minDuration = dialogueWords > 0
+        ? dialogueWords / rules.normalWordsPerSecondMax
+        : 0.5;
+    const sceneContext = `${scene.title}\n${scene.visual}\n${scene.textInImage.join(' ')}`;
+    const hasReadableText = scene.textInImage.length > 0;
+    const isEndCard = /\b(?:end card|outro|cta|final|logo|brand resolve)\b/i.test(sceneContext);
+    if (isEndCard) {
+        minDuration = Math.max(minDuration, rules.minEndCardHoldSec);
+    }
+    else if (hasReadableText) {
+        minDuration = Math.max(minDuration, 1.2);
+    }
+    return Math.round(minDuration * 100) / 100;
+}
+function retimeStoryboardScenesForDialogue(scenes, targetDurationSec, rules = DEFAULT_STORYBOARD_TIMING_RULES) {
+    if (targetDurationSec === null || scenes.length === 0)
+        return scenes;
+    if (!scenes.every(scene => scene.startSec !== null && scene.endSec !== null && scene.durationSec !== null && scene.durationSec > 0)) {
+        return scenes;
+    }
+    const minimumDurations = scenes.map(scene => minimumStoryboardSceneDurationForDialogue(scene, rules));
+    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;
+    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 timelineStartSec = scenes[0].startSec ?? 0;
+    const timelineEndSec = Math.round((timelineStartSec + targetDurationSec) * 100) / 100;
+    let cursor = timelineStartSec;
+    return scenes.map((scene, index) => {
+        const isLast = index === scenes.length - 1;
+        const startSec = Math.round(cursor * 100) / 100;
+        const endSec = isLast
+            ? timelineEndSec
+            : Math.round((startSec + unroundedDurations[index]) * 100) / 100;
+        const durationSec = Math.round((endSec - startSec) * 100) / 100;
+        cursor = endSec;
+        return {
+            ...scene,
+            startSec,
+            endSec,
+            durationSec,
+        };
+    });
+}
+function quotedStoryboardVoiceLinesFromText(text) {
+    const lines = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = compactStoryboardLine(stripStoryboardMarkup(rawLine));
+        if (!line || !/"[^"]{1,800}"/.test(line))
+            continue;
+        const fieldLabel = line.match(/^\s*(?:[-*+]\s*)?(?:[*_]{1,3})?\s*([^:\n]{1,60})\s*:/)?.[1] ?? '';
+        const isExplicitVoiceField = /\b(?:dialogue|vo|v\.o\.|voiceover|voice-over|speech|narration|spoken)\b/i.test(fieldLabel);
+        const isNonVoiceProductionField = /\b(?:audio|sfx|fx|foley|sound|music|action|motion|transition|camera|lighting|style|visual|visible|text|copy|cta|tagline|headline|title\s+card|caption|subtitle|super)\b/i.test(fieldLabel)
+            && !isExplicitVoiceField;
+        const hasSpeechVerb = /\b(?:says?|speaks?|speaking|asks?|replies?|responds?|whispers?|shouts?|yells?|sings?|narrates?|voiceover|voice-over)\b/i.test(line);
+        if (isNonVoiceProductionField && !hasSpeechVerb)
+            continue;
+        if (!isExplicitVoiceField && !hasSpeechVerb)
+            continue;
+        lines.push(...extractQuotedDialogueSegments(line).map(item => compactStoryboardLine(item)).filter(Boolean));
+    }
+    return lines;
+}
+function assignVoiceLinesToScenes(scenes, sourceText) {
+    const sceneLines = scenes.flatMap(scene => {
+        const dialogue = scene.dialogue.trim();
+        if (!dialogue)
+            return [];
+        const quoted = extractQuotedDialogueSegments(dialogue);
+        const lines = quoted.length > 0 ? quoted : [dialogue];
+        return lines.map((text) => ({
+            text,
+            sceneId: scene.id,
+            startSec: scene.startSec,
+            endSec: scene.endSec,
+            delivery: '',
+            priority: 'required',
+        }));
+    });
+    if (sceneLines.length > 0)
+        return sceneLines;
+    const quoted = quotedStoryboardVoiceLinesFromText(sourceText);
+    return quoted.map((text, index) => {
+        const scene = scenes[Math.min(index, Math.max(0, scenes.length - 1))];
+        return {
+            text,
+            sceneId: scene?.id ?? 'scene_01',
+            startSec: scene?.startSec ?? null,
+            endSec: scene?.endSec ?? null,
+            delivery: '',
+            priority: 'required',
+        };
+    });
+}
+function inferStoryboardToneProgression(text) {
+    const progression = text.match(/\b(?:tone progression|progression|arc)\s*:\s*([^\n]{1,240})/i)?.[1];
+    if (!progression)
+        return [];
+    return progression.split(/\s*(?:->|,|;|\|)\s*/).map(item => item.trim()).filter(Boolean);
+}
+function cleanStoryboardStorySpine(value) {
+    const cleaned = sanitizeStoryboardExternalAudioReferences(compactStoryboardLine(stripStoryboardMarkup(value)))
+        .replace(/^[:*_\-\s]+|[:*_\-\s]+$/g, '')
+        .trim();
+    if (!cleaned || /^[*_\-:.\s]+$/.test(cleaned))
+        return '';
+    return cleaned;
+}
+function inferStoryboardStorySpineFromHeading(text) {
+    const lines = stripStoryboardMarkup(text)
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(Boolean);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const inline = line.match(/^(?:story\s+spine|narrative\s+spine|throughline|story\s+arc|creative\s+intent)\s*:\s*(.+)$/i)?.[1];
+        const cleanedInline = cleanStoryboardStorySpine(inline || '');
+        if (cleanedInline)
+            return cleanedInline;
+        if (!/^(?:story\s+spine|narrative\s+spine|throughline|story\s+arc|creative\s+intent)\s*:?\s*$/i.test(line)) {
+            continue;
+        }
+        const collected = [];
+        for (let cursor = index + 1; cursor < lines.length && collected.length < 4; cursor += 1) {
+            const candidate = lines[cursor];
+            if (/^(?:storyboard|video|production|reference|timecoded|beat\s+\d|scene\s+\d|format|duration|aspect|does this|please confirm)\b/i.test(candidate)) {
+                break;
+            }
+            const cleaned = cleanStoryboardStorySpine(candidate);
+            if (cleaned)
+                collected.push(cleaned);
+        }
+        const combined = cleanStoryboardStorySpine(collected.join(' '));
+        if (combined)
+            return combined;
+    }
+    return '';
+}
+function inferStoryboardStorySpine(text, fallbackBrief) {
+    const explicit = cleanStoryboardStorySpine(text.match(/\b(?:story\s+spine|narrative\s+spine|throughline|story\s+arc|creative\s+intent)\s*:\s*([^\n]{1,360})/i)?.[1] || '');
+    if (explicit)
+        return explicit;
+    const fromHeading = inferStoryboardStorySpineFromHeading(text);
+    if (fromHeading)
+        return fromHeading;
+    const compactFallback = sanitizeStoryboardExternalAudioReferences(compactStoryboardLine(fallbackBrief || text));
+    if (compactFallback) {
+        return `One continuous progression from the source brief: ${compactFallback.slice(0, 260)}`;
+    }
+    return 'A coherent sequence where every scene follows from the previous beat and supports the requested final video outcome.';
+}
+function inferStoryboardProductFeatureMap(text, scenes) {
+    const explicitLines = text
+        .split(/\r?\n/)
+        .map(line => compactStoryboardLine(stripStoryboardMarkup(line)))
+        .filter(line => /\b(?:product\/feature|product feature|feature mapping|product meaning|capability)\b\s*:/i.test(line))
+        .map(line => line.replace(/^[^:]{1,80}:\s*/, '').trim())
+        .filter(Boolean);
+    const sceneFeatures = scenes
+        .map(scene => scene.productFeature)
+        .filter(Boolean);
+    return [...new Set([...explicitLines, ...sceneFeatures])];
+}
+function inferEndCard(projectText, references, requiredText) {
+    const logo = references.find(ref => ref.kind === 'logo');
+    const endBlock = projectText.match(/\b(?:end card|cta|final card|brand resolve|logo reveal)\b[\s\S]{0,420}/i)?.[0] ?? '';
+    return {
+        requiredText,
+        logoUsage: logo
+            ? `${logo.id} should be used according to its ${logo.usageScope} usage scope.`
+            : 'Use any approved logo or brand reference only where the source brief assigns it.',
+        backgroundStyle: extractStoryboardField(endBlock, ['Background', 'Background style', 'Visual', 'Style']),
+        composition: extractStoryboardField(endBlock, ['Composition', 'Layout', 'Camera']) || compactStoryboardLine(endBlock.slice(0, 180)),
+    };
+}
+export function buildStoryboardProject(options) {
+    const prompt = options.prompt.trim();
+    const rawUserIntentText = options.userIntentText.trim();
+    const userIntentText = canonicalStoryboardScriptContext(rawUserIntentText) || rawUserIntentText;
+    const approvedScriptContext = canonicalStoryboardScriptContext(options.approvedScriptContext);
+    const primarySourceBrief = selectStoryboardSourceBrief(prompt, userIntentText);
+    const sourceText = sanitizeStoryboardExternalAudioReferences([
+        primarySourceBrief,
+        approvedScriptContext
+            ? `APPROVED STORYBOARD SCRIPT CONTEXT TO PRESERVE:\n${approvedScriptContext}`
+            : '',
+    ].filter(Boolean).join('\n\n'));
+    const allText = `${userIntentText}\n${sourceText}`;
+    const layoutTextParts = [userIntentText].filter(Boolean);
+    if (primarySourceBrief
+        && !storyboardBriefContains(userIntentText, primarySourceBrief)
+        && !storyboardBriefContains(primarySourceBrief, userIntentText)) {
+        layoutTextParts.push(primarySourceBrief);
+    }
+    if (approvedScriptContext
+        && !storyboardBriefContains(layoutTextParts.join('\n'), approvedScriptContext)) {
+        layoutTextParts.push(approvedScriptContext);
+    }
+    const layoutText = layoutTextParts.join('\n\n') || sourceText;
+    const layout = inferStoryboardLayoutSpec(layoutText, options.frameCount, options.planningContract);
+    const requestedDurationSec = inferRequestedTotalVideoDurationSeconds(userIntentText);
+    const durationSec = requestedDurationSec ?? inferRequestedTotalVideoDurationSeconds(sourceText);
+    const references = buildStoryboardReferenceAssets(userIntentText, [
+        prompt,
+        approvedScriptContext,
+    ].filter(Boolean).join('\n\n'));
+    const approvedSections = approvedScriptContext
+        ? splitStoryboardSections(approvedScriptContext)
+        : [];
+    const sourceSections = splitStoryboardSections(sourceText);
+    const approvedSectionsHaveExplicitTiming = storyboardSectionsHavePreservableExplicitTiming(approvedSections);
+    const sourceSectionsHaveExplicitTiming = storyboardSectionsHavePreservableExplicitTiming(sourceSections);
+    const assistantApprovedDraftUndercounted = options.promptAuthorship === 'assistant'
+        && approvedSections.length > 0
+        && approvedSections.length < options.frameCount
+        && !approvedSectionsHaveExplicitTiming;
+    const assistantDraftUndercounted = options.promptAuthorship === 'assistant'
+        && !approvedScriptContext
+        && sourceSections.length > 0
+        && sourceSections.length < options.frameCount
+        && !sourceSectionsHaveExplicitTiming;
+    const sections = approvedSections.length > 0 && !assistantApprovedDraftUndercounted
+        ? approvedSections
+        : assistantDraftUndercounted || assistantApprovedDraftUndercounted
+            ? []
+            : sourceSections;
+    const sceneCountForTiming = sections.length > 0 ? sections.length : options.frameCount;
+    const equalDuration = durationSec && sceneCountForTiming > 0
+        ? Math.round((durationSec / sceneCountForTiming) * 100) / 100
+        : null;
+    const scenes = sections.length > 0
+        ? sections.map((section, index) => {
+            const fallbackTiming = equalDuration !== null
+                ? {
+                    startSec: Math.round(index * equalDuration * 100) / 100,
+                    endSec: index === sceneCountForTiming - 1 && durationSec !== null
+                        ? durationSec
+                        : Math.round((index + 1) * equalDuration * 100) / 100,
+                    durationSec: index === sceneCountForTiming - 1 && durationSec !== null
+                        ? Math.round((durationSec - index * equalDuration) * 100) / 100
+                        : equalDuration,
+                }
+                : null;
+            return buildSceneFromSection(section, references, fallbackTiming, storyboardScenePlanningContractForIndex(options.planningContract, section.number));
+        })
+        : buildFallbackScenes(options.frameCount, durationSec, sourceText)
+            .map((scene, index) => applyStoryboardScenePlanningContract(scene, storyboardScenePlanningContractForIndex(options.planningContract, index + 1)));
+    const timingNormalizedScenes = normalizeAssistantStoryboardSceneTiming(scenes, durationSec, options.promptAuthorship);
+    const dialogueAlignment = alignAssistantStoryboardDialogueWithUserSource(timingNormalizedScenes, userIntentText, options.promptAuthorship);
+    const normalizedScenes = dialogueAlignment.shouldRetime
+        ? retimeStoryboardScenesForDialogue(dialogueAlignment.scenes, durationSec)
+        : dialogueAlignment.scenes;
+    const userConstraintSource = buildStoryboardUserConstraintSource(userIntentText, primarySourceBrief, options);
+    const requiredText = uniqueStoryboardStrings([
+        ...extractStoryboardRequiredText(userConstraintSource),
+        ...normalizeStoryboardContractTextArray(options.planningContract?.endCard?.visibleText),
+    ]);
+    const voiceLines = assignVoiceLinesToScenes(normalizedScenes, sourceText);
+    const storySpineFallback = approvedScriptContext
+        || (options.promptAuthorship === 'assistant' ? userIntentText : primarySourceBrief)
+        || prompt
+        || userIntentText;
+    const storySpine = inferStoryboardStorySpine(allText, storySpineFallback);
+    const productFeatureMap = inferStoryboardProductFeatureMap(allText, scenes);
+    return {
+        title: inferStoryboardTitle(allText),
+        durationSec,
+        outputAspectRatio: layout.boardAspectRatio,
+        frameAspectRatio: layout.cellAspectRatio,
+        targetVideoAspectRatio: layout.targetVideoAspectRatio,
+        ...(layout.boardDimensions ? { boardDimensions: layout.boardDimensions } : {}),
+        boardLayout: layout.layoutKind,
+        layoutSource: storyboardPlanningSourceFromContract(options.planningContract),
+        ...(options.planningContract ? { planningContract: options.planningContract } : {}),
+        metadataLabels: metadataLabelsFromPlanningContract(options.planningContract),
+        intendedUse: /commercial|ad|promo|launch/i.test(allText) ? 'commercial storyboard' : 'video storyboard',
+        references,
+        creativeBrief: {
+            concept: compactStoryboardLine(primarySourceBrief || prompt || userIntentText),
+            storySpine,
+            toneProgression: inferStoryboardToneProgression(allText),
+            productFeatureMap,
+            mustInclude: requiredText,
+            mustAvoid: extractStoryboardAvoidConstraints(userConstraintSource),
+            brandRules: requiredText.length > 0 ? requiredText.map(text => `Preserve exact visible text: "${text}"`) : [],
+            visualQualityBar: /production[-\s]?ready|premium|commercial|cinematic|high[-\s]?end/i.test(allText)
+                ? 'production-ready commercial storyboard sheet'
+                : 'clean readable storyboard sheet',
+        },
+        voiceover: {
+            fullScript: voiceLines.map(line => line.text).join('\n'),
+            lines: voiceLines,
+        },
+        scenes: normalizedScenes,
+        endCard: inferEndCard(allText, references, requiredText),
+    };
+}
+export function validateStoryboardProjectTiming(project, rules = DEFAULT_STORYBOARD_TIMING_RULES) {
+    const issues = [];
+    const timedScenes = project.scenes
+        .filter(scene => scene.startSec !== null && scene.endSec !== null && scene.durationSec !== null)
+        .slice()
+        .sort((a, b) => (a.startSec ?? 0) - (b.startSec ?? 0));
+    if (project.durationSec === null) {
+        issues.push({
+            severity: 'warning',
+            code: 'missing_target_duration',
+            message: 'No target video duration was detected; timing checks are limited to scene-local ranges.',
+            repair: 'Add an explicit total duration such as 15 seconds when this storyboard is meant to drive a video.',
+        });
+    }
+    if (timedScenes.length < project.scenes.length) {
+        issues.push({
+            severity: 'warning',
+            code: 'missing_scene_timing',
+            message: `${project.scenes.length - timedScenes.length} scene(s) do not have explicit start/end/duration timing.`,
+            repair: 'Add start and end seconds for every storyboard scene before video generation.',
+        });
+    }
+    for (const scene of timedScenes) {
+        const start = scene.startSec ?? 0;
+        const end = scene.endSec ?? 0;
+        const duration = scene.durationSec ?? 0;
+        if (end <= start || duration <= 0) {
+            issues.push({
+                severity: 'error',
+                code: 'invalid_scene_range',
+                sceneId: scene.id,
+                message: `${scene.id} has an invalid timing range.`,
+                repair: 'Set startSec < endSec and durationSec to the range length.',
+            });
+            continue;
+        }
+        const dialogueWords = countWords(scene.dialogue);
+        if (dialogueWords > 0) {
+            const wordsPerSecond = dialogueWords / duration;
+            if (wordsPerSecond > rules.fastWordsPerSecondMax) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'dialogue_too_dense',
+                    sceneId: scene.id,
+                    message: `${scene.id} has about ${dialogueWords} spoken words in ${duration}s (${wordsPerSecond.toFixed(1)} words/sec).`,
+                    repair: 'Increase this scene duration, reallocate time from non-dialogue beats, or split the dialogue across adjacent scenes before changing any supplied words.',
+                });
+            }
+            else if (wordsPerSecond > rules.normalWordsPerSecondMax) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'dialogue_fast',
+                    sceneId: scene.id,
+                    message: `${scene.id} dialogue is fast at ${wordsPerSecond.toFixed(1)} words/sec.`,
+                    repair: 'Prefer more time or a split across adjacent scenes for cleaner delivery; only shorten dialogue that was not supplied by the user.',
+                });
+            }
+        }
+        const isPunchline = dialogueWords > 0
+            && dialogueWords <= 3
+            && /\b(?:punchline|reveal|joke|twist|tag)\b/i.test(`${scene.title}\n${scene.dialogue}`);
+        if (isPunchline && duration < rules.minPunchlineSec) {
+            issues.push({
+                severity: 'warning',
+                code: 'punchline_hold_too_short',
+                sceneId: scene.id,
+                message: `${scene.id} punchline/reveal hold is only ${duration}s.`,
+                repair: `Hold punchline/reveal scenes for at least ${rules.minPunchlineSec}s.`,
+            });
+        }
+        const isEndCard = /\b(?:end card|cta|final|logo|brand resolve)\b/i.test(`${scene.title}\n${scene.visual}`);
+        if (isEndCard && duration < rules.minEndCardHoldSec) {
+            issues.push({
+                severity: 'warning',
+                code: 'end_card_hold_too_short',
+                sceneId: scene.id,
+                message: `${scene.id} end-card hold is only ${duration}s.`,
+                repair: `Hold the CTA/end card for at least ${rules.minEndCardHoldSec}s when the user requested brand text or logo readability.`,
+            });
+        }
+    }
+    for (let index = 1; index < timedScenes.length; index += 1) {
+        const previous = timedScenes[index - 1];
+        const current = timedScenes[index];
+        const previousEnd = previous.endSec ?? 0;
+        const currentStart = current.startSec ?? 0;
+        const delta = Math.round((currentStart - previousEnd) * 100) / 100;
+        if (delta < -rules.toleranceSec) {
+            issues.push({
+                severity: 'error',
+                code: 'overlapping_scene_ranges',
+                sceneId: current.id,
+                message: `${current.id} overlaps the previous scene by ${Math.abs(delta).toFixed(2)}s.`,
+                repair: 'Adjust scene start/end ranges so they do not overlap.',
+            });
+        }
+        else if (delta > rules.toleranceSec) {
+            issues.push({
+                severity: 'warning',
+                code: 'scene_timing_gap',
+                sceneId: current.id,
+                message: `${current.id} starts ${delta.toFixed(2)}s after the previous scene ends.`,
+                repair: 'Remove unintentional gaps or mark them as intentional holds.',
+            });
+        }
+    }
+    const totalSceneDurationSec = timedScenes.length > 0
+        ? Math.round(timedScenes.reduce((sum, scene) => sum + (scene.durationSec ?? 0), 0) * 100) / 100
+        : null;
+    if (project.durationSec !== null && totalSceneDurationSec !== null) {
+        const diff = Math.abs(totalSceneDurationSec - project.durationSec);
+        if (diff > rules.toleranceSec) {
+            issues.push({
+                severity: 'error',
+                code: 'scene_total_duration_mismatch',
+                message: `Timed scenes add up to ${totalSceneDurationSec}s but the target duration is ${project.durationSec}s.`,
+                repair: 'Repair scene durations so their total matches the requested video duration.',
+            });
+        }
+    }
+    return {
+        ok: issues.every(issue => issue.severity !== 'error'),
+        issues,
+        totalSceneDurationSec,
+        timedSceneCount: timedScenes.length,
+    };
+}
+function compileStoryboardCriticalRequirements() {
+    return [
+        'This must read as production logic, not a concept collage or mood board. Every panel needs a narrative job and a clear reason to exist in sequence.',
+        'Preserve user-provided jokes, slogans, dialogue, brand copy, timings, and scene order unless the source brief explicitly asks for a rewrite.',
+        'Preserve the story spine across the full board. Each scene should visibly cause, motivate, reveal, or set up the next scene.',
+        'When a product, feature, brand, capability, or CTA is part of the brief, keep its scene-level purpose legible in the non-frame notes without inventing unsupported product claims.',
+        'Use explicit transition logic between adjacent beats: object motion, light/color handoff, match cut, camera move, wipe, reaction, or another concrete edit idea.',
+        'Use shaped pacing when timings are flexible: fast hook, escalating middle, readable reveal, and a final CTA/end card held long enough for critical text/logo recognition.',
+        'Divide each scene cell into a clean video-frame artwork area plus a clearly associated note/header/footer area. Put Time, scene/frame numbers, Visual/Action, Camera/Motion, Lighting/Style, Dialogue/VO, and Audio/SFX outside the video frame artwork, never overlaid on top of the cinematic frame.',
+        'Every cinematic video-frame artwork area must preserve the requested Individual scene-cell/frame aspect ratio. Keep all frame artwork areas locked to the same W:H unless the source explicitly requests mixed ratios; do not make individual stills square or let one or two cells drift to a different crop.',
+        'Use concise readable storyboard labels in the non-frame note areas. Do not place long paragraphs of production notes inside every cell.',
+        'Every scene cell must include compact fields for Time, Visual/Action, Camera/Motion, Lighting/Style, Dialogue/VO, and Audio/SFX, attached to the correct frame but outside the video-frame artwork.',
+        'When a scene has no spoken dialogue or voiceover, write exactly [no dialogue] in the Dialogue/VO field; never use "-", None, N/A, or a blank field.',
+        'Keep generated SFX/action words such as whoosh, boom, impact, thud, slash, crack, pop, and similar motion callouts in Visual/Action or Audio/SFX note areas only. Do not render them inside the video-frame artwork unless the source explicitly requires that exact word as visible on-screen text.',
+        'When audio is not explicitly supplied, propose scene-appropriate generated audio, ambience, music bed, and foley/SFX generically. Do not label a scene silent, muted, or "no audio" unless the source brief explicitly requests silence.',
+        'Do not reference unattached songs, trending tracks, stock sound libraries, or external media. Treat Audio/SFX/Music notes as instructions for the downstream video model to generate the sound unless an audio reference asset is explicitly listed.',
+        'Give the audio direction an arc when the final asset is video: build, peak, resolve, transition accents, and final logo/CTA hit.',
+        'Keep character, product, logo, and style references bound to their assigned scenes. Do not replace referenced assets with invented substitutes.',
+    ];
+}
+function compileStoryboardAvoidSection(userIntentText) {
+    const avoidLines = [
+        'Avoid malformed text, misspelled brand words, inconsistent reference identities, missing scene cells, wrong timings, and mismatched board/cell aspect ratios.',
+        'Avoid scene numbers, timing badges, timecodes, production tables, Dialogue/VO labels, Audio/SFX labels, or other production notes overlaid inside the video frame artwork.',
+        'Avoid in-frame comic-book SFX/action text such as Whoosh!, Impact!, Boom!, Thud!, Slash!, Crack!, or Pop! unless the source explicitly marks that word as required visible text.',
+    ];
+    for (const constraint of extractStoryboardAvoidConstraints(userIntentText)) {
+        avoidLines.push(`Preserve this user avoid-list constraint: ${constraint}`);
+    }
+    return avoidLines;
+}
+function formatStoryboardSeconds(value) {
+    return value === null ? 'unspecified' : `${Number(value.toFixed(2))}s`;
+}
+function defaultStoryboardAudioSfxLine() {
+    return 'Scene-appropriate generated audio bed, ambience, and foley/SFX matching the action; do not mark silent/no audio unless the source brief explicitly requests silence.';
+}
+function compileStoryboardStoryContinuitySection(project) {
+    return [
+        'STORY / CONTINUITY:',
+        `Story spine: ${project.creativeBrief.storySpine}`,
+        'Every panel must feel like the next beat in one continuous sequence, not an unrelated feature card, contact sheet, or mood board.',
+        'Use visible cause-and-effect between beats through action, object motion, eyeline, lighting/color handoff, match cut, wipe, camera movement, or another concrete transition idea.',
+        'Keep product/feature/brand meaning in the associated notes. Do not force long product explanations or the whole script into tiny in-frame text.',
+        ...(project.creativeBrief.productFeatureMap.length > 0
+            ? [
+                'Product/feature mapping to preserve:',
+                ...project.creativeBrief.productFeatureMap.map(item => `- ${item}`),
+            ]
+            : []),
+    ];
+}
+function compileStoryboardCountContractSection(project, layout) {
+    if (project.scenes.length === 0)
+        return [];
+    const sceneSlots = project.scenes
+        .map((scene, index) => `[${index + 1}] ${scene.id.toUpperCase()}`)
+        .join(', ');
+    return [
+        'COUNT / GRID CONTRACT:',
+        `Required scene count: exactly ${project.scenes.length} numbered storyboard scene slots; do not render fewer slots and do not add extra scene slots.`,
+        `Allocate the full ${project.scenes.length}-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.`,
+        `Use the layout preset exactly: ${layout.layoutKind} - ${layout.layoutDescription}. The final sheet should be visibly countable as ${project.scenes.length} 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 => {
+        const found = referenceById.get(value);
+        if (!found)
+            return value;
+        return formatModelRef(modelId, found.ref.index ?? found.index + 1, 'image');
+    })).join(', ');
+}
+function storyboardMetadataLabelAliases(labels) {
+    return uniqueStoryboardStrings(labels.flatMap(label => [
+        label,
+        removeStoryboardTimingText(label),
+    ]));
+}
+function removeStoryboardMetadataLabelsFromPromptText(value, metadataLabels) {
+    if (metadataLabels.length === 0)
+        return compactStoryboardLine(value);
+    let cleaned = value
+        .replace(/\b(?:visible\s+text|metadata\s+labels?)\s*:\s*/gi, '')
+        .replace(/\btext\s+overlay\s*:\s*/gi, '');
+    const aliases = storyboardMetadataLabelAliases(metadataLabels)
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
+    for (const label of aliases) {
+        cleaned = cleaned.replace(new RegExp(escapeStoryboardRegExp(label), 'gi'), '');
+    }
+    return compactStoryboardLine(cleaned)
+        .replace(/\s+([,.;:])/g, '$1')
+        .replace(/^[:;,\s]+|[:;,\s]+$/g, '')
+        .trim();
+}
+function compileStoryboardScenesSection(project) {
+    if (project.scenes.length === 0)
+        return [];
+    const lines = ['SCENES:'];
+    for (const scene of project.scenes) {
+        const timing = scene.startSec !== null && scene.endSec !== null
+            ? `${formatStoryboardSeconds(scene.startSec)}-${formatStoryboardSeconds(scene.endSec)}`
+            : 'timing unspecified';
+        lines.push(`${scene.id.toUpperCase()} - ${scene.title} - ${timing}`);
+        if (scene.purpose)
+            lines.push(`Scene purpose: ${scene.purpose}`);
+        if (scene.productFeature)
+            lines.push(`Product/feature mapping: ${scene.productFeature}`);
+        lines.push(`Visual/Action: ${[scene.visual, scene.action].filter(Boolean).join(' ') || 'Follow the approved storyboard beat.'}`);
+        lines.push(`Camera/Motion: ${scene.camera || 'Use the approved storyboard framing and motion notes.'}`);
+        lines.push(`Lighting/Style: ${scene.lighting || 'Use the approved storyboard lighting and style notes.'}`);
+        if (scene.transitionIn || scene.transitionOut) {
+            lines.push(`Transition: ${[scene.transitionIn, scene.transitionOut].filter(Boolean).join(' / ')}`);
+        }
+        lines.push(`Dialogue/VO: ${scene.dialogue || '[no dialogue]'}`);
+        lines.push(`Audio/SFX: ${scene.audioSfx.length > 0 ? scene.audioSfx.join(', ') : defaultStoryboardAudioSfxLine()}`);
+        if (scene.music)
+            lines.push(`Music: ${scene.music}`);
+        const referenceUsage = promptReferenceUsageForScene(scene.referenceUsage, project.references, 'gpt-image-2');
+        if (referenceUsage)
+            lines.push(`Reference usage: ${referenceUsage}`);
+        if ((scene.metadataLabels ?? []).length > 0) {
+            lines.push(`Metadata labels (outside frame only): ${(scene.metadataLabels ?? []).join('; ')}`);
+        }
+        if (scene.textInImage.length > 0)
+            lines.push(`Visible text: ${scene.textInImage.map(text => `"${text}"`).join(', ')}`);
+        if (scene.mustAvoid.length > 0)
+            lines.push(`Avoid: ${scene.mustAvoid.join('; ')}`);
+        lines.push('');
+    }
+    return lines;
+}
+function storyboardLayoutSpecFromProject(project, frameCount) {
+    const layout = describeStoryboardLayout(project.outputAspectRatio, project.frameAspectRatio, frameCount);
+    return {
+        boardAspectRatio: project.outputAspectRatio,
+        cellAspectRatio: project.frameAspectRatio,
+        targetVideoAspectRatio: project.targetVideoAspectRatio,
+        ...layout,
+        ...(project.boardDimensions ? { boardDimensions: project.boardDimensions } : {}),
+    };
+}
+function compileStoryboardTimingValidationSection(project) {
+    const validation = validateStoryboardProjectTiming(project);
+    const errors = validation.issues.filter(issue => issue.severity === 'error');
+    if (errors.length === 0)
+        return [];
+    return [
+        'TIMING VALIDATION:',
+        ...errors.map(issue => {
+            const prefix = 'ERROR';
+            const repair = issue.repair ? ` Repair: ${issue.repair}` : '';
+            return `${prefix} ${issue.code}: ${issue.message}${repair}`;
+        }),
+        'Resolve these ERROR items before treating this as video-model-ready. Do not add validation, warning, or repair-status text inside any storyboard frame.',
+    ];
+}
+export function compileVideoStoryboardImagePrompt(options) {
+    const rawUserIntentText = options.userIntentText.trim();
+    const userIntentText = canonicalStoryboardScriptContext(rawUserIntentText) || rawUserIntentText;
+    const project = buildStoryboardProject(options);
+    const compiledFrameCount = project.scenes.length || options.frameCount;
+    const layout = storyboardLayoutSpecFromProject(project, compiledFrameCount);
+    const sourceBrief = sanitizeStoryboardExternalAudioReferences(buildStoryboardSourceBriefForPrompt(options.prompt.trim(), userIntentText, options.approvedScriptContext, options.promptAuthorship));
+    const selectedBrief = selectStoryboardSourceBrief(options.prompt.trim(), userIntentText);
+    const avoidSource = buildStoryboardUserConstraintSource(userIntentText, selectedBrief, options);
+    const boardSizeLine = layout.boardDimensions
+        ? `Overall storyboard canvas: ${layout.boardDimensions} pixels (${layout.boardAspectRatio}).`
+        : `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),
+        '',
+        ...compileStoryboardReferenceSection(project),
+        '',
+        'CANVAS / LAYOUT:',
+        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.',
+        '',
+        ...compileStoryboardFrameGeometrySection(layout),
+        '',
+        ...compileStoryboardStoryContinuitySection(project),
+        '',
+        'GLOBAL STYLE:',
+        `${project.creativeBrief.visualQualityBar} with cinematic shot language, coherent art direction, readable labels, and consistent reference usage.`,
+        '',
+        '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}.`),
+        '',
+        ...compileStoryboardTimingValidationSection(project),
+        '',
+        ...compileStoryboardScenesSection(project),
+        'TEXT RENDERING:',
+        '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, unless the source explicitly marks them as visible on-screen text. Only user-required diegetic or brand text belongs inside a frame. Quote and spell any required visible text exactly.',
+        ...project.endCard.requiredText.map(text => `Required exact visible text: "${text}".`),
+        project.endCard.logoUsage ? `Logo usage: ${project.endCard.logoUsage}` : '',
+        '',
+        'SOURCE BRIEF TO FOLLOW:',
+        sourceBrief,
+        '',
+        'NEGATIVE / AVOID:',
+        ...compileStoryboardAvoidSection(avoidSource).map(item => `- ${item}`),
+    ].join('\n');
+}
+export function ensureCompiledVideoStoryboardPromptPreservesSourceBrief(compiledPrompt, userIntentText, approvedScriptContext) {
+    const prompt = compiledPrompt.trim();
+    const rawUserIntentText = userIntentText.trim();
+    if (!prompt || !rawUserIntentText)
+        return prompt;
+    const canonicalUserIntentText = canonicalStoryboardScriptContext(rawUserIntentText) || rawUserIntentText;
+    const selectedSourceBrief = sanitizeStoryboardExternalAudioReferences(buildStoryboardSourceBriefForPrompt('', canonicalUserIntentText, approvedScriptContext)).trim();
+    const sourceBrief = selectedSourceBrief && storyboardBriefContains(selectedSourceBrief, canonicalUserIntentText)
+        ? selectedSourceBrief
+        : [
+            `ORIGINAL USER INTENT:\n${canonicalUserIntentText}`,
+            selectedSourceBrief && !storyboardBriefContains(canonicalUserIntentText, selectedSourceBrief)
+                ? `SELECTED STORYBOARD BRIEF:\n${selectedSourceBrief}`
+                : '',
+        ].filter(Boolean).join('\n\n');
+    if (!sourceBrief || storyboardBriefContains(prompt, sourceBrief))
+        return prompt;
+    return [
+        prompt,
+        '',
+        'ORIGINAL SOURCE BRIEF TO PRESERVE:',
+        sourceBrief,
+        'Preserve these user-provided brands, names, dialogue, CTA text, reference assignments, timings, and scene order when rendering the storyboard image.',
+    ].join('\n');
+}
+export function lintStoryboardImagePrompt(prompt, layout, project) {
+    const errors = [];
+    const warnings = [];
+    if (!/CREATE:/i.test(prompt))
+        errors.push('missing CREATE section');
+    if (!/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))
+        errors.push('missing CANVAS / LAYOUT section');
+    if (!/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)) {
+        errors.push('missing PORTRAIT FRAME GEOMETRY section');
+    }
+    if (cellOrientation === 'landscape' && !/LANDSCAPE FRAME GEOMETRY:/i.test(prompt)) {
+        errors.push('missing LANDSCAPE FRAME GEOMETRY section');
+    }
+    if (cellOrientation === 'square' && !/SQUARE FRAME GEOMETRY:/i.test(prompt)) {
+        errors.push('missing SQUARE FRAME GEOMETRY section');
+    }
+    if (!/TEXT RENDERING:/i.test(prompt))
+        errors.push('missing TEXT RENDERING section');
+    if (!prompt.includes(`Overall storyboard canvas aspect ratio: ${layout.boardAspectRatio}`)
+        && !prompt.includes(`(${layout.boardAspectRatio})`)) {
+        errors.push(`missing board aspect ratio ${layout.boardAspectRatio}`);
+    }
+    if (!prompt.includes(`Individual scene-cell/frame aspect ratio: ${layout.cellAspectRatio}`)) {
+        errors.push(`missing cell aspect ratio ${layout.cellAspectRatio}`);
+    }
+    if (!prompt.includes(`Target final video aspect ratio: ${layout.targetVideoAspectRatio}`)) {
+        errors.push(`missing target video aspect ratio ${layout.targetVideoAspectRatio}`);
+    }
+    if (!/\bDialogue\/VO\b/i.test(prompt))
+        warnings.push('missing explicit Dialogue/VO field');
+    if (!/\bAudio\/SFX\b/i.test(prompt))
+        warnings.push('missing explicit Audio/SFX field');
+    if (/\bparagraphs?\s+inside\s+each\s+(?:cell|frame|panel)\b/i.test(prompt)) {
+        warnings.push('prompt may encourage dense paragraphs inside storyboard cells');
+    }
+    if (project) {
+        const sceneCount = project.scenes.length;
+        if (sceneCount > 0 && !new RegExp(String.raw `Create exactly\s+${sceneCount}\s+sequential video storyboard frames`, 'i').test(prompt)) {
+            errors.push(`missing exact scene count ${sceneCount}`);
+        }
+        for (const ref of project.references.filter(item => item.preservePriority === 'critical')) {
+            const refPattern = ref.index
+                ? new RegExp(String.raw `\bImage\s+${ref.index}\b`, 'i')
+                : new RegExp(String.raw `\b${ref.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\b`, 'i');
+            if (!refPattern.test(prompt)) {
+                errors.push(`missing critical reference ${ref.id}`);
+            }
+        }
+        for (const requiredText of [
+            ...project.creativeBrief.mustInclude,
+            ...project.endCard.requiredText,
+        ]) {
+            if (requiredText && !prompt.includes(requiredText)) {
+                errors.push(`missing required text "${requiredText}"`);
+            }
+        }
+        const timing = validateStoryboardProjectTiming(project);
+        for (const issue of timing.issues) {
+            const target = issue.severity === 'error' ? errors : warnings;
+            target.push(`timing ${issue.code}: ${issue.message}`);
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+function parseStoryboardDimensionText(value) {
+    if (!value)
+        return null;
+    const match = value.match(/\b(\d{2,5})\s*x\s*(\d{2,5})\b/i);
+    if (!match)
+        return null;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+        return null;
+    return { width, height };
+}
+function exactPixelAspectDescription(width, height) {
+    const ratio = formatAspectRatio(width, height) ?? '16:9';
+    const orientation = width > height ? 'landscape' : height > width ? 'portrait' : 'square';
+    return `${ratio} ${orientation} video`;
+}
+function storyboardCanvasContextMentionsPage(context) {
+    return /\b(?:board|canvas|page|sheet|poster|story\s*board\s+(?:image|sheet|canvas|board|page)|storyboard\s+(?:image|sheet|canvas|board|page)|(?:image|sheet|canvas|board|page)\s+(?:story\s*board|storyboard))\b/i.test(context);
+}
+export function stripGeneratedStoryboardLayoutHints(text) {
+    return text
+        .replace(new RegExp(`${DEFAULT_STORYBOARD_CANVAS_HINT_MARKER}[^\\n]*`, 'gi'), '')
+        .replace(/^Storyboard layout target:[^\n]*$/gmi, '')
+        .replace(/^Storyboard layout:[^\n]*$/gmi, '');
+}
+export function inferExplicitStoryboardCanvasPixelDimensions(text) {
+    const source = stripGeneratedStoryboardLayoutHints(text);
+    const matcher = /\b(\d{3,5})\s*x\s*(\d{3,5})\b/gi;
+    for (const match of source.matchAll(matcher)) {
+        const index = match.index ?? 0;
+        const context = source.slice(Math.max(0, index - 80), Math.min(source.length, index + match[0].length + 80));
+        if (!storyboardCanvasContextMentionsPage(context))
+            continue;
+        const width = Number(match[1]);
+        const height = Number(match[2]);
+        if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) {
+            return { width, height };
+        }
+    }
+    return null;
+}
+export function userDefinedStoryboardCanvas(text) {
+    const source = stripGeneratedStoryboardLayoutHints(text);
+    if (inferStoryboardBoardAspectDirective(source))
+        return true;
+    if (inferExplicitStoryboardCanvasPixelDimensions(source))
+        return true;
+    const pageUnit = String.raw `(?:board|canvas|page|sheet|poster|story\s*board\s+(?:image|sheet|canvas|board|page)|storyboard\s+(?:image|sheet|canvas|board|page)|(?:image|sheet|canvas|board|page)\s+(?:story\s*board|storyboard))`;
+    const aspectToken = String.raw `(?:\d{1,4}\s*:\s*\d{1,4}|\d{3,5}\s*x\s*\d{3,5}|portrait|vertical|landscape|horizontal|widescreen)`;
+    return new RegExp(String.raw `\b${pageUnit}\b[\s\S]{0,80}\b${aspectToken}\b`, 'i').test(source)
+        || new RegExp(String.raw `\b${aspectToken}\b[\s\S]{0,80}\b${pageUnit}\b`, 'i').test(source);
+}
+export function maskNonCanvasExactPixelDimensionsForStoryboard(text) {
+    return text.replace(/\b(\d{3,5})\s*x\s*(\d{3,5})\b/gi, (match, rawWidth, rawHeight, offset, fullText) => {
+        const source = String(fullText);
+        const context = source.slice(Math.max(0, offset - 80), Math.min(source.length, offset + match.length + 80));
+        if (storyboardCanvasContextMentionsPage(context))
+            return match;
+        const width = Number(rawWidth);
+        const height = Number(rawHeight);
+        return exactPixelAspectDescription(width, height);
+    });
+}
+function parseAspectRatioOrientation(aspectRatio) {
+    const normalized = normalizeAspectRatio(aspectRatio);
+    if (!normalized)
+        return null;
+    const [widthText, heightText] = normalized.split(':');
+    const width = Number(widthText);
+    const height = Number(heightText);
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        return null;
+    }
+    if (width > height)
+        return 'landscape';
+    if (height > width)
+        return 'portrait';
+    return 'square';
+}
+function defaultStoryboardCanvasForVideoAspectRatio(targetVideoAspectRatio) {
+    const orientation = parseAspectRatioOrientation(targetVideoAspectRatio);
+    if (orientation === 'portrait')
+        return GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardLandscape;
+    if (orientation === 'landscape')
+        return GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardPortrait;
+    return null;
+}
+function storyboardCanvasHintText(canvas, targetVideoAspectRatio) {
+    const boardAspect = canvas === GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardLandscape
+        ? '16:9 landscape'
+        : '9:16 portrait';
+    return [
+        `${DEFAULT_STORYBOARD_CANVAS_HINT_MARKER} Use a ${boardAspect} storyboard canvas/page (${canvas.aspectRatio}) for the composite storyboard sheet unless the user explicitly specifies another storyboard page size.`,
+        `Keep individual scene-cell/frame aspect ratio ${targetVideoAspectRatio}; target final video aspect ratio ${targetVideoAspectRatio}.`,
+    ].join(' ');
+}
+function insertDefaultStoryboardCanvasHint(text, hint) {
+    const generatedBriefMatch = text.match(/^\s*(?:[-*+]\s*)?(?:#{1,6}\s*)?(?:[*_]{1,3})?\s*(?:storyboard\s+image\s+brief|subsequent\s+video\s+brief|video\s+generation\s+stage|next\s+steps?)\b[^\n]*$/im);
+    if (!generatedBriefMatch || generatedBriefMatch.index === undefined) {
+        return `${hint}\n${text}`;
+    }
+    const before = text.slice(0, generatedBriefMatch.index).trimEnd();
+    const after = text.slice(generatedBriefMatch.index).trimStart();
+    return `${before}\n${hint}\n\n${after}`;
+}
+export function applyDefaultStoryboardCanvasHint(text, frameCount) {
+    if (text.includes(DEFAULT_STORYBOARD_CANVAS_HINT_MARKER))
+        return text;
+    if (userDefinedStoryboardCanvas(text))
+        return text;
+    const maskedText = maskNonCanvasExactPixelDimensionsForStoryboard(text);
+    const layout = inferStoryboardLayoutSpec(maskedText, frameCount);
+    const explicitRatio = inferExplicitAspectRatioFromText(maskedText);
+    const explicitTargetAspectRatio = explicitRatio ? `${explicitRatio.width}:${explicitRatio.height}` : null;
+    const targetVideoAspectRatio = explicitTargetAspectRatio ?? layout.targetVideoAspectRatio;
+    const canvas = defaultStoryboardCanvasForVideoAspectRatio(targetVideoAspectRatio);
+    if (!canvas)
+        return maskedText;
+    return insertDefaultStoryboardCanvasHint(maskedText, storyboardCanvasHintText(canvas, targetVideoAspectRatio));
+}
+export function buildStoryboardCanvasArgs(boardAspectRatio, isGptImage2) {
+    const normalizedBoardAspectRatio = normalizeAspectRatio(boardAspectRatio) ?? boardAspectRatio;
+    const orientation = parseAspectRatioOrientation(normalizedBoardAspectRatio);
+    const canvas = orientation === 'landscape'
+        ? GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardLandscape
+        : orientation === 'portrait'
+            ? GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardPortrait
+            : null;
+    if (!canvas) {
+        return { aspectRatio: normalizedBoardAspectRatio };
+    }
+    if (isGptImage2) {
+        return {
+            width: canvas.width,
+            height: canvas.height,
+            aspectRatio: canvas.aspectRatio,
+        };
+    }
+    const isLandscapeCanvas = canvas === GPT_IMAGE_STORYBOARD_DEFAULTS.storyboardLandscape;
+    const width = isLandscapeCanvas ? 1920 : 1080;
+    const height = isLandscapeCanvas ? 1080 : 1920;
+    return { width, height, aspectRatio: `${width}x${height}` };
+}
+function storyboardIntentWithDefaultCanvasHint(userIntentText, frameCount) {
+    return applyDefaultStoryboardCanvasHint(userIntentText, frameCount);
+}
+export function defaultStoryboardImageDimensions(layout) {
+    const explicit = parseStoryboardDimensionText(layout.boardDimensions);
+    if (explicit)
+        return explicit;
+    const normalized = normalizeAspectRatio(layout.boardAspectRatio);
+    if (normalized === '9:16')
+        return { width: 1440, height: 2560 };
+    if (normalized === '1:1')
+        return { width: 2048, height: 2048 };
+    if (normalized === '4:3')
+        return { width: 2048, height: 1536 };
+    if (normalized === '3:4')
+        return { width: 1536, height: 2048 };
+    return { width: 2560, height: 1440 };
+}
+function dimensionsForShortSideAspectRatio(aspectRatio, shortSide) {
+    const normalized = normalizeAspectRatio(aspectRatio) ?? '16:9';
+    const [widthText, heightText] = normalized.split(':');
+    const ratioWidth = Number(widthText);
+    const ratioHeight = Number(heightText);
+    if (!Number.isFinite(ratioWidth)
+        || !Number.isFinite(ratioHeight)
+        || ratioWidth <= 0
+        || ratioHeight <= 0) {
+        return { width: 1280, height: 720 };
+    }
+    const multiple = 16;
+    const side = Math.max(multiple, Math.round(shortSide / multiple) * multiple);
+    const roundLongSide = (value) => Math.max(multiple, Math.round(value / multiple) * multiple);
+    if (ratioWidth >= ratioHeight) {
+        return {
+            width: roundLongSide(side * ratioWidth / ratioHeight),
+            height: side,
+        };
+    }
+    return {
+        width: side,
+        height: roundLongSide(side * ratioHeight / ratioWidth),
+    };
+}
+function clampSeedanceStoryboardDuration(value) {
+    const raw = typeof value === 'number' && Number.isFinite(value) ? value : 5;
+    return Math.max(4, Math.min(15, Math.round(raw)));
+}
+function sceneLineForSeedanceStoryboardProject(scene, index) {
+    const timing = scene.startSec !== null && scene.endSec !== null
+        ? `${formatStoryboardSeconds(scene.startSec)}-${formatStoryboardSeconds(scene.endSec)}`
+        : 'untimed';
+    const voice = scene.dialogue || '[no dialogue]';
+    const metadataLabels = scene.metadataLabels ?? [];
+    return [
+        `SCENE ${String(index + 1).padStart(2, '0')} - ${removeStoryboardMetadataLabelsFromPromptText(scene.title, metadataLabels) || scene.title}`,
+        `TIME: ${timing}`,
+        `PURPOSE: ${scene.purpose || 'Advance the approved story spine.'}`,
+        `VISUAL: ${removeStoryboardMetadataLabelsFromPromptText(scene.visual, metadataLabels) || 'Follow the approved storyboard visual.'}`,
+        `ACTION: ${removeStoryboardMetadataLabelsFromPromptText(scene.action, metadataLabels) || 'Use clear motion that connects to the next beat.'}`,
+        `CAMERA: ${scene.camera || 'Use the approved shot language.'}`,
+        `LIGHTING/STYLE: ${scene.lighting || 'Preserve the storyboard style and lighting.'}`,
+        `TRANSITION: ${[scene.transitionIn, scene.transitionOut].filter(Boolean).join('; ') || 'Use a clean motivated continuity transition.'}`,
+        `VOICE/DIALOGUE: ${voice}`,
+        `AUDIO/SFX: ${scene.audioSfx.join(', ') || defaultStoryboardAudioSfxLine()}`,
+        `MUSIC: ${scene.music || 'Follow the global generated music arc.'}`,
+        `REFERENCE USAGE: ${scene.referenceUsage.join('; ') || `Use ${PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF} storyboard only.`}`,
+        `METADATA LABELS (do not render): ${metadataLabels.join('; ') || 'none'}`,
+        `VISIBLE TEXT: ${scene.textInImage.join('; ') || 'none'}`,
+    ].join('\n');
+}
+export function compileSeedanceStoryboardPromptFromProject(project, options = {}) {
+    const storyboardImageTag = options.storyboardImageTag ?? PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF;
+    const durationSec = clampSeedanceStoryboardDuration(options.durationSec ?? project.durationSec);
+    const aspectRatio = normalizeAspectRatio(options.aspectRatio ?? project.targetVideoAspectRatio)
+        ?? project.targetVideoAspectRatio
+        ?? '16:9';
+    const avoidList = [
+        ...project.creativeBrief.mustAvoid,
+        'Do not render the storyboard board, grid, captions, panel dividers, thumbnails, or collage layout as the video.',
+        'Do not add extra readable text beyond required brand/CTA text.',
+        'Do not drift reference assets, product design, logo, recurring character identity, shot order, or scene timing.',
+    ];
+    const requiredText = project.endCard.requiredText.length > 0
+        ? project.endCard.requiredText.join('; ')
+        : 'none';
+    const metadataLabels = uniqueStoryboardStrings([
+        ...(project.metadataLabels ?? []),
+        ...project.scenes.flatMap(scene => scene.metadataLabels ?? []),
+    ]);
+    const storySpine = removeStoryboardMetadataLabelsFromPromptText(project.creativeBrief.storySpine, metadataLabels) || project.creativeBrief.storySpine;
+    return [
+        'PROJECT:',
+        `Title: ${project.title}`,
+        `Duration: ${durationSec} seconds total.`,
+        `Aspect ratio: ${aspectRatio}.`,
+        `Story spine: ${storySpine}`,
+        '',
+        'INPUT ASSETS:',
+        `${storyboardImageTag}: approved GPT Image 2 storyboard board. Treat it as an ordered shot guide and timing reference only, not as a collage, split-screen, grid, or picture-in-picture layout to reproduce.`,
+        '',
+        'GLOBAL VIDEO INSTRUCTIONS:',
+        `Render one continuous cinematic video in ${aspectRatio}. Follow the storyboard scene order, timing ranges, transitions, audio plan, and CTA hold exactly where specified.`,
+        'Use the storyboard as the controlling source for shot order and intent while converting each panel into full-screen motion.',
+        'Keep required visible text minimal and exact. All scene numbers, timecodes, labels, and production notes remain metadata only and must not appear in the video.',
+        metadataLabels.length > 0 ? `Do not render these metadata labels as video text: ${metadataLabels.join('; ')}.` : '',
+        `Visual style: ${project.creativeBrief.visualQualityBar}`,
+        `Tone progression: ${project.creativeBrief.toneProgression.join(' -> ') || 'preserve the approved tone progression.'}`,
+        `Music arc: ${project.scenes.map(scene => scene.music).filter(Boolean).join(' -> ') || 'support the approved story arc without overpowering dialogue.'}`,
+        '',
+        'TIMECODED SCENES:',
+        ...project.scenes.map(sceneLineForSeedanceStoryboardProject),
+        '',
+        'END CARD / CTA HOLD:',
+        `Required visible text: ${requiredText}`,
+        'Hold readable CTA or brand text long enough to read.',
+        `Treatment: ${[project.endCard.backgroundStyle, project.endCard.composition, project.endCard.logoUsage].filter(Boolean).join(' ') || 'clean branded end frame that remains readable.'}`,
+        '',
+        'NEGATIVE / AVOID:',
+        ...Array.from(new Set(avoidList.map(item => compactStoryboardLine(item)).filter(Boolean))).map(item => `- ${item}`),
+    ].join('\n');
+}
+export function lintSeedanceStoryboardPromptFromProject(prompt, project) {
+    const errors = [];
+    const warnings = [];
+    if (!/\bPROJECT:/i.test(prompt))
+        errors.push('missing PROJECT section');
+    if (!/\bINPUT ASSETS:/i.test(prompt))
+        errors.push('missing INPUT ASSETS section');
+    if (!/\bGLOBAL VIDEO INSTRUCTIONS:/i.test(prompt))
+        errors.push('missing GLOBAL VIDEO INSTRUCTIONS section');
+    if (!new RegExp(PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF, 'i').test(prompt)) {
+        errors.push(`missing ${PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF} storyboard reference`);
+    }
+    if (!/\bshot guide\b/i.test(prompt))
+        errors.push('missing shot-guide instruction');
+    if (!/\bnot\s+as\s+a\s+(?:collage|split-screen|grid)/i.test(prompt)) {
+        errors.push('missing anti-collage/grid instruction');
+    }
+    if (project.scenes.length === 0)
+        errors.push('missing storyboard scenes');
+    project.scenes.forEach((scene, index) => {
+        const sceneNumber = String(index + 1).padStart(2, '0');
+        if (!new RegExp(`SCENE\\s+${sceneNumber}\\b`, 'i').test(prompt)) {
+            errors.push(`missing scene ${index + 1}`);
+        }
+        if (scene.startSec !== null && scene.endSec !== null) {
+            const timeText = `${formatStoryboardSeconds(scene.startSec)}-${formatStoryboardSeconds(scene.endSec)}`;
+            if (!prompt.includes(timeText))
+                warnings.push(`missing exact time range for scene ${index + 1}`);
+        }
+    });
+    for (const text of project.endCard.requiredText) {
+        if (text && !prompt.includes(text))
+            errors.push(`missing required text "${text}"`);
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function buildStoryboardVideoHostedToolSequenceInput(options) {
+    const storyline = options.storyline.trim();
+    const userIntentText = options.userIntentText.trim();
+    if (!storyline) {
+        throw new Error('Storyboard video workflow requires a generated storyline or approved storyboard script.');
+    }
+    if (!userIntentText) {
+        throw new Error('Storyboard video workflow requires the original user intent text.');
+    }
+    const initialFrameCount = Math.max(1, Math.min(24, options.frameCount
+        ?? inferExplicitStoryboardFrameCountFromText(`${userIntentText}\n${storyline}`)
+        ?? inferDefaultStoryboardFrameCountFromText(`${userIntentText}\n${storyline}`)));
+    const workflowUserIntentText = storyboardIntentWithDefaultCanvasHint(userIntentText, initialFrameCount);
+    const frameCount = Math.max(1, Math.min(24, options.frameCount
+        ?? inferExplicitStoryboardFrameCountFromText(`${workflowUserIntentText}\n${storyline}`)
+        ?? inferDefaultStoryboardFrameCountFromText(`${workflowUserIntentText}\n${storyline}`)));
+    const compileOptions = {
+        prompt: storyline,
+        userIntentText: workflowUserIntentText,
+        approvedScriptContext: storyline,
+        frameCount,
+        promptAuthorship: 'assistant',
+    };
+    const project = buildStoryboardProject(compileOptions);
+    const layout = storyboardLayoutSpecFromProject(project, project.scenes.length || frameCount);
+    const defaultImageDimensions = defaultStoryboardImageDimensions(layout);
+    const imageWidth = options.imageWidth ?? defaultImageDimensions.width;
+    const imageHeight = options.imageHeight ?? defaultImageDimensions.height;
+    const videoDuration = clampSeedanceStoryboardDuration(options.videoDurationSec ?? project.durationSec);
+    const videoDimensions = dimensionsForShortSideAspectRatio(project.targetVideoAspectRatio, options.videoTargetResolution ?? 720);
+    const storyboardImagePrompt = compileVideoStoryboardImagePrompt(compileOptions);
+    const seedanceVideoPrompt = compileSeedanceStoryboardPromptFromProject(project, {
+        storyboardImageTag: PUBLIC_SEEDANCE_PRIMARY_IMAGE_REF,
+        durationSec: videoDuration,
+        aspectRatio: project.targetVideoAspectRatio,
+    });
+    const storyboardLint = lintStoryboardImagePrompt(storyboardImagePrompt, layout, project);
+    const seedanceLint = lintSeedanceStoryboardPromptFromProject(seedanceVideoPrompt, project);
+    const title = options.title || `${project.title} storyboard video`;
+    const imageModel = options.imageModel ?? 'gpt-image-2';
+    const imageQuality = options.imageQuality ?? 'high';
+    const imageOutputFormat = options.imageOutputFormat ?? 'png';
+    const videoModel = options.videoModel ?? 'seedance2';
+    const generateAudio = options.generateAudio ?? true;
+    const input = {
+        title,
+        steps: [
+            {
+                id: 'storyboard_image',
+                toolName: 'sogni_generate_image',
+                arguments: {
+                    prompt: storyboardImagePrompt,
+                    model: imageModel,
+                    width: imageWidth,
+                    height: imageHeight,
+                    number_of_variations: 1,
+                    gpt_image_quality: imageQuality,
+                    output_format: imageOutputFormat,
+                },
+            },
+            {
+                id: 'seedance_video',
+                toolName: 'sogni_generate_video',
+                arguments: {
+                    prompt: seedanceVideoPrompt,
+                    model: videoModel,
+                    width: videoDimensions.width,
+                    height: videoDimensions.height,
+                    duration: videoDuration,
+                    fps: 24,
+                    number_of_variations: 1,
+                    generate_audio: generateAudio,
+                    expand_prompt: false,
+                },
+                dependsOn: [
+                    {
+                        sourceStepId: 'storyboard_image',
+                        sourceArtifactIndex: 0,
+                        targetArgument: 'reference_image_url',
+                        mediaType: 'image',
+                        transform: 'artifact_url',
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+    return {
+        title,
+        frameCount,
+        storyline,
+        storyboardProject: project,
+        storyboardImagePrompt,
+        seedanceVideoPrompt,
+        image: {
+            width: imageWidth,
+            height: imageHeight,
+            model: imageModel,
+            quality: imageQuality,
+            outputFormat: imageOutputFormat,
+        },
+        video: {
+            width: videoDimensions.width,
+            height: videoDimensions.height,
+            duration: videoDuration,
+            model: videoModel,
+            generateAudio,
+        },
+        input,
+        warnings: [
+            ...storyboardLint.warnings.map(warning => `storyboard image: ${warning}`),
+            ...storyboardLint.errors.map(error => `storyboard image error: ${error}`),
+            ...seedanceLint.warnings.map(warning => `seedance prompt: ${warning}`),
+            ...seedanceLint.errors.map(error => `seedance prompt error: ${error}`),
+        ],
+    };
+}
 export function inferDefaultVideoSteps(modelId) {
     const id = (modelId || '').toLowerCase();
     if (isSeedanceModel(id))