venice-video-harness 2.4.0

package/dist/mini-drama/prompt-builder.js

@@ -0,0 +1,722 @@
+import { VIDEO_NO_MUSIC_SUFFIX, FEMALE_BASE_TRAITS, MALE_BASE_TRAITS, KLING_MULTISHOT_MODEL, KLING_R2V_MODEL, DAYTIME_ENVIRONMENTS, MODELS_SUPPORTING_ELEMENTS, MODELS_SUPPORTING_REFERENCE_IMAGES, MODELS_SUPPORTING_SCENE_IMAGES, MODELS_SUPPORTING_REFERENCE_AUDIO, MODELS_USING_IMAGE_TAGS, DEFAULT_CHARACTER_CONSISTENCY_MODEL, getMaxReferenceImages, } from '../series/types.js';
+import { parseShotDuration } from './generation-planner.js';
+import { getMaxPositivePromptChars } from '../venice/models.js';
+import { getLocation } from '../series/manager.js';
+import { buildReferenceSlotPlan } from './reference-slots.js';
+// The audio-suppression chunk keeps the video model from baking music,
+// score, sound effects, or foley into the dialogue track. The harness adds
+// music (musicCues / generate_music) and ambient/SFX (generate_ambient /
+// mix_audio) in post — bakes-in fight the assembler's mix and can't be
+// removed once they're in the output. Keep this in NEGATIVE_PROMPT for
+// every shot type; the workshop system prompt also asks the script LLM to
+// repeat it per-shot, but this is the always-on belt-and-braces.
+const AUDIO_SUPPRESSION_NEGATIVE = 'background music, soundtrack, score, musical score, sound effects, sfx, foley, ' +
+    'orchestral hits, sound design, audio drops';
+const NEGATIVE_PROMPT = 'comic panels, multiple panels, panel layout, panel borders, panel grid, speech bubbles, text bubbles, ' +
+    'manga panels, comic strip, storyboard grid, split screen, multiple frames, ' +
+    'deformed, blurry, bad anatomy, bad hands, extra fingers, mutation, ' +
+    'poorly drawn face, watermark, text, signature, low quality, ugly, ' +
+    'umbrella, holding umbrella, ' +
+    AUDIO_SUPPRESSION_NEGATIVE;
+const NO_PEOPLE_NEGATIVE = NEGATIVE_PROMPT + ', people, person, human, figure, silhouette, crowd, pedestrian, bystander';
+const CAMERA_TERMS = {
+    'static': 'locked-off static shot',
+    'slow dolly forward': 'slow dolly shot pushing forward',
+    'slow dolly back': 'slow dolly shot pulling back',
+    'pan left': 'slow pan left',
+    'pan right': 'slow pan right',
+    'tilt up': 'tilt up',
+    'tilt down': 'tilt down',
+    'tracking': 'tracking shot following the subject',
+    'crane up': 'crane shot rising upward',
+    'handheld': 'handheld shot with subtle movement',
+    'zoom in': 'slow zoom in',
+    'zoom out': 'slow zoom out',
+};
+function getCharacterPromptText(char) {
+    const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+    return `${char.name} (${baseTraits}): ${char.fullDescription}`;
+}
+function buildAestheticString(aesthetic) {
+    return [aesthetic.style, aesthetic.palette, aesthetic.lighting, aesthetic.lensCharacteristics, `shot on ${aesthetic.filmStock}`]
+        .filter(Boolean)
+        .join(', ');
+}
+/**
+ * Determines if a shot should use daytime aesthetics. Uses the explicit
+ * `environment` field when set; falls back to panelDescription heuristics
+ * for backwards compatibility with scripts that don't have it yet.
+ */
+function isDaytimeShot(shot) {
+    if (shot.environment) {
+        return DAYTIME_ENVIRONMENTS.has(shot.environment);
+    }
+    const sceneText = (shot.panelDescription ?? shot.description).toUpperCase();
+    return sceneText.includes('NO RAIN') || sceneText.includes('BRIGHT INDOOR') || sceneText.includes('DAYTIME');
+}
+/**
+ * Strips rain, dark-sky, and wet-surface terms from the aesthetic string
+ * so that daytime scenes aren't contaminated by the series' default
+ * nighttime cyberpunk aesthetic.
+ */
+function stripDarkAesthetic(aestheticStr) {
+    return aestheticStr
+        .replace(/,?\s*rain rendered as[^,]*(?:,|$)/gi, ', ')
+        .replace(/,?\s*neon reflections on wet surfaces/gi, '')
+        .replace(/,?\s*volumetric light rays through rain/gi, ', soft volumetric light')
+        .replace(/,?\s*dark charcoal backgrounds\s*\([^)]*\)/gi, ', warm bright interior backgrounds')
+        .replace(/\s{2,}/g, ' ')
+        .replace(/,\s*,/g, ',')
+        .trim();
+}
+/**
+ * Selects the video model for a shot. The core principle is simple:
+ *
+ *   - **R2V by default** for all non-establishing shots (consistency first)
+ *   - **Atmosphere model only** for truly empty establishing/mood shots
+ *
+ * R2V models accept `elements` and `reference_image_urls`, which are the
+ * only reliable way to maintain character identity across shots. Since the
+ * action model now defaults to R2V, almost all shots benefit from reference
+ * anchoring. The atmosphere model is reserved for truly empty
+ * establishing/insert shots with no characters on screen.
+ *
+ * When the resolved model supports elements or reference images, those
+ * capabilities are auto-enabled.
+ */
+export function resolveVideoModel(shot, series, _previousShot) {
+    const baseModel = shot.videoModel === 'action'
+        ? series.videoDefaults.actionModel
+        : series.videoDefaults.atmosphereModel;
+    const consistencyModel = series.videoDefaults.characterConsistencyModel ?? DEFAULT_CHARACTER_CONSISTENCY_MODEL;
+    const hasCharacters = shot.characters.length > 0;
+    if (!hasCharacters) {
+        // With Enhanced R2V as the default for all lanes, even empty
+        // establishing/atmosphere shots can anchor to location references
+        // (@ImageN env tags) when the base model supports them.
+        return {
+            modelId: baseModel,
+            upgraded: false,
+            reason: 'no characters — atmosphere model (location refs when supported)',
+            autoUseElements: false,
+            autoUseReferenceImages: MODELS_SUPPORTING_REFERENCE_IMAGES.has(baseModel),
+            useImageTags: MODELS_USING_IMAGE_TAGS.has(baseModel),
+        };
+    }
+    // dialogue shots whose speaker is a non-narrator visible
+    // character with low/medium motion route to Wan 2.7 i2v for lip-sync.
+    // High-motion dialogue stays on R2V because Wan 2.7 prioritizes motion
+    // over reference adherence (hair color shifts, shirt pattern simplifies,
+    // eyes change) when forced to handle big movement.
+    const lipSyncModel = series.videoDefaults.lipSyncModel;
+    if (lipSyncModel && shotWantsLipSync(shot) && shot.characters.length <= 1) {
+        return {
+            modelId: lipSyncModel,
+            upgraded: true,
+            reason: 'single-speaker dialogue, low/medium motion — Wan 2.7 lip-sync',
+            autoUseElements: false,
+            autoUseReferenceImages: false,
+            useImageTags: false,
+        };
+    }
+    // Kling fallback only when the character count alone would overflow the
+    // flat-reference budget (leaving no room for location/storyboard refs).
+    // With the 9-image budget on Seedance 2.0 R2V / Enhanced, scenes with up
+    // to ~6 characters stay in-family; the old 3+ threshold dated from the
+    // 4-image era.
+    const refBudget = getMaxReferenceImages(consistencyModel);
+    const needsElementsFallback = shot.characters.length > Math.max(2, refBudget - 3)
+        && MODELS_USING_IMAGE_TAGS.has(consistencyModel)
+        && !MODELS_SUPPORTING_ELEMENTS.has(consistencyModel);
+    if (needsElementsFallback) {
+        return {
+            modelId: KLING_R2V_MODEL,
+            upgraded: true,
+            reason: `${shot.characters.length} characters overflow the ${refBudget}-reference budget — falling back to Kling O3 R2V for structured elements`,
+            autoUseElements: true,
+            autoUseReferenceImages: true,
+            useImageTags: false,
+        };
+    }
+    return {
+        modelId: consistencyModel,
+        upgraded: consistencyModel !== baseModel,
+        reason: 'characters present — R2V for identity anchoring',
+        autoUseElements: MODELS_SUPPORTING_ELEMENTS.has(consistencyModel),
+        autoUseReferenceImages: MODELS_SUPPORTING_REFERENCE_IMAGES.has(consistencyModel),
+        useImageTags: MODELS_USING_IMAGE_TAGS.has(consistencyModel),
+    };
+}
+/**
+ * does this shot want lip-sync routing? A dialogue shot whose
+ * speaker is not the narrator and whose face is (or might be) visible,
+ * with motion not classified as 'high'.
+ */
+function shotWantsLipSync(shot) {
+    if (!shot.dialogue)
+        return false;
+    const speaker = shot.dialogue.character.toUpperCase();
+    if (speaker === 'NARRATOR' || speaker === 'V.O.' || speaker === 'VO')
+        return false;
+    if (shot.motion === 'high')
+        return false;
+    if (shot.faceVisible === false)
+        return false;
+    return true;
+}
+export function buildImagePrompt(shot, series) {
+    if (!series.aesthetic) {
+        throw new Error('Series aesthetic must be set before generating images.');
+    }
+    const isDaytime = isDaytimeShot(shot);
+    let aestheticStr = buildAestheticString(series.aesthetic);
+    if (isDaytime) {
+        aestheticStr = stripDarkAesthetic(aestheticStr);
+    }
+    const parts = [];
+    parts.push(`STYLE: ${aestheticStr}.`);
+    parts.push('Single cinematic frame, one continuous image, NOT a comic panel layout, NO panel borders, NO speech bubbles, NO text overlays.');
+    const isEmptyScene = shot.characters.length === 0;
+    parts.push('Characters are engaged in the scene, NOT looking at the camera.');
+    if (!isEmptyScene && shot.characters.length === 1) {
+        parts.push('This is NOT a portrait or headshot. The environment, props, and action are equally important as the character. Show the full scene composition with widescreen cinematic framing.');
+    }
+    parts.push(`Camera: ${shot.cameraMovement}.`);
+    parts.push(shot.panelDescription ?? shot.description);
+    // Silhouette characters appear in the panel but don't trigger R2V
+    if (shot.silhouetteCharacters && shot.silhouetteCharacters.length > 0) {
+        for (const charName of shot.silhouetteCharacters) {
+            const char = series.characters.find(c => c.name.toUpperCase() === charName.toUpperCase());
+            if (char) {
+                parts.push(`A distant silhouetted figure (${char.name}) is visible — seen from behind or at a distance, no face detail needed, identifiable by wardrobe: ${char.wardrobe}.`);
+            }
+        }
+    }
+    if (isEmptyScene && (!shot.silhouetteCharacters || shot.silhouetteCharacters.length === 0)) {
+        parts.push('Empty environment, no people present, no human figures, uninhabited scene.');
+    }
+    else if (isEmptyScene) {
+        // Has silhouette characters but no main characters — don't add "no people" directive
+    }
+    else {
+        for (const charName of shot.characters) {
+            const char = series.characters.find(c => c.name.toUpperCase() === charName.toUpperCase());
+            if (char) {
+                const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+                const wardrobe = shot.episodeWardrobe?.[charName.toUpperCase()] ?? char.wardrobe;
+                parts.push(`${char.name} (${baseTraits}): ${char.description}, wearing ${wardrobe}.`);
+            }
+        }
+    }
+    parts.push(`STYLE REMINDER: ${aestheticStr}.`);
+    const seed = series.aestheticSeed ?? undefined;
+    const hasSilhouettes = shot.silhouetteCharacters && shot.silhouetteCharacters.length > 0;
+    let negativePrompt = (isEmptyScene && !hasSilhouettes) ? NO_PEOPLE_NEGATIVE : NEGATIVE_PROMPT;
+    if (isDaytime) {
+        negativePrompt += ', rain, rain streaks, wet surfaces, wet pavement, dark sky, storm, night sky, outdoor rain, neon reflections on wet ground';
+    }
+    return {
+        prompt: parts.join(' ').trim(),
+        negativePrompt,
+        seed,
+    };
+}
+function getCharacterVideoTag(char) {
+    const key = char.gender === 'female'
+        ? `${char.name}, ${char.age}, ${char.wardrobe}`
+        : `${char.name}, ${char.age}, ${char.wardrobe}`;
+    return key;
+}
+function buildCharacterAnchorText(characters) {
+    if (characters.length === 0)
+        return '';
+    const anchors = characters.map(char => {
+        const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+        return `${char.name}: ${baseTraits}, ${char.fullDescription}, wearing ${char.wardrobe}`;
+    });
+    return `Core subjects: ${anchors.join('; ')}.`;
+}
+function buildCompactAestheticString(aesthetic) {
+    return [
+        aesthetic.style,
+        aesthetic.palette,
+        aesthetic.lighting,
+    ]
+        .filter(Boolean)
+        .join(', ');
+}
+function summarizeCharacterForMultiShot(char, wardrobeOverride, elementSlot) {
+    const wardrobe = wardrobeOverride ?? char.wardrobe;
+    const shortWardrobe = wardrobe.split(',').slice(0, 2).join(',').trim();
+    const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+    const label = elementSlot ? `@Element${elementSlot.elementIndex} (${char.name})` : char.name;
+    return `[${label}: ${baseTraits}, ${char.age}, ${char.description.split(',').slice(0, 3).join(',').trim()}, wearing ${shortWardrobe}]`;
+}
+/**
+ * Build a video-generation prompt for a shot.
+ *
+ * Directing principle (see .claude/agents/prompt-engineer.md and the README
+ * "Directing layer"): this assembles the prose that DIRECTS the shot -- one
+ * intention expressed through camera, light, blocking, performance, and sound
+ * -- not a pile of "cinematic" adjectives. It intentionally leans on the
+ * shot's authored `description`/delivery (which the workshop system prompt
+ * directs) rather than decorating it here. Identity is locked downstream by
+ * R2V references, so this does not inject exhaustive character descriptions.
+ */
+export function buildVideoPrompt(shot, series, previousShot, episodeAudioMix) {
+    if (!series.aesthetic) {
+        throw new Error('Series aesthetic must be set before generating videos.');
+    }
+    const resolution = resolveVideoModel(shot, series, previousShot);
+    const modelId = resolution.modelId;
+    const useElements = resolution.autoUseElements
+        || (shot.useElements && MODELS_SUPPORTING_ELEMENTS.has(modelId));
+    const useRefs = resolution.autoUseReferenceImages
+        || (shot.useReferenceImages && MODELS_SUPPORTING_REFERENCE_IMAGES.has(modelId));
+    const useImageTags = resolution.useImageTags;
+    const resolvedCharacters = shot.characters
+        .map(name => series.characters.find(c => c.name.toUpperCase() === name.toUpperCase()))
+        .filter((c) => Boolean(c));
+    let characterElements;
+    let referenceSlots;
+    if (useImageTags) {
+        // Central slot allocator: character primaries first, then storyboard
+        // blocking plate (protected), location angles, second character angles —
+        // budgeted per model (9 on Seedance R2V). The @ImageN indices here are
+        // authoritative; the video generator pushes reference_image_urls in
+        // exactly this order.
+        const plan = buildReferenceSlotPlan(series, shot, modelId, {
+            characterNames: resolvedCharacters.map(c => c.name),
+        });
+        referenceSlots = plan.slots;
+        for (const note of plan.dropped) {
+            console.warn(`  ⚠ Reference budget: dropped ${note}`);
+        }
+        if (plan.characterSlotByName.size > 0) {
+            characterElements = resolvedCharacters
+                .filter(char => plan.characterSlotByName.has(char.name.toUpperCase()))
+                .map(char => ({
+                characterName: char.name,
+                elementIndex: plan.characterSlotByName.get(char.name.toUpperCase()),
+            }));
+        }
+    }
+    else if (useElements && resolvedCharacters.length > 0) {
+        characterElements = resolvedCharacters.slice(0, 2).map((char, index) => ({
+            characterName: char.name,
+            elementIndex: index + 1,
+        }));
+    }
+    const tagPrefix = useImageTags ? '@Image' : '@Element';
+    const parts = [];
+    const cameraTerm = CAMERA_TERMS[shot.cameraMovement.toLowerCase()] ?? shot.cameraMovement;
+    parts.push(`${cameraTerm}.`);
+    // Up-front identity declarations for @Image-tag models ("@Image1 is Bob").
+    // Restating the invariant identity per shot (rule 37) plus the explicit
+    // tag→name binding keeps multi-reference prompts unambiguous for the model.
+    if (useImageTags && characterElements) {
+        for (const slot of characterElements) {
+            const char = resolvedCharacters.find(c => c.name.toUpperCase() === slot.characterName.toUpperCase());
+            if (!char)
+                continue;
+            const wardrobe = shot.episodeWardrobe?.[char.name.toUpperCase()] ?? char.wardrobe;
+            parts.push(`@Image${slot.elementIndex} is ${char.name} — wearing ${wardrobe}.`);
+        }
+    }
+    if ((useElements || useImageTags) && characterElements) {
+        let desc = shot.description;
+        for (const slot of characterElements) {
+            const re = new RegExp(`\\b${slot.characterName}\\b`, 'gi');
+            desc = desc.replace(re, `${tagPrefix}${slot.elementIndex}`);
+        }
+        parts.push(desc);
+    }
+    else {
+        parts.push(shot.description);
+    }
+    // NARRATOR / V.O. lines are voice-over — there is no on-camera speaker, so
+    // the line must never reach the video prompt. Including it is what makes
+    // Seedance synthesize its own competing English narrator. The line still
+    // lives in script.json for the assembler's TTS pass.
+    const dialogueSpeaker = shot.dialogue?.character?.toUpperCase();
+    const isVoiceOverLine = dialogueSpeaker === 'NARRATOR' || dialogueSpeaker === 'V.O.' || dialogueSpeaker === 'VO';
+    // Voice-reference slots: when the model can take reference audio, voice-refs
+    // aren't disabled, and the speaking character has a voice-donor clip, bind
+    // it in-prompt as @AudioN. The audioIndex here MUST match the push order of
+    // reference_audio_urls in the video generator (see resolveVoiceReferences).
+    const voiceRefEnabled = series.videoDefaults.voiceReferenceForDialogue !== false
+        && MODELS_SUPPORTING_REFERENCE_AUDIO.has(modelId);
+    let voiceReferenceSlots;
+    if (voiceRefEnabled && shot.dialogue && !isVoiceOverLine) {
+        // Multi-speaker: the dialogue speaker gets @Audio1; every OTHER on-screen
+        // character with a voice-donor clip gets the next slot (Venice budget:
+        // ≤3 clips, ≤15s aggregate — enforced downstream in renderVideoFile).
+        // This keeps each character's voice right even when the model improvises
+        // reactions/off-lines for non-speaking characters.
+        const slots = [];
+        const speakerUpper = shot.dialogue.character.toUpperCase();
+        const speakingChar = series.characters.find(c => c.name.toUpperCase() === speakerUpper);
+        if (speakingChar?.voiceReferencePath) {
+            slots.push({ characterName: speakingChar.name, audioIndex: slots.length + 1 });
+        }
+        for (const charName of shot.characters) {
+            if (charName.toUpperCase() === speakerUpper)
+                continue;
+            if (slots.length >= 3)
+                break;
+            const char = series.characters.find(c => c.name.toUpperCase() === charName.toUpperCase());
+            if (char?.voiceReferencePath) {
+                slots.push({ characterName: char.name, audioIndex: slots.length + 1 });
+            }
+        }
+        if (slots.length > 0)
+            voiceReferenceSlots = slots;
+    }
+    if (shot.dialogue && !isVoiceOverLine) {
+        const speakingChar = series.characters.find(c => c.name.toUpperCase() === shot.dialogue.character.toUpperCase());
+        const voiceDesc = speakingChar?.voiceDescription ?? '';
+        const delivery = shot.dialogue.delivery || '';
+        const charRef = (useElements || useImageTags) && characterElements
+            ? (characterElements.find(s => s.characterName.toUpperCase() === shot.dialogue.character.toUpperCase())
+                ? `${tagPrefix}${characterElements.find(s => s.characterName.toUpperCase() === shot.dialogue.character.toUpperCase()).elementIndex}`
+                : shot.dialogue.character)
+            : shot.dialogue.character;
+        const voiceParts = [voiceDesc, delivery].filter(Boolean).join(', ');
+        parts.push(`[${charRef}, ${voiceParts}]: "${shot.dialogue.line}"`);
+        // Bind the voice-donor clip. @AudioN carries voice identity ONLY; the
+        // model should still render clean studio dialogue for the line above.
+        const slot = voiceReferenceSlots?.find(s => s.characterName.toUpperCase() === shot.dialogue.character.toUpperCase());
+        if (slot) {
+            parts.push(`Use @Audio${slot.audioIndex} only for voice identity — timbre, accent, pacing; ` +
+                `regenerate clean studio dialogue, do not copy any noise from the reference.`);
+        }
+        // Bind the remaining voice-donor clips to their characters so any
+        // improvised lines/reactions from non-speaking characters use the
+        // right voice too.
+        for (const other of voiceReferenceSlots ?? []) {
+            if (slot && other.audioIndex === slot.audioIndex)
+                continue;
+            const otherCharSlot = characterElements?.find(s => s.characterName.toUpperCase() === other.characterName.toUpperCase());
+            const otherRef = otherCharSlot ? `${tagPrefix}${otherCharSlot.elementIndex}` : other.characterName;
+            parts.push(`@Audio${other.audioIndex} is ${otherRef}'s voice — use it only if ${otherRef} speaks.`);
+        }
+    }
+    if (shot.sfx) {
+        parts.push(`Sound of ${shot.sfx}.`);
+    }
+    // Scene image refs use @Image tags — offset indices when image tags are
+    // already used for character refs so tags don't collide.
+    if (shot.sceneImagePaths && shot.sceneImagePaths.length > 0 && MODELS_SUPPORTING_SCENE_IMAGES.has(modelId)) {
+        const sceneOffset = useImageTags ? (characterElements?.length ?? 0) : 0;
+        const refs = shot.sceneImagePaths.slice(0, 4).map((_, i) => `@Image${sceneOffset + i + 1}`);
+        parts.push(`Scene style references: ${refs.join(', ')}.`);
+    }
+    // Location environment description. When the shot is tagged with a location,
+    // inject its locked description + lighting so consecutive shots in the same
+    // place stay consistent (anti-pattern 7).
+    let locationEnvSlot;
+    if (shot.location) {
+        const loc = getLocation(series, shot.location);
+        if (loc) {
+            const envNote = [loc.description, loc.lightingNotes ? `Lighting: ${loc.lightingNotes}.` : '']
+                .filter(Boolean).join(' ');
+            if (envNote)
+                parts.push(`Location: ${envNote}`);
+        }
+    }
+    // Role clauses for every non-primary-character reference slot (storyboard
+    // blocking plates, location angles, second character angles). The clause
+    // text lives on the slot itself (reference-slots.ts) so the prompt and the
+    // reference_image_urls array can never disagree about what @ImageN means.
+    if (useImageTags && referenceSlots) {
+        for (const slot of referenceSlots) {
+            if (slot.kind === 'character-primary')
+                continue; // named via description substitution
+            parts.push(`@Image${slot.imageIndex} ${slot.roleClause}.`);
+        }
+        const firstLocationSlot = referenceSlots.find(s => s.kind === 'location');
+        if (firstLocationSlot) {
+            locationEnvSlot = { slug: firstLocationSlot.label, imageIndex: firstLocationSlot.imageIndex };
+        }
+        const sbSlot = referenceSlots.find(s => s.kind === 'storyboard');
+        if (sbSlot) {
+            parts.push('Every reference must stay consistent across space and time: characters keep their ' +
+                'appearance, the location keeps its geography, and the blocking follows ' +
+                `@Image${sbSlot.imageIndex} even as the camera angle changes.`);
+        }
+    }
+    let aestheticStr = buildAestheticString(series.aesthetic);
+    if (isDaytimeShot(shot)) {
+        aestheticStr = stripDarkAesthetic(aestheticStr);
+        parts.push('Bright daytime scene, natural light, no rain.');
+    }
+    parts.push(aestheticStr + '.');
+    parts.push(VIDEO_NO_MUSIC_SUFFIX);
+    if (isVoiceOverLine) {
+        // The VO line was withheld from the prompt above; also tell the model
+        // explicitly that this shot carries no speech, so its audio track is
+        // ambient + SFX only (the Venice TTS narrator is mixed in by the
+        // assembler).
+        parts.push('No narration, no voice-over, no spoken words in this shot.');
+    }
+    const videoPrompt = parts.join(' ');
+    // Decide whether to ask the video model to synthesize audio. Default is
+    // `true` — ambient sound and SFX from the model are wanted even on
+    // narrator-VO shots (the VO line never reaches the prompt, see above, so
+    // there is no competing narrator to suppress). Audio is only disabled when:
+    //   - the episode's audio mix has opted into suppressModelNarration for
+    //     every dialogue-bearing shot, or
+    //   - the shot has nativeAudio === 'mute' (per-shot override).
+    // Callers that need the native track regardless can flip nativeAudio: 'keep'.
+    const suppressGlobal = episodeAudioMix?.suppressModelNarration === true && Boolean(shot.dialogue);
+    const muteByOverride = shot.nativeAudio === 'mute';
+    const keepByOverride = shot.nativeAudio === 'keep';
+    const audio = keepByOverride
+        ? true
+        : (suppressGlobal || muteByOverride)
+            ? false
+            : true;
+    return {
+        prompt: videoPrompt,
+        model: modelId,
+        duration: shot.duration,
+        audio,
+        characterElements,
+        sceneImagePaths: shot.sceneImagePaths,
+        voiceReferenceSlots,
+        locationEnvSlot,
+        referenceSlots,
+        referenceImageUrls: useRefs ? [] : undefined,
+        modelResolution: resolution,
+    };
+}
+export function buildKlingMultiShotPrompt(shots, unit, series) {
+    if (!series.aesthetic) {
+        throw new Error('Series aesthetic must be set before generating videos.');
+    }
+    const uniqueCharNames = Array.from(new Set(shots.flatMap(shot => shot.characters.map(name => name.toUpperCase()))));
+    const uniqueCharacters = uniqueCharNames
+        .map(name => series.characters.find(char => char.name.toUpperCase() === name))
+        .filter((char) => Boolean(char));
+    // Build element slots for identity anchoring (Kling O3 Pro supports elements)
+    const useElements = MODELS_SUPPORTING_ELEMENTS.has(KLING_MULTISHOT_MODEL);
+    let characterElements;
+    if (useElements && uniqueCharacters.length > 0) {
+        characterElements = uniqueCharacters.slice(0, 2).map((char, index) => ({
+            characterName: char.name,
+            elementIndex: index + 1,
+        }));
+    }
+    const useRefs = MODELS_SUPPORTING_REFERENCE_IMAGES.has(KLING_MULTISHOT_MODEL);
+    const wardrobeByChar = new Map();
+    for (const shot of shots) {
+        if (!shot.episodeWardrobe)
+            continue;
+        for (const [charName, wardrobe] of Object.entries(shot.episodeWardrobe)) {
+            if (!wardrobeByChar.has(charName.toUpperCase())) {
+                wardrobeByChar.set(charName.toUpperCase(), wardrobe);
+            }
+        }
+    }
+    // --- Kling 3.0 native multi-shot prompt structure ---
+    // Per https://blog.fal.ai/kling-3-0-prompting-guide/:
+    // 1. Define core subjects up front with @Element refs and traits
+    // 2. State shot count and continuity instruction
+    // 3. Label each shot as "Shot N (Xs):" with cinematic direction
+    // 4. Use [Character, voice description]: "dialogue" format
+    // 5. Use "Immediately," between shots for temporal control
+    // 6. Append compact aesthetic and audio instructions
+    const parts = [];
+    // Subject definition block — Kling 3.0 locks these across all shots
+    if (uniqueCharacters.length > 0) {
+        for (const char of uniqueCharacters) {
+            const slot = characterElements?.find(s => s.characterName.toUpperCase() === char.name.toUpperCase());
+            const wardrobe = wardrobeByChar.get(char.name.toUpperCase()) ?? char.wardrobe;
+            const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+            const label = slot ? `@Element${slot.elementIndex}` : char.name;
+            parts.push(`${label} is ${char.name}: ${char.age}, ${baseTraits}, ${char.description}. Wearing ${wardrobe}.`);
+        }
+    }
+    parts.push(`\n${shots.length}-shot continuous sequence. Lock face, wardrobe, and environment across all shots.\n`);
+    // Per-shot blocks with Kling 3.0 dialogue format
+    for (let index = 0; index < shots.length; index++) {
+        const shot = shots[index];
+        const cameraTerm = CAMERA_TERMS[shot.cameraMovement.toLowerCase()] ?? shot.cameraMovement;
+        const shotParts = [];
+        shotParts.push(`Shot ${index + 1} (${parseShotDuration(shot.duration)}s): ${cameraTerm}.`);
+        let desc = shot.description;
+        if (useElements && characterElements) {
+            for (const slot of characterElements) {
+                const re = new RegExp(`\\b${slot.characterName}\\b`, 'gi');
+                desc = desc.replace(re, `@Element${slot.elementIndex}`);
+            }
+        }
+        shotParts.push(desc);
+        // Kling 3.0 dialogue format: [Character, voice description]: "line"
+        if (shot.dialogue) {
+            const speakingChar = series.characters.find(c => c.name.toUpperCase() === shot.dialogue.character.toUpperCase());
+            const voiceDesc = speakingChar?.voiceDescription ?? '';
+            const delivery = shot.dialogue.delivery || '';
+            const charRef = useElements && characterElements
+                ? (characterElements.find(s => s.characterName.toUpperCase() === shot.dialogue.character.toUpperCase())
+                    ? `@Element${characterElements.find(s => s.characterName.toUpperCase() === shot.dialogue.character.toUpperCase()).elementIndex}`
+                    : shot.dialogue.character)
+                : shot.dialogue.character;
+            const voiceParts = [voiceDesc, delivery].filter(Boolean).join(', ');
+            shotParts.push(`[${charRef}, ${voiceParts}]: "${shot.dialogue.line}"`);
+        }
+        if (shot.sfx) {
+            shotParts.push(`Sound: ${shot.sfx}.`);
+        }
+        parts.push(shotParts.join('\n'));
+        // Temporal separator between shots
+        if (index < shots.length - 1) {
+            parts.push('\nImmediately, cut to:\n');
+        }
+    }
+    const anyDaytime = shots.some(s => isDaytimeShot(s));
+    let compactAesthetic = buildCompactAestheticString(series.aesthetic);
+    if (anyDaytime) {
+        compactAesthetic = stripDarkAesthetic(compactAesthetic);
+        parts.push('Bright daytime scene, natural light, no rain.');
+    }
+    parts.push(`Visual style: ${compactAesthetic}.`);
+    parts.push(VIDEO_NO_MUSIC_SUFFIX);
+    let prompt = parts.join(' ').trim();
+    const VENICE_PROMPT_LIMIT = 2500;
+    if (prompt.length > VENICE_PROMPT_LIMIT) {
+        console.warn(`  Multi-shot prompt is ${prompt.length} chars (limit: ${VENICE_PROMPT_LIMIT}). Truncating aesthetic to fit.`);
+        const overBy = prompt.length - VENICE_PROMPT_LIMIT + 20;
+        const aestheticPart = buildCompactAestheticString(series.aesthetic);
+        const truncatedAesthetic = aestheticPart.slice(0, Math.max(40, aestheticPart.length - overBy));
+        parts[parts.length - 2] = `Visual style: ${truncatedAesthetic}.`;
+        prompt = parts.join(' ').trim();
+        if (prompt.length > VENICE_PROMPT_LIMIT) {
+            prompt = prompt.slice(0, VENICE_PROMPT_LIMIT);
+            console.warn(`  Prompt still over limit after truncation. Hard-cut to ${VENICE_PROMPT_LIMIT} chars.`);
+        }
+    }
+    return {
+        prompt,
+        model: KLING_MULTISHOT_MODEL,
+        duration: unit.duration,
+        audio: true,
+        characterElements,
+        referenceImageUrls: useRefs ? [] : undefined,
+    };
+}
+/**
+ * Build a character reference prompt within a per-model length cap.
+ *
+ * Returns just the positive prompt (string) for backwards compatibility.
+ * For the structured form that includes the recommended negative-prompt
+ * additions, use `buildCharacterReferencePromptParts`.
+ */
+export function buildCharacterReferencePrompt(char, aesthetic, angle, options) {
+    return buildCharacterReferencePromptParts(char, aesthetic, angle, options).positive;
+}
+/**
+ * Structured character-reference prompt that splits style and
+ * "no realism" cues into the negative prompt, keeping the positive prompt
+ * under the per-model cap.
+ *
+ * Discovered: above ~1800-2200 chars on seedream-v5-lite Venice silently
+ * rejects the request (panel returns < 30KB; see ). Moving STYLE
+ * REMINDER content to negative_prompt drops 60-80 chars and stops the
+ * silent rejections in production (Glass panel re-generation, v3 -> v4).
+ *
+ * The positive prompt keeps the most-important style cue + character
+ * anchor inline; everything else moves to negative_prompt.
+ */
+export function buildCharacterReferencePromptParts(char, aesthetic, angle, options) {
+    const baseTraits = char.baseTraits ?? (char.gender === 'female' ? FEMALE_BASE_TRAITS : MALE_BASE_TRAITS);
+    const cap = options?.maxChars
+        ?? getMaxPositivePromptChars(options?.model ?? 'seedream-v5-lite');
+    const anglePrompts = {
+        'front': 'front portrait, looking at camera, centered, studio lighting, neutral background',
+        'three-quarter': 'three-quarter view, 45 degree angle, studio lighting, neutral background',
+        'profile': 'side profile, 90 degree angle, studio lighting, neutral background',
+        'full-body': 'full body, head to toe, standing pose, studio lighting, neutral background',
+    };
+    // Style is a single front-loaded cue; the rest (palette, lensCharacteristics,
+    // film stock) move to negativeAdditions as anti-realism guards.
+    const styleCue = aesthetic.style;
+    // Build prompt parts in priority order. We greedily append until the cap
+    // is hit; the tail is dropped and the consumer can choose to push the
+    // dropped pieces into the negative prompt.
+    const parts = [
+        `STYLE: ${styleCue}.`,
+        `${anglePrompts[angle]}.`,
+        `${char.fullDescription}.`,
+        `${baseTraits}.`,
+        `${char.wardrobe}.`,
+    ];
+    let positive = '';
+    for (const p of parts) {
+        const candidate = positive ? `${positive} ${p}` : p;
+        if (candidate.length > cap)
+            break;
+        positive = candidate;
+    }
+    // If the very first part already exceeds the cap, hard-truncate.
+    if (!positive) {
+        positive = parts[0].slice(0, cap);
+    }
+    // Style-reminder content + photorealism guards belong on the negative side.
+    // They steer the model away from the wrong rendering family without eating
+    // positive-prompt budget.
+    //
+    // Strategy selects whether to emit anti-photoreal guards. For photoreal
+    // aesthetics ("documentary", "photograph", "cinematic photography") these
+    // guards fight the positives — the legislator-as-bird and founder-as-bird
+    // regressions in the PNW field-guide episode were caused exactly by this.
+    const strategy = options?.negativePromptStrategy ?? 'auto';
+    const wantsAntiPhotoreal = strategy === 'stylized'
+        ? true
+        : strategy === 'photoreal' || strategy === 'none'
+            ? false
+            : !isPhotorealAesthetic(aesthetic);
+    if (strategy === 'none') {
+        return { positive, negativeAdditions: [] };
+    }
+    const antiPhotorealParts = wantsAntiPhotoreal
+        ? ['photorealistic', 'photograph', 'photo', '3D render', 'Pixar']
+        : [];
+    const negativeAdditions = [
+        aesthetic.filmStock ? `not ${aesthetic.filmStock}` : null,
+        aesthetic.palette && wantsAntiPhotoreal ? `not ${aesthetic.palette}` : null,
+        ...antiPhotorealParts,
+        'no text',
+        'no labels',
+        'no annotations',
+        'no inset panels',
+        'no detail callouts',
+        'no multi-view layout',
+    ].filter((s) => Boolean(s));
+    return { positive, negativeAdditions };
+}
+/**
+ * Detect a photoreal series aesthetic from natural-language fields so
+ * `negativePromptStrategy: 'auto'` can do the right thing without making
+ * the user spell it out. We check `style`, `lensCharacteristics`,
+ * `filmStock`, and a `notes` field (when present) for any of:
+ *   photoreal, photograph, photo, documentary, live action, naturalist,
+ *   cinematic photography
+ *
+ * This is a precision-over-recall heuristic — anything close to photoreal
+ * suppresses the anti-photoreal guards. Operators who want the legacy
+ * behaviour back can flip `negativePromptStrategy: 'stylized'`.
+ */
+function isPhotorealAesthetic(aesthetic) {
+    const blob = [
+        aesthetic.style,
+        aesthetic.lensCharacteristics,
+        aesthetic.filmStock,
+        aesthetic.notes,
+    ]
+        .filter((s) => typeof s === 'string')
+        .join(' ')
+        .toLowerCase();
+    return /\b(photoreal|photograph|photo|documentary|live[- ]action|naturalist|cinematic photography|nature[- ]documentary)\b/.test(blob);
+}
+//# sourceMappingURL=prompt-builder.js.map