diff --git a/README.md b/README.md
index 67dcb97..b43966d 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,54 @@ Direct Webcam capture workflow (without webcam app)
 ![workflow (40)](https://github.com/toyxyz/ComfyUI_toyxyz_test_nodes/assets/8006000/cac4b89b-c2a1-4007-8906-fb8de9e26213)
 (Workflow embedded)
 
+## Minimax-H3-prompter
+
+Builds structured MiniMax H3 audiovisual prompts from a shot timeline and optional image, video,
+and audio references. It supports `Auto`, `T2VA`, `I2VA`, `FL2VA`, `L2VA`, and `REF2VA`.
+
+### Quick start
+
+1. Select a mode, duration, and model. `Auto` chooses a mode from the reference layout.
+2. Describe each shot naturally in **Prompt**, including actions, camera direction, dialogue,
+   visible text, sound, and music.
+3. Add assets with **+ Image**, **+ Video**, or **+ Audio**. Enter aliases as plain words, then
+   type `@` in Prompt to insert one from the alias menu.
+4. Arrange and resize shots on the timeline. The total always remains equal to the target duration.
+5. Press **Generate Prompt**. Press it again while it displays **Stop** to cancel generation.
+
+The last successful prompt remains available while inputs are edited and is replaced only after a
+new generation succeeds.
+
+### Models
+
+- **Qwen3.8 Q4_K_M + Vision F16:** supports all modes, including `REF2VA`, and analyzes image
+  references plus duration-limited video frames.
+- **LightX2V MiniMax-H3 Prompt Rewriter 8B Q8_0 + Vision F16:** supports `T2VA`, `I2VA`,
+  `FL2VA`, and `L2VA`; it does not support `REF2VA/R2V`.
+
+Missing model files download only after confirmation. With Qwen3.8, enable **Enhance** for a richer
+single-pass expansion or disable it for a shorter, fidelity-first result. LightX2V uses its own
+expansion behavior.
+
+### References
+
+- **Image:** choose `First frame`, `Last frame`, or `Subject`. Subject preservation can be `Weak`,
+  `Normal`, or `Strong`; Strong also retains the source visual medium/style.
+- **Video:** preserve video editing, continuation, motion/action timing, camera movement, or cuts and
+  temporal structure. Analysis uses only the configured leading duration.
+- **Audio:** guide the target with a source signal, voice, music, rhythm, ambience, or timing.
+
+References are numbered independently as `<Picture N>`, `<Video N>`, and `<Audio N>`. Their order in
+the node must match the downstream H3 reference-slot order.
+
+### Outputs
+
+- `generated_prompt` — latest successfully generated H3 prompt
+- `length` — H3-aligned frame count on the 24fps `17k+5` grid
+- `image_N` — uploaded image references in slot order
+- `video_N` — ComfyUI VIDEO references resampled to 24fps and trimmed to `length`; shorter videos
+  return only their available duration
+- `audio_N` — uploaded audio references trimmed to the target duration
 
 ## Visual area mask
 
diff --git a/__init__.py b/__init__.py
index f5d3eca..01ff7c4 100644
--- a/__init__.py
+++ b/__init__.py
@@ -6,6 +6,7 @@ from .nodes.crop_area_mask import CropAreaMask
 from .nodes.draw_area_mask import DrawAreaMask
 from .nodes.toyxyz_test_nodes import CaptureWebcam, LoadWebcamImage, LoadImageFromPath, SaveImagetoPath, LatentDelay, ImageResize_Padding, Direct_screenCap, Depth_to_normal, Remove_noise, Export_glb, Load_Random_Text_From_File
 from .nodes.visual_area_mask import VisualAreaMask
+from .nodes.minimax_h3_prompter import MinimaxH3Prompter
 from .openposeeditor.openpose_editor_nodes import OpenposeEditorNode, PoseToMaskNode
 from .openposeeditor.poseinter import Pose_Inter, PoseKeypointToCoordStr, JoinPose
 from .TiledDiffusion import NODE_CLASS_MAPPINGS as TD_NCM, NODE_DISPLAY_NAME_MAPPINGS as TD_NDNM
@@ -22,6 +23,7 @@ NODE_CLASS_MAPPINGS = {
     "CropAreaMask": CropAreaMask,
     "DrawAreaMask": DrawAreaMask,
     "VisualAreaMask": VisualAreaMask,
+    "MinimaxH3Prompter": MinimaxH3Prompter,
     "CaptureWebcam": CaptureWebcam,
     "LoadWebcamImage": LoadWebcamImage,
     "LoadImageFromPath": LoadImageFromPath,
@@ -54,6 +56,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "CropAreaMask": "Crop area mask",
     "DrawAreaMask": "Draw area mask",
     "VisualAreaMask": "Visual Area Mask",
+    "MinimaxH3Prompter": "Minimax-H3-prompter",
     "CaptureWebcam": "Capture Webcam",
     "LoadWebcamImage": "Load Webcam Image",
     "LoadImageFromPath": "Load Image From Path",
diff --git a/nodes/minimax_h3_lightx2v_system_prompts.json b/nodes/minimax_h3_lightx2v_system_prompts.json
new file mode 100644
index 0000000..9cdd148
--- /dev/null
+++ b/nodes/minimax_h3_lightx2v_system_prompts.json
@@ -0,0 +1,10 @@
+{
+  "source": "lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B prompt_template.py",
+  "system": "You are a professional MiniMax-H3 prompt rewriter for joint video-and-audio generation.\n\nRewrite the user's request according to the supplied duration, task type, and reference-frame roles. Return only the final production-ready prompt. Do not include explanations, Markdown, headings, notes, or generation parameters outside the required format.\n\nTask-name mapping: T2AV corresponds to T2VA, I2AV to I2VA, FL2AV to FL2VA, and L2AV to L2VA.\n\nWrite descriptive sections in English. Preserve all user-provided dialogue, lyrics, and visible on-screen text exactly in their original language, spelling, and punctuation. Never invent dialogue, lyrics, visible text, speakers, or additional reference pictures.\n\nThe output body contains exactly these fields in order: integrated_multimodal_description, overall_soundscape, non_diegetic_music. T2AV begins directly with these fields. I2AV begins exactly with: For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced. FL2AV begins with: How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot N) aligns with the S.SS-second mark of the target video. L2AV begins with: How the reference pictures align with the target video — <Picture 1> (from [Shot N]) aligns with the S.SS-second mark of the target video. Replace N with the final shot number and S.SS with the supplied effective end time. Put one blank line before integrated_multimodal_description.\n\nI2AV treats Picture 1 as the exact first frame and develops forward through observable motion. FL2AV follows a continuous physically plausible path from Picture 1 to the exact final state in Picture 2, preferring one shot unless cuts are requested. L2AV infers a plausible preceding state and progressively converges to Picture 1 as the exact final frame. Preserve identity and scene continuity; exact composition matching applies at each frame's assigned timestamp.\n\nBegin integrated_multimodal_description with [Shot 1]. Describe concrete visible or audible events, sequential shots, physically plausible actions, camera behavior, dialogue, visible text, and synchronized sound. Do not timestamp Shot 1. Begin later shots with their strictly increasing supplied timestamps. Do not add, remove, merge, split, duplicate, or renumber supplied shots. Add a cut only for meaningful new information.\n\nAssign stable (S1), (S2), and later IDs only to vocalizing subjects. Identify each speaker. Put only exact supplied content inside <d> after one language tag. Never translate, correct, or extend it. Voiceover uses says in an off-screen voiceover and keeps the on-screen character's lips closed. Use <scenetrans> across a cut and <cutoff> only for intentional end truncation. Quote visible text exactly.\n\noverall_soundscape is one concise English paragraph containing ambience, physical sounds, and non-verbal sounds, without dialogue, singing, or diegetic music. Use N/A only for explicit silence. non_diegetic_music describes only audience-only music through instrumentation, tempo, rhythm, and dynamics; use N/A when it is not requested or implied. Preserve user intent without contradictory events, identities, text, references, or invented consequences.",
+  "task_messages": {
+    "t2av": [],
+    "i2av": ["Picture 1 — exact first frame at 0.00 seconds:\n", "image"],
+    "l2av": ["Picture 1 — exact final frame at the end of the target video:\n", "image"],
+    "fl2av": ["Picture 1 — exact first frame at 0.00 seconds:\n", "image", "\nPicture 2 — exact final frame at the end of the target video:\n", "image"]
+  }
+}
diff --git a/nodes/minimax_h3_prompter.py b/nodes/minimax_h3_prompter.py
new file mode 100644
index 0000000..ba966f1
--- /dev/null
+++ b/nodes/minimax_h3_prompter.py
@@ -0,0 +1,4174 @@
+import base64
+import copy
+import glob
+import json
+import math
+import mimetypes
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from contextlib import contextmanager
+from typing import Any
+
+
+MODEL_FPS = 24
+MIN_SHOT_DURATION = 0.25
+CURRENT_PROJECT_VERSION = 20
+SUPPORTED_MODES = ("AUTO", "T2VA", "I2VA", "FL2VA", "L2VA", "REF2VA")
+SUPPORTED_DIALOGUE_MODES = ("spoken", "voiceover", "singing")
+SUPPORTED_TRANSITIONS = ("cut", "cross-dissolve", "fade", "wipe")
+SUPPORTED_LANGUAGES = (
+    "Arabic", "Chinese", "English", "French", "German", "Italian",
+    "Japanese", "Korean", "Portuguese", "Russian", "Spanish",
+)
+REFERENCE_ROLES = {
+    "picture": ("first_frame", "last_frame", "subject_identity"),
+    "video": ("none", "video_editing", "video_continuation", "motion", "camera", "cuts_rhythm"),
+    "audio": (
+        "none", "full_signal_copy", "partial_signal_copy", "voice_delivery",
+        "dialogue_lyrics", "sound_ambience", "music_rhythm",
+    ),
+}
+SUBJECT_STRENGTHS = ("weak", "normal", "strong")
+MAX_REF_IMAGES = 9
+MAX_REF_VIDEOS = 3
+MAX_REF_AUDIOS = 3
+MAX_REF_FILES = 12
+REF_VIDEO_MIN_SECONDS = 2.0
+REF_VIDEO_MAX_SECONDS = 15.0
+REF_VIDEO_TOTAL_SECONDS = 15.0
+VIDEO_EXTENSIONS = {".mp4", ".webm", ".mov", ".mkv", ".avi", ".m4v"}
+AUDIO_EXTENSIONS = {".wav", ".mp3", ".flac", ".ogg", ".m4a", ".aac", ".opus"}
+VIDEO_UPLOAD_MAX_BYTES = 2 * 1024 * 1024 * 1024
+VIDEO_ANALYSIS_MAX_FRAMES = 10
+DEFAULT_ENHANCE_MODEL_ID = "hf:JonathanColetti/Qwen3.8-27B-Uncensored-GGUF/Qwen3.8-27B-Uncensored-Q4_K_M.gguf"
+DEFAULT_ENHANCE_MODEL_REPO = "JonathanColetti/Qwen3.8-27B-Uncensored-GGUF"
+DEFAULT_ENHANCE_MODEL_FILE = "Qwen3.8-27B-Uncensored-Q4_K_M.gguf"
+DEFAULT_ENHANCE_MODEL_SIZE = 16810714528
+QWEN_IMAGE_MODEL_ID = "hf:JonathanColetti/Qwen3.8-27B-Uncensored-GGUF/Q4_K_M+vision-f16"
+DEFAULT_IMAGE_MODEL_ID = QWEN_IMAGE_MODEL_ID
+QWEN_IMAGE_MODEL_REPO = DEFAULT_ENHANCE_MODEL_REPO
+QWEN_IMAGE_MODEL_FILE = DEFAULT_ENHANCE_MODEL_FILE
+QWEN_IMAGE_MMPROJ_FILE = "Qwen3.8-27B-Uncensored-vision-f16.gguf"
+QWEN_IMAGE_MODEL_SIZE = DEFAULT_ENHANCE_MODEL_SIZE
+QWEN_IMAGE_MMPROJ_SIZE = 927606912
+QWEN_MODEL_DISPLAY_NAME = "JonathanColetti/Qwen3.8-27B-Uncensored-GGUF · Q4_K_M + Vision F16"
+QWEN_MODEL_VRAM_LABEL = "VRAM ≈ 20–22 GB"
+LEGACY_LIGHTX2V_MODEL_ID = "hf:lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B"
+LIGHTX2V_MODEL_ID = "hf:indhic-ai/MiniMax_H3-Prompt_Rewriter-8B-LORA-Merged-GGUF/Q8_0+vision-f16"
+LIGHTX2V_MODEL_REPO = "indhic-ai/MiniMax_H3-Prompt_Rewriter-8B-LORA-Merged-GGUF"
+LIGHTX2V_MODEL_FILE = "minimax-h3-prompt-rewriter-8b-Q8_0.gguf"
+LIGHTX2V_MMPROJ_FILE = "mmproj-minimax-h3-prompt-rewriter-8b-f16.gguf"
+LIGHTX2V_MODEL_SIZE = 8710000000
+LIGHTX2V_MMPROJ_SIZE = 1160000000
+LIGHTX2V_TOTAL_SIZE = LIGHTX2V_MODEL_SIZE + LIGHTX2V_MMPROJ_SIZE
+LIGHTX2V_MODEL_DISPLAY_NAME = "indhic-ai/MiniMax_H3-Prompt_Rewriter-8B-LORA-Merged-GGUF · Q8_0 + Vision F16"
+LIGHTX2V_MODEL_VRAM_LABEL = "VRAM ≈ 10–12 GB"
+LIGHTX2V_SUPPORTED_MODES = ("T2VA", "I2VA", "FL2VA", "L2VA")
+LIGHTX2V_SYSTEM_PROMPTS_PATH = os.path.join(
+    os.path.dirname(__file__), "minimax_h3_lightx2v_system_prompts.json"
+)
+BASE_ENHANCE_MAX_NEW_TOKENS = 1800
+RICH_ENHANCE_MAX_NEW_TOKENS = 3072
+REF_ENHANCE_MAX_NEW_TOKENS = 3072
+ENHANCE_CONTEXT_SIZE = 16384
+_ENHANCE_LOCK = threading.Lock()
+_ENHANCE_JOBS: dict[str, dict[str, Any]] = {}
+_ENHANCE_JOBS_LOCK = threading.Lock()
+_ENHANCE_CANCEL_EVENTS: dict[str, threading.Event] = {}
+_ENHANCE_STOPPERS: dict[str, Any] = {}
+
+
+class EnhancementCancelled(RuntimeError):
+    pass
+
+
+def _set_enhance_job(job_id: str, **values: Any) -> None:
+    if not job_id:
+        return
+    with _ENHANCE_JOBS_LOCK:
+        job = _ENHANCE_JOBS.setdefault(job_id, {})
+        job.update(values)
+        job["updated_at"] = time.time()
+
+
+def _get_enhance_job(job_id: str) -> dict[str, Any]:
+    with _ENHANCE_JOBS_LOCK:
+        return dict(_ENHANCE_JOBS.get(job_id, {}))
+
+
+def _begin_enhance_job(job_id: str) -> threading.Event:
+    event = threading.Event()
+    with _ENHANCE_JOBS_LOCK:
+        _ENHANCE_CANCEL_EVENTS[job_id] = event
+        _ENHANCE_STOPPERS.pop(job_id, None)
+    return event
+
+
+def _set_enhance_stopper(job_id: str, stopper: Any | None) -> None:
+    with _ENHANCE_JOBS_LOCK:
+        if stopper is None:
+            _ENHANCE_STOPPERS.pop(job_id, None)
+        else:
+            _ENHANCE_STOPPERS[job_id] = stopper
+
+
+def _cancel_enhance_job(job_id: str) -> bool:
+    with _ENHANCE_JOBS_LOCK:
+        event = _ENHANCE_CANCEL_EVENTS.get(job_id)
+        stopper = _ENHANCE_STOPPERS.get(job_id)
+        if event is not None:
+            event.set()
+    if stopper is not None:
+        try:
+            stopper()
+        except Exception:
+            pass
+    if event is not None:
+        _set_enhance_job(job_id, stage="cancelled", message="Prompt generation stopped by the user.")
+    return event is not None
+
+
+def _finish_enhance_job(job_id: str) -> None:
+    with _ENHANCE_JOBS_LOCK:
+        _ENHANCE_CANCEL_EVENTS.pop(job_id, None)
+        _ENHANCE_STOPPERS.pop(job_id, None)
+
+
+DEFAULT_PROJECT = {
+    "version": CURRENT_PROJECT_VERSION,
+    "mode": "AUTO",
+    "requested_duration": 5.0,
+    "user_request": "",
+    "shots": [
+        {
+            "id": "shot-1",
+            "duration": 5.0,
+            "visual_action": "",
+        }
+    ],
+    "references": [],
+    "constraints": "",
+    "verbatim_content": "",
+    "enhance_model": DEFAULT_ENHANCE_MODEL_ID,
+    "image_model": DEFAULT_IMAGE_MODEL_ID,
+    "auto_run": False,
+    "enhance": False,
+    "enhanced_prompt": "",
+}
+
+
+CAMERA_SENTENCES = {
+    "Static Shot": "The camera holds a static shot.",
+    "Push In": "The camera pushes in toward the subject.",
+    "Pull Out": "The camera pulls out from the subject.",
+    "Zoom In": "The camera zooms in while remaining stationary.",
+    "Zoom Out": "The camera zooms out while remaining stationary.",
+    "Pan Left": "The camera pans left.",
+    "Pan Right": "The camera pans right.",
+    "Truck Left": "The camera trucks left.",
+    "Truck Right": "The camera trucks right.",
+    "Tilt Up": "The camera tilts up.",
+    "Tilt Down": "The camera tilts down.",
+    "Pedestal Up": "The camera pedestals up.",
+    "Pedestal Down": "The camera pedestals down.",
+    "Arc Shot": "The camera moves in an arc around the subject.",
+    "Tracking Shot": "The camera tracks the moving subject.",
+    "POV": "The shot uses the subject's point of view.",
+    "Shake Slightly": "The camera shakes slightly.",
+    "Shake Strongly": "The camera shakes strongly.",
+    "Roll Clockwise": "The camera rolls clockwise.",
+    "Roll Counterclockwise": "The camera rolls counterclockwise.",
+}
+
+CAMERA_ANGLE_SENTENCES = {
+    "Eye Level Shot": "The camera uses an eye-level angle.",
+    "Low Angle Shot": "The camera uses a low angle, looking upward at the subject.",
+    "High Angle Shot": "The camera uses a high angle, looking downward at the subject.",
+    "Bird's-Eye View": "The camera uses an extreme bird's-eye view from directly above.",
+    "Worm's-Eye View": "The camera uses an extreme worm's-eye view from below.",
+    "Overhead Shot": "The camera is positioned overhead and looks down on the scene.",
+    "Top-Down Shot": "The camera points straight down in a top-down view.",
+    "Ground-Level Shot": "The camera is positioned at ground level.",
+    "Dutch Angle Shot": "The camera uses a Dutch angle with a visibly tilted horizon.",
+    "Over-the-Shoulder Shot": "The camera uses an over-the-shoulder angle.",
+    "Point-of-View Shot": "The camera shows the scene from the subject's point of view.",
+    "Aerial Shot": "The camera uses a high aerial angle over the scene.",
+    "Three-Quarter Angle": "The camera views the subject from a three-quarter angle.",
+    "Profile Angle": "The camera views the subject in profile from the side.",
+    "Rear Angle": "The camera views the subject from behind.",
+}
+
+CAMERA_FRAMING_SENTENCES = {
+    "Extreme Close-Up Shot": "The composition uses an extreme close-up, isolating a very small facial or subject detail.",
+    "Close-Up Shot": "The composition uses a close-up, filling the frame with the subject's face or primary detail.",
+    "Medium Close-Up Shot": "The composition uses a medium close-up, framing the subject approximately from the chest upward.",
+    "Medium Shot": "The composition uses a medium shot, framing the subject approximately from the waist upward.",
+    "Cowboy Shot": "The composition uses a cowboy shot, framing the subject approximately from mid-thigh upward.",
+    "Medium Long Shot": "The composition uses a medium long shot, framing most of the subject while retaining environmental context.",
+    "Long Shot": "The composition uses a long shot, showing the full subject with substantial surrounding environment.",
+    "Full Shot": "The composition uses a full shot, keeping the subject's entire body visible in frame.",
+    "Wide Shot": "The composition uses a wide shot, emphasizing the environment and the subject's spatial context.",
+}
+
+TRANSITION_SENTENCES = {
+    "cut": "cut to a new shot.",
+    "cross-dissolve": "cross-dissolve into a new shot.",
+    "fade": "fade into a new shot.",
+    "wipe": "wipe into a new shot.",
+}
+
+
+SYSTEM_PROMPTS_PATH = os.path.join(os.path.dirname(__file__), "minimax_h3_system_prompts.json")
+
+
+def _load_system_prompt_config(path: str = SYSTEM_PROMPTS_PATH) -> dict[str, Any]:
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            config = json.load(handle)
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"Unable to load MiniMax H3 system prompts from {path}: {error}") from error
+
+    if not isinstance(config, dict):
+        raise RuntimeError(f"MiniMax H3 system prompt config must be a JSON object: {path}")
+    common = config.get("common")
+    common_enhanced = config.get("common_enhanced")
+    enhance_addendum = config.get("enhance_addendum", "")
+    action_semantics = config.get("action_semantics")
+    static_asset_rules = config.get("static_asset_rules")
+    common_addendum = config.get("common_addendum", "")
+    video_reference_common = config.get("video_reference_common")
+    video_reference_roles = config.get("video_reference_roles")
+    audio_reference_common = config.get("audio_reference_common")
+    audio_reference_roles = config.get("audio_reference_roles")
+    base = config.get("base")
+    mode_addenda = config.get("mode_addenda", {})
+    modes = config.get("modes")
+    if (
+        not isinstance(common, str)
+        or not isinstance(common_enhanced, str)
+        or not isinstance(enhance_addendum, str)
+        or not isinstance(action_semantics, str)
+        or not isinstance(static_asset_rules, dict)
+        or not isinstance(common_addendum, str)
+        or not isinstance(video_reference_common, str)
+        or not isinstance(video_reference_roles, dict)
+        or not isinstance(audio_reference_common, str)
+        or not isinstance(audio_reference_roles, dict)
+        or not isinstance(base, str)
+        or not isinstance(mode_addenda, dict)
+        or not isinstance(modes, dict)
+    ):
+        raise RuntimeError(
+            "MiniMax H3 system prompt config requires strings 'common', 'common_enhanced', "
+            "'common_addendum', 'enhance_addendum', 'action_semantics', 'video_reference_common', "
+            "'audio_reference_common', and 'base', objects 'video_reference_roles', "
+            "'audio_reference_roles', 'static_asset_rules', 'mode_addenda', "
+            f"and 'modes': {path}"
+        )
+
+    expected_video_roles = set(REFERENCE_ROLES["video"])
+    if set(video_reference_roles) != expected_video_roles or any(
+        not isinstance(video_reference_roles[key], str) for key in expected_video_roles
+    ):
+        raise RuntimeError(
+            "MiniMax H3 video_reference_roles must contain one string for every supported video role: "
+            f"{path}"
+        )
+
+    expected_audio_roles = set(REFERENCE_ROLES["audio"])
+    if set(audio_reference_roles) != expected_audio_roles or any(
+        not isinstance(audio_reference_roles[key], str) for key in expected_audio_roles
+    ):
+        raise RuntimeError(
+            "MiniMax H3 audio_reference_roles must contain one string for every supported audio role: "
+            f"{path}"
+        )
+
+    required_static_rules = {"common", "enhanced", "FL2VA", "FL2VA_enhanced"}
+    if set(static_asset_rules) != required_static_rules or any(
+        not isinstance(static_asset_rules[key], str) for key in required_static_rules
+    ):
+        raise RuntimeError(
+            "MiniMax H3 static_asset_rules requires string keys common, enhanced, FL2VA, "
+            f"and FL2VA_enhanced: {path}"
+        )
+
+    expected_modes = set(SUPPORTED_MODES) - {"AUTO"}
+    if set(modes) != expected_modes:
+        missing = sorted(expected_modes - set(modes))
+        extra = sorted(set(modes) - expected_modes)
+        raise RuntimeError(
+            f"MiniMax H3 system prompt modes do not match supported modes; missing={missing}, extra={extra}: {path}"
+        )
+    if any(not isinstance(modes[mode], str) for mode in expected_modes):
+        raise RuntimeError(f"Every MiniMax H3 mode prompt must be a string: {path}")
+    unknown_addenda = set(mode_addenda) - expected_modes
+    if unknown_addenda or any(not isinstance(value, str) for value in mode_addenda.values()):
+        raise RuntimeError(
+            f"MiniMax H3 mode addenda must be strings for supported modes only: {path}"
+        )
+    return {
+        "common": common,
+        "common_enhanced": common_enhanced,
+        "enhance_addendum": enhance_addendum,
+        "action_semantics": action_semantics,
+        "static_asset_rules": static_asset_rules,
+        "common_addendum": common_addendum,
+        "video_reference_common": video_reference_common,
+        "video_reference_roles": video_reference_roles,
+        "audio_reference_common": audio_reference_common,
+        "audio_reference_roles": audio_reference_roles,
+        "base": base,
+        "mode_addenda": mode_addenda,
+        "modes": modes,
+    }
+
+
+SYSTEM_PROMPT_CONFIG = _load_system_prompt_config()
+COMMON_LLM_SYSTEM_RULES = SYSTEM_PROMPT_CONFIG["common"]
+COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["action_semantics"]
+COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["static_asset_rules"]["common"]
+COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["common_addendum"]
+ENHANCED_COMMON_LLM_SYSTEM_RULES = SYSTEM_PROMPT_CONFIG["common_enhanced"]
+ENHANCED_COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["action_semantics"]
+ENHANCED_COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["static_asset_rules"]["common"]
+ENHANCED_COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["static_asset_rules"]["enhanced"]
+ENHANCED_COMMON_LLM_SYSTEM_RULES += SYSTEM_PROMPT_CONFIG["common_addendum"]
+BASE_LLM_SYSTEM_RULES = SYSTEM_PROMPT_CONFIG["base"]
+MODE_LLM_SYSTEM_PROMPTS = {
+    mode: COMMON_LLM_SYSTEM_RULES
+    + ("" if mode == "REF2VA" else BASE_LLM_SYSTEM_RULES)
+    + SYSTEM_PROMPT_CONFIG["modes"][mode]
+    + SYSTEM_PROMPT_CONFIG["mode_addenda"].get(mode, "")
+    + (SYSTEM_PROMPT_CONFIG["static_asset_rules"]["FL2VA"] if mode == "FL2VA" else "")
+    for mode in SUPPORTED_MODES
+    if mode != "AUTO"
+}
+ENHANCED_MODE_LLM_SYSTEM_PROMPTS = {
+    mode: ENHANCED_COMMON_LLM_SYSTEM_RULES
+    + ("" if mode == "REF2VA" else BASE_LLM_SYSTEM_RULES)
+    + SYSTEM_PROMPT_CONFIG["modes"][mode]
+    + SYSTEM_PROMPT_CONFIG["mode_addenda"].get(mode, "")
+    + (SYSTEM_PROMPT_CONFIG["static_asset_rules"]["FL2VA"] if mode == "FL2VA" else "")
+    + (SYSTEM_PROMPT_CONFIG["static_asset_rules"]["FL2VA_enhanced"] if mode == "FL2VA" else "")
+    + SYSTEM_PROMPT_CONFIG["enhance_addendum"]
+    for mode in SUPPORTED_MODES
+    if mode != "AUTO"
+}
+
+
+def _clean_text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _normalize_alias(value: Any) -> str:
+    alias = _clean_text(value).lstrip("@").strip()
+    alias = re.sub(r"\s+", "_", alias)
+    alias = re.sub(r"[^\w-]", "", alias, flags=re.UNICODE)
+    return f"@{alias}" if alias else ""
+
+
+def _number(value: Any, default: float) -> float:
+    try:
+        result = float(value)
+    except (TypeError, ValueError):
+        return default
+    return result if math.isfinite(result) else default
+
+
+def _contains_hangul(text: str) -> bool:
+    return any("\uac00" <= character <= "\ud7a3" for character in text)
+
+
+_INLINE_QUOTE_RE = re.compile(
+    r'"([^"\r\n]+)"|“([^”\r\n]+)”|‘([^’\r\n]+)’|「([^」\r\n]+)」'
+)
+_VOCAL_CUE_RE = re.compile(
+    r"말(?:한다|하며|하고|했다|하다|해)|외치|소리치|속삭|노래|부르|대사|보이스오버|"
+    r"\b(?:say|says|said|speak|speaks|shout|shouts|whisper|whispers|sing|sings|voiceover)\b",
+    flags=re.IGNORECASE,
+)
+_VISIBLE_TEXT_CUE_RE = re.compile(
+    r"간판|화면|자막|문구|표지|라벨|텍스트|쓰여|적혀|표시|"
+    r"\b(?:sign|screen|caption|subtitle|label|banner|visible text|reads|written|displayed)\b",
+    flags=re.IGNORECASE,
+)
+
+
+def _inferred_dialogue_language(text: str) -> str:
+    if re.search(r"[\uac00-\ud7a3\u3131-\u318e]", text):
+        return "Korean"
+    if re.search(r"[\u3040-\u30ff]", text):
+        return "Japanese"
+    if re.search(r"[\u0600-\u06ff]", text):
+        return "Arabic"
+    if re.search(r"[\u0400-\u04ff]", text):
+        return "Russian"
+    if re.search(r"[\u3400-\u9fff]", text):
+        return "Chinese"
+    return "English"
+
+
+def _nearest_cue_distance(text: str, start: int, end: int, pattern: re.Pattern[str]) -> int | None:
+    distances = []
+    for match in pattern.finditer(text):
+        if match.end() < start:
+            distances.append(start - match.end())
+        elif match.start() > end:
+            distances.append(match.start() - end)
+        else:
+            distances.append(0)
+    return min(distances) if distances else None
+
+
+def _speaker_phrase_from_context(text: str, position: int) -> str:
+    before = text[:position]
+    candidates: list[tuple[int, str]] = []
+    patterns = (
+        (r"여성|여자", "the woman"),
+        (r"남성|남자", "the man"),
+        (r"소녀", "the girl"),
+        (r"소년", "the boy"),
+        (r"아이", "the child"),
+        (r"\bwoman\b", "the woman"),
+        (r"\bman\b", "the man"),
+        (r"\bgirl\b", "the girl"),
+        (r"\bboy\b", "the boy"),
+        (r"\bchild\b", "the child"),
+    )
+    for pattern, phrase in patterns:
+        matches = list(re.finditer(pattern, before, flags=re.IGNORECASE))
+        if matches:
+            candidates.append((matches[-1].start(), phrase))
+    return max(candidates, default=(-1, "the on-screen speaker"))[1]
+
+
+def _input_content_locks(project: dict[str, Any]) -> list[str]:
+    """Extract lightweight pre-generation locks without adding another LLM pass."""
+    detected: list[dict[str, Any]] = []
+    generic_vocal_shots: list[int] = []
+    for shot_number, shot in enumerate(project.get("shots", []), 1):
+        action = _clean_text(shot.get("visual_action"))
+        if not action:
+            continue
+        occupied: list[tuple[int, int]] = []
+        for match in re.finditer(
+            r"<d>\s*\[([^\]\r\n]+)\]\s*(.*?)\s*</d>",
+            action,
+            flags=re.DOTALL | re.IGNORECASE,
+        ):
+            prefix = action[max(0, match.start() - 120):match.start()]
+            speaker_match = re.search(r"\((S[1-6](?:,S[1-6])*)\)[^()]*$", prefix, flags=re.IGNORECASE)
+            identity_match = re.search(
+                r"(?:^|[.!?\n])\s*([^.!?\n]{1,100}?)\s*\(S[1-6](?:,S[1-6])*\)[^()]*$",
+                prefix,
+                flags=re.IGNORECASE,
+            )
+            lowered_prefix = prefix.lower()
+            if "says in an off-screen voiceover:" in lowered_prefix:
+                vocal_form = "says in an off-screen voiceover:"
+            elif "sings:" in lowered_prefix:
+                vocal_form = "sings:"
+            else:
+                vocal_form = "says:"
+            detected.append({
+                "shot": shot_number,
+                "kind": "vocal",
+                "words": match.group(2).strip(),
+                "language": match.group(1).strip(),
+                "speaker": speaker_match.group(1).upper() if speaker_match else "",
+                "speaker_phrase": identity_match.group(1).strip() if identity_match else _speaker_phrase_from_context(
+                    action, match.start()
+                ),
+                "vocal_form": vocal_form,
+            })
+            occupied.append(match.span())
+
+        for match in _INLINE_QUOTE_RE.finditer(action):
+            if any(start <= match.start() and match.end() <= end for start, end in occupied):
+                continue
+            words = next(group for group in match.groups() if group is not None).strip()
+            if not words:
+                continue
+            vocal_distance = _nearest_cue_distance(action, match.start(), match.end(), _VOCAL_CUE_RE)
+            visible_distance = _nearest_cue_distance(action, match.start(), match.end(), _VISIBLE_TEXT_CUE_RE)
+            if vocal_distance is None and visible_distance is None:
+                continue
+            kind = "vocal" if visible_distance is None or (
+                vocal_distance is not None and vocal_distance <= visible_distance
+            ) else "visible"
+            local_context = action[max(0, match.start() - 80):min(len(action), match.end() + 80)].lower()
+            if re.search(r"노래|부르|\b(?:sing|sings|sang)\b", local_context):
+                vocal_form = "sings:"
+            elif re.search(r"보이스오버|voiceover", local_context):
+                vocal_form = "says in an off-screen voiceover:"
+            else:
+                vocal_form = "says:"
+            detected.append({
+                "shot": shot_number,
+                "kind": kind,
+                "words": words,
+                "language": _inferred_dialogue_language(words) if kind == "vocal" else "",
+                "speaker": "",
+                "speaker_phrase": _speaker_phrase_from_context(action, match.start()),
+                "vocal_form": vocal_form,
+            })
+        if _VOCAL_CUE_RE.search(action) and not any(
+            item["shot"] == shot_number and item["kind"] == "vocal" for item in detected
+        ):
+            generic_vocal_shots.append(shot_number)
+
+    vocal_items = [item for item in detected if item["kind"] == "vocal"]
+    if len(vocal_items) == 1 and not vocal_items[0]["speaker"]:
+        vocal_items[0]["speaker"] = "S1"
+
+    locks: list[str] = []
+    for item in detected:
+        exact_words = json.dumps(item["words"], ensure_ascii=False)
+        if item["kind"] == "visible":
+            locks.append(
+                f"[Shot {item['shot']}] visible text: preserve {exact_words} verbatim in English double quotes; "
+                "never put it in <d> or assign a speaker ID."
+            )
+            continue
+        speaker = f"({item['speaker']})" if item["speaker"] else "a stable parenthesized (Sx) ID"
+        tag = f"<d>[{item['language']}] {item['words']}</d>"
+        if item["speaker"]:
+            source_rule = (
+                "In REF2VA, identify a referenced visible speaker with the applicable <Subject N> label; "
+                "do not replace it with a generic noun. "
+                if str(project.get("mode", "")).upper() == "REF2VA"
+                else ""
+            )
+            locks.append(
+                f"[Shot {item['shot']}] vocal lock: copy this block character-for-character, including every "
+                f"space and punctuation mark: `{tag}`. Use speaker ID {speaker} once before the block and the "
+                f"vocal form `{item['vocal_form']}` once. Precede {speaker} with a visible speaker identity; "
+                f"never begin the clause with bare {speaker}. {source_rule}For on-screen speech or singing, add only one "
+                "short scene-specific lip-synchronization sentence. Never copy this instruction, a checklist, "
+                "or hypothetical event examples into the answer."
+            )
+        else:
+            locks.append(
+                f"[Shot {item['shot']}] vocal content: the identifying phrase must include {speaker} before "
+                f"the vocal block; reproduce exactly `{tag}` without changing spacing or punctuation. Unless "
+                "the input explicitly says voiceover, make this diegetic speech physically produced by the "
+                "visible speaker: the mouth must articulate every syllable in precise synchronization with the "
+                "voice and the lips may close only after the line ends."
+            )
+    for shot_number in generic_vocal_shots:
+        locks.append(
+            f"[Shot {shot_number}] contains explicit vocal content in visual_action: the first vocal source "
+            "must use (S1), and every vocal line must retain its inferred language and exact supplied words in "
+            "<d>. Unless explicitly requested as voiceover, the visible speaker must physically produce the "
+            "diegetic voice with natural mouth movement synchronized to every syllable; the lips close only "
+            "after the line ends."
+        )
+    return locks
+
+
+def align_frame_count(seconds: float) -> int:
+    frames = max(5, int(round(seconds * MODEL_FPS)))
+    while frames % 17 != 5:
+        frames += 1
+    return frames
+
+
+def format_timestamp(seconds: float) -> str:
+    seconds = max(0.0, seconds)
+    minutes = int(seconds // 60)
+    remainder = seconds - minutes * 60
+    return f"{minutes:02d}:{remainder:06.3f}"
+
+
+def _normalize_shot(raw: Any, index: int) -> dict[str, Any]:
+    raw = raw if isinstance(raw, dict) else {}
+    visual_action = _clean_text(raw.get("visual_action"))
+
+    # Version 12 and earlier stored dialogue and visible text in dedicated UI
+    # fields. Preserve those projects by moving their content into the unified
+    # natural-language Visual / action input exactly once.
+    legacy_dialogue = _clean_text(raw.get("dialogue"))
+    if legacy_dialogue:
+        language = _clean_text(raw.get("dialogue_language"))
+        language = language if language in SUPPORTED_LANGUAGES else "English"
+        speaker = _clean_text(raw.get("dialogue_speaker")).upper().strip("()")
+        speaker = speaker if re.fullmatch(r"S[1-6]", speaker) else "S1"
+        delivery = _clean_text(raw.get("dialogue_delivery")) or "The on-screen speaker"
+        mode = _clean_text(raw.get("dialogue_mode")).lower()
+        mode = mode if mode in SUPPORTED_DIALOGUE_MODES else "spoken"
+        wrapped = re.fullmatch(
+            r"<d>\s*(?:\[([^\]\r\n]+)\]\s*)?(.*?)\s*</d>",
+            legacy_dialogue,
+            flags=re.DOTALL | re.IGNORECASE,
+        )
+        if wrapped:
+            supplied_language, legacy_dialogue = wrapped.groups()
+            if supplied_language in SUPPORTED_LANGUAGES:
+                language = supplied_language
+        else:
+            legacy_dialogue = re.sub(r"</?d>", "", legacy_dialogue, flags=re.IGNORECASE).strip()
+        if mode == "voiceover":
+            migrated = (
+                f"{delivery} ({speaker}) says in an off-screen voiceover: "
+                f"<d>[{language}] {legacy_dialogue}</d> while the corresponding "
+                "on-screen character's lips remain completely closed."
+            )
+        elif mode == "singing":
+            migrated = f"{delivery} ({speaker}) sings: <d>[{language}] {legacy_dialogue}</d>"
+        else:
+            migrated = f"{delivery} ({speaker}) says: <d>[{language}] {legacy_dialogue}</d>"
+        visual_action = "\n".join(part for part in (visual_action, migrated) if part)
+
+    legacy_visible_text = _clean_text(raw.get("visible_text"))
+    if legacy_visible_text:
+        visible_instruction = (
+            f'A visible on-screen text element reads "{_quoted_prompt_text(legacy_visible_text)}".'
+        )
+        visual_action = "\n".join(part for part in (visual_action, visible_instruction) if part)
+
+    legacy_diegetic_sound = _clean_text(raw.get("diegetic_sound"))
+    if legacy_diegetic_sound:
+        sound_instruction = f"Synchronized physical sound: {legacy_diegetic_sound}"
+        visual_action = "\n".join(part for part in (visual_action, sound_instruction) if part)
+
+    # Version 14 and earlier stored camera choices in separate selectors.
+    # Preserve meaningful legacy choices once in the unified natural-language
+    # input, then drop the obsolete fields from the normalized schema.
+    legacy_camera: list[str] = []
+    framing = _clean_text(raw.get("camera_framing"))
+    angle = _clean_text(raw.get("camera_angle"))
+    motion = _clean_text(raw.get("camera_motion"))
+    if framing:
+        legacy_camera.append(
+            CAMERA_FRAMING_SENTENCES.get(framing, f"Camera framing: {framing}.")
+        )
+    if angle:
+        legacy_camera.append(
+            CAMERA_ANGLE_SENTENCES.get(angle, f"Camera angle: {angle}.")
+        )
+    if motion:
+        legacy_camera.append(
+            CAMERA_SENTENCES.get(motion, f"Camera motion: {motion}.")
+        )
+    transition = _clean_text(raw.get("transition")).lower()
+    if index > 0 and transition in SUPPORTED_TRANSITIONS and transition != "cut":
+        legacy_camera.append(f"Transition into this shot with a {transition}.")
+    if legacy_camera:
+        visual_action = "\n".join((visual_action, *legacy_camera)).strip()
+
+    return {
+        "id": _clean_text(raw.get("id")) or f"shot-{index + 1}",
+        "duration": max(MIN_SHOT_DURATION, _number(raw.get("duration"), 1.0)),
+        "visual_action": visual_action,
+    }
+
+
+def _normalize_reference(raw: Any, index: int) -> dict[str, Any]:
+    raw = raw if isinstance(raw, dict) else {}
+    ref_type = _clean_text(raw.get("type")).lower()
+    if ref_type not in ("picture", "video", "audio"):
+        ref_type = "picture"
+    role = _clean_text(raw.get("role")).lower()
+    strength = _clean_text(raw.get("strength")).lower()
+    if ref_type == "picture":
+        if role in {"reference", "environment", "style", "storyboard"}:
+            role = "subject_identity"
+            strength = "weak"
+        elif role == "subject_identity":
+            # Version 9 and earlier used Subject as an implicit strong role.
+            strength = strength if strength in SUBJECT_STRENGTHS else "strong"
+        elif role not in {"first_frame", "last_frame"}:
+            role = "subject_identity"
+            strength = strength if strength in SUBJECT_STRENGTHS else "normal"
+        else:
+            strength = "normal"
+    elif ref_type == "video":
+        legacy_video_roles = {
+            "reference": "none",
+            "continuation": "video_continuation",
+            "pacing": "cuts_rhythm",
+        }
+        role = role if role in REFERENCE_ROLES["video"] else legacy_video_roles.get(role, "none")
+    elif ref_type == "audio":
+        legacy_audio_roles = {
+            "reference": "none",
+            "voice_timbre": "voice_delivery",
+            "dialogue": "dialogue_lyrics",
+            "music_style": "music_rhythm",
+            "sound_effect": "sound_ambience",
+            "signal_copy": "partial_signal_copy",
+        }
+        role = role if role in REFERENCE_ROLES["audio"] else legacy_audio_roles.get(role, "none")
+    description = _clean_text(raw.get("description"))
+    # Picture analysis is transient enhancement evidence, never persisted
+    # project input. Older versions wrote it here and thereby changed Raw Prompt.
+    if ref_type == "picture":
+        description = ""
+    return {
+        "id": _clean_text(raw.get("id")) or f"ref-{index + 1}",
+        "type": ref_type,
+        "role": role if role in REFERENCE_ROLES[ref_type] else "reference",
+        "strength": strength if strength in SUBJECT_STRENGTHS else "normal",
+        "alias": _normalize_alias(raw.get("alias")),
+        "description": description,
+        "duration": max(0.0, _number(raw.get("duration"), 0.0)),
+        "image_filename": os.path.basename(_clean_text(raw.get("image_filename"))),
+        "image_subfolder": _clean_text(raw.get("image_subfolder")).replace("\\", "/").strip("/"),
+        "image_type": "input" if _clean_text(raw.get("image_type")).lower() != "input" else "input",
+        "video_filename": os.path.basename(_clean_text(raw.get("video_filename"))),
+        "video_subfolder": _clean_text(raw.get("video_subfolder")).replace("\\", "/").strip("/"),
+        "video_type": "input",
+        "audio_filename": os.path.basename(_clean_text(raw.get("audio_filename"))),
+        "audio_subfolder": _clean_text(raw.get("audio_subfolder")).replace("\\", "/").strip("/"),
+        "audio_type": "input",
+    }
+
+
+def infer_auto_mode(references: list[dict[str, Any]]) -> str:
+    """Resolve Auto from an exact anchor layout so no extra asset is silently ignored."""
+    if not references:
+        return "T2VA"
+    signature = [(ref.get("type"), ref.get("role")) for ref in references]
+    if signature == [("picture", "first_frame")]:
+        return "I2VA"
+    if signature == [("picture", "first_frame"), ("picture", "last_frame")]:
+        return "FL2VA"
+    if signature == [("picture", "last_frame")]:
+        return "L2VA"
+    return "REF2VA"
+
+
+def normalize_project(project_data: Any) -> tuple[dict[str, Any], list[str]]:
+    parse_warnings: list[str] = []
+    if isinstance(project_data, str):
+        try:
+            raw = json.loads(project_data) if project_data.strip() else {}
+        except json.JSONDecodeError as exc:
+            raw = {}
+            parse_warnings.append(f"Project JSON was invalid and defaults were used: {exc.msg}.")
+    elif isinstance(project_data, dict):
+        raw = project_data
+    else:
+        raw = {}
+
+    project = copy.deepcopy(DEFAULT_PROJECT)
+    raw_version = raw.get("version")
+    # Version 8 is a lossless cleanup migration from version 7: cached picture
+    # analysis text is discarded. Do not report that expected upgrade as a warning.
+    if raw_version is not None and raw_version != CURRENT_PROJECT_VERSION and raw_version not in {7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19}:
+        relation = "newer than" if isinstance(raw_version, (int, float)) and raw_version > CURRENT_PROJECT_VERSION else "different from"
+        parse_warnings.append(
+            f"Project version {raw_version!r} is {relation} supported version {CURRENT_PROJECT_VERSION}; known fields were normalized."
+        )
+    mode = _clean_text(raw.get("mode")).upper()
+    selected_mode = mode if mode in SUPPORTED_MODES else "AUTO"
+    project["user_request"] = _clean_text(raw.get("user_request"))
+    project["constraints"] = _clean_text(raw.get("constraints"))
+    project["verbatim_content"] = _clean_text(raw.get("verbatim_content"))
+    selected_enhance_model = _clean_text(raw.get("enhance_model"))
+    if selected_enhance_model == LEGACY_LIGHTX2V_MODEL_ID:
+        selected_enhance_model = LIGHTX2V_MODEL_ID
+    project["enhance_model"] = (
+        selected_enhance_model
+        if selected_enhance_model in {DEFAULT_ENHANCE_MODEL_ID, LIGHTX2V_MODEL_ID}
+        else DEFAULT_ENHANCE_MODEL_ID
+    )
+    selected_image_model = _clean_text(raw.get("image_model"))
+    if selected_image_model == LEGACY_LIGHTX2V_MODEL_ID:
+        selected_image_model = LIGHTX2V_MODEL_ID
+    project["image_model"] = (
+        selected_image_model
+        if selected_image_model in {QWEN_IMAGE_MODEL_ID, LIGHTX2V_MODEL_ID}
+        else QWEN_IMAGE_MODEL_ID
+    )
+    project["auto_run"] = raw.get("auto_run") is True
+    project["enhance"] = raw.get("enhance") is True
+    project["enhanced_prompt"] = _clean_text(raw.get("enhanced_prompt"))
+
+    raw_shots = raw.get("shots")
+    if isinstance(raw_shots, list) and raw_shots:
+        project["shots"] = [_normalize_shot(item, i) for i, item in enumerate(raw_shots)]
+    else:
+        requested = min(15.0, max(MIN_SHOT_DURATION, _number(raw.get("requested_duration"), 5.0)))
+        project["shots"][0]["duration"] = requested
+
+    # Version 13 and earlier stored three dedicated audio UI values. Preserve
+    # them once as natural-language instructions in the unified first-shot
+    # prompt, then drop the obsolete schema fields.
+    legacy_soundscape = _clean_text(raw.get("overall_soundscape"))
+    legacy_music = _clean_text(raw.get("non_diegetic_music"))
+    legacy_audio = []
+    if legacy_soundscape:
+        legacy_audio.append(f"Overall soundscape: {legacy_soundscape}")
+    if legacy_music:
+        legacy_audio.append(f"Non-diegetic music: {legacy_music}")
+    if legacy_audio:
+        project["shots"][0]["visual_action"] = "\n".join(
+            part for part in (project["shots"][0]["visual_action"], *legacy_audio) if part
+        )
+
+    shot_total = sum(float(shot["duration"]) for shot in project["shots"])
+    requested_duration = max(
+        len(project["shots"]) * MIN_SHOT_DURATION,
+        _number(raw.get("requested_duration"), shot_total),
+    )
+    if shot_total > 0 and not math.isclose(shot_total, requested_duration, abs_tol=0.0005):
+        distributable = requested_duration - len(project["shots"]) * MIN_SHOT_DURATION
+        weights = [max(0.0, float(shot["duration"]) - MIN_SHOT_DURATION) for shot in project["shots"]]
+        weight_total = sum(weights)
+        for index, shot in enumerate(project["shots"]):
+            share = weights[index] / weight_total if weight_total else 1.0 / len(project["shots"])
+            shot["duration"] = MIN_SHOT_DURATION + distributable * share
+    project["requested_duration"] = round(requested_duration, 3)
+    raw_refs = raw.get("references")
+    project["references"] = (
+        [_normalize_reference(item, i) for i, item in enumerate(raw_refs)]
+        if isinstance(raw_refs, list)
+        else []
+    )
+    if isinstance(raw_refs, list):
+        for index, (raw_ref, ref) in enumerate(zip(raw_refs, project["references"]), 1):
+            supplied = _clean_text(raw_ref.get("role")) if isinstance(raw_ref, dict) else ""
+            if supplied and supplied.lower() != ref["role"]:
+                expected_picture_migration = (
+                    ref["type"] == "picture"
+                    and supplied.lower() in {"reference", "environment", "style", "storyboard"}
+                )
+                expected_video_migration = (
+                    ref["type"] == "video"
+                    and supplied.lower() in {"reference", "continuation", "pacing"}
+                )
+                expected_audio_migration = (
+                    ref["type"] == "audio"
+                    and supplied.lower() in {
+                        "reference", "voice_timbre", "dialogue", "music_style",
+                        "sound_effect", "signal_copy",
+                    }
+                )
+                if not expected_picture_migration and not expected_video_migration and not expected_audio_migration:
+                    parse_warnings.append(
+                        f"Reference {index} role={supplied!r} is invalid for {ref['type']} and was normalized to {ref['role']!r}."
+                    )
+    project["mode"] = infer_auto_mode(project["references"]) if selected_mode == "AUTO" else selected_mode
+    project["mode_selection"] = selected_mode
+    return project, parse_warnings
+
+
+def _reference_labels(references: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    counts = {"picture": 0, "video": 0, "audio": 0}
+    labeled = []
+    for ref in references:
+        item = dict(ref)
+        counts[item["type"]] += 1
+        label_name = {"picture": "Picture", "video": "Video", "audio": "Audio"}[item["type"]]
+        item["label"] = f"<{label_name} {counts[item['type']]}>"
+        labeled.append(item)
+    return labeled
+
+
+def validate_project(project: dict[str, Any], parse_warnings: list[str] | None = None) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings = list(parse_warnings or [])
+    duration = float(project["requested_duration"])
+    shot_total = sum(float(shot["duration"]) for shot in project["shots"])
+    refs = _reference_labels(project["references"])
+    aliases = [ref["alias"].lower() for ref in refs if ref["alias"]]
+    pictures = [ref for ref in refs if ref["type"] == "picture"]
+    videos = [ref for ref in refs if ref["type"] == "video"]
+    audios = [ref for ref in refs if ref["type"] == "audio"]
+
+    if len(aliases) != len(set(aliases)):
+        errors.append("Reference aliases must be unique so each @mention resolves to exactly one reference.")
+
+    if duration < 4.0 or duration > 15.0:
+        errors.append(f"H3 output duration must be between 4 and 15 seconds; received {duration:.2f}s.")
+    if not math.isclose(shot_total, duration, abs_tol=0.001):
+        errors.append(f"Shot durations total {shot_total:.3f}s and must equal the {duration:.3f}s timeline duration.")
+    if not project["user_request"] and not any(shot["visual_action"] for shot in project["shots"]):
+        warnings.append("No overall request or shot action has been entered.")
+    descriptive_text = [
+        project["user_request"], project["constraints"],
+        *(shot["visual_action"] for shot in project["shots"]),
+        *(ref["description"] for ref in project["references"]),
+    ]
+    if any(_contains_hangul(text) for text in descriptive_text):
+        warnings.append(
+            "Direct compilation does not translate descriptive Korean text; English is recommended outside dialogue and visible text."
+        )
+    if project["mode"] == "T2VA" and refs:
+        warnings.append("T2VA does not use reference assets; manifest entries will be context only.")
+    if project["mode"] == "I2VA" and (not pictures or pictures[0]["role"] != "first_frame"):
+        errors.append("I2VA requires <Picture 1> to have role=first_frame.")
+    if project["mode"] == "FL2VA":
+        if len(pictures) < 2 or pictures[0]["role"] != "first_frame" or pictures[1]["role"] != "last_frame":
+            errors.append("FL2VA requires <Picture 1> role=first_frame and <Picture 2> role=last_frame, in that order.")
+        if len(project["shots"]) > 1:
+            warnings.append("FL2VA usually works best as one continuous shot unless cuts are intentional.")
+    if project["mode"] == "L2VA" and (not pictures or pictures[0]["role"] != "last_frame"):
+        errors.append("L2VA requires <Picture 1> to have role=last_frame.")
+    if project["mode"] == "REF2VA" and not refs:
+        errors.append("REF2VA requires at least one reference asset.")
+    if len(pictures) > MAX_REF_IMAGES:
+        errors.append(f"REF2VA accepts at most {MAX_REF_IMAGES} reference images; received {len(pictures)}.")
+    if len(videos) > MAX_REF_VIDEOS:
+        errors.append(f"REF2VA accepts at most {MAX_REF_VIDEOS} reference videos; received {len(videos)}.")
+    if len(audios) > MAX_REF_AUDIOS:
+        errors.append(f"REF2VA accepts at most {MAX_REF_AUDIOS} reference audio clips; received {len(audios)}.")
+    if len(refs) > MAX_REF_FILES:
+        errors.append(f"REF2VA accepts at most {MAX_REF_FILES} reference files in total; received {len(refs)}.")
+    video_total = sum(ref["duration"] for ref in videos)
+    for ref in videos:
+        if ref["duration"] and not REF_VIDEO_MIN_SECONDS <= ref["duration"] <= REF_VIDEO_MAX_SECONDS:
+            errors.append(f"{ref['label']} duration must be 2-15 seconds; received {ref['duration']:.2f}s.")
+        elif not ref["duration"] and ref.get("video_filename"):
+            warnings.append(f"{ref['label']} has no duration metadata; the 2-15 second limit cannot be verified.")
+    if video_total > REF_VIDEO_TOTAL_SECONDS:
+        errors.append(f"Reference-video duration totals {video_total:.2f}s; the maximum is 15.00s.")
+    for ref in audios:
+        role = ref.get("role", "none")
+        description = _clean_text(ref.get("description"))
+        if role in {"full_signal_copy", "partial_signal_copy", "dialogue_lyrics"} and not ref.get("audio_filename"):
+            errors.append(f"{ref['label']} preset={role} requires an uploaded audio file.")
+        if role == "none" and not description:
+            warnings.append(f"{ref['label']} has preset=None and no user-defined audio relationship.")
+        if role == "dialogue_lyrics" and not description:
+            warnings.append(
+                f"{ref['label']} dialogue/lyrics reuse has no exact words or transcription instructions; "
+                "the prompt must not invent them."
+            )
+        if role == "voice_delivery" and not description:
+            warnings.append(
+                f"{ref['label']} voice/delivery reference does not identify a target speaker or voice traits."
+            )
+
+    effective_frames = align_frame_count(duration)
+    effective_seconds = effective_frames / MODEL_FPS
+    if effective_seconds > 15.0:
+        warnings.append(f"Aligned duration is {effective_seconds:.2f}s, slightly beyond H3's 15-second envelope.")
+    return errors, warnings
+
+
+def _sentence(text: str) -> str:
+    text = _clean_text(text)
+    if not text:
+        return ""
+    return text if text[-1] in ".?!:;" else text + "."
+
+
+def _replace_aliases(text: str, aliases: dict[str, str]) -> str:
+    if not text or not aliases:
+        return text
+    lookup = {alias.lower(): replacement for alias, replacement in aliases.items()}
+    pattern = re.compile(
+        "(" + "|".join(re.escape(alias) for alias in sorted(aliases, key=len, reverse=True)) + ")"
+        r"(?![\w-])",
+        flags=re.IGNORECASE,
+    )
+    return pattern.sub(lambda match: lookup[match.group(0).lower()], text)
+
+
+def _quoted_prompt_text(text: str) -> str:
+    """Keep user-visible text unambiguous inside a quoted prompt sentence."""
+    return text.replace("\\", "\\\\").replace('"', '\\"').replace("\r", " ").replace("\n", " ")
+
+
+def _reference_model(project: dict[str, Any]) -> dict[str, Any]:
+    references = _reference_labels(project["references"])
+    subject_count = 0
+    aliases: dict[str, str] = {}
+    definitions: list[str] = []
+    retention: list[str] = []
+    applications: list[str] = []
+    task_types: list[str] = []
+    label_plan: dict[str, dict[str, str]] = {}
+    summary_relations: list[str] = []
+    final_shot = len(project["shots"])
+
+    def add_task(task_type: str):
+        if task_type not in task_types:
+            task_types.append(task_type)
+
+    for ref in references:
+        source_label = ref["label"]
+        role_text = ref["role"].replace("_", " ")
+        if ref["type"] == "video":
+            role_text = {
+                "none": "user-defined video relationship",
+                "video_editing": "source video editing",
+                "video_continuation": "source video continuation",
+                "motion": "motion and action timing",
+                "camera": "camera movement and viewpoint behavior",
+                "cuts_rhythm": "cuts, pacing, rhythm, and temporal structure",
+            }.get(ref["role"], role_text)
+        elif ref["type"] == "audio":
+            role_text = {
+                "none": "user-defined audio relationship",
+                "full_signal_copy": "complete source-audio reuse",
+                "partial_signal_copy": "partial source-audio reuse",
+                "voice_delivery": "voice timbre and delivery",
+                "dialogue_lyrics": "dialogue or lyrics reuse",
+                "sound_ambience": "sound effects and ambience",
+                "music_rhythm": "music style, tempo, and rhythm",
+            }.get(ref["role"], role_text)
+        generic_reference_text = {
+            "picture": "general visual reference",
+            "video": "general video reference",
+            "audio": "general audio reference",
+        }[ref["type"]]
+        description = _sentence(ref["description"])
+        if ref["type"] == "picture" and ref["role"] in {"reference", "subject_identity"}:
+            subject_count += 1
+            subject = f"<Subject {subject_count}>"
+            if ref["alias"]:
+                aliases[ref["alias"]] = subject
+            strength = "weak" if ref["role"] == "reference" else ref.get("strength", "strong")
+            definition = f"{subject} is the reusable visible subject derived from {source_label}"
+            if description:
+                definition += f", described as {description.rstrip('.')}"
+            definitions.append(definition + ".")
+            marker = {
+                "weak": "weak_reference",
+                "normal": "partially_preserved",
+                "strong": "fully_preserved",
+            }[strength]
+            retention_detail = {
+                "weak": "retain only broad similarity in a small set of target-relevant visible characteristics",
+                "normal": "retain core identity and primary visible appearance while allowing secondary details to vary",
+                "strong": "preserve the complete visible subject identity, appearance, and source visual medium/rendering style wherever it appears",
+            }[strength]
+            retention.append(f"{subject}: {marker} - {retention_detail}.")
+            if not ref["alias"]:
+                applications.append(f"Apply {subject} only as its defined Subject content at {strength} strength.")
+            role_contract = {
+                "weak": "broad subject appearance similarity only; exclude source setting, style, composition, camera, lighting, palette, pose, and action",
+                "normal": "core subject identity and primary visible appearance; secondary details may vary; exclude source setting, style, composition, camera, lighting, palette, pose, and action",
+                "strong": "complete visible subject identity and appearance plus that subject's source visual medium/rendering style; preserve the style independently per subject; exclude source setting, composition, camera, lighting setup, scene-wide palette, pose, and action",
+            }[strength]
+            label_plan[subject] = {
+                "kind": "Subject", "source": source_label, "role": "subject_identity", "marker": marker,
+                "strength": strength, "contract": role_contract,
+            }
+            summary_relations.append(f"{subject} as a {strength}-strength subject reference")
+            add_task("reference generation")
+            continue
+
+        if ref["alias"]:
+            aliases[ref["alias"]] = source_label
+        if ref["type"] == "picture" and ref["role"] == "first_frame":
+            definition = f"{source_label} is the first frame of [Shot 1]"
+        elif ref["type"] == "picture" and ref["role"] == "last_frame":
+            definition = f"{source_label} is the final frame of [Shot {final_shot}]"
+        elif ref["type"] == "video" and ref["role"] == "video_editing":
+            definition = f"{source_label} is the source video for the target video edit"
+        elif ref["type"] == "video" and ref["role"] == "video_continuation":
+            definition = f"{source_label} is the continuation source for the target video"
+        elif ref["type"] == "video" and ref["role"] == "none":
+            definition = f"{source_label} has a user-defined video relationship"
+        elif ref["type"] == "audio" and ref["role"] == "none":
+            definition = f"{source_label} has a user-defined audio relationship"
+        elif ref["type"] == "audio" and ref["role"] == "full_signal_copy":
+            definition = f"{source_label} is the complete source audio to reuse"
+        elif ref["type"] == "audio" and ref["role"] == "partial_signal_copy":
+            definition = f"{source_label} supplies selected source-audio signal or layers to reuse"
+        elif ref["role"] == "reference":
+            definition = f"{source_label} is a {generic_reference_text}"
+        else:
+            definition = f"{source_label} is the {role_text} reference"
+        if description:
+            definition += f", described as {description.rstrip('.')}"
+        if ref["duration"]:
+            if ref["type"] == "video":
+                definition += (
+                    f", using only the first {ref['duration']:.2f} seconds as the configured "
+                    "analysis and reference segment"
+                )
+            else:
+                definition += f", with a source duration of {ref['duration']:.2f} seconds"
+        definitions.append(definition + ".")
+
+        if ref["type"] == "picture":
+            if ref["role"] in ("first_frame", "last_frame"):
+                marker = "fully_preserved"
+                add_task("keyframe completion")
+            else:
+                marker = "weak_reference"
+                add_task("reference generation")
+            retention.append(f"{source_label}: {marker} - apply only its defined {role_text} role.")
+        elif ref["type"] == "video":
+            if ref["role"] == "video_editing":
+                marker = "partially_preserved"
+                add_task("video editing")
+            elif ref["role"] == "video_continuation":
+                marker = "partially_preserved"
+                add_task("video continuation")
+            else:
+                marker = "weak_reference"
+                add_task("reference generation")
+            retention.append(f"{source_label}: {marker} - use only its defined {role_text} relationship.")
+        else:
+            if ref["role"] == "full_signal_copy":
+                marker = "fully_copy"
+                add_task("audio reuse")
+            elif ref["role"] in ("partial_signal_copy", "dialogue_lyrics"):
+                marker = "partially_copy"
+                add_task("audio reuse")
+            else:
+                marker = "reference"
+                add_task("audio reference")
+            retention.append(f"{source_label}: {marker} - use only its defined {role_text} relationship.")
+        video_contracts = {
+            "none": "follow only the user-written relationship; do not infer an editing, continuation, motion, camera, or timing role",
+            "video_editing": "treat as the source video being directly edited; preserve source timeline elements except those the user explicitly changes",
+            "video_continuation": "continue from the source video's ending state, preserving final composition, positions, movement direction and momentum, camera behavior, lighting, and continuity unless changed",
+            "motion": "reference only subject motion, action sequence, movement timing, and physical rhythm; do not copy identity, setting, style, camera, cuts, or audio",
+            "camera": "reference only camera movement, viewpoint, framing progression, and camera timing; do not copy identity, setting, action content, style, or audio",
+            "cuts_rhythm": "reference only cut placement, pacing, rhythm, and temporal structure; do not copy identity, setting, action content, visual style, or audio",
+        }
+        audio_contracts = {
+            "none": "follow only the user-written audio relationship; do not infer signal copying, voice, dialogue, lyrics, effects, ambience, music, or rhythm",
+            "full_signal_copy": "reuse the complete source audio signal as the target audio; do not invent or replace layers",
+            "partial_signal_copy": "reuse only the user-specified source interval or audio layers; leave every other layer unspecified unless requested",
+            "voice_delivery": "reference only voice timbre, delivery, accent, emotion, pace, and vocal texture; do not copy source words, music, ambience, or effects",
+            "dialogue_lyrics": "reuse only exact user-supplied or reliably transcribed dialogue or lyrics; never invent, translate, correct, or complete unavailable words",
+            "sound_ambience": "reference only user-described sound effects, ambience, room tone, and acoustic character; do not copy dialogue, lyrics, or music",
+            "music_rhythm": "reference only user-described instrumentation, tempo, meter, rhythm, dynamics, structure, and musical mood; do not claim source-signal reuse",
+        }
+        label_plan[source_label] = {
+            "kind": ref["type"].title(), "source": source_label,
+            "role": ref["role"], "marker": marker,
+            "contract": (
+                video_contracts.get(ref["role"], f"use only as the defined {role_text} relationship")
+                if ref["type"] == "video"
+                else audio_contracts.get(ref["role"], f"use only as the defined {role_text} relationship")
+            ),
+        }
+        summary_relations.append(f"{source_label} for {role_text}")
+        if not ref["alias"]:
+            if ref["role"] == "reference":
+                applications.append(f"Apply {source_label} only as a {generic_reference_text}.")
+            else:
+                applications.append(f"Apply {source_label} only as the {role_text} reference.")
+
+    return {
+        "definitions": definitions,
+        "retention": retention,
+        "applications": applications,
+        "aliases": aliases,
+        "task_types": task_types or ["reference generation"],
+        "label_plan": label_plan,
+        "summary_relations": summary_relations,
+    }
+
+
+def _shot_description(project: dict[str, Any], effective_seconds: float, aliases: dict[str, str],
+                      reference_applications: list[str] | None = None) -> str:
+    requested_seconds = sum(float(shot["duration"]) for shot in project["shots"])
+    scale = effective_seconds / requested_seconds if requested_seconds > 0 else 1.0
+    cursor = 0.0
+    blocks: list[str] = []
+    for index, shot in enumerate(project["shots"], 1):
+        fragments: list[str] = []
+        if index == 1 and project["user_request"]:
+            fragments.append(_sentence(_replace_aliases(project["user_request"], aliases)))
+        if index == 1 and reference_applications:
+            fragments.extend(reference_applications)
+        if shot["visual_action"]:
+            fragments.append(_sentence(_replace_aliases(shot["visual_action"], aliases)))
+        if index == 1:
+            prefix = "[Shot 1] "
+            if not fragments:
+                fragments.append("The scene begins with no additional shot-specific action specified.")
+        else:
+            prefix = f"[Shot {index}] At {format_timestamp(cursor)}, cut to a new shot. "
+            if not fragments:
+                fragments.append("The scene continues with no additional shot-specific action specified.")
+        blocks.append(prefix + " ".join(fragment for fragment in fragments if fragment))
+        cursor += float(shot["duration"]) * scale
+
+    if project["constraints"]:
+        blocks.append(_sentence(f"Throughout the video, {_replace_aliases(project['constraints'], aliases)}"))
+    if project["verbatim_content"]:
+        blocks.append(_sentence(f"Preserve this verbatim content exactly: {project['verbatim_content']}"))
+    return " ".join(blocks)
+
+
+def _fl2va_alignment_instruction(effective_seconds: float, final_shot: int) -> str:
+    return (
+        "How the reference pictures align with the target video — "
+        "Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; "
+        f"Picture 2 (from Shot {final_shot}) aligns with the {effective_seconds:.2f}-second mark of the target video."
+    )
+
+
+I2VA_ALIGNMENT_INSTRUCTION = (
+    "For the target video, at 0.00 seconds into the target video, "
+    "<Picture 1> (from [Shot 1]) is fully referenced."
+)
+
+
+def _l2va_alignment_instruction(effective_seconds: float, final_shot: int) -> str:
+    return (
+        "How the reference pictures align with the target video — "
+        f"<Picture 1> (from [Shot {final_shot}]) aligns with the "
+        f"{effective_seconds:.2f}-second mark of the target video."
+    )
+
+
+def _mode_prompt_preamble(mode: str) -> str:
+    if mode == "REF2VA":
+        return (
+            "ACTIVE MODE: REF2VA FULL-REFERENCE.\n"
+            "OUTPUT FAMILY: exactly six REF2VA sections.\n"
+            "FORBIDDEN OUTPUT FIELD: integrated_multimodal_description.\n"
+            "Do not answer in the three-field Base/T2VA format."
+        )
+    return (
+        f"ACTIVE MODE: {mode}.\n"
+        "OUTPUT FAMILY: MiniMax H3 Base format with exactly three fields.\n"
+        "FORBIDDEN OUTPUT SECTIONS: subject_definitions, summary, retention_analysis, "
+        "and detailed_description."
+    )
+
+
+def _single_pass_output_lock(mode: str, effective_seconds: float, final_shot: int,
+                             expected_shots: list[int],
+                             reference_model: dict[str, Any] | None = None,
+                             content_locks: list[str] | None = None) -> str:
+    shots = ", ".join(f"[Shot {number}]" for number in expected_shots)
+    content_lock = ""
+    if content_locks:
+        content_lock = (
+            "\nINPUT-DERIVED CONTENT LOCKS — these are binding, not output headings:\n- "
+            + "\n- ".join(content_locks)
+        )
+    if mode == "REF2VA":
+        label_plan = (reference_model or {}).get("label_plan", {})
+        labels = ", ".join(label_plan) or "the locked labels above"
+        retention_markers = "; ".join(
+            f"{label} uses {plan.get('marker', 'the locked marker')}"
+            for label, plan in label_plan.items()
+        ) or "use the locked marker for each label"
+        return f"""FINAL MODE LOCK — REF2VA
+Highest-priority format lock. Return one <H3_PROMPT> block with no JSON, Markdown, or commentary.
+Start exactly with `subject_definitions:` and never use `integrated_multimodal_description:`.
+Use these headers once in this order:
+subject_definitions:
+summary:
+retention_analysis:
+detailed_description:
+overall_soundscape:
+non_diegetic_music:
+Define exactly these output labels in order: {labels}.
+Use exactly these labels in order: {labels}. Keep them literal where their roles apply; create no others.
+RETENTION OUTPUT MARKERS: {retention_markers}.
+In retention_analysis, print only each label, applicable shots, its marker above, and a concise description. Never print input strength names or `=`.
+detailed_description must contain exactly {shots}, once each in order; [Shot 1] has no timestamp.{content_lock}
+Speaker IDs, exact <d> content, lip synchronization, and event order must be correct in the final output.
+Do not invent people, dialogue, vocal reactions, or music. Use N/A for unrequested non-diegetic music.
+End after non_diegetic_music and close </H3_PROMPT>."""
+
+    if mode == "I2VA":
+        opening = I2VA_ALIGNMENT_INSTRUCTION
+        endpoint_lock = ""
+    elif mode == "FL2VA":
+        opening = _fl2va_alignment_instruction(effective_seconds, final_shot)
+        endpoint_lock = (
+            "\nPicture 2 is reached only at the effective end time. Never reveal the completed Picture 2 "
+            "at the start of the final shot; make that shot continue the transition and stabilize exactly on "
+            "Picture 2 only in its final frames. Never morph one character into another unless the input "
+            "explicitly requests morphing or transformation. Bind Picture 2 traits only to the entity that "
+            "matches or enters as the final-frame entity, never to a different affected character."
+        )
+    elif mode == "L2VA":
+        opening = _l2va_alignment_instruction(effective_seconds, final_shot)
+        endpoint_lock = ""
+    else:
+        opening = "integrated_multimodal_description:"
+        endpoint_lock = ""
+    return f"""FINAL MODE LOCK — {mode}
+Highest-priority format lock. Return one <H3_PROMPT> block with no JSON, Markdown, or commentary.
+Begin exactly with: {opening}
+Use exactly these fields once in order: integrated_multimodal_description, overall_soundscape, non_diegetic_music.
+For I2VA, FL2VA, and L2VA, keep the alignment line before the main field, never inside it.
+Never use REF2VA sections. The timeline must contain exactly {shots}, once each in order; [Shot 1] has no timestamp.{endpoint_lock}{content_lock}
+Preserve every explicit SHOT_PLAN action in order; omit none.
+Speaker IDs, exact <d> content, lip synchronization, and event order must be correct in the final output.
+Do not invent dialogue, vocal reactions, or music. overall_soundscape must not repeat or summarize speech. Use N/A for unrequested non-diegetic music.
+End after non_diegetic_music and close </H3_PROMPT>."""
+
+
+_BASE_FIELD_PATTERN = re.compile(
+    r"^[ \t]*(integrated_multimodal_description|overall_soundscape|non_diegetic_music)[ \t]*:[ \t]*",
+    flags=re.IGNORECASE | re.MULTILINE,
+)
+
+
+def _base_prompt_sections(prompt: str) -> dict[str, str]:
+    matches = list(_BASE_FIELD_PATTERN.finditer(prompt))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        name = match.group(1).lower()
+        if name in sections:
+            continue
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(prompt)
+        sections[name] = prompt[match.end():end].strip()
+    return sections
+
+
+def _remove_embedded_alignment(text: str) -> str:
+    text = re.sub(
+        r"For the target video,\s*at 0\.00 seconds into the target video,\s*"
+        r"<Picture 1>\s*\(from \[Shot 1\]\)\s*is fully referenced\.\s*",
+        "",
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(
+        r"How the reference pictures align with the target video\s*[—-]\s*.*?"
+        r"(?:mark of the target video|target video)\.\s*",
+        "",
+        text,
+        count=1,
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    return text.strip()
+
+
+def _move_preamble_after_shot_one(text: str) -> str:
+    shot = re.search(r"\[Shot\s+1\]", text, flags=re.IGNORECASE)
+    if not shot:
+        return text.strip()
+    remainder = text[shot.end():].strip()
+    # Alignment paraphrases and conversational lead-ins before the first shot
+    # are transport noise, not scene content. The Base schema starts at Shot 1.
+    return "[Shot 1]" + (" " + remainder if remainder else "")
+
+
+def _normalize_base_enhanced_prompt(prompt: str, mode: str, effective_seconds: float,
+                                    final_shot: int) -> str:
+    """Canonicalize Base-mode field order and keyframe alignment without rewriting content."""
+    sections = _base_prompt_sections(prompt)
+    required = ("integrated_multimodal_description", "overall_soundscape", "non_diegetic_music")
+    if any(name not in sections for name in required):
+        return prompt.strip()
+
+    main = _move_preamble_after_shot_one(_remove_embedded_alignment(sections[required[0]]))
+    body = "\n\n".join((
+        "integrated_multimodal_description: " + main,
+        "overall_soundscape: " + sections[required[1]],
+        "non_diegetic_music: " + sections[required[2]],
+    ))
+    if mode == "I2VA":
+        return I2VA_ALIGNMENT_INSTRUCTION + "\n\n" + body
+    if mode == "FL2VA":
+        return _fl2va_alignment_instruction(effective_seconds, final_shot) + "\n\n" + body
+    if mode == "L2VA":
+        return _l2va_alignment_instruction(effective_seconds, final_shot) + "\n\n" + body
+    return body
+
+
+def _base_prompt_structure_issues(prompt: str, mode: str, effective_seconds: float,
+                                  final_shot: int) -> list[str]:
+    matches = list(_BASE_FIELD_PATTERN.finditer(prompt))
+    sections = _base_prompt_sections(prompt)
+    required = ("integrated_multimodal_description", "overall_soundscape", "non_diegetic_music")
+    issues: list[str] = []
+    if len(matches) != len(required) or list(sections) != list(required):
+        issues.append("Use exactly the three Base-mode fields once and in the required order.")
+        return issues
+    main = sections[required[0]].lstrip()
+    if not re.match(r"\[Shot\s+1\](?=\s|$)", main, flags=re.IGNORECASE):
+        issues.append("integrated_multimodal_description must begin with [Shot 1].")
+    expected_prefix = ""
+    if mode == "I2VA":
+        expected_prefix = I2VA_ALIGNMENT_INSTRUCTION
+    elif mode == "FL2VA":
+        expected_prefix = _fl2va_alignment_instruction(effective_seconds, final_shot)
+    elif mode == "L2VA":
+        expected_prefix = _l2va_alignment_instruction(effective_seconds, final_shot)
+    if expected_prefix and not prompt.startswith(expected_prefix + "\n\n"):
+        issues.append("Place the exact mode alignment instruction on the first line.")
+    if mode == "T2VA" and not prompt.startswith("integrated_multimodal_description:"):
+        issues.append("T2VA must begin directly with integrated_multimodal_description.")
+    if re.search(r"For the target video,\s*at 0\.00 seconds", main, flags=re.IGNORECASE):
+        issues.append("Remove the alignment instruction from the main description.")
+    return issues
+
+
+REF_PROMPT_FIELDS = (
+    "subject_definitions", "summary", "retention_analysis",
+    "detailed_description", "overall_soundscape", "non_diegetic_music",
+)
+_REF_FIELD_PATTERN = re.compile(
+    r"^[ \t]*(subject_definitions|summary|retention_analysis|detailed_description|"
+    r"overall_soundscape|non_diegetic_music)[ \t]*:[ \t]*",
+    flags=re.IGNORECASE | re.MULTILINE,
+)
+_REF_LABEL_PATTERN = re.compile(r"<(Subject|Picture|Video|Audio)\s+(\d+)>", re.IGNORECASE)
+_SHOT_HEADER_PATTERN = re.compile(
+    r"(?:\A|(?<=\n))\s*\[Shot\s+(\d+)\](?=\s|$)"
+    r"|\[Shot\s+(\d+)\]\s+At\s+\d{2}:\d{2}\.\d{3}",
+    flags=re.IGNORECASE,
+)
+
+
+def _ref_prompt_sections(prompt: str) -> dict[str, str]:
+    matches = list(_REF_FIELD_PATTERN.finditer(prompt))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        name = match.group(1).lower()
+        if name in sections:
+            continue
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(prompt)
+        sections[name] = prompt[match.end():end].strip()
+    return sections
+
+
+def _insert_ref_first_shot_header(detail: str, boundary: int) -> str:
+    """Insert a real Shot 1 header into prose that precedes the first later-shot header."""
+    opening = detail[:boundary].strip()
+    remainder = detail[boundary:].strip()
+    if not opening:
+        return detail
+    paragraphs = [part.strip() for part in re.split(r"\n\s*\n", opening) if part.strip()]
+    if len(paragraphs) >= 2:
+        paragraphs[1] = "[Shot 1] " + re.sub(
+            r"^\[Shot\s+1\]\s*", "", paragraphs[1], flags=re.IGNORECASE,
+        )
+        opening = "\n\n".join(paragraphs)
+    else:
+        style_sentence = re.match(
+            r"^(.+?\b(?:style|aesthetic|presentation|rendering)\b[^.!?]*[.!?])\s*(.+)$",
+            opening,
+            flags=re.IGNORECASE | re.DOTALL,
+        )
+        if style_sentence:
+            action_body = re.sub(
+                r"^\[Shot\s+1\]\s*", "", style_sentence.group(2).strip(), flags=re.IGNORECASE,
+            )
+            opening = style_sentence.group(1).strip() + "\n[Shot 1] " + action_body
+        else:
+            opening = "[Shot 1] " + re.sub(
+                r"^\[Shot\s+1\]\s*", "", opening, flags=re.IGNORECASE,
+            )
+    return opening + ("\n" + remainder if remainder else "")
+
+
+def _normalize_ref_enhanced_prompt(prompt: str, task_types: list[str] | None = None,
+                                   expected_shots: list[int] | None = None) -> str:
+    sections = _ref_prompt_sections(prompt)
+    if any(field not in sections for field in REF_PROMPT_FIELDS):
+        return prompt.strip()
+    if task_types:
+        summary_body = re.sub(r"^\s*\[[^\]\n]*\]\s*", "", sections["summary"], count=1)
+        sections["summary"] = f"[{' + '.join(task_types)}] {summary_body}".rstrip()
+    detail = sections["detailed_description"].strip()
+    header_matches = list(_SHOT_HEADER_PATTERN.finditer(detail))
+    actual_headers = [int(match.group(1) or match.group(2)) for match in header_matches]
+    if detail and expected_shots:
+        if not actual_headers and expected_shots == [1]:
+            detail = _insert_ref_first_shot_header(detail, len(detail))
+        elif (expected_shots[0] == 1 and actual_headers == expected_shots[1:]
+              and header_matches):
+            detail = _insert_ref_first_shot_header(detail, header_matches[0].start())
+        sections["detailed_description"] = detail
+    return "\n\n".join(f"{field}:\n{sections[field]}" for field in REF_PROMPT_FIELDS)
+
+
+def _canonical_ref_label(match: re.Match[str]) -> str:
+    return f"<{match.group(1).title()} {int(match.group(2))}>"
+
+
+def _ref_prompt_structure_issues(prompt: str, label_plan: dict[str, dict[str, str]]) -> list[str]:
+    matches = list(_REF_FIELD_PATTERN.finditer(prompt))
+    sections = _ref_prompt_sections(prompt)
+    issues: list[str] = []
+    if len(matches) != len(REF_PROMPT_FIELDS) or list(sections) != list(REF_PROMPT_FIELDS):
+        issues.append("Use exactly the six REF2VA sections once and in the required order.")
+        return issues
+    empty_sections = [field for field in REF_PROMPT_FIELDS if not sections[field].strip()]
+    if empty_sections:
+        issues.append("Do not leave REF2VA sections empty: " + ", ".join(empty_sections) + ".")
+
+    expected_labels = list(label_plan)
+    definition_labels: list[str] = []
+    for line in sections["subject_definitions"].splitlines():
+        match = re.match(r"\s*<(Subject|Picture|Video|Audio)\s+(\d+)>", line, flags=re.IGNORECASE)
+        if match:
+            definition_labels.append(_canonical_ref_label(match))
+    if definition_labels != expected_labels:
+        issues.append(
+            f"Define exactly these reference labels once and in order: {', '.join(expected_labels) or 'none'}."
+        )
+    definition_lines = {
+        _canonical_ref_label(match): line
+        for line in sections["subject_definitions"].splitlines()
+        if (match := re.match(r"\s*<(Subject|Picture|Video|Audio)\s+(\d+)>", line, flags=re.IGNORECASE))
+    }
+    for label, plan in label_plan.items():
+        if plan["kind"] != "Subject" or label not in definition_lines:
+            continue
+        source = plan["source"]
+        if source.casefold() not in definition_lines[label].casefold():
+            issues.append(f"{label} must cite its source asset {source} in subject_definitions.")
+
+    retention_labels: list[str] = []
+    retention_markers: dict[str, str] = {}
+    for line in sections["retention_analysis"].splitlines():
+        match = re.match(
+            r"\s*<(Subject|Picture|Video|Audio)\s+(\d+)>\s*(?:\([^)]*\))?\s*:\s*"
+            r"(fully_preserved|partially_preserved|attribute_transfer|weak_reference|"
+            r"fully_copy|partially_copy|reference)\b",
+            line,
+            flags=re.IGNORECASE,
+        )
+        if match:
+            label = _canonical_ref_label(match)
+            retention_labels.append(label)
+            retention_markers[label] = match.group(3).lower()
+    if retention_labels != expected_labels:
+        issues.append("retention_analysis must contain exactly one ordered entry for every defined label.")
+    for label, plan in label_plan.items():
+        if label in retention_markers and retention_markers[label] != plan["marker"]:
+            issues.append(f"{label} must use retention marker {plan['marker']} for its defined role.")
+    if re.search(r"\(S\d+\)", sections["retention_analysis"], flags=re.IGNORECASE):
+        issues.append("Do not place speaker IDs in retention_analysis.")
+
+    summary_labels = {
+        _canonical_ref_label(match) for match in _REF_LABEL_PATTERN.finditer(sections["summary"])
+    }
+    missing_summary = [label for label in expected_labels if label not in summary_labels]
+    if missing_summary:
+        issues.append("summary must mention every defined reference relationship: " + ", ".join(missing_summary) + ".")
+    prefix = re.match(r"\s*\[([^\]]+)\]", sections["summary"])
+    allowed_tasks = {
+        "keyframe completion", "reference generation", "video editing",
+        "video continuation", "audio reuse", "audio reference",
+    }
+    if not prefix or any(task.strip().lower() not in allowed_tasks for task in prefix.group(1).split("+")):
+        issues.append("summary must begin with only valid REF2VA task types joined by ' + '.")
+
+    downstream_text = "\n".join(sections[field] for field in REF_PROMPT_FIELDS[1:])
+    downstream_labels = {
+        _canonical_ref_label(match) for match in _REF_LABEL_PATTERN.finditer(downstream_text)
+    }
+    unexpected = sorted(downstream_labels.difference(expected_labels))
+    if unexpected:
+        issues.append("Remove undefined or source-only labels outside subject_definitions: " + ", ".join(unexpected) + ".")
+    visual_labels = [
+        label for label, plan in label_plan.items()
+        if plan["kind"] in {"Subject", "Picture", "Video"}
+    ]
+    detailed_labels = {
+        _canonical_ref_label(match)
+        for match in _REF_LABEL_PATTERN.finditer(sections["detailed_description"])
+    }
+    missing_visual = [label for label in visual_labels if label not in detailed_labels]
+    if missing_visual:
+        issues.append("detailed_description must apply every defined visual relationship: " + ", ".join(missing_visual) + ".")
+    audio_labels = [
+        label for label, plan in label_plan.items() if plan["kind"] == "Audio"
+    ]
+    audio_application_text = "\n".join((
+        sections["detailed_description"], sections["overall_soundscape"],
+        sections["non_diegetic_music"],
+    ))
+    applied_audio_labels = {
+        _canonical_ref_label(match) for match in _REF_LABEL_PATTERN.finditer(audio_application_text)
+    }
+    missing_audio = [label for label in audio_labels if label not in applied_audio_labels]
+    if missing_audio:
+        issues.append(
+            "Apply every audio relationship in detailed_description, overall_soundscape, or "
+            "non_diegetic_music as appropriate: " + ", ".join(missing_audio) + "."
+        )
+    if re.search(r"^\s*integrated_multimodal_description\s*:", prompt, flags=re.IGNORECASE | re.MULTILINE):
+        issues.append("REF2VA must use detailed_description, not integrated_multimodal_description.")
+    return issues
+
+
+def _explicit_project_context(project: dict[str, Any]) -> str:
+    values = [project.get("user_request", ""), project.get("constraints", ""), project.get("verbatim_content", "")]
+    for shot in project.get("shots", []):
+        values.append(shot.get("visual_action", ""))
+    return "\n".join(_clean_text(value) for value in values if _clean_text(value))
+
+
+def _ref_prompt_semantic_issues(prompt: str, project: dict[str, Any], explicit_context: str,
+                                visual_evidence: dict[str, str] | None = None) -> list[str]:
+    sections = _ref_prompt_sections(prompt)
+    if any(field not in sections for field in REF_PROMPT_FIELDS):
+        return []
+    explicit = explicit_context.casefold()
+    descriptive = "\n".join((
+        sections["subject_definitions"], sections["summary"], sections["detailed_description"],
+    )).casefold()
+    issues: list[str] = []
+    inferred_terms = {
+        "young": ("젊은", "어린"),
+        "teenage": ("청소년", "십대"),
+        "middle-aged": ("중년",),
+        "elderly": ("노인", "고령"),
+        "east asian": ("동아시아",),
+        "asian": ("아시아",),
+        "japanese": ("일본인",),
+        "korean": ("한국인",),
+        "chinese": ("중국인",),
+        "ukrainian": ("우크라이나인",),
+    }
+    for term, aliases in inferred_terms.items():
+        if term in descriptive and term not in explicit and not any(alias in explicit_context for alias in aliases):
+            message = "Remove demographic age, ethnicity, or nationality claims not explicitly supplied by the user."
+            if message not in issues:
+                issues.append(message)
+
+    reference_model = _reference_model(project)
+    label_plan = reference_model["label_plan"]
+    retention_lines: dict[str, str] = {}
+    for line in sections["retention_analysis"].splitlines():
+        match = re.match(r"\s*<(Subject|Picture|Video|Audio)\s+(\d+)>", line, flags=re.IGNORECASE)
+        if match:
+            retention_lines[_canonical_ref_label(match)] = line
+    for label, plan in label_plan.items():
+        if plan["marker"] != "weak_reference":
+            continue
+        detail = retention_lines.get(label, "").split("-", 1)[-1].strip().casefold()
+        exhaustive_list = detail.count(",") >= 2 and re.search(r"\b(?:retain|preserve|copy|match)\b", detail)
+        strong_claim = re.search(
+            r"\b(?:exact(?:ly)?|identical(?:ly)?|fully|strictly)\b|"
+            r"\b(?:preserve|retain|copy|match)\s+(?:the\s+)?(?:complete|entire|all|identity)\b",
+            detail,
+        )
+        if exhaustive_list or strong_claim:
+            issues.append(
+                f"{label} is weak_reference: describe only broad similarity in a small set of "
+                "target-relevant characteristics, not an exhaustive or identity-preserving inventory."
+            )
+
+    summary = sections["summary"].casefold()
+    for label, plan in label_plan.items():
+        if plan["kind"] != "Subject" or label.casefold() not in summary:
+            continue
+        if plan["marker"] == "weak_reference" and re.search(
+            r"\b(?:identity|styling|environment|composition|pose|camera|palette)\b", summary,
+        ):
+            issues.append(
+                f"{label} is a weak general reference; summary must describe weak appearance guidance only, "
+                "not identity, style, environment, composition, pose, camera, or palette transfer."
+            )
+
+    source_refs = {ref["label"]: ref for ref in _reference_labels(project.get("references", []))}
+    visual_evidence = visual_evidence or {}
+    detail_lower = sections["detailed_description"].casefold()
+    style_opening = re.split(r"\[shot\s+1\]", detail_lower, maxsplit=1, flags=re.IGNORECASE)[0]
+    environment_terms = (
+        "beach", "ocean", "sea", "shore", "sand", "coast", "mountain", "forest", "street",
+        "corridor", "hallway", "room", "studio", "sky", "cloud", "horizon",
+    )
+    style_terms = (
+        "anime", "photorealistic", "cinematic", "illustration", "watercolor", "oil painting",
+        "pixel art", "3d render", "color palette", "high-key", "low-key", "natural lighting",
+    )
+    def contains_term(text: str, term: str) -> bool:
+        return bool(re.search(rf"(?<!\w){re.escape(term)}(?!\w)", text))
+
+    def explicitly_transfers_source_style(text: str, label: str) -> bool:
+        """Detect source attribution rather than harmless target-style overlap."""
+        escaped_label = re.escape(label.casefold())
+        attribution_patterns = (
+            rf"{escaped_label}(?:'s)?[^.!?\n]{{0,80}}\b(?:style|aesthetic|rendering|lighting|palette)\b",
+            rf"\b(?:style|aesthetic|rendering|lighting|palette)\b[^.!?\n]{{0,80}}{escaped_label}",
+            r"\b(?:source|reference(?:d)?)(?:\s+(?:image|picture|asset))?(?:'s)?"
+            r"[^.!?\n]{0,50}\b(?:style|aesthetic|rendering|lighting|palette)\b",
+            r"\b(?:style|aesthetic|rendering|lighting|palette)\b[^.!?\n]{0,50}"
+            r"\b(?:from|of|defined by|derived from|matching)\s+(?:the\s+)?"
+            r"(?:source|reference(?:d)?(?:\s+(?:image|picture|asset))?)\b",
+        )
+        return any(re.search(pattern, text) for pattern in attribution_patterns)
+
+    for label, plan in label_plan.items():
+        if plan["kind"] != "Subject" or plan["role"] != "subject_identity":
+            continue
+        source_description = (
+            visual_evidence.get(plan["source"])
+            or source_refs.get(plan["source"], {}).get("description", "")
+        ).casefold()
+        if any(
+            contains_term(source_description, term) and contains_term(detail_lower, term)
+            and not contains_term(explicit, term)
+            for term in environment_terms
+        ):
+            issues.append(
+                f"{label} role={plan['role']} does not transfer source environment details; remove unrequested "
+                "source setting content unless the target text explicitly requests it."
+            )
+        shares_unrequested_source_style = any(
+            contains_term(source_description, term) and contains_term(style_opening, term)
+            and not contains_term(explicit, term)
+            for term in style_terms
+        )
+        style_transfer_violation = plan.get("strength") != "strong" and shares_unrequested_source_style and (
+            plan["marker"] == "weak_reference"
+            or explicitly_transfers_source_style(style_opening, label)
+        )
+        if style_transfer_violation:
+            issues.append(
+                f"{label} role={plan['role']} does not transfer source style; remove unrequested rendering, "
+                "lighting, and palette claims unless the target text explicitly requests them."
+            )
+    silent_tokens = ("silence", "silent", "no sound", "mute", "무음", "소리 없")
+    has_visible_action = bool(project.get("user_request") or any(
+        shot.get("visual_action") for shot in project.get("shots", [])
+    ))
+    if (sections["overall_soundscape"].strip().upper() == "N/A" and has_visible_action
+            and not any(token in explicit for token in silent_tokens)):
+        issues.append("Replace overall_soundscape N/A with concise plausible ambience and physical action sounds unless silence was explicitly requested.")
+    return issues
+
+
+def _i2va_semantic_issues(prompt: str, explicit_context: str,
+                          visual_context: str = "") -> list[str]:
+    """Detect high-confidence I2VA fidelity failures suitable for one focused retry."""
+    lower = prompt.casefold()
+    explicit = explicit_context.casefold()
+    visual = visual_context.casefold()
+    issues: list[str] = []
+
+    unsupported_terms = {
+        "young": ("Remove inferred age descriptions.", ("젊은", "어린")),
+        "teenage": ("Remove inferred age descriptions.", ("청소년", "십대")),
+        "middle-aged": ("Remove inferred age descriptions.", ("중년",)),
+        "elderly": ("Remove inferred age descriptions.", ("노인", "고령")),
+        "east asian": ("Remove inferred ethnicity descriptions.", ("동아시아",)),
+        "asian": ("Remove inferred ethnicity descriptions.", ("아시아",)),
+        "japanese": ("Remove inferred nationality descriptions.", ("일본인",)),
+        "korean": ("Remove inferred nationality descriptions.", ("한국인",)),
+        "chinese": ("Remove inferred nationality descriptions.", ("중국인",)),
+        "ukrainian": ("Remove inferred nationality descriptions.", ("우크라이나인",)),
+        "blood": ("Remove graphic effects not explicitly supplied by the user.", ("피가", "피를", "피로", "피범벅", "혈액", "출혈")),
+        "bone fragments": ("Remove graphic effects not explicitly supplied by the user.", ("뼈 조각", "뾏조각")),
+        "gore": ("Remove graphic effects not explicitly supplied by the user.", ("고어",)),
+    }
+    for term, (message, aliases) in unsupported_terms.items():
+        supported = term in explicit or any(alias in explicit_context for alias in aliases)
+        if term in lower and not supported and message not in issues:
+            issues.append(message)
+
+    for term in ("revolver", "semi-automatic"):
+        if term in lower and term not in explicit and term not in visual:
+            message = "Do not specialize the weapon type beyond the supplied evidence."
+            if message not in issues:
+                issues.append(message)
+
+    hidden_source_patterns = (
+        "unseen object", "just below the frame", "below the frame's bottom edge",
+        "below the frame’s bottom edge", "off-frame object", "out of frame to grasp",
+    )
+    if any(pattern in lower and pattern not in explicit for pattern in hidden_source_patterns):
+        issues.append("Remove the invented hidden or off-frame source; describe only the first visible entry.")
+
+    speculative_alternatives = ("oil or water", "photograph or rendering", "smiling or neutral")
+    if any(pattern in lower and pattern not in explicit for pattern in speculative_alternatives):
+        issues.append("Remove speculative alternatives joined by 'or'.")
+    if any(term in lower and term not in explicit for term in ("likely", "suggesting", "suggests")):
+        issues.append("Replace speculative interpretation with directly observable facts.")
+
+    if re.search(r"\bmedium shot\b[^.]{0,180}\bmid[- ]thigh", lower):
+        issues.append("Use one framing term consistent with a mid-thigh crop.")
+    if re.search(r"\bslightly low\b[^.]{0,40}\beye[- ]level\b", lower):
+        issues.append("Use one non-contradictory camera angle.")
+    if ("hiss of smoke" in lower or "hiss of dissolving smoke" in lower) and "hiss" not in explicit:
+        issues.append("Remove unsupported smoke sound effects.")
+
+    unsupported_consequences = (
+        "head snaps", "head jerks", "body begins to slump", "begins to slump",
+        "head to jerk", "impact causes her head", "impact causes his head",
+        "sways slightly from the force", "from the force of the movement",
+        "due to the impact", "from the impact", "soft thud of the woman's head",
+        "soft thud of the woman’s head",
+    )
+    if any(phrase in lower and phrase not in explicit for phrase in unsupported_consequences):
+        issues.append("Remove physical consequences and reaction sounds not explicitly requested by the user.")
+    return issues
+
+
+def _sanitize_i2va_semantics(prompt: str, explicit_context: str) -> str:
+    """Apply narrow deterministic repairs after a failed semantic LLM correction."""
+    text = re.sub(
+        r"\bmedium shot\b(?=[^.]{0,180}\bmid[- ]thigh)",
+        "medium-full shot",
+        prompt,
+        flags=re.IGNORECASE,
+    )
+    explicit = explicit_context.casefold()
+
+    speculative_patterns: list[re.Pattern[str]] = []
+    if "suggesting" not in explicit and "suggests" not in explicit:
+        speculative_patterns.extend((
+            re.compile(r"\b(?:suggesting|which\s+suggests)\b", flags=re.IGNORECASE),
+            re.compile(r"\bsuggests\b", flags=re.IGNORECASE),
+        ))
+    if "likely" not in explicit:
+        speculative_patterns.append(re.compile(r"\blikely\b", flags=re.IGNORECASE))
+
+    if speculative_patterns:
+        parts = re.split(r"(?<=[.!?])(\s+)", text)
+        for index in range(0, len(parts), 2):
+            sentence = parts[index]
+            matches = [pattern.search(sentence) for pattern in speculative_patterns]
+            matches = [match for match in matches if match]
+            if not matches:
+                continue
+            first = min(matches, key=lambda match: match.start())
+            prefix = sentence[:first.start()].rstrip(" ,;:-")
+            words = re.findall(r"[A-Za-z]+", prefix)
+            if len(words) < 3 or (words and words[-1].casefold() in {
+                "is", "are", "was", "were", "seems", "appears",
+            }):
+                prefix = ""
+            parts[index] = prefix + ("." if prefix and not prefix.endswith((".", "!", "?")) else "")
+            if (not parts[index] and index + 1 < len(parts)
+                    and "\n" not in parts[index + 1]):
+                parts[index + 1] = ""
+        text = "".join(parts)
+
+    if "oil or water" not in explicit:
+        text = re.sub(
+            r"(?:the\s+application\s+of\s+)?(?:body\s+)?oil\s+or\s+water",
+            "a visible sheen",
+            text,
+            flags=re.IGNORECASE,
+        )
+    if "photograph or rendering" not in explicit:
+        text = re.sub(r"photograph\s+or\s+rendering", "image", text, flags=re.IGNORECASE)
+    if "smiling or neutral" not in explicit:
+        text = re.sub(r"smiling\s+or\s+neutral", "restrained", text, flags=re.IGNORECASE)
+
+    consequence_patterns: list[tuple[str, tuple[str, ...]]] = [
+        (
+            r"\b(?:(?:her|his|their|the woman's|the woman’s|the subject's|the subject’s)\s+)?"
+            r"head\s+(?:snaps|jerks)(?:\s+sharply)?(?:\s+to\s+(?:her|his|their)\s+\w+\s+side)?",
+            ("head snaps", "head jerks", "머리가 획", "고개가 획", "머리가 꺽", "고개가 꺽"),
+        ),
+        (
+            r"\b(?:the\s+)?impact\s+causes\s+(?:her|his|their|the\s+subject's|the\s+subject’s)\s+"
+            r"head\s+to\s+jerk(?:\s+sharply)?(?:\s+to\s+(?:her|his|their)\s+\w+\s+side)?",
+            ("impact causes her head", "impact causes his head", "head to jerk", "충격으로 머리", "충격으로 고개"),
+        ),
+        (
+            r"\b(?:(?:her|his|their|the woman's|the woman’s|the subject's|the subject’s)\s+)?"
+            r"body\s+begins\s+to\s+slump(?:\s+slightly\s+forward)?",
+            ("begins to slump", "body slumps", "쓰러", "주저앉", "고꾸라"),
+        ),
+        (
+            r"\b(?:(?:her|his|their|the woman's|the woman’s|the subject's|the subject’s)\s+)?"
+            r"body\s+(?:remains\s+upright\s+but\s+)?sways(?:\s+slightly)?\s+from\s+the\s+force"
+            r"(?:\s+of\s+the\s+movement)?",
+            ("sways slightly from the force", "sways from the force", "몸이 휘청", "몸이 흔들"),
+        ),
+        (
+            r"\bdue\s+to\s+(?:the\s+)?impact\b|\bfrom\s+the\s+impact\b",
+            ("due to the impact", "from the impact", "충격으로", "충격 때문"),
+        ),
+        (
+            r"\b(?:the\s+)?soft\s+thud\s+of\b[^.!?\n]*",
+            ("soft thud", "둔탁한", "쿠 소리", "쿠하는"),
+        ),
+    ]
+    active = [
+        re.compile(pattern, flags=re.IGNORECASE)
+        for pattern, support_terms in consequence_patterns
+        if not any(term in explicit for term in support_terms)
+    ]
+    if not active:
+        return text.strip()
+
+    parts = re.split(r"(?<=[.!?])(\s+)", text)
+    for index in range(0, len(parts), 2):
+        sentence = parts[index]
+        matches = [pattern.search(sentence) for pattern in active]
+        matches = [match for match in matches if match]
+        if not matches:
+            continue
+        first = min(matches, key=lambda match: match.start())
+        prefix = sentence[:first.start()]
+        prefix = re.sub(
+            r"(?:[,;:]\s*)?(?:(?:and|followed\s+(?:immediately\s+)?by|with)\s+)?"
+            r"(?:the\s+)?$",
+            "",
+            prefix,
+            flags=re.IGNORECASE,
+        ).rstrip(" ,;:-")
+        # A stranded possessive or pronoun contains no useful event.
+        if re.fullmatch(r"(?:her|his|their|the woman'?s|the subject'?s)?", prefix, flags=re.IGNORECASE):
+            prefix = ""
+        parts[index] = prefix + ("." if prefix and not prefix.endswith((".", "!", "?")) else "")
+        if (not parts[index] and index + 1 < len(parts)
+                and "\n" not in parts[index + 1]):
+            parts[index + 1] = ""
+    return "".join(parts).strip()
+
+
+def _qwen_reference_plan(project: dict[str, Any], effective_seconds: float,
+                         visual_evidence: dict[str, str]) -> str:
+    references = _reference_labels(project["references"])
+    if not references:
+        return "REFERENCE_PLAN:\nnone"
+    refs_by_label = {ref["label"]: ref for ref in references}
+    blocks: list[str] = []
+
+    def evidence_for(source_label: str) -> str:
+        if visual_evidence.get(source_label):
+            return visual_evidence[source_label]
+        ref = refs_by_label.get(source_label, {})
+        if ref.get("type") == "picture" and ref.get("image_filename"):
+            return "pending role-aware image analysis during enhancement"
+        if ref.get("type") == "video" and ref.get("video_filename"):
+            return "pending duration-limited ordered-frame analysis during enhancement"
+        return "not supplied"
+
+    if project["mode"] == "REF2VA":
+        model = _reference_model(project)
+        for label, plan in model["label_plan"].items():
+            source = plan["source"]
+            ref = refs_by_label.get(source, {})
+            lines = [
+                label,
+                f"source: {source}",
+                f"media_type: {str(ref.get('type') or plan['kind']).lower()}",
+                f"role: {plan['role']}",
+            ]
+            if plan["kind"] == "Subject":
+                lines.append(f"input_strength_for_definition_scope_only: {plan.get('strength', 'normal')}")
+            lines.extend((
+                f"retention_output_marker: {plan['marker']}",
+                f"contract: {plan['contract']}",
+            ))
+            if ref.get("description"):
+                lines.append(f"user_metadata: {ref['description']}")
+            if ref.get("type") == "picture":
+                lines.append(f"visual_evidence: {evidence_for(source)}")
+            elif ref.get("type") == "video":
+                lines.append(f"temporal_visual_evidence: {evidence_for(source)}")
+            if ref.get("duration"):
+                duration_key = (
+                    "analysis_leading_duration_seconds"
+                    if ref.get("type") == "video"
+                    else "source_duration_seconds"
+                )
+                lines.append(f"{duration_key}: {ref['duration']:.2f}")
+            blocks.append("\n".join(lines))
+        return (
+            "REFERENCE_PLAN:\n"
+            f"task_types: {' + '.join(model['task_types'])}\n\n"
+            + "\n\n".join(blocks)
+        )
+
+    for ref in references:
+        lines = [ref["label"], f"media_type: {ref['type']}", f"role: {ref['role']}"]
+        if ref["role"] == "first_frame":
+            lines.extend(("anchor: exact opening frame", "anchor_time_seconds: 0.00"))
+        elif ref["role"] == "last_frame":
+            lines.extend(("anchor: exact final frame", f"anchor_time_seconds: {effective_seconds:.2f}"))
+        if ref["description"]:
+            lines.append(f"user_metadata: {ref['description']}")
+        if ref["type"] == "picture":
+            lines.append(f"visual_evidence: {evidence_for(ref['label'])}")
+        elif ref["type"] == "video":
+            lines.append(f"temporal_visual_evidence: {evidence_for(ref['label'])}")
+        if ref["duration"]:
+            duration_key = (
+                "analysis_leading_duration_seconds"
+                if ref["type"] == "video"
+                else "source_duration_seconds"
+            )
+            lines.append(f"{duration_key}: {ref['duration']:.2f}")
+        blocks.append("\n".join(lines))
+    plan = "REFERENCE_PLAN:\n" + "\n\n".join(blocks)
+    if project["mode"] == "FL2VA":
+        plan += (
+            "\n\nENDPOINT_CONTRACT:\n"
+            "Picture 1 is the exact whole frame only at 0.00 seconds.\n"
+            f"Picture 2 is the exact whole frame only at {effective_seconds:.2f} seconds.\n"
+            "Picture 2 is not the opening state of the final shot. The final shot continues from the preceding "
+            "transition and reaches Picture 2 only in its final frames.\n"
+            "Do not merge identities or transfer clothing, anatomy, materials, or features between distinct "
+            "visible entities unless the user explicitly uses morph or transform language. Punch, hit, fall, "
+            "enter, exit, and cut are not transformation requests. Content absent from Picture 2 must leave "
+            "the frame before the endpoint.\n"
+            "entity_binding: the entity visible in Picture 1 owns only Picture 1 traits; the entity visible in "
+            "Picture 2 owns only Picture 2 traits. If the final shot introduces an entity matching Picture 2, "
+            "that introduced entity is the final-frame entity. Never apply Picture 2 traits to the Picture 1 "
+            "entity without an explicit morph or transform request."
+        )
+    return plan
+
+
+def _qwen_shot_plan(project: dict[str, Any], effective_seconds: float,
+                    aliases: dict[str, str]) -> str:
+    requested_seconds = sum(float(shot["duration"]) for shot in project["shots"])
+    scale = effective_seconds / requested_seconds if requested_seconds > 0 else 1.0
+    cursor = 0.0
+    blocks: list[str] = []
+    for index, shot in enumerate(project["shots"], 1):
+        shot_seconds = float(shot["duration"]) * scale
+        end = cursor + shot_seconds
+        lines = [f"[Shot {index}]", f"time_range_seconds: {cursor:.3f}-{end:.3f}"]
+        if index > 1:
+            lines.append(f"required_output_header: [Shot {index}] At {format_timestamp(cursor)},")
+        action = _replace_aliases(shot["visual_action"], aliases)
+        if action:
+            lines.append(f"visual_action: {action}")
+            lines.append("action_contract: preserve every explicit action above in the same order; omit none")
+            lines.append(
+                "semantic_lock: translate faithfully; preserve every explicitly named actor, body part, "
+                "object, quantity, direction, simultaneity, and physical action verb; never replace one with a broader state or euphemism"
+            )
+            lines.append(
+                "motion_semantics_contract: preserve the source verb at its original specificity. If it denotes "
+                "continuous or repeated motion, show distinct ongoing motion phases appropriate to that verb rather "
+                "than replacing it with a single contact, broad pose, or static hold. Preserve stated actors, limb or "
+                "hand count, contact target, direction, and simultaneity without inventing an exact cycle or step count"
+            )
+        if project["mode"] == "FL2VA" and index == len(project["shots"]):
+            lines.extend((
+                "opening_state: continue the incomplete transition from the preceding shot; do not reveal the completed Picture 2",
+                "entity_continuity: an entering entity that matches Picture 2 is the same final-frame entity; do not rename or duplicate it",
+                f"required_end_state: exact whole-frame match to Picture 2 at {effective_seconds:.2f} seconds",
+            ))
+        blocks.append("\n".join(lines))
+        cursor = end
+    return "SHOT_PLAN:\n" + "\n\n".join(blocks)
+
+
+_TARGET_STYLE_PATTERNS = (
+    (re.compile(r"(?i)(?:\b3d\s*(?:cg|cgi|animation)\b|3d\s*애니메이션)"), "3D CG animation"),
+    (re.compile(r"(?i)(?:\b2d\s*animation\b|2d\s*애니메이션)"), "2D animation"),
+    (re.compile(r"(?i)(?:\blive[\s-]*action\b|실사)"), "live-action"),
+    (re.compile(r"(?i)(?:\bphotorealistic\b|포토리얼|사실적인\s*사진)"), "photorealistic live-action"),
+    (re.compile(r"(?i)(?:\bstop[\s-]*motion\b|스톱\s*모션)"), "stop-motion"),
+    (re.compile(r"(?i)(?:\bclaymation\b|클레이메이션)"), "claymation"),
+    (re.compile(r"(?i)(?:\banime[\s-]*style(?:d)?\b|애니메\s*스타일|애니메이션풍)"), "anime-style animation"),
+)
+_LARGE_MOTION_RE = re.compile(
+    r"(?i)(?:걷|걸|달리|뛰|기어|점프|춤|회전|\bwalk|\brun|\bcrawl|\bjump|\bdance|\bspin|\bturn)"
+)
+
+
+def _project_instruction_text(project: dict[str, Any]) -> str:
+    return "\n".join((
+        _clean_text(project.get("user_request")),
+        *(_clean_text(shot.get("visual_action")) for shot in project.get("shots", [])),
+        _clean_text(project.get("constraints")),
+    ))
+
+
+def _extract_target_style_lock(project: dict[str, Any]) -> str:
+    text = _project_instruction_text(project)
+    for pattern, canonical in _TARGET_STYLE_PATTERNS:
+        if pattern.search(text):
+            return canonical
+    return ""
+
+
+def _requires_action_visibility_lock(project: dict[str, Any]) -> bool:
+    return bool(_LARGE_MOTION_RE.search(_project_instruction_text(project)))
+
+
+def _enhanced_output_budget(effective_seconds: float, shot_count: int) -> str:
+    if effective_seconds <= 6.5:
+        words = "140-220" if shot_count == 1 else "180-300 total"
+    elif effective_seconds <= 12.5:
+        words = "220-360" if shot_count == 1 else "300-480 total"
+    else:
+        words = "380-620 total"
+    return (
+        "OUTPUT_BUDGET:\n"
+        f"recommended_english_words: {words}\n"
+        "priority: concise action clarity over exhaustive appearance inventory or decorative prose"
+    )
+
+
+def build_video_prompt(project: dict[str, Any], effective_seconds: float,
+                       visual_evidence: dict[str, str] | None = None) -> str:
+    """Build compact mode data for the single-pass Qwen H3 rewriter."""
+    visual_evidence = visual_evidence or {}
+    mode = project["mode"]
+    model = _reference_model(project) if mode == "REF2VA" else None
+    aliases = model["aliases"] if model else {}
+    user_request = _replace_aliases(project["user_request"], aliases)
+    target_style = _extract_target_style_lock(project)
+    has_strong_subject = bool(model and any(
+        plan.get("kind") == "Subject" and plan.get("strength") == "strong"
+        for plan in model["label_plan"].values()
+    ))
+    if mode == "I2VA":
+        reference_style_policy = (
+            "Picture 1's observable visual medium/rendering style is part of the exact opening-frame anchor; "
+            "preserve it unless the user explicitly requests a style change"
+        )
+    elif mode == "FL2VA":
+        reference_style_policy = (
+            "the observable media/rendering styles of Picture 1 and Picture 2 are endpoint evidence; preserve a "
+            "shared style or describe only the requested transition needed to reach Picture 2"
+        )
+    elif mode == "L2VA":
+        reference_style_policy = (
+            "Picture 1's observable visual medium/rendering style is part of the exact final-frame anchor"
+        )
+    elif has_strong_subject:
+        reference_style_policy = (
+            "for each strong Subject, preserve that Subject's source visual medium/rendering style as part of its "
+            "identity; keep different Subjects' styles independent and do not turn them into a target-wide style, "
+            "source setting, composition, camera, lighting setup, or scene-wide palette"
+        )
+    else:
+        reference_style_policy = "analysis evidence only; do not transfer or name it unless explicitly requested"
+    sections = [
+        "INPUT DATA ONLY - DO NOT COPY THESE KEYS INTO THE FINAL H3 PROMPT",
+        "MODE_DATA:\n"
+        f"mode: {mode}\n"
+        f"requested_duration_seconds: {project['requested_duration']:.2f}\n"
+        f"effective_duration_seconds: {effective_seconds:.2f}\n"
+        f"shot_count: {len(project['shots'])}",
+        "STYLE_POLICY:\n"
+        "target_video_style: use only when explicitly requested in TARGET_REQUEST, SHOT_PLAN visual_action, or CONSTRAINTS\n"
+        "when_unspecified: omit any target-wide style invented beyond a concrete keyframe or Strong Subject contract\n"
+        f"reference_visual_style: {reference_style_policy}",
+        "CAMERA_POLICY:\n"
+        "source: infer composition, viewpoint, camera behavior, and explicit transition intent from TARGET_REQUEST and SHOT_PLAN visual_action\n"
+        "per_shot: choose framing that contains the largest required visible action and final state; use a static shot only when all required events remain inside the opening crop, otherwise use one motivated reframe\n"
+        "expression: write camera behavior as natural English; add amplitude and speed only when meaningful\n"
+        "shot_boundaries: each configured shot after Shot 1 is an ordinary cut at its time-range start; use cross-dissolve, fade, or wipe only when explicitly requested\n"
+        "restraint: do not invent decorative motion or a new cut when a static camera or a small continuous camera move presents the action clearly",
+    ]
+    if user_request:
+        sections.append("TARGET_REQUEST:\n" + user_request)
+    if target_style:
+        if mode == "FL2VA":
+            style_application = (
+                "use this target style except where an explicitly requested style transition is needed to reach an exact endpoint; "
+                "the assigned Picture 1 and Picture 2 states remain exact at their timestamps"
+            )
+        elif mode == "L2VA":
+            style_application = (
+                "use this target style along the approach when compatible, but converge to Picture 1's exact final-frame medium and rendering state"
+            )
+        elif mode == "REF2VA":
+            style_application = (
+                "apply this as the target-video style; it overrides incompatible source presentation, while Strong Subjects retain identity, "
+                "design, and compatible material traits; preserve a conflicting source medium only when mixed-media treatment is explicitly requested"
+            )
+        else:
+            style_application = "begin Shot 1 with this style and maintain it throughout"
+        sections.append(
+            "TARGET_STYLE_LOCK:\n"
+            f"canonical_style: {target_style}\n"
+            "source: explicit user request\n"
+            "priority: overrides an incompatible source-image medium or photographed-object presentation\n"
+            f"application: {style_application}"
+        )
+        if project.get("references"):
+            sections.append(
+                "REFERENCE_MEDIUM_CONTRACT:\n"
+                "use_reference_for: identity, design, assigned anchor pose and composition, action-relevant "
+                "objects, and environment\n"
+                f"target_medium: {target_style}\n"
+                "exclude_incompatible_source_presentation: photographed collectible, rigid display object, product photography, "
+                "and display-only joint sounds\n"
+                "material_policy: preserve visible plastic, resin, vinyl, jelly, glass, or translucent material only when it is part "
+                "of the character or object design and compatible with the requested target style"
+            )
+    if _requires_action_visibility_lock(project):
+        sections.append(
+            "ACTION_VISIBILITY_LOCK:\n"
+            "A frame anchor is exact at its assigned time. Outside that instant, use one small motivated reframe "
+            "only when the opening crop cannot show the requested body movement or interaction. Do not describe "
+            "off-frame foot placement, steps, or contact sounds as visible action. For forward locomotion from a "
+            "close crop, reveal enough of the stride to make locomotion observable."
+        )
+    if project.get("enhance") is True:
+        sections.append(_enhanced_output_budget(effective_seconds, len(project["shots"])))
+    sections.extend((
+        _qwen_reference_plan(project, effective_seconds, visual_evidence),
+        _qwen_shot_plan(project, effective_seconds, aliases),
+        "AUDIO_POLICY:\n"
+        "source: infer audio intent only from TARGET_REQUEST, SHOT_PLAN visual_action, and locked audio relationships in REFERENCE_PLAN\n"
+        "diegetic_and_ambience: derive concise synchronized action sounds and plausible environmental ambience from requested visible events and setting\n"
+        "material_sound_fidelity: do not invent fabric rustle, clothing creak, plastic joint noise, smoke hiss, or another material sound unless that material and audible cause are established by user text or reference evidence\n"
+        "music_routing: music with an in-scene source is diegetic and belongs in the shot timeline; requested BGM, background music, soundtrack, score, or source-free music belongs in non_diegetic_music\n"
+        "when_music_unspecified: output non_diegetic_music: N/A",
+    ))
+    if project["constraints"]:
+        sections.append("CONSTRAINTS:\n" + _replace_aliases(project["constraints"], aliases))
+    if project["verbatim_content"]:
+        sections.append("VERBATIM_CONTENT:\n" + project["verbatim_content"])
+    return "\n\n".join(sections)
+
+
+def build_llm_prompt(project: dict[str, Any], video_prompt: str) -> str:
+    mode = project["mode"]
+    expected_shots = list(range(1, len(project["shots"]) + 1))
+    final_shot = len(expected_shots)
+    effective_seconds = align_frame_count(project["requested_duration"]) / MODEL_FPS
+    reference_model = _reference_model(project) if mode == "REF2VA" else None
+    content_locks = _input_content_locks(project)
+    system_prompt = "\n\n".join((
+        _mode_prompt_preamble(mode),
+        MODE_LLM_SYSTEM_PROMPTS[mode],
+        _reference_system_modules(project) if mode == "REF2VA" else "",
+        _single_pass_output_lock(
+            mode, effective_seconds, final_shot, expected_shots, reference_model, content_locks,
+        ),
+    ))
+    return (
+        "SYSTEM PROMPT:\n"
+        f"{system_prompt}\n\n"
+        f"USER DATA FOR ACTIVE MODE {mode}:\n"
+        f"{video_prompt}"
+    )
+
+
+def _llm_roots() -> list[str]:
+    roots: list[str] = []
+    try:
+        import folder_paths
+
+        try:
+            roots.extend(folder_paths.get_folder_paths("LLM"))
+        except KeyError:
+            pass
+        fallback = os.path.join(folder_paths.models_dir, "LLM")
+        roots.append(fallback)
+    except ImportError:
+        pass
+    return list(dict.fromkeys(os.path.abspath(path) for path in roots if path))
+
+
+def _is_writer_gguf(path: str) -> bool:
+    name = os.path.basename(path).lower()
+    excluded = ("mmproj", "lora", "vision", "draft")
+    return name.endswith(".gguf") and not any(token in name for token in excluded)
+
+
+def list_enhance_models(roots: list[str] | None = None) -> list[dict[str, Any]]:
+    roots = roots if roots is not None else _llm_roots()
+    default_installed = any(
+        os.path.isfile(path)
+        for root in roots
+        for path in glob.iglob(os.path.join(root, "**", DEFAULT_ENHANCE_MODEL_FILE), recursive=True)
+    )
+    lightx2v = _lightx2v_install_state(roots)
+    return [{
+        "id": DEFAULT_ENHANCE_MODEL_ID,
+        "label": "Qwen3.8-27B Uncensored Q4_K_M",
+        "installed": default_installed,
+        "size": 0 if default_installed else DEFAULT_ENHANCE_MODEL_SIZE,
+    }, {
+        "id": LIGHTX2V_MODEL_ID,
+        "label": LIGHTX2V_MODEL_DISPLAY_NAME,
+        "installed": lightx2v["installed"],
+        "size": lightx2v["missing_size"],
+    }]
+
+
+def _lightx2v_model_dir(roots: list[str]) -> str:
+    return os.path.join(
+        roots[0], "indhic-ai", "MiniMax_H3-Prompt_Rewriter-8B-LORA-Merged-GGUF",
+    )
+
+
+def _lightx2v_install_state(roots: list[str]) -> dict[str, Any]:
+    if not roots:
+        return {
+            "installed": False, "model_installed": False, "mmproj_installed": False,
+            "missing_size": LIGHTX2V_TOTAL_SIZE, "model_path": "", "mmproj_path": "",
+        }
+    model_dir = _lightx2v_model_dir(roots)
+    model_path = os.path.join(model_dir, LIGHTX2V_MODEL_FILE)
+    mmproj_path = os.path.join(model_dir, LIGHTX2V_MMPROJ_FILE)
+    model_installed = os.path.isfile(model_path)
+    mmproj_installed = os.path.isfile(mmproj_path)
+    return {
+        "installed": model_installed and mmproj_installed,
+        "model_installed": model_installed,
+        "mmproj_installed": mmproj_installed,
+        "missing_size": (0 if model_installed else LIGHTX2V_MODEL_SIZE)
+                        + (0 if mmproj_installed else LIGHTX2V_MMPROJ_SIZE),
+        "model_path": model_path,
+        "mmproj_path": mmproj_path,
+    }
+
+
+def list_image_models(roots: list[str] | None = None) -> list[dict[str, Any]]:
+    roots = roots if roots is not None else _llm_roots()
+    writer_model = next((path for root in roots for path in glob.iglob(os.path.join(root, "**", DEFAULT_ENHANCE_MODEL_FILE), recursive=True) if os.path.isfile(path)), None)
+    qwen_mmproj = next((path for root in roots for path in glob.iglob(os.path.join(root, "**", QWEN_IMAGE_MMPROJ_FILE), recursive=True) if os.path.isfile(path)), None)
+    qwen_installed = bool(writer_model and qwen_mmproj)
+    qwen_missing_size = (0 if writer_model else QWEN_IMAGE_MODEL_SIZE) + (0 if qwen_mmproj else QWEN_IMAGE_MMPROJ_SIZE)
+    lightx2v = _lightx2v_install_state(roots)
+    return [{
+        "id": QWEN_IMAGE_MODEL_ID,
+        "label": (
+            QWEN_MODEL_DISPLAY_NAME
+            + (" · installed" if qwen_installed else f" · {qwen_missing_size / 1e9:.2f} GB missing")
+            + f" · {QWEN_MODEL_VRAM_LABEL}"
+        ),
+        "installed": qwen_installed,
+        "size": qwen_missing_size,
+        "text_installed": bool(writer_model),
+        "vision_installed": bool(qwen_mmproj),
+        "text_size": 0 if writer_model else QWEN_IMAGE_MODEL_SIZE,
+        "vision_size": 0 if qwen_mmproj else QWEN_IMAGE_MMPROJ_SIZE,
+        "enhance_model": DEFAULT_ENHANCE_MODEL_ID,
+        "image_model": QWEN_IMAGE_MODEL_ID,
+        "supported_modes": list(SUPPORTED_MODES[1:]),
+        "runtime": "llama.cpp",
+    }, {
+        "id": LIGHTX2V_MODEL_ID,
+        "label": (
+            LIGHTX2V_MODEL_DISPLAY_NAME
+            + (" · installed" if lightx2v["installed"] else f" · {lightx2v['missing_size'] / 1e9:.2f} GB missing")
+            + f" · {LIGHTX2V_MODEL_VRAM_LABEL} · R2V unsupported"
+        ),
+        "installed": lightx2v["installed"],
+        "size": lightx2v["missing_size"],
+        "text_installed": lightx2v["installed"],
+        "vision_installed": lightx2v["installed"],
+        "text_size": lightx2v["missing_size"],
+        "vision_size": 0,
+        "enhance_model": LIGHTX2V_MODEL_ID,
+        "image_model": LIGHTX2V_MODEL_ID,
+        "supported_modes": list(LIGHTX2V_SUPPORTED_MODES),
+        "runtime": "llama.cpp-gguf",
+    }]
+
+
+def _download_image_component(repo_id: str, filename: str, local_dir: str, component_size: int,
+                              completed_size: int, bundle_size: int, progress=None) -> str:
+    from huggingface_hub import hf_hub_download
+
+    stop_monitor = threading.Event()
+
+    def monitor_download() -> None:
+        last_size = -1
+        while not stop_monitor.wait(0.35):
+            candidates = glob.glob(os.path.join(local_dir, "**", "*.incomplete"), recursive=True)
+            candidates.append(os.path.join(local_dir, filename))
+            size = min(component_size, max((os.path.getsize(path) for path in candidates if os.path.isfile(path)), default=0))
+            if size != last_size and progress:
+                progress(stage="downloading", message=f"Downloading image model component: {filename}",
+                         downloaded=completed_size + size, total=bundle_size)
+                last_size = size
+
+    monitor = threading.Thread(target=monitor_download, name="toyxyz-h3-image-download", daemon=True)
+    monitor.start()
+    try:
+        return hf_hub_download(repo_id=repo_id, filename=filename, local_dir=local_dir)
+    finally:
+        stop_monitor.set()
+        monitor.join(timeout=1)
+
+
+def _resolve_lightx2v_model(progress=None) -> tuple[str, str]:
+    roots = _llm_roots()
+    if not roots:
+        raise RuntimeError("ComfyUI has no registered models/LLM directory.")
+    state = _lightx2v_install_state(roots)
+    if state["installed"]:
+        if progress:
+            progress(stage="model_ready", message="LightX2V merged GGUF Q8_0 + Vision F16 bundle is installed.")
+        return os.path.abspath(state["model_path"]), os.path.abspath(state["mmproj_path"])
+    try:
+        import huggingface_hub  # noqa: F401
+    except ImportError as exc:
+        raise RuntimeError("huggingface_hub is required to download the LightX2V GGUF bundle.") from exc
+
+    model_dir = _lightx2v_model_dir(roots)
+    os.makedirs(model_dir, exist_ok=True)
+    total = int(state["missing_size"])
+    completed = 0
+    try:
+        if progress:
+            progress(
+                stage="downloading", message="Starting LightX2V merged GGUF bundle download.",
+                downloaded=0, total=total,
+            )
+        if not state["model_installed"]:
+            _download_image_component(
+                LIGHTX2V_MODEL_REPO, LIGHTX2V_MODEL_FILE, model_dir,
+                LIGHTX2V_MODEL_SIZE, completed, total, progress,
+            )
+            completed += LIGHTX2V_MODEL_SIZE
+        if not state["mmproj_installed"]:
+            _download_image_component(
+                LIGHTX2V_MODEL_REPO, LIGHTX2V_MMPROJ_FILE, model_dir,
+                LIGHTX2V_MMPROJ_SIZE, completed, total, progress,
+            )
+        installed = _lightx2v_install_state(roots)
+        if not installed["installed"]:
+            raise RuntimeError("The LightX2V merged GGUF download completed but required files are missing.")
+        if progress:
+            progress(
+                stage="downloading", message="LightX2V merged GGUF bundle download completed.",
+                downloaded=total, total=total,
+            )
+            progress(
+                stage="model_ready", message="LightX2V merged GGUF Q8_0 + Vision F16 bundle is ready.",
+                downloaded=total, total=total,
+            )
+        return os.path.abspath(installed["model_path"]), os.path.abspath(installed["mmproj_path"])
+    finally:
+        pass
+
+
+def _resolve_image_model(model_id: str, progress=None) -> tuple[str, str]:
+    roots = _llm_roots()
+    if not roots:
+        raise RuntimeError("ComfyUI has no registered models/LLM directory.")
+    if model_id != QWEN_IMAGE_MODEL_ID:
+        raise ValueError("Only the Qwen3.8 Vision F16 image analysis bundle is supported.")
+    repo_id = QWEN_IMAGE_MODEL_REPO
+    model_file = QWEN_IMAGE_MODEL_FILE
+    mmproj_file = QWEN_IMAGE_MMPROJ_FILE
+    model_size = QWEN_IMAGE_MODEL_SIZE
+    mmproj_size = QWEN_IMAGE_MMPROJ_SIZE
+    bundle_name = "Qwen3.8 Vision F16"
+    model_path = next((path for root in roots for path in glob.iglob(os.path.join(root, "**", model_file), recursive=True) if os.path.isfile(path)), None)
+    mmproj_path = next((path for root in roots for path in glob.iglob(os.path.join(root, "**", mmproj_file), recursive=True) if os.path.isfile(path)), None)
+    if model_path and mmproj_path:
+        if progress:
+            progress(stage="image_model_ready", message=f"{bundle_name} image analysis bundle is installed.")
+        return os.path.abspath(model_path), os.path.abspath(mmproj_path)
+    try:
+        import huggingface_hub  # noqa: F401
+    except ImportError as exc:
+        raise RuntimeError(f"huggingface_hub is required to download the {bundle_name} image model bundle.") from exc
+    local_dir = roots[0]
+    os.makedirs(local_dir, exist_ok=True)
+    download_total = (0 if model_path else model_size) + (0 if mmproj_path else mmproj_size)
+    completed_size = 0
+    if not model_path:
+        model_path = _download_image_component(
+            repo_id, model_file, local_dir, model_size, 0, download_total, progress,
+        )
+        completed_size += model_size
+    if not mmproj_path:
+        mmproj_path = _download_image_component(
+            repo_id, mmproj_file, local_dir, mmproj_size, completed_size, download_total, progress,
+        )
+    if progress:
+        progress(stage="image_model_ready", message=f"{bundle_name} image analysis bundle is ready.",
+                 downloaded=download_total, total=download_total)
+    return os.path.abspath(model_path), os.path.abspath(mmproj_path)
+
+
+def _resolve_local_model(model_id: str, roots: list[str]) -> str | None:
+    if model_id == DEFAULT_ENHANCE_MODEL_ID:
+        for root in roots:
+            for path in glob.iglob(os.path.join(root, "**", DEFAULT_ENHANCE_MODEL_FILE), recursive=True):
+                if os.path.isfile(path):
+                    return os.path.abspath(path)
+        return None
+    if not model_id.startswith("local:"):
+        raise ValueError("Unknown enhancement model selection.")
+    relative = model_id[len("local:"):].replace("/", os.sep)
+    for root in roots:
+        root_path = os.path.abspath(root)
+        candidate = os.path.abspath(os.path.join(root_path, relative))
+        try:
+            inside = os.path.commonpath((root_path, candidate)) == root_path
+        except ValueError:
+            inside = False
+        if inside and os.path.isfile(candidate) and _is_writer_gguf(candidate):
+            return candidate
+    raise FileNotFoundError("The selected local GGUF model is no longer available.")
+
+
+def _resolve_enhance_model(model_id: str, progress=None) -> str:
+    roots = _llm_roots()
+    if not roots:
+        raise RuntimeError("ComfyUI has no registered models/LLM directory.")
+    local = _resolve_local_model(model_id, roots)
+    if local:
+        if progress:
+            progress(stage="model_ready", message="Selected GGUF model is installed.")
+        return local
+    if model_id != DEFAULT_ENHANCE_MODEL_ID:
+        raise FileNotFoundError("The selected enhancement model was not found.")
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError as exc:
+        raise RuntimeError("huggingface_hub is required to download the default enhancement model.") from exc
+    os.makedirs(roots[0], exist_ok=True)
+    stop_monitor = threading.Event()
+
+    def monitor_download() -> None:
+        last_size = -1
+        while not stop_monitor.wait(0.35):
+            candidates = glob.glob(os.path.join(roots[0], "**", "*.incomplete"), recursive=True)
+            candidates.append(os.path.join(roots[0], DEFAULT_ENHANCE_MODEL_FILE))
+            size = max((os.path.getsize(path) for path in candidates if os.path.isfile(path)), default=0)
+            if size != last_size and progress:
+                progress(
+                    stage="downloading",
+                    message="Downloading the default GGUF model.",
+                    downloaded=size,
+                    total=DEFAULT_ENHANCE_MODEL_SIZE,
+                )
+                last_size = size
+
+    monitor = threading.Thread(target=monitor_download, name="toyxyz-h3-download-progress", daemon=True)
+    monitor.start()
+    try:
+        if progress:
+            progress(stage="downloading", message="Starting model download.", downloaded=0, total=DEFAULT_ENHANCE_MODEL_SIZE)
+        downloaded_path = hf_hub_download(
+            repo_id=DEFAULT_ENHANCE_MODEL_REPO,
+            filename=DEFAULT_ENHANCE_MODEL_FILE,
+            local_dir=roots[0],
+        )
+        if progress:
+            progress(
+                stage="downloading",
+                message="Model download completed.",
+                downloaded=DEFAULT_ENHANCE_MODEL_SIZE,
+                total=DEFAULT_ENHANCE_MODEL_SIZE,
+            )
+        return downloaded_path
+    finally:
+        stop_monitor.set()
+        monitor.join(timeout=1)
+
+
+def _find_llama_cli() -> str:
+    configured = os.environ.get("TOYXYZ_LLAMA_CLI", "").strip()
+    candidates = [configured, shutil.which("llama-cli") or "", shutil.which("llama-cli.exe") or ""]
+    try:
+        import folder_paths
+
+        user_root = os.path.join(folder_paths.base_path, "user")
+        candidates.extend(glob.glob(os.path.join(user_root, "**", "llama-cli.exe"), recursive=True))
+        candidates.extend(glob.glob(os.path.join(user_root, "**", "llama-cli"), recursive=True))
+    except ImportError:
+        pass
+    for candidate in candidates:
+        if candidate and os.path.isfile(candidate):
+            return os.path.abspath(candidate)
+    raise RuntimeError(
+        "llama-cli was not found. Install llama.cpp, install MiniMax-H3-Prompt-Rewriter-ComfyUI, "
+        "or set TOYXYZ_LLAMA_CLI to the executable path."
+    )
+
+
+def _find_llama_server() -> str:
+    configured = os.environ.get("TOYXYZ_LLAMA_SERVER", "").strip()
+    candidates = [configured, shutil.which("llama-server") or "", shutil.which("llama-server.exe") or ""]
+    try:
+        cli_path = _find_llama_cli()
+        sibling_name = "llama-server.exe" if os.name == "nt" else "llama-server"
+        candidates.append(os.path.join(os.path.dirname(cli_path), sibling_name))
+    except RuntimeError:
+        pass
+    try:
+        import folder_paths
+
+        user_root = os.path.join(folder_paths.base_path, "user")
+        candidates.extend(glob.glob(os.path.join(user_root, "**", "llama-server.exe"), recursive=True))
+        candidates.extend(glob.glob(os.path.join(user_root, "**", "llama-server"), recursive=True))
+    except ImportError:
+        pass
+    for candidate in candidates:
+        if candidate and os.path.isfile(candidate):
+            return os.path.abspath(candidate)
+    raise RuntimeError("llama-server was not found; image analysis will use llama-cli instead.")
+
+
+def _available_local_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:
+        listener.bind(("127.0.0.1", 0))
+        return int(listener.getsockname()[1])
+
+
+class _LlamaServerSession:
+    def __init__(self, executable: str, model_path: str, mmproj_path: str,
+                 image_model_id: str = DEFAULT_IMAGE_MODEL_ID, context_size: int = 8192,
+                 extra_args: list[str] | None = None):
+        self.executable = executable
+        self.model_path = model_path
+        self.mmproj_path = mmproj_path
+        self.image_model_id = image_model_id
+        self.context_size = context_size
+        self.extra_args = list(extra_args or [])
+        self.port = _available_local_port()
+        self.process: subprocess.Popen[str] | None = None
+
+    @property
+    def base_url(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+    def start(self, timeout: float = 600.0) -> None:
+        command = [
+            self.executable, "-m", self.model_path, "--mmproj", self.mmproj_path,
+            "--host", "127.0.0.1", "--port", str(self.port), "-c", str(self.context_size),
+            "-ngl", "all", "-np", "1", "--no-webui", "--log-disable",
+            "--jinja", "--timeout", "1800",
+        ]
+        if self.image_model_id == QWEN_IMAGE_MODEL_ID:
+            command.extend([
+                "--chat-template-kwargs", '{"enable_thinking":false}',
+                "--reasoning", "off",
+            ])
+        command.extend(self.extra_args)
+        creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+        self.process = subprocess.Popen(
+            command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            text=True, creationflags=creationflags,
+        )
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self.process.poll() is not None:
+                raise RuntimeError(f"llama-server exited during startup with code {self.process.returncode}.")
+            try:
+                with urllib.request.urlopen(f"{self.base_url}/health", timeout=2) as response:
+                    if response.status == 200:
+                        return
+            except (OSError, urllib.error.URLError):
+                pass
+            time.sleep(0.2)
+        raise RuntimeError("llama-server did not become ready within 10 minutes.")
+
+    def close(self) -> None:
+        process, self.process = self.process, None
+        if process is None or process.poll() is not None:
+            return
+        process.terminate()
+        try:
+            process.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait(timeout=5)
+
+    def _chat(self, messages: list[dict[str, Any]], max_tokens: int, temperature: float) -> str:
+        payload = json.dumps({
+            "model": "local-model", "messages": messages, "stream": False,
+            "max_tokens": max_tokens, "temperature": temperature,
+            "top_p": 0.9, "top_k": 40, "repeat_penalty": 1.05,
+        }).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.base_url}/v1/chat/completions", data=payload,
+            headers={"Content-Type": "application/json"}, method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=1800) as response:
+                result = json.loads(response.read().decode("utf-8", errors="replace"))
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")[-2000:]
+            raise RuntimeError(f"llama-server request failed with HTTP {exc.code}: {detail}") from exc
+        try:
+            content = result["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise RuntimeError("llama-server returned an unexpected chat-completion response.") from exc
+        if isinstance(content, list):
+            content = "".join(
+                str(item.get("text", "")) for item in content if isinstance(item, dict)
+            )
+        return str(content or "")
+
+    def analyze_image(self, image_path: str, prompt: str) -> str:
+        mime_type = mimetypes.guess_type(image_path)[0] or "image/png"
+        with open(image_path, "rb") as handle:
+            encoded = base64.b64encode(handle.read()).decode("ascii")
+        messages = [{
+            "role": "user",
+            "content": [
+                {"type": "text", "text": prompt},
+                {"type": "image_url", "image_url": {"url": f"data:{mime_type};base64,{encoded}"}},
+            ],
+        }]
+        return self._chat(messages, max_tokens=700, temperature=0.2)
+
+    def analyze_images(self, image_paths: list[str], captions: list[str], prompt: str,
+                       max_tokens: int = 1600) -> str:
+        if len(image_paths) != len(captions) or not image_paths:
+            raise ValueError("Ordered image paths and captions are required for multimodal analysis.")
+        content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
+        for image_path, caption in zip(image_paths, captions):
+            mime_type = mimetypes.guess_type(image_path)[0] or "image/jpeg"
+            with open(image_path, "rb") as handle:
+                encoded = base64.b64encode(handle.read()).decode("ascii")
+            content.extend((
+                {"type": "text", "text": caption},
+                {"type": "image_url", "image_url": {"url": f"data:{mime_type};base64,{encoded}"}},
+            ))
+        return self._chat([{"role": "user", "content": content}], max_tokens=max_tokens, temperature=0.2)
+
+    def chat(self, messages: list[dict[str, Any]], max_tokens: int = 4096,
+             temperature: float = 0.0) -> str:
+        return self._chat(messages, max_tokens=max_tokens, temperature=temperature)
+
+
+def _start_persistent_image_server(image_model_id: str, progress=None) -> _LlamaServerSession:
+    executable = _find_llama_server()
+    model_path, mmproj_path = _resolve_image_model(image_model_id or DEFAULT_IMAGE_MODEL_ID, progress)
+    session = _LlamaServerSession(executable, model_path, mmproj_path, image_model_id, context_size=16384)
+    try:
+        session.start()
+    except Exception:
+        session.close()
+        raise
+    return session
+
+
+def _clean_llm_output(text: str) -> str:
+    # Older llama-cli builds can enter conversation mode when the prompt is
+    # supplied with -f and mix their banner, echoed input and shutdown message
+    # into stdout. Prefer explicit response markers, but keep a defensive
+    # fallback for output produced by those builds.
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", text).replace("\r\n", "\n")
+    marked = re.search(r"<H3_PROMPT>\s*(.*?)\s*</H3_PROMPT>", text, flags=re.DOTALL | re.IGNORECASE)
+    if marked:
+        text = marked.group(1)
+    elif "\n> " in text:
+        text = text.rsplit("\n> ", 1)[1]
+        # The first line is llama-cli's echoed (often truncated) user prompt.
+        text = text.partition("\n")[2]
+    text = re.sub(r"(?:^|\n)Exiting\.\.\.\s*$", "", text, flags=re.IGNORECASE).strip()
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL | re.IGNORECASE).strip()
+    fence = re.fullmatch(r"```(?:text)?\s*(.*?)\s*```", text, flags=re.DOTALL | re.IGNORECASE)
+    if fence:
+        text = fence.group(1).strip()
+    return text
+
+
+def _resolve_uploaded_image(image: dict[str, Any]) -> str:
+    filename = os.path.basename(_clean_text(image.get("filename")))
+    subfolder = _clean_text(image.get("subfolder")).replace("\\", "/").strip("/")
+    if not filename or os.path.splitext(filename)[1].lower() not in {".png", ".jpg", ".jpeg", ".webp", ".bmp"}:
+        raise ValueError("Select a supported uploaded image before analysis.")
+    import folder_paths
+
+    input_root = os.path.abspath(folder_paths.get_input_directory())
+    candidate = os.path.abspath(os.path.join(input_root, subfolder.replace("/", os.sep), filename))
+    try:
+        inside = os.path.commonpath((input_root, candidate)) == input_root
+    except ValueError:
+        inside = False
+    if not inside or not os.path.isfile(candidate):
+        raise FileNotFoundError("The uploaded reference image is unavailable in ComfyUI's input directory.")
+    return candidate
+
+
+def _resolve_uploaded_video(video: dict[str, Any]) -> str:
+    filename = os.path.basename(_clean_text(video.get("filename")))
+    subfolder = _clean_text(video.get("subfolder")).replace("\\", "/").strip("/")
+    if not filename or os.path.splitext(filename)[1].lower() not in VIDEO_EXTENSIONS:
+        raise ValueError("Select a supported uploaded video before analysis.")
+    import folder_paths
+
+    input_root = os.path.abspath(folder_paths.get_input_directory())
+    candidate = os.path.abspath(os.path.join(input_root, subfolder.replace("/", os.sep), filename))
+    try:
+        inside = os.path.commonpath((input_root, candidate)) == input_root
+    except ValueError:
+        inside = False
+    if not inside or not os.path.isfile(candidate):
+        raise FileNotFoundError("The uploaded reference video is unavailable in ComfyUI's input directory.")
+    return candidate
+
+
+def _resolve_uploaded_audio(audio: dict[str, Any]) -> str:
+    filename = os.path.basename(_clean_text(audio.get("filename")))
+    subfolder = _clean_text(audio.get("subfolder")).replace("\\", "/").strip("/")
+    if not filename or os.path.splitext(filename)[1].lower() not in AUDIO_EXTENSIONS:
+        raise ValueError("Select a supported uploaded audio file.")
+    import folder_paths
+
+    input_root = os.path.abspath(folder_paths.get_input_directory())
+    candidate = os.path.abspath(os.path.join(input_root, subfolder.replace("/", os.sep), filename))
+    try:
+        inside = os.path.commonpath((input_root, candidate)) == input_root
+    except ValueError:
+        inside = False
+    if not inside or not os.path.isfile(candidate):
+        raise FileNotFoundError("The uploaded reference audio is unavailable in ComfyUI's input directory.")
+    return candidate
+
+
+def _find_ffmpeg() -> str:
+    configured = os.environ.get("TOYXYZ_FFMPEG", "").strip()
+    candidates = [configured, shutil.which("ffmpeg") or "", shutil.which("ffmpeg.exe") or ""]
+    try:
+        import imageio_ffmpeg
+        candidates.append(imageio_ffmpeg.get_ffmpeg_exe())
+    except (ImportError, RuntimeError):
+        pass
+    for candidate in candidates:
+        if candidate and os.path.isfile(candidate):
+            return os.path.abspath(candidate)
+    raise RuntimeError("FFmpeg was not found. Install FFmpeg or set TOYXYZ_FFMPEG before analyzing videos.")
+
+
+def _find_ffprobe() -> str | None:
+    configured = os.environ.get("TOYXYZ_FFPROBE", "").strip()
+    candidates = [configured, shutil.which("ffprobe") or "", shutil.which("ffprobe.exe") or ""]
+    ffmpeg = shutil.which("ffmpeg") or shutil.which("ffmpeg.exe")
+    if ffmpeg:
+        candidates.append(os.path.join(os.path.dirname(ffmpeg), "ffprobe.exe" if os.name == "nt" else "ffprobe"))
+    for candidate in candidates:
+        if candidate and os.path.isfile(candidate):
+            return os.path.abspath(candidate)
+    return None
+
+
+def _probe_video_duration(video_path: str) -> float | None:
+    ffprobe = _find_ffprobe()
+    if not ffprobe:
+        return None
+    creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+    completed = subprocess.run(
+        [ffprobe, "-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", video_path],
+        stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        text=True, encoding="utf-8", errors="replace", timeout=60,
+        creationflags=creationflags, check=False,
+    )
+    if completed.returncode != 0:
+        return None
+    try:
+        duration = float(completed.stdout.strip())
+    except ValueError:
+        return None
+    return duration if math.isfinite(duration) and duration > 0 else None
+
+
+def _extract_video_analysis_frames(video_path: str, duration: float, output_dir: str) -> tuple[list[str], list[float]]:
+    duration = min(REF_VIDEO_MAX_SECONDS, max(REF_VIDEO_MIN_SECONDS, float(duration)))
+    frame_count = min(VIDEO_ANALYSIS_MAX_FRAMES, max(4, int(math.ceil(duration * 1.5)) + 1))
+    sampled_span = max(0.001, duration - min(0.05, duration / 100.0))
+    sample_fps = (frame_count - 1) / sampled_span
+    output_pattern = os.path.join(output_dir, "frame-%03d.jpg")
+    video_filter = f"fps={sample_fps:.8f},scale='min(768,iw)':-2"
+    command = [
+        _find_ffmpeg(), "-hide_banner", "-loglevel", "error", "-ss", "0", "-t", f"{duration:.3f}",
+        "-i", video_path, "-an", "-vf", video_filter, "-frames:v", str(frame_count),
+        "-q:v", "3", "-y", output_pattern,
+    ]
+    creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+    completed = subprocess.run(
+        command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        text=True, encoding="utf-8", errors="replace", timeout=300,
+        creationflags=creationflags, check=False,
+    )
+    if completed.returncode != 0:
+        tail = "\n".join(completed.stderr.splitlines()[-12:])
+        raise RuntimeError(f"Video frame extraction failed with code {completed.returncode}.\n{tail}")
+    frame_paths = sorted(glob.glob(os.path.join(output_dir, "frame-*.jpg")))
+    if not frame_paths:
+        raise RuntimeError("FFmpeg extracted no frames from the selected video segment.")
+    timestamps = [min(duration, index / sample_fps) for index in range(len(frame_paths))]
+    endpoint_time = max(0.0, duration - 0.05)
+    if timestamps[-1] < endpoint_time - 0.05:
+        endpoint_temp = os.path.join(output_dir, "endpoint-final.jpg")
+        endpoint_command = [
+            _find_ffmpeg(), "-hide_banner", "-loglevel", "error", "-ss", f"{endpoint_time:.3f}",
+            "-i", video_path, "-an", "-vf", "scale='min(768,iw)':-2", "-frames:v", "1",
+            "-q:v", "3", "-y", endpoint_temp,
+        ]
+        endpoint = subprocess.run(
+            endpoint_command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, encoding="utf-8", errors="replace", timeout=120,
+            creationflags=creationflags, check=False,
+        )
+        if endpoint.returncode == 0 and os.path.isfile(endpoint_temp):
+            if len(frame_paths) < frame_count:
+                endpoint_path = os.path.join(output_dir, f"frame-{len(frame_paths) + 1:03d}.jpg")
+                os.replace(endpoint_temp, endpoint_path)
+                frame_paths.append(endpoint_path)
+                timestamps.append(endpoint_time)
+            else:
+                os.replace(endpoint_temp, frame_paths[-1])
+                timestamps[-1] = endpoint_time
+    return frame_paths, timestamps
+
+
+def _video_analysis_prompt(role: str, duration: float, timestamps: list[float]) -> str:
+    role = role if role in REFERENCE_ROLES["video"] else "none"
+    role_focus = {
+        "none": "Describe the observable video content neutrally so the user-written relationship can be applied without guessing.",
+        "video_editing": "Prioritize every source element needed for a scoped edit: visible subjects, performances, objects, environment, camera, cuts, timing, and continuity.",
+        "video_continuation": "Prioritize the ending state, final composition, positions, motion direction and momentum, camera behavior, lighting, and unresolved actions.",
+        "motion": "Prioritize subject actions, pose progression, direction, speed, contacts, interaction timing, and physical rhythm.",
+        "camera": "Prioritize shot size, viewpoint, framing changes, camera motion type, direction, amplitude, speed, and stabilization.",
+        "cuts_rhythm": "Prioritize shot boundaries, cut times, viewpoint changes, pacing, event rhythm, and temporal structure.",
+    }[role]
+    timestamp_text = ", ".join(f"{value:.3f}s" for value in timestamps)
+    return f"""Analyze the supplied images as chronologically ordered samples from the first {duration:.3f} seconds of one reference video.
+Sample timestamps in image order: {timestamp_text}.
+{role_focus}
+Infer change only when supported by adjacent samples. Never treat the samples as unrelated images, invent events between them, infer audio, or claim that an unseen detail exists.
+Return exactly the eight labeled sections below as compact English evidence. Use explicit time ranges where supported.
+
+VIDEO_OVERVIEW: source duration analyzed, visual medium, probable shot count supported by samples, and overall composition.
+SUBJECTS: stable observable identities, clothing, props, initial positions, and which visible entity performs each action.
+ACTION_TIMELINE: chronological actions, pose changes, movement paths, contacts, interactions, object states, and final state with timestamps.
+CAMERA_EDITING: framing, viewpoint, camera movement, supported cut boundaries, and pacing; write unknown when samples cannot distinguish camera motion from subject motion.
+ENVIRONMENT_OBJECTS: location, layout, surfaces, furniture, background elements, and action-relevant object relationships.
+STYLE_LIGHTING: observable rendering medium, lighting direction and continuity, palette, materials, reflections, and shadows.
+VISIBLE_TEXT: exact readable text with its timestamp; otherwise none visible.
+EDIT_CONTINUITY: temporal and structural elements normally preserved by editing: performance, action order, timing, paths, contacts, object interaction, environment, camera, cuts, lighting continuity, and final state. Keep source appearance only in SUBJECTS; do not mark identity, body appearance, hair, clothing, or accessories as mandatory preservation.
+
+Enclose the result exactly once in <VIDEO_ANALYSIS> and </VIDEO_ANALYSIS>."""
+
+
+def _clean_video_analysis(text: str) -> str:
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", text).replace("\r\n", "\n")
+    marked = re.search(r"<VIDEO_ANALYSIS>\s*(.*?)\s*</VIDEO_ANALYSIS>", text, re.DOTALL | re.IGNORECASE)
+    if marked:
+        text = marked.group(1)
+    elif re.search(r"<VIDEO_ANALYSIS>\s*", text, re.IGNORECASE):
+        text = re.split(r"<VIDEO_ANALYSIS>\s*", text, maxsplit=1, flags=re.IGNORECASE)[1]
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL | re.IGNORECASE)
+    return re.sub(r"(?:^|\n)Exiting\.\.\.\s*$", "", text, flags=re.IGNORECASE).strip()
+
+
+def _video_reference_system_modules(project: dict[str, Any]) -> str:
+    videos = [ref for ref in project.get("references", []) if ref.get("type") == "video"]
+    if not videos:
+        return ""
+    roles = [
+        ref.get("role") if ref.get("role") in REFERENCE_ROLES["video"] else "none"
+        for ref in videos
+    ]
+    mapping = ", ".join(f"<Video {index}>={role}" for index, role in enumerate(roles, 1))
+    modules = [SYSTEM_PROMPT_CONFIG["video_reference_common"], f"\nVIDEO PRESET MAP: {mapping}."]
+    for role in REFERENCE_ROLES["video"]:
+        if role in roles:
+            modules.append(SYSTEM_PROMPT_CONFIG["video_reference_roles"][role])
+    return "".join(modules)
+
+
+def _audio_reference_system_modules(project: dict[str, Any]) -> str:
+    audios = [ref for ref in project.get("references", []) if ref.get("type") == "audio"]
+    if not audios:
+        return ""
+    roles = [
+        ref.get("role") if ref.get("role") in REFERENCE_ROLES["audio"] else "none"
+        for ref in audios
+    ]
+    mapping = ", ".join(f"<Audio {index}>={role}" for index, role in enumerate(roles, 1))
+    modules = [SYSTEM_PROMPT_CONFIG["audio_reference_common"], f"\nAUDIO PRESET MAP: {mapping}."]
+    for role in REFERENCE_ROLES["audio"]:
+        if role in roles:
+            modules.append(SYSTEM_PROMPT_CONFIG["audio_reference_roles"][role])
+    return "".join(modules)
+
+
+def _reference_system_modules(project: dict[str, Any]) -> str:
+    return _video_reference_system_modules(project) + _audio_reference_system_modules(project)
+
+
+def analyze_reference_video(video: dict[str, Any], role: str, duration: float,
+                            image_model_id: str = DEFAULT_IMAGE_MODEL_ID,
+                            session: _LlamaServerSession | None = None, progress=None) -> dict[str, str]:
+    video_path = _resolve_uploaded_video(video)
+    actual_duration = _probe_video_duration(video_path)
+    analysis_duration = min(float(duration), actual_duration) if actual_duration else float(duration)
+    if analysis_duration <= 0:
+        raise ValueError("Set a positive video duration before analysis.")
+    if progress:
+        progress(
+            stage="reference_analysis",
+            message=(f"Sampling the first {analysis_duration:.2f}s of reference video "
+                     f"for role '{role}': {os.path.basename(video_path)}"),
+        )
+    with tempfile.TemporaryDirectory(prefix="toyxyz-h3-video-") as frame_dir:
+        frame_paths, timestamps = _extract_video_analysis_frames(video_path, analysis_duration, frame_dir)
+        captions = [f"Frame {index + 1} at {timestamp:.3f} seconds." for index, timestamp in enumerate(timestamps)]
+        prompt = _video_analysis_prompt(role, analysis_duration, timestamps)
+        if progress:
+            progress(
+                stage="reference_analysis",
+                message=f"Analyzing {len(frame_paths)} ordered frames from {os.path.basename(video_path)}.",
+            )
+        if session is not None:
+            output = session.analyze_images(frame_paths, captions, prompt)
+            model_path, mmproj_path = session.model_path, session.mmproj_path
+        else:
+            model_path, mmproj_path = _resolve_image_model(image_model_id or DEFAULT_IMAGE_MODEL_ID, progress)
+            command = [_find_llama_cli(), "-m", model_path, "--mmproj", mmproj_path]
+            for frame_path in frame_paths:
+                command.extend(("--image", frame_path))
+            command.extend((
+                "-p", prompt, "--single-turn", "--no-display-prompt", "--no-show-timings", "--simple-io",
+                "--no-context-shift", "--log-disable", "--color", "off", "-c", "16384", "-n", "1600",
+                "-ngl", "all", "--temp", "0.2", "--top-p", "0.9", "--top-k", "40", "--jinja",
+            ))
+            if image_model_id == QWEN_IMAGE_MODEL_ID:
+                command.extend(("--chat-template-kwargs", '{"enable_thinking":false}', "--reasoning", "off"))
+            creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+            completed = subprocess.run(
+                command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                text=True, encoding="utf-8", errors="replace", timeout=1800,
+                creationflags=creationflags, check=False,
+            )
+            if completed.returncode != 0:
+                tail = "\n".join(completed.stderr.splitlines()[-12:])
+                raise RuntimeError(f"Video analysis failed with code {completed.returncode}.\n{tail}")
+            output = completed.stdout
+    analysis = _clean_video_analysis(output)
+    if not analysis:
+        raise RuntimeError("The vision model returned an empty video analysis.")
+    return {
+        "analysis": analysis, "model_path": model_path, "mmproj_path": mmproj_path,
+        "analyzed_duration": f"{analysis_duration:.3f}", "frame_count": str(len(frame_paths)),
+    }
+
+
+@contextmanager
+def _vision_compatible_image(image_path: str):
+    """Provide a decoder-safe image path for llama.cpp vision backends.
+
+    The bundled llama.cpp build can report a WebP as loaded while producing
+    unrelated visual embeddings. Converting only WebP inputs to PNG avoids
+    that silent failure without modifying the user's uploaded file.
+    """
+    if os.path.splitext(image_path)[1].lower() != ".webp":
+        yield image_path
+        return
+    try:
+        from PIL import Image, ImageOps
+    except ImportError as exc:
+        raise RuntimeError("Pillow is required to prepare WebP reference images for vision analysis.") from exc
+    file_descriptor, converted_path = tempfile.mkstemp(prefix="toyxyz-h3-vision-", suffix=".png")
+    os.close(file_descriptor)
+    try:
+        with Image.open(image_path) as source:
+            normalized = ImageOps.exif_transpose(source)
+            if normalized.mode not in {"RGB", "RGBA"}:
+                normalized = normalized.convert("RGB")
+            normalized.save(converted_path, format="PNG")
+        yield converted_path
+    finally:
+        try:
+            os.unlink(converted_path)
+        except FileNotFoundError:
+            pass
+
+
+def _clean_reference_analysis(text: str) -> str:
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", text).replace("\r\n", "\n")
+    marked = re.search(r"<REFERENCE_ANALYSIS>\s*(.*?)\s*</REFERENCE_ANALYSIS>", text, re.DOTALL | re.IGNORECASE)
+    if marked:
+        text = marked.group(1)
+    elif re.search(r"<REFERENCE_ANALYSIS>\s*", text, re.IGNORECASE):
+        # Some vision models emit the opening transport marker but consume the
+        # generation budget before the closing marker. Everything before the
+        # opening marker is llama-cli startup output and echoed input.
+        text = re.split(r"<REFERENCE_ANALYSIS>\s*", text, maxsplit=1, flags=re.IGNORECASE)[1]
+    elif "\n> " in text:
+        text = text.rsplit("\n> ", 1)[1].partition("\n")[2]
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL | re.IGNORECASE)
+    text = re.sub(r"(?:^|\n)Exiting\.\.\.\s*$", "", text, flags=re.IGNORECASE).strip()
+    fence = re.fullmatch(r"```(?:text)?\s*(.*?)\s*```", text, flags=re.DOTALL | re.IGNORECASE)
+    return (fence.group(1) if fence else text).strip()
+
+
+def _reference_analysis_prompt(role: str) -> str:
+    role = role if role in REFERENCE_ROLES["picture"] else "subject_identity"
+    role_focus = {
+        "first_frame": "Treat it as an opening-frame anchor. Prioritize the exact style, composition, pose, support, contact, scene layout, and action-relevant objects that must continue forward.",
+        "last_frame": "Treat it as a final-frame anchor. Prioritize the exact style, pose, object state, support, contact, composition, viewpoint, and lighting on which motion must land.",
+        "subject_identity": "Prioritize stable identity features, hair, face, body silhouette, clothing, accessories, colors, distinctive objects, and the source medium or rendering style required by the assigned strength.",
+    }[role]
+    return f"""Analyze the supplied image as visual reference metadata for a MiniMax H3 video prompt.
+{role_focus}
+Return compact structured evidence using exactly the eight labeled lines below. Write only directly observable facts. Use "none visible" when a category has no evidence; never omit a line.
+
+VISUAL_MEDIUM: Classify the image as specifically as visible evidence permits, such as live-action photograph, 2D anime illustration, cel-shaded animation frame, hand-drawn illustration, 3D CGI render, physical collectible figurine photograph, or three-dimensional anime-figurine render. Include only brief supporting cues. If uncertain, write "indeterminate image" and list the visible rendering cues; never guess a production method.
+COMPOSITION: State shot size, viewpoint, crop boundaries, visible body range, and important frame positions.
+SUBJECTS: State each important subject's stable observable identity features, hairstyle, clothing, accessories, expression, and position. Keep style separate from identity facts.
+POSE_SUPPORT_CONTACT: State pose, seated or standing support, visible furniture or ground contact, hand placement, held objects, and occlusion.
+ACTION_RELEVANT_OBJECTS: State visible fasteners, seams, layers, openings, containers, surfaces, foreground obstacles, tools, props, and their exact spatial relationships when they could constrain a later action.
+ENVIRONMENT: State the evidenced location type, background layout, furniture, and important scene objects. Never replace a specific environment with a generic room, office, studio, or gradient.
+LIGHTING_MATERIALS: State observable light direction and quality, colors, materials, reflections, depth, and shadows.
+VISIBLE_TEXT: Quote only clearly readable text exactly; otherwise write "none visible".
+
+An object or body part counts as visible only when its pixels are discernible inside the frame. Never infer an off-frame floor object, hidden pocket content, unseen hand-held item, cropped body part, nearby prop, or probable continuation beyond an image boundary. Never infer or label nationality, ethnicity, race, age, celebrity identity, occupation, personality, attractiveness, backstory, motion, sound, intent, or future action. Do not use speculative alternatives joined by or. Choose only what is visibly supported or omit it. Do not use quality praise, bullets, prose before the labels, or extra headings. Enclose the eight lines exactly once in <REFERENCE_ANALYSIS> and </REFERENCE_ANALYSIS>."""
+
+
+def _report_reference_analysis(image: dict[str, Any], role: str, image_path: str, progress=None) -> None:
+    if not progress:
+        return
+    analysis_index = int(_number(image.get("_analysis_index"), 0))
+    analysis_total = int(_number(image.get("_analysis_total"), 0))
+    ordinal = f" {analysis_index}/{analysis_total}" if analysis_index and analysis_total else ""
+    progress(
+        stage="reference_analysis",
+        message=f"Analyzing reference image{ordinal} for role '{role}': {os.path.basename(image_path)}",
+    )
+
+
+def _analyze_reference_image_with_server(image: dict[str, Any], role: str,
+                                         session: _LlamaServerSession, progress=None) -> dict[str, str]:
+    role = role if role in REFERENCE_ROLES["picture"] else "subject_identity"
+    image_path = _resolve_uploaded_image(image)
+    _report_reference_analysis(image, role, image_path, progress)
+    with _vision_compatible_image(image_path) as vision_path:
+        analysis = _clean_reference_analysis(session.analyze_image(vision_path, _reference_analysis_prompt(role)))
+    if not analysis:
+        raise RuntimeError("The vision model returned an empty image analysis.")
+    return {"analysis": analysis, "model_path": session.model_path, "mmproj_path": session.mmproj_path}
+
+
+def analyze_reference_image(image: dict[str, Any], role: str = "subject_identity",
+                            image_model_id: str = DEFAULT_IMAGE_MODEL_ID, progress=None) -> dict[str, str]:
+    role = role if role in REFERENCE_ROLES["picture"] else "subject_identity"
+    image_path = _resolve_uploaded_image(image)
+    model_path, mmproj_path = _resolve_image_model(image_model_id or DEFAULT_IMAGE_MODEL_ID, progress)
+    _report_reference_analysis(image, role, image_path, progress)
+    prompt = _reference_analysis_prompt(role)
+    with _vision_compatible_image(image_path) as vision_path:
+        command = [
+            _find_llama_cli(), "-m", model_path, "--mmproj", mmproj_path, "--image", vision_path,
+            "-p", prompt, "--single-turn", "--no-display-prompt", "--no-show-timings", "--simple-io",
+            "--no-context-shift", "--log-disable", "--color", "off", "-c", "8192", "-n", "700",
+            "-ngl", "all", "--temp", "0.2", "--top-p", "0.9", "--top-k", "40", "--jinja",
+        ]
+        if image_model_id == QWEN_IMAGE_MODEL_ID:
+            command.extend([
+                "--chat-template-kwargs", '{"enable_thinking":false}',
+                "--reasoning", "off",
+            ])
+        creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+        completed = subprocess.run(
+            command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, encoding="utf-8", errors="replace", timeout=900,
+            creationflags=creationflags, check=False,
+        )
+    if completed.returncode != 0:
+        tail = "\n".join(completed.stderr.splitlines()[-12:])
+        raise RuntimeError(f"Image analysis failed with code {completed.returncode}.\n{tail}")
+    analysis = _clean_reference_analysis(completed.stdout)
+    if not analysis:
+        raise RuntimeError("The vision model returned an empty image analysis.")
+    return {"analysis": analysis, "model_path": model_path, "mmproj_path": mmproj_path}
+
+
+def _prompt_shot_numbers(prompt: str) -> list[int]:
+    main_field = re.search(
+        r"(?:integrated_multimodal_description|detailed_description)\s*:\s*",
+        prompt,
+        flags=re.IGNORECASE,
+    )
+    if not main_field:
+        return []
+    body = prompt[main_field.end():]
+    body = re.split(r"\n\s*overall_soundscape\s*:", body, maxsplit=1, flags=re.IGNORECASE)[0]
+    # A reference such as "Picture 1 comes from [Shot 1]" is not a shot
+    # header. Count headers only when they start a body line, or when a later
+    # inline header carries the guide-required timestamp.
+    numbers: list[int] = []
+    seen_spans: set[tuple[int, int]] = set()
+    for match in _SHOT_HEADER_PATTERN.finditer(body):
+        if match.span() in seen_spans:
+            continue
+        seen_spans.add(match.span())
+        numbers.append(int(match.group(1) or match.group(2)))
+    return numbers
+
+
+def _build_lightx2v_original_prompt(project: dict[str, Any], effective_seconds: float) -> str:
+    lines = [
+        f"Create exactly {len(project['shots'])} shot(s) in the supplied order.",
+        f"The target video ends at {effective_seconds:.2f} seconds.",
+    ]
+    elapsed = 0.0
+    for index, shot in enumerate(project["shots"], 1):
+        start = elapsed
+        elapsed += float(shot["duration"])
+        action = _clean_text(shot.get("visual_action")) or "Maintain a coherent visible state."
+        if index == 1:
+            lines.append(f"[Shot 1] 0.000-{elapsed:.3f} seconds: {action}")
+        else:
+            lines.append(f"[Shot {index}] begins at {start:.3f} seconds with a cut: {action}")
+    if project.get("user_request"):
+        lines.append(f"Overall request: {project['user_request']}")
+    if project.get("constraints"):
+        lines.append(f"Constraints: {project['constraints']}")
+    if project.get("verbatim_content"):
+        lines.append(f"Verbatim dialogue or visible text to preserve exactly: {project['verbatim_content']}")
+    return "\n".join(lines)
+
+
+def _lightx2v_reference_paths(project: dict[str, Any], mode: str) -> list[str]:
+    pictures = [ref for ref in project["references"] if ref["type"] == "picture"]
+    expected_roles = {
+        "T2VA": (), "I2VA": ("first_frame",), "L2VA": ("last_frame",),
+        "FL2VA": ("first_frame", "last_frame"),
+    }[mode]
+    paths: list[str] = []
+    for role in expected_roles:
+        reference = next((ref for ref in pictures if ref["role"] == role), None)
+        if not reference or not reference.get("image_filename"):
+            raise ValueError(f"LightX2V {mode} requires an uploaded {role.replace('_', ' ')} image.")
+        paths.append(_resolve_uploaded_image({
+            "filename": reference["image_filename"], "subfolder": reference["image_subfolder"],
+        }))
+    return paths
+
+
+def _lightx2v_messages(prompt: str, task: str, resolution: str, duration: int,
+                       image_paths: list[str]) -> list[dict[str, Any]]:
+    with open(LIGHTX2V_SYSTEM_PROMPTS_PATH, "r", encoding="utf-8") as handle:
+        config = json.load(handle)
+    content: list[dict[str, Any]] = []
+    image_index = 0
+    for item in config["task_messages"][task]:
+        if item == "image":
+            image_path = image_paths[image_index]
+            image_index += 1
+            mime_type = mimetypes.guess_type(image_path)[0] or "image/png"
+            with open(image_path, "rb") as image_handle:
+                encoded = base64.b64encode(image_handle.read()).decode("ascii")
+            content.append({
+                "type": "image_url",
+                "image_url": {"url": f"data:{mime_type};base64,{encoded}"},
+            })
+        else:
+            content.append({"type": "text", "text": item})
+    request = (
+        f"task: {task}\nresolution: {resolution}\nduration: {duration}s\n"
+        f"original_prompt: {prompt.strip()}"
+    )
+    content.append({"type": "text", "text": ("\n" if content else "") + request})
+    return [
+        {"role": "system", "content": config["system"]},
+        {"role": "user", "content": content},
+    ]
+
+
+def _enhance_project_lightx2v(result: dict[str, Any], model_id: str, progress=None,
+                              cancel_event: threading.Event | None = None,
+                              job_id: str = "") -> dict[str, Any]:
+    project = result["project"]
+    mode = project["mode"]
+    if mode == "REF2VA":
+        raise ValueError(
+            "lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B does not support R2V/REF2VA. "
+            "Select Qwen3.8 + Vision F16 or use T2VA, I2VA, L2VA, or FL2VA."
+        )
+    if mode not in LIGHTX2V_SUPPORTED_MODES:
+        raise ValueError(f"The LightX2V 8B rewriter does not support mode {mode}.")
+    image_paths = _lightx2v_reference_paths(project, mode)
+    if progress and image_paths:
+        progress(
+            stage="reference_analysis",
+            message=(f"Passing {len(image_paths)} reference frame{'s' if len(image_paths) != 1 else ''} "
+                     "directly to the LightX2V multimodal rewriter in role order."),
+        )
+    with _ENHANCE_LOCK:
+        if cancel_event is not None and cancel_event.is_set():
+            raise EnhancementCancelled("Prompt generation was stopped by the user.")
+        model_path, mmproj_path = _resolve_lightx2v_model(progress)
+        original_prompt = _build_lightx2v_original_prompt(project, result["effective_duration"])
+        task = {"T2VA": "t2va", "I2VA": "i2va", "L2VA": "l2va", "FL2VA": "fl2va"}[mode]
+        adapter_task = {"t2va": "t2av", "i2va": "i2av", "l2va": "l2av", "fl2va": "fl2av"}[task]
+        duration = min(15, max(4, int(round(float(project["requested_duration"])))))
+        resolution = "16:9" if mode == "T2VA" else "adaptive"
+        messages = _lightx2v_messages(original_prompt, adapter_task, resolution, duration, image_paths)
+        try:
+            import comfy.model_management as model_management
+            model_management.unload_all_models()
+            model_management.soft_empty_cache(force=True)
+        except (ImportError, AttributeError):
+            pass
+        if progress:
+            progress(stage="generating", message="Loading LightX2V merged Qwen3-VL-8B GGUF Q8_0 + Vision F16.")
+        session = _LlamaServerSession(
+            _find_llama_server(), model_path, mmproj_path, LIGHTX2V_MODEL_ID,
+            context_size=16384,
+            extra_args=[
+                "--chat-template-kwargs", '{"enable_thinking":false}',
+                "--reasoning", "off", "--image-min-tokens", "1024",
+            ],
+        )
+        try:
+            if job_id:
+                _set_enhance_stopper(job_id, session.close)
+            session.start()
+            if cancel_event is not None and cancel_event.is_set():
+                raise EnhancementCancelled("Prompt generation was stopped by the user.")
+            enhanced = _clean_llm_output(session.chat(messages, max_tokens=4096, temperature=0.0))
+            if cancel_event is not None and cancel_event.is_set():
+                raise EnhancementCancelled("Prompt generation was stopped by the user.")
+        finally:
+            session.close()
+            if job_id:
+                _set_enhance_stopper(job_id, None)
+        if not enhanced:
+            raise RuntimeError("The LightX2V rewriter returned an empty prompt.")
+        if progress:
+            progress(stage="complete", message="LightX2V prompt generation completed.")
+        return {
+            "enhanced_prompt": enhanced, "model": model_id, "model_path": model_path,
+            "reference_analyses": [],
+        }
+
+
+def enhance_project(project_data: Any, model_id: str, image_model_id: str = DEFAULT_IMAGE_MODEL_ID,
+                    progress=None, cancel_event: threading.Event | None = None,
+                    job_id: str = "") -> dict[str, Any]:
+    def check_cancelled() -> None:
+        if cancel_event is not None and cancel_event.is_set():
+            raise EnhancementCancelled("Prompt generation was stopped by the user.")
+
+    check_cancelled()
+    if progress:
+        progress(stage="compiling", message="Compiling the current node inputs into a raw prompt.")
+    result = compile_project(project_data, use_enhanced=False)
+    if result["errors"]:
+        raise ValueError("Fix project validation errors before generating the prompt.")
+    project = result["project"]
+    selected_model = model_id or DEFAULT_ENHANCE_MODEL_ID
+    if selected_model == LIGHTX2V_MODEL_ID:
+        return _enhance_project_lightx2v(
+            result, selected_model, progress, cancel_event=cancel_event, job_id=job_id,
+        )
+    rich_enhance = project.get("enhance") is True
+    reference_analyses: list[dict[str, str]] = []
+    analysis_lines: list[str] = []
+    picture_labels = {
+        ref["id"]: ref["label"]
+        for ref in _reference_labels(project["references"])
+        if ref["type"] == "picture"
+    }
+    video_labels = {
+        ref["id"]: ref["label"]
+        for ref in _reference_labels(project["references"])
+        if ref["type"] == "video"
+    }
+    # Uploaded visual references are intentionally re-analyzed on every enhancement.
+    # A changed role or video-duration crop changes the evidence needed by the rewriter.
+    pictures_to_analyze = [
+        ref for ref in project["references"]
+        if ref["type"] == "picture" and ref["image_filename"]
+    ]
+    videos_to_analyze = [
+        ref for ref in project["references"]
+        if ref["type"] == "video" and ref["video_filename"] and ref["duration"] > 0
+    ]
+    if pictures_to_analyze or videos_to_analyze:
+        try:
+            import comfy.model_management as model_management
+
+            model_management.unload_all_models()
+            model_management.soft_empty_cache(force=True)
+        except (ImportError, AttributeError):
+            pass
+        with _ENHANCE_LOCK:
+            total_assets = len(pictures_to_analyze) + len(videos_to_analyze)
+            server_session: _LlamaServerSession | None = None
+            try:
+                if progress:
+                    progress(
+                        stage="image_model_check",
+                        message="Starting the persistent visual-analysis server and loading the model once.",
+                    )
+                try:
+                    server_session = _start_persistent_image_server(image_model_id, progress)
+                    if job_id:
+                        _set_enhance_stopper(job_id, server_session.close)
+                    check_cancelled()
+                    if progress:
+                        progress(
+                            stage="reference_analysis",
+                            message=(
+                                f"Persistent visual-analysis server is ready; analyzing {total_assets} "
+                                f"reference asset{'s' if total_assets != 1 else ''} without reloading the model."
+                            ),
+                        )
+                except Exception as exc:
+                    if progress:
+                        progress(
+                            stage="reference_analysis",
+                            message=f"Persistent server unavailable; using llama-cli fallback: {exc}",
+                        )
+
+                def run_analysis_batch(session: _LlamaServerSession | None) -> None:
+                    for analysis_index, ref in enumerate(pictures_to_analyze, 1):
+                        check_cancelled()
+                        image_payload = {
+                            "filename": ref["image_filename"],
+                            "subfolder": ref["image_subfolder"],
+                            "type": "input",
+                            "_analysis_index": analysis_index,
+                            "_analysis_total": total_assets,
+                        }
+                        if session is not None:
+                            analyzed = _analyze_reference_image_with_server(
+                                image_payload, ref["role"], session, progress,
+                            )
+                        else:
+                            analyzed = analyze_reference_image(
+                                image_payload, ref["role"], image_model_id, progress,
+                            )
+                        label = picture_labels[ref["id"]]
+                        analysis = analyzed["analysis"]
+                        analysis_lines.append(f"{label} [role={ref['role']}]: {analysis}")
+                        reference_analyses.append({
+                            "id": ref["id"], "label": label,
+                            "role": ref["role"],
+                            "filename": ref["image_filename"],
+                            "analysis": analysis,
+                        })
+                    for video_index, ref in enumerate(videos_to_analyze, len(pictures_to_analyze) + 1):
+                        check_cancelled()
+                        video_payload = {
+                            "filename": ref["video_filename"],
+                            "subfolder": ref["video_subfolder"],
+                            "type": "input",
+                            "_analysis_index": video_index,
+                            "_analysis_total": total_assets,
+                        }
+                        analyzed = analyze_reference_video(
+                            video_payload, ref["role"], ref["duration"], image_model_id,
+                            session=session, progress=progress,
+                        )
+                        label = video_labels[ref["id"]]
+                        analysis = analyzed["analysis"]
+                        analysis_lines.append(
+                            f"{label} [role={ref['role']}, analyzed_first_seconds={analyzed['analyzed_duration']}]: {analysis}"
+                        )
+                        reference_analyses.append({
+                            "id": ref["id"], "label": label, "type": "video",
+                            "role": ref["role"], "filename": ref["video_filename"],
+                            "analysis": analysis, "analyzed_duration": analyzed["analyzed_duration"],
+                            "frame_count": analyzed["frame_count"],
+                        })
+
+                if server_session is not None:
+                    try:
+                        run_analysis_batch(server_session)
+                    except EnhancementCancelled:
+                        raise
+                    except Exception as exc:
+                        server_session.close()
+                        server_session = None
+                        analysis_lines.clear()
+                        reference_analyses.clear()
+                        if progress:
+                            progress(
+                                stage="reference_analysis",
+                                message=f"Persistent image analysis failed; retrying with llama-cli: {exc}",
+                            )
+                        run_analysis_batch(None)
+                else:
+                    run_analysis_batch(None)
+            finally:
+                if server_session is not None:
+                    server_session.close()
+                    if progress:
+                        progress(
+                            stage="reference_analysis",
+                            message="Persistent visual analysis completed; the vision model was released.",
+                        )
+                if job_id:
+                    _set_enhance_stopper(job_id, None)
+
+    # Raw Prompt remains the deterministic result of user-controlled fields.
+    # Automatic image analyses are supplied only in the private LLM context.
+    expected_shots = list(range(1, len(result["project"]["shots"]) + 1))
+    shot_headers = ", ".join(f"[Shot {number}]" for number in expected_shots)
+    mode = result["project"]["mode"]
+    active_mode_prompts = ENHANCED_MODE_LLM_SYSTEM_PROMPTS if rich_enhance else MODE_LLM_SYSTEM_PROMPTS
+    system_prompt = _mode_prompt_preamble(mode) + "\n\n" + active_mode_prompts[mode]
+    reference_model = _reference_model(result["project"]) if mode == "REF2VA" else None
+    system_prompt += (
+        f"\n\nEXACT SHOTS: Use only {shot_headers}, once each in that order. "
+        "Do not add, remove, split, merge, duplicate, or renumber shots or invent another cut."
+    )
+    if analysis_lines:
+        if result["project"]["mode"] == "FL2VA":
+            system_prompt += (
+                "\n\nFL2VA IMAGE EVIDENCE: The analyses are authoritative endpoint evidence. "
+                "Use them to plan interpolation, but do not copy their appearance inventories into the output."
+            )
+        elif result["project"]["mode"] == "I2VA":
+            system_prompt += (
+                "\n\nI2VA IMAGE EVIDENCE: The <Picture 1> analysis is the sole evidence for 0.00 seconds. "
+                "Discard demographic guesses, hidden details, and speculation even if present in the analysis. "
+                "The raw action starts after the anchor; never backfill it or an invented source into Picture 1."
+            )
+        elif result["project"]["mode"] == "REF2VA":
+            system_prompt += (
+                "\n\nREF2VA VISUAL EVIDENCE: Image analyses describe still sources; video analyses describe "
+                "chronologically ordered samples from only the configured leading duration. "
+                "Treat the supplied video timeline, subjects, actions, camera, cuts, environment, and final state as "
+                "authoritative only where the evidence states them. Analyses describe source assets, not output labels. "
+                "Follow the locked label plan below; do not promote a source-only Picture label into summary, "
+                "retention_analysis, or detailed_description. Use only role-relevant facts and never transfer a "
+                "source background into an incompatible target setting."
+            )
+        else:
+            system_prompt += (
+                "\n\nREFERENCE IMAGE EVIDENCE: Each analysis is authoritative observable evidence for its "
+                "matching picture and role. Use relevant facts in context without contradiction or a detached appendix."
+            )
+    if reference_model:
+        plan_lines = []
+        for label, plan in reference_model["label_plan"].items():
+            strength = f", input_definition_scope={plan['strength']}" if plan["kind"] == "Subject" else ""
+            plan_lines.append(
+                f"- {label}: kind={plan['kind']}, source={plan['source']}, role={plan['role']}"
+                f"{strength}, retention={plan['marker']}; contract={plan['contract']}"
+            )
+        system_prompt += (
+            "\n\nLOCKED REF2VA LABEL PLAN:\n" + "\n".join(plan_lines)
+            + "\nDefine exactly these output labels in this order. Source labels that are not output labels may "
+              "appear only as provenance inside subject_definitions. Mention every output label in summary and "
+              "retention_analysis, and apply every visual output label in detailed_description."
+        )
+        system_prompt += _reference_system_modules(result["project"])
+    system_prompt += (
+        "\n\nOUTPUT: Return only the finished English H3 prompt, enclosed exactly once between "
+        "<H3_PROMPT> and </H3_PROMPT>, with no commentary or Markdown fence."
+    )
+    system_prompt += "\n\n" + _single_pass_output_lock(
+        mode,
+        result["effective_duration"],
+        len(expected_shots),
+        expected_shots,
+        reference_model,
+        _input_content_locks(result["project"]),
+    )
+    evidence_by_label = {
+        item["label"]: item["analysis"] for item in reference_analyses
+    }
+    user_prompt = build_video_prompt(
+        result["project"], result["effective_duration"], evidence_by_label,
+    )
+    with _ENHANCE_LOCK, tempfile.TemporaryDirectory(prefix="toyxyz_h3_") as temp_dir:
+        check_cancelled()
+        if progress:
+            progress(stage="model_check", message="Checking the selected GGUF model.")
+        model_path = _resolve_enhance_model(model_id or DEFAULT_ENHANCE_MODEL_ID, progress)
+        llama_cli = _find_llama_cli()
+        system_file = os.path.join(temp_dir, "system.txt")
+        user_file = os.path.join(temp_dir, "user.txt")
+        with open(system_file, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(system_prompt)
+        with open(user_file, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(user_prompt)
+        try:
+            import comfy.model_management as model_management
+
+            model_management.unload_all_models()
+            model_management.soft_empty_cache(force=True)
+        except (ImportError, AttributeError):
+            pass
+        if progress:
+            progress(
+                stage="generating",
+                message=("Loading Qwen3.8 and generating a richly enhanced prompt."
+                         if rich_enhance else "Loading the model and generating the prompt."),
+            )
+        creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0) if os.name == "nt" else 0
+        def run_generation(prompt_text: str, temperature: float = 0.22) -> str:
+            max_new_tokens = (
+                REF_ENHANCE_MAX_NEW_TOKENS if mode == "REF2VA"
+                else RICH_ENHANCE_MAX_NEW_TOKENS if rich_enhance
+                else BASE_ENHANCE_MAX_NEW_TOKENS
+            )
+            top_p = 0.93 if rich_enhance else 0.88
+            top_k = 40 if rich_enhance else 20
+            repeat_penalty = 1.03 if rich_enhance else 1.05
+            command = [
+                llama_cli, "-m", model_path, "-sysf", system_file, "-p", prompt_text,
+                "--jinja", "--chat-template-kwargs", '{"enable_thinking":false}',
+                "--single-turn", "--no-display-prompt", "--no-show-timings", "--simple-io", "--no-context-shift",
+                "--log-disable", "--color", "off",
+                "-c", str(ENHANCE_CONTEXT_SIZE), "-n", str(max_new_tokens),
+                "-ngl", "all", "--temp", str(temperature), "--top-p", str(top_p), "--top-k", str(top_k),
+                "--repeat-penalty", str(repeat_penalty),
+            ]
+            if cancel_event is None:
+                try:
+                    completed = subprocess.run(
+                        command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                        text=True, encoding="utf-8", errors="replace", timeout=1800,
+                        creationflags=creationflags, check=False,
+                    )
+                except subprocess.TimeoutExpired as exc:
+                    raise RuntimeError("Prompt enhancement exceeded the 30-minute timeout.") from exc
+            else:
+                process = subprocess.Popen(
+                    command, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                    text=True, encoding="utf-8", errors="replace", creationflags=creationflags,
+                )
+                if job_id:
+                    _set_enhance_stopper(job_id, process.terminate)
+                deadline = time.monotonic() + 1800
+                try:
+                    while True:
+                        check_cancelled()
+                        remaining = deadline - time.monotonic()
+                        if remaining <= 0:
+                            process.terminate()
+                            raise RuntimeError("Prompt enhancement exceeded the 30-minute timeout.")
+                        try:
+                            stdout, stderr = process.communicate(timeout=min(0.25, remaining))
+                            break
+                        except subprocess.TimeoutExpired:
+                            continue
+                finally:
+                    if process.poll() is None:
+                        process.terminate()
+                        try:
+                            process.wait(timeout=5)
+                        except subprocess.TimeoutExpired:
+                            process.kill()
+                            process.wait(timeout=5)
+                    if job_id:
+                        _set_enhance_stopper(job_id, None)
+                completed = subprocess.CompletedProcess(command, process.returncode, stdout, stderr)
+            if completed.returncode != 0:
+                tail = "\n".join(completed.stderr.splitlines()[-12:])
+                raise RuntimeError(f"llama-cli exited with code {completed.returncode}.\n{tail}")
+            return _clean_llm_output(completed.stdout)
+
+        # Enhancement is intentionally single-pass. The system prompt carries
+        # the H3 structure and fidelity rules, while the generated text is
+        # returned as-is after transport-noise removal. Do not normalize,
+        # validate, sanitize, or send the output through a correction call.
+        enhanced = run_generation(user_prompt, temperature=0.38 if rich_enhance else 0.22)
+        if not enhanced:
+            raise RuntimeError("The selected model returned an empty prompt.")
+        if progress:
+            progress(stage="complete", message="Prompt generation completed.")
+        return {
+            "enhanced_prompt": enhanced,
+            "model": model_id,
+            "model_path": model_path,
+            "reference_analyses": reference_analyses,
+        }
+
+
+def compile_project(project_data: Any, use_enhanced: bool = True) -> dict[str, Any]:
+    project, parse_warnings = normalize_project(project_data)
+    effective_frames = align_frame_count(project["requested_duration"])
+    effective_seconds = effective_frames / MODEL_FPS
+    errors, warnings = validate_project(project, parse_warnings)
+    report_lines = [*(f"ERROR: {item}" for item in errors), *(f"WARNING: {item}" for item in warnings)]
+    if not report_lines:
+        report_lines.append("OK: Project metadata passes Minimax-H3 prompt validation.")
+    draft_video_prompt = build_video_prompt(project, effective_seconds)
+    video_prompt = project["enhanced_prompt"] if use_enhanced and project["enhanced_prompt"] else draft_video_prompt
+    return {
+        "project": project,
+        "draft_video_prompt": draft_video_prompt,
+        "video_prompt": video_prompt,
+        "enhanced_prompt": project["enhanced_prompt"],
+        "llm_prompt": build_llm_prompt(project, draft_video_prompt),
+        "validation_report": "\n".join(report_lines),
+        "errors": errors,
+        "warnings": warnings,
+        "effective_frames": effective_frames,
+        "effective_duration": round(effective_seconds, 6),
+        "resolved_mode": project["mode"],
+        "mode_selection": project["mode_selection"],
+    }
+
+
+def _blank_reference_image():
+    import torch
+
+    return torch.zeros((1, 64, 64, 3), dtype=torch.float32, device="cpu")
+
+
+def _load_reference_image_tensor(reference: dict[str, Any]):
+    import numpy as np
+    import torch
+    from PIL import Image, ImageOps
+
+    image_path = _resolve_uploaded_image({
+        "filename": reference.get("image_filename"),
+        "subfolder": reference.get("image_subfolder"),
+    })
+    with Image.open(image_path) as source:
+        image = ImageOps.exif_transpose(source).convert("RGB")
+        array = np.asarray(image, dtype=np.float32) / 255.0
+    return torch.from_numpy(array.copy())[None,]
+
+
+def _reference_image_outputs(project: dict[str, Any]) -> tuple[Any, ...]:
+    pictures = [ref for ref in project.get("references", []) if ref.get("type") == "picture"]
+    blank = _blank_reference_image()
+    outputs: list[Any] = []
+    for index in range(MAX_REF_IMAGES):
+        if index >= len(pictures) or not pictures[index].get("image_filename"):
+            outputs.append(blank.clone())
+            continue
+        try:
+            outputs.append(_load_reference_image_tensor(pictures[index]))
+        except (FileNotFoundError, OSError, ValueError):
+            outputs.append(blank.clone())
+    return tuple(outputs)
+
+
+def _trim_audio_value(audio: Any, target_duration: float):
+    if not isinstance(audio, dict):
+        return audio
+    waveform = audio.get("waveform")
+    sample_rate = audio.get("sample_rate")
+    if waveform is None or not sample_rate:
+        return audio
+    end_sample = min(
+        waveform.shape[-1],
+        max(1, int(round(float(target_duration) * int(sample_rate)))),
+    )
+    return {**audio, "waveform": waveform[..., :end_sample]}
+
+
+def _load_reference_video(reference: dict[str, Any], target_frame_count: int):
+    from fractions import Fraction
+    import torch
+    from comfy_api.latest import InputImpl, Types
+
+    video_path = _resolve_uploaded_video({
+        "filename": reference.get("video_filename"),
+        "subfolder": reference.get("video_subfolder"),
+    })
+    target_frame_count = max(1, int(target_frame_count))
+    target_duration = target_frame_count / MODEL_FPS
+    video = InputImpl.VideoFromFile(video_path)
+    trimmed = video.as_trimmed(0.0, target_duration, strict_duration=False)
+    if trimmed is None:
+        raise ValueError("The reference video could not be trimmed to the target duration.")
+    components = trimmed.get_components()
+    source_count = int(components.images.shape[0])
+    source_fps = float(components.frame_rate)
+    if source_count <= 0 or not math.isfinite(source_fps) or source_fps <= 0:
+        raise ValueError("The reference video contains no decodable frames or valid frame rate.")
+    available_target_count = max(1, int(round(source_count * MODEL_FPS / source_fps)))
+    output_count = min(target_frame_count, available_target_count)
+    source_indices = torch.round(
+        torch.arange(output_count, dtype=torch.float64) * source_fps / MODEL_FPS
+    ).to(dtype=torch.long).clamp_(0, source_count - 1)
+    images = components.images.index_select(0, source_indices.to(components.images.device))
+    output_duration = output_count / MODEL_FPS
+    audio = _trim_audio_value(components.audio, output_duration)
+    return InputImpl.VideoFromComponents(
+        Types.VideoComponents(
+            images=images,
+            audio=audio,
+            frame_rate=Fraction(MODEL_FPS),
+        ),
+        bit_depth=trimmed.get_bit_depth(),
+    )
+
+
+def _blank_reference_video():
+    from fractions import Fraction
+    from comfy_api.latest import InputImpl, Types
+
+    return InputImpl.VideoFromComponents(
+        Types.VideoComponents(
+            images=_blank_reference_image(),
+            audio=None,
+            frame_rate=Fraction(MODEL_FPS),
+        )
+    )
+
+
+def _blank_reference_audio():
+    import torch
+
+    return {"waveform": torch.zeros((1, 1, 1), dtype=torch.float32), "sample_rate": 44100}
+
+
+def _load_reference_audio(reference: dict[str, Any], target_duration: float):
+    from comfy_extras.nodes_audio import load
+
+    audio_path = _resolve_uploaded_audio({
+        "filename": reference.get("audio_filename"),
+        "subfolder": reference.get("audio_subfolder"),
+    })
+    waveform, sample_rate = load(audio_path)
+    audio = _trim_audio_value({"waveform": waveform, "sample_rate": sample_rate}, target_duration)
+    return {"waveform": audio["waveform"].unsqueeze(0), "sample_rate": sample_rate}
+
+
+def _reference_media_outputs(project: dict[str, Any], target_frame_count: int) -> tuple[Any, ...]:
+    pictures = [ref for ref in project.get("references", []) if ref.get("type") == "picture"]
+    videos = [ref for ref in project.get("references", []) if ref.get("type") == "video"]
+    audios = [ref for ref in project.get("references", []) if ref.get("type") == "audio"]
+    blank = _blank_reference_image()
+    target_duration = target_frame_count / MODEL_FPS
+    outputs: list[Any] = []
+    for reference in pictures[:MAX_REF_IMAGES]:
+        if not reference.get("image_filename"):
+            outputs.append(blank.clone())
+            continue
+        try:
+            outputs.append(_load_reference_image_tensor(reference))
+        except (FileNotFoundError, OSError, ValueError):
+            outputs.append(blank.clone())
+    for reference in videos[:MAX_REF_VIDEOS]:
+        if not reference.get("video_filename"):
+            outputs.append(_blank_reference_video())
+            continue
+        try:
+            outputs.append(_load_reference_video(reference, target_frame_count))
+        except (FileNotFoundError, OSError, RuntimeError, ValueError):
+            outputs.append(_blank_reference_video())
+    for reference in audios[:MAX_REF_AUDIOS]:
+        if not reference.get("audio_filename"):
+            outputs.append(_blank_reference_audio())
+            continue
+        try:
+            outputs.append(_load_reference_audio(reference, target_duration))
+        except (FileNotFoundError, OSError, RuntimeError, ValueError):
+            outputs.append(_blank_reference_audio())
+    total_media_outputs = MAX_REF_IMAGES + MAX_REF_VIDEOS + MAX_REF_AUDIOS
+    outputs.extend(blank.clone() for _ in range(total_media_outputs - len(outputs)))
+    return tuple(outputs)
+
+
+class _FlexibleOutputType(str):
+    def __ne__(self, _value):
+        return False
+
+
+FLEXIBLE_MEDIA_TYPE = _FlexibleOutputType("*")
+
+
+class MinimaxH3Prompter:
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "project_data": (
+                    "STRING",
+                    {"default": json.dumps(DEFAULT_PROJECT, ensure_ascii=False), "multiline": True},
+                ),
+            }
+        }
+
+    RETURN_TYPES = ("STRING", "INT") + (FLEXIBLE_MEDIA_TYPE,) * (
+        MAX_REF_IMAGES + MAX_REF_VIDEOS + MAX_REF_AUDIOS
+    )
+    RETURN_NAMES = (
+        "generated_prompt",
+        "length",
+    ) + tuple(f"image_{index}" for index in range(1, MAX_REF_IMAGES + 1)) + tuple(
+        f"video_{index}" for index in range(1, MAX_REF_VIDEOS + 1)
+    ) + tuple(f"audio_{index}" for index in range(1, MAX_REF_AUDIOS + 1))
+    FUNCTION = "compile"
+    CATEGORY = "ToyxyzTestNodes/Prompt"
+    DESCRIPTION = "Director-style editor that directly compiles a production-ready MiniMax-H3 video prompt."
+
+    def compile(self, project_data: str):
+        result = compile_project(project_data)
+        enhanced_prompt = result["enhanced_prompt"]
+        auto_run = bool(result["project"].get("auto_run"))
+        if auto_run:
+            if result["errors"]:
+                raise ValueError("Fix project validation errors before Auto Run can generate the prompt.")
+            enhanced = enhance_project(
+                project_data,
+                result["project"].get("enhance_model") or DEFAULT_ENHANCE_MODEL_ID,
+                result["project"].get("image_model") or DEFAULT_IMAGE_MODEL_ID,
+            )
+            enhanced_prompt = enhanced["enhanced_prompt"]
+        outputs = (
+            enhanced_prompt,
+            result["effective_frames"],
+            *_reference_media_outputs(result["project"], result["effective_frames"]),
+        )
+        if auto_run:
+            return {
+                "ui": {"auto_run_prompt": [enhanced_prompt]},
+                "result": outputs,
+            }
+        return outputs
+
+
+try:
+    import asyncio
+    from aiohttp import web
+    from server import PromptServer
+
+    if getattr(PromptServer, "instance", None) is not None:
+        @PromptServer.instance.routes.post("/toyxyz/minimax_h3_prompter/upload-video")
+        async def minimax_h3_prompter_upload_video(request):
+            partial_path = ""
+            try:
+                if request.content_type == "application/octet-stream":
+                    upload_id = request.query.get("upload_id", "")
+                    if not re.fullmatch(r"[A-Za-z0-9]{12,80}", upload_id):
+                        raise ValueError("Invalid video upload identifier.")
+                    original_name = os.path.basename(request.query.get("filename", ""))
+                    extension = os.path.splitext(original_name)[1].lower()
+                    if extension not in VIDEO_EXTENSIONS:
+                        raise ValueError("Supported video formats are MP4, WebM, MOV, MKV, AVI, and M4V.")
+                    try:
+                        chunk_index = int(request.query.get("chunk_index", "-1"))
+                    except ValueError as exc:
+                        raise ValueError("Invalid video chunk index.") from exc
+                    if chunk_index < 0:
+                        raise ValueError("Invalid video chunk index.")
+                    safe_stem = re.sub(
+                        r"[^\w.-]+", "_", os.path.splitext(original_name)[0], flags=re.UNICODE
+                    ).strip("._")
+                    safe_stem = safe_stem[:100] or "reference-video"
+                    stored_name = f"{safe_stem}-{upload_id[:20]}{extension}"
+                    import folder_paths
+
+                    input_root = os.path.abspath(folder_paths.get_input_directory())
+                    subfolder = "toyxyz_h3_references"
+                    target_dir = os.path.abspath(os.path.join(input_root, subfolder))
+                    if os.path.commonpath((input_root, target_dir)) != input_root:
+                        raise ValueError("Invalid reference-video destination.")
+                    os.makedirs(target_dir, exist_ok=True)
+                    target_path = os.path.join(target_dir, stored_name)
+                    partial_path = target_path + ".part"
+                    if chunk_index == 0:
+                        mode = "wb"
+                    elif not os.path.isfile(partial_path):
+                        raise ValueError("Video upload chunks arrived out of order.")
+                    else:
+                        mode = "ab"
+                    existing_size = os.path.getsize(partial_path) if mode == "ab" else 0
+                    received = 0
+                    with open(partial_path, mode) as handle:
+                        async for chunk in request.content.iter_chunked(1024 * 1024):
+                            received += len(chunk)
+                            if existing_size + received > VIDEO_UPLOAD_MAX_BYTES:
+                                raise ValueError("Reference video exceeds the 2 GiB upload limit.")
+                            handle.write(chunk)
+                    if received == 0:
+                        raise ValueError("An empty video upload chunk was received.")
+                    if request.query.get("final") != "1":
+                        return web.json_response({"status": "partial", "received": existing_size + received})
+                    os.replace(partial_path, target_path)
+                    partial_path = ""
+                    duration = await asyncio.to_thread(_probe_video_duration, target_path)
+                    if _find_ffprobe() and duration is None:
+                        try:
+                            os.unlink(target_path)
+                        except FileNotFoundError:
+                            pass
+                        raise ValueError("The uploaded file is not a readable video.")
+                    return web.json_response({
+                        "status": "success", "name": stored_name, "subfolder": subfolder,
+                        "type": "input", "duration": round(duration, 3) if duration else None,
+                    })
+
+                reader = await request.multipart()
+                field = await reader.next()
+                if field is None or field.name != "video" or not field.filename:
+                    raise ValueError("A video file is required.")
+                original_name = os.path.basename(field.filename)
+                extension = os.path.splitext(original_name)[1].lower()
+                if extension not in VIDEO_EXTENSIONS:
+                    raise ValueError("Supported video formats are MP4, WebM, MOV, MKV, AVI, and M4V.")
+                safe_stem = re.sub(r"[^\w.-]+", "_", os.path.splitext(original_name)[0], flags=re.UNICODE).strip("._")
+                safe_stem = safe_stem[:100] or "reference-video"
+                stored_name = f"{safe_stem}-{uuid.uuid4().hex[:10]}{extension}"
+                import folder_paths
+
+                input_root = os.path.abspath(folder_paths.get_input_directory())
+                subfolder = "toyxyz_h3_references"
+                target_dir = os.path.abspath(os.path.join(input_root, subfolder))
+                if os.path.commonpath((input_root, target_dir)) != input_root:
+                    raise ValueError("Invalid reference-video destination.")
+                os.makedirs(target_dir, exist_ok=True)
+                target_path = os.path.join(target_dir, stored_name)
+                partial_path = target_path + ".part"
+                total = 0
+                with open(partial_path, "wb") as handle:
+                    while True:
+                        chunk = await field.read_chunk(size=1024 * 1024)
+                        if not chunk:
+                            break
+                        total += len(chunk)
+                        if total > VIDEO_UPLOAD_MAX_BYTES:
+                            raise ValueError("Reference video exceeds the 2 GiB upload limit.")
+                        handle.write(chunk)
+                if total == 0:
+                    raise ValueError("The uploaded video is empty.")
+                os.replace(partial_path, target_path)
+                partial_path = ""
+                duration = await asyncio.to_thread(_probe_video_duration, target_path)
+                if _find_ffprobe() and duration is None:
+                    try:
+                        os.unlink(target_path)
+                    except FileNotFoundError:
+                        pass
+                    raise ValueError("The uploaded file is not a readable video.")
+                return web.json_response({
+                    "status": "success", "name": stored_name, "subfolder": subfolder,
+                    "type": "input", "duration": round(duration, 3) if duration else None,
+                })
+            except ValueError as exc:
+                if partial_path:
+                    try:
+                        os.unlink(partial_path)
+                    except FileNotFoundError:
+                        pass
+                return web.json_response({"status": "error", "message": str(exc)}, status=400)
+            except Exception as exc:
+                if partial_path:
+                    try:
+                        os.unlink(partial_path)
+                    except FileNotFoundError:
+                        pass
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+
+        @PromptServer.instance.routes.get("/toyxyz/minimax_h3_prompter/video")
+        async def minimax_h3_prompter_video(request):
+            try:
+                video_path = _resolve_uploaded_video({
+                    "filename": request.query.get("filename", ""),
+                    "subfolder": request.query.get("subfolder", ""),
+                })
+                return web.FileResponse(video_path)
+            except (ValueError, FileNotFoundError) as exc:
+                return web.json_response({"status": "error", "message": str(exc)}, status=404)
+
+        @PromptServer.instance.routes.post("/toyxyz/minimax_h3_prompter/compile")
+        async def minimax_h3_prompter_compile(request):
+            try:
+                payload = await request.json()
+                result = compile_project(payload.get("project_data", ""))
+                return web.json_response({
+                    "status": "success",
+                    "raw_prompt": result["draft_video_prompt"],
+                    "video_prompt": result["video_prompt"],
+                    "enhanced_prompt": result["enhanced_prompt"],
+                    "validation_report": result["validation_report"],
+                    "errors": result["errors"],
+                    "warnings": result["warnings"],
+                    "effective_frames": result["effective_frames"],
+                    "effective_duration": result["effective_duration"],
+                    "resolved_mode": result["resolved_mode"],
+                    "mode_selection": result["mode_selection"],
+                    "project": result["project"],
+                })
+            except Exception as exc:
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+
+        @PromptServer.instance.routes.get("/toyxyz/minimax_h3_prompter/models")
+        async def minimax_h3_prompter_models(_request):
+            try:
+                return web.json_response({
+                    "status": "success",
+                    "default": DEFAULT_ENHANCE_MODEL_ID,
+                    "models": list_enhance_models(),
+                    "image_default": DEFAULT_IMAGE_MODEL_ID,
+                    "image_models": list_image_models(),
+                })
+            except Exception as exc:
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+
+        @PromptServer.instance.routes.get("/toyxyz/minimax_h3_prompter/enhance/status")
+        async def minimax_h3_prompter_enhance_status(request):
+            job_id = _clean_text(request.query.get("job_id"))
+            job = _get_enhance_job(job_id)
+            return web.json_response({"status": "success", "job": job})
+
+        @PromptServer.instance.routes.post("/toyxyz/minimax_h3_prompter/enhance/cancel")
+        async def minimax_h3_prompter_enhance_cancel(request):
+            try:
+                payload = await request.json()
+                job_id = _clean_text(payload.get("job_id"))
+                if not job_id:
+                    return web.json_response(
+                        {"status": "error", "message": "A prompt generation job id is required."},
+                        status=400,
+                    )
+                found = await asyncio.to_thread(_cancel_enhance_job, job_id)
+                return web.json_response({
+                    "status": "success",
+                    "cancelled": found,
+                    "message": "Prompt generation stop requested." if found else "The job is no longer active.",
+                })
+            except Exception as exc:
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+
+        @PromptServer.instance.routes.post("/toyxyz/minimax_h3_prompter/analyze-reference")
+        async def minimax_h3_prompter_analyze_reference(request):
+            try:
+                payload = await request.json()
+                job_id = _clean_text(payload.get("job_id"))
+                _set_enhance_job(job_id, stage="image_model_check", message="Checking the selected image analysis model.")
+                try:
+                    import comfy.model_management as model_management
+
+                    model_management.unload_all_models()
+                    model_management.soft_empty_cache(force=True)
+                except (ImportError, AttributeError):
+                    pass
+                result = await asyncio.to_thread(
+                    analyze_reference_image,
+                    payload.get("image") if isinstance(payload.get("image"), dict) else {},
+                    _clean_text(payload.get("role")).lower() or "subject_identity",
+                    _clean_text(payload.get("image_model")) or DEFAULT_IMAGE_MODEL_ID,
+                    lambda **values: _set_enhance_job(job_id, **values),
+                )
+                return web.json_response({"status": "success", **result})
+            except (ValueError, FileNotFoundError) as exc:
+                _set_enhance_job(locals().get("job_id", ""), stage="error", message=str(exc))
+                return web.json_response({"status": "error", "message": str(exc)}, status=400)
+            except Exception as exc:
+                _set_enhance_job(locals().get("job_id", ""), stage="error", message=str(exc))
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+
+        @PromptServer.instance.routes.post("/toyxyz/minimax_h3_prompter/enhance")
+        async def minimax_h3_prompter_enhance(request):
+            try:
+                payload = await request.json()
+                job_id = _clean_text(payload.get("job_id"))
+                cancel_event = _begin_enhance_job(job_id)
+                _set_enhance_job(job_id, stage="queued", message="Prompt generation request queued.")
+
+                def report_progress(**values):
+                    if cancel_event.is_set():
+                        raise EnhancementCancelled("Prompt generation was stopped by the user.")
+                    _set_enhance_job(job_id, **values)
+
+                result = await asyncio.to_thread(
+                    enhance_project,
+                    payload.get("project_data", ""),
+                    _clean_text(payload.get("model")) or DEFAULT_ENHANCE_MODEL_ID,
+                    _clean_text(payload.get("image_model")) or DEFAULT_IMAGE_MODEL_ID,
+                    report_progress,
+                    cancel_event,
+                    job_id,
+                )
+                return web.json_response({"status": "success", **result})
+            except EnhancementCancelled as exc:
+                _set_enhance_job(locals().get("job_id", ""), stage="cancelled", message=str(exc))
+                return web.json_response({"status": "cancelled", "message": str(exc)}, status=409)
+            except ValueError as exc:
+                _set_enhance_job(locals().get("job_id", ""), stage="error", message=str(exc))
+                return web.json_response({"status": "error", "message": str(exc)}, status=400)
+            except Exception as exc:
+                _set_enhance_job(locals().get("job_id", ""), stage="error", message=str(exc))
+                return web.json_response({"status": "error", "message": str(exc)}, status=500)
+            finally:
+                _finish_enhance_job(locals().get("job_id", ""))
+except ImportError:
+    # Allows the pure compiler to be imported by lightweight tests outside ComfyUI.
+    pass
diff --git a/nodes/minimax_h3_system_prompts.json b/nodes/minimax_h3_system_prompts.json
new file mode 100644
index 0000000..d1161c1
--- /dev/null
+++ b/nodes/minimax_h3_system_prompts.json
@@ -0,0 +1,44 @@
+{
+  "common": "You write one production-ready MiniMax H3 audiovisual prompt from structured user data. Return only the requested H3 format in fluent English. Preserve dialogue, lyrics, and visible text exactly in their original language. Never echo input-section headings or planning notes.\n\nPRIORITY\n1. Explicit user actions, words, constraints, references, shot count, order, and duration.\n2. Observable reference evidence, limited to its assigned role.\n3. Temporal, spatial, body, object, and camera continuity.\n4. Minimal detail needed to make the request renderable.\nWhen rules conflict, the higher priority wins. Omit unsupported details instead of guessing. Do not invent identities, demographics, backstory, extra people, crowds, props, dialogue, music, targets, directions, or unrelated reactions and effects. Add only physical consequences and audiovisual cues directly implied by the requested setting and visible actions.\n\nSTYLE AND REFERENCE FIDELITY\nUse a target-wide style only when the user explicitly requests it, except that I2VA, FL2VA, and L2VA must preserve the observable visual medium and rendering style of their concrete frame anchors. In REF2VA, Weak and Normal do not transfer source style; a Strong Subject keeps only its own source medium or rendering style without transferring it to the scene or other Subjects. When no target style or keyframe style applies, omit target-wide medium, aesthetic, rendering, lighting-treatment, palette, and color-grade declarations. Preserve concrete frame anchors as visible states.\n\nTIMELINE AND CAMERA\nSHOT_PLAN visual_action is the unified source for visuals, action, camera, transitions, dialogue, visible text, sound, and music. Use exactly the configured shots in order. [Shot 1] has no timestamp. Every later shot starts at its supplied timestamp and represents an ordinary cut unless another transition is explicit. Never add, remove, merge, split, duplicate, or renumber shots. Preserve every requested action in order, show only the intermediate motion needed to make it physically legible, and finish each action on a stable observable state. Honor explicit camera instructions. Otherwise choose one coherent framing that contains the complete action path, using a static camera or one simple motivated movement. Never mention a surface, container, doorway, pocket, furniture item, obstacle, or target unless reference evidence or user text establishes it. Use a cut only when the configured next shot reveals new subject, space, state, viewpoint, or time information.\n\nDIALOGUE AND VISIBLE TEXT\nAssign stable (S1), (S2), and later IDs only to actual vocal sources in first-vocalization order. Identify the visible speaker before (Sx); add voice or delivery traits only when supplied or clearly required. Write spoken dialogue as identity (Sx) says: <d>[Language] exact words</d>, singing with sings:, and explicit voiceover with says in an off-screen voiceover:. Inside <d>, keep only one language tag and the exact supplied words; never translate, paraphrase, duplicate, or add words. For on-screen speech, keep the face readable and state briefly that visible mouth movement synchronizes with the line and ends when the line ends. Give speech a readable beat; separate a competing high-salience action unless the user explicitly requests simultaneity. Visible text uses exact double-quoted characters, never <d> or a speaker ID.\n\nAUDIO\nInfer only concise ambience and physical sounds directly implied by the requested environment and visible actions. Place a synchronized physical sound beside its visible cause when useful. overall_soundscape is one concise video-wide paragraph without shot labels, timestamps, dialogue, singing, diegetic music, or unsupported reactions; use N/A only when complete silence is explicit. Music audible inside the scene stays in the shot. Put only explicitly requested audience-only BGM, soundtrack, or score in non_diegetic_music, described by instrumentation, tempo, rhythm, and dynamics; otherwise output N/A.\n\nReturn the final prompt only, with correct labels, timestamps, verbatim content, continuity, audio routing, and final state.",
+  "common_enhanced": "You are a creative cinematic rewriter producing one richly developed, production-ready MiniMax H3 audiovisual prompt from structured user data and role-aware reference evidence. Return only the requested H3 format in fluent English. Preserve dialogue, lyrics, and visible text verbatim in their original language. Never echo input keys, analysis labels, planning notes, or commentary.\n\nPRIORITY\n1. Preserve explicit actions, words, constraints, references, shot count, order, timestamps, and duration.\n2. Preserve observable frame anchors and role-limited reference identity.\n3. Build convincing temporal, spatial, anatomical, object, camera, and audiovisual continuity.\n4. Enrich the scene with concrete cinematic detail that supports the requested events.\nA lower priority may elaborate but never replace or contradict a higher one.\n\nRICH CINEMATIC DEVELOPMENT\nTreat the input as a scene brief, not text to paraphrase. Establish the visible composition, subject placement, environment, lighting direction, important materials, support and contact, and action-relevant objects. Develop every shot as a fluent early-to-middle-to-late progression: preparation, onset, continuous physical execution, secondary motion and material response, immediate reaction, and a stable final state. Add plausible small gestures, weight shifts, hand repositioning, gaze changes, hair and clothing response, reflections, shadows, environmental motion, and synchronized physical sounds when they make the requested event clearer. Use specific observable language, varied sentence rhythm, and enough detail to visualize the complete shot. Do not pad with praise, repeated appearance inventories, abstract mood, or synonymous restatement.\n\nCREATIVE BOUNDARY\nInfer minor staging only when it connects explicit events. Never add a new major event, person, crowd, dialogue line, visible text, injury, transformation, discharge, cut, target, or outcome. Do not infer demographic identity or backstory. Never write alternatives using or, either, possibly, perhaps, may, or might; choose one coherent visible path. If an object's origin or destination is not established, describe it entering or leaving through the appropriate frame edge without inventing a pocket, holster, container, table, surface, doorway, or hiding place. Track which hand holds every object and resolve object state before a hand performs another action. Keep anatomy, contact, occlusion, scale, screen direction, and continuity coherent across beats and cuts. Keep the action load achievable within the supplied duration.\n\nSTYLE AND REFERENCES\nUse an explicitly requested target style. I2VA, FL2VA, and L2VA preserve the observable medium and rendering style of their frame anchors. In REF2VA, Weak and Normal do not transfer source style; a Strong Subject preserves only that Subject's source medium or rendering style. Do not spread a Subject's style to the scene or another Subject. Preserve concrete anchor states and describe a continuous departure, interpolation, or convergence appropriate to the active mode.\n\nCAMERA AND EDITING\nUse exactly the configured shots and timestamps. Never add, remove, merge, split, duplicate, or renumber shots. Honor explicit camera instructions. Otherwise select framing that contains the whole action and use one motivated camera behavior per shot, described naturally with motion type and, when useful, amplitude and speed. A configured cut must provide a clear continuation or new view while preserving subject and object state.\n\nDIALOGUE, TEXT, AND AUDIO\nAssign stable speaker IDs only to vocal sources. Keep identity and delivery outside <d>; inside <d>, retain only the language tag and exact supplied words. For visible on-screen speech, keep the face readable and synchronize mouth articulation through the complete line. Preserve visible text exactly in double quotation marks. Place useful synchronized physical sounds beside their causes and summarize ambience and non-verbal sounds concisely in overall_soundscape without repeating dialogue. Put audience-only music in non_diegetic_music only when explicitly requested; otherwise output N/A.\n\nReturn only the finished prompt with correct fields, labels, timing, continuity, and final state.",
+  "action_semantics": "\n\nINPUT LOCKS\nObey TARGET_STYLE_LOCK and every supplied lock; each overrides inference and is not an output heading. Preserve each action's actor, target, verb meaning, direction, repetition, and duration. Never generalize a named body part or object, weaken a repeated action into one contact or static hold, insert unsupported clothing over the named contact target, or invent an exact repetition or step count.",
+  "static_asset_rules": {
+    "common": "\n\nSTATIC CHARACTER MOTION\nA figurine, doll, statue, mannequin, toy, or illustrated character is not required to stay frozen. When explicit action asks it to move, speak, transform, or interact, animate it as an articulated character. Preserve its material, construction, proportions, and style only when the user has not explicitly requested a different target medium or rendering style. An explicit target style such as 3D animation overrides a photographed collectible presentation: preserve character identity and design, but do not call it PVC, resin, vinyl, a physical collectible, or a display object unless that presentation is requested. Its reference pose is fixed only at its assigned anchor time. Show relevant joint and balance changes. Preserve bases, rods, stands, strings, props, and contact until their change is requested or physically required. Never replace requested motion with camera-only motion, a slideshow, static crossfade, frozen-pose transformation, or appearance-only morph. Keep it still when only a still pose or camera motion is requested.",
+    "enhanced": "\n\nFor requested static-asset motion, stage visible changes through only the joints, balance, and contact needed for the requested action. Drive hair, clothing, ribbons, and attached accessories from that primary body motion. Preserve character design and compatible material traits, but when an explicit target style is present, do not restore an incompatible photographed collectible, display-object, or source-rendering presentation.",
+    "FL2VA": "\n\nFL2VA STATIC-ASSET LOCK\nIf either endpoint is a static character asset and motion is requested, show an articulated pose path from Picture 1 to Picture 2. Do not hold the first pose while only color, hair, clothing, texture, or style dissolves into the final image.",
+    "FL2VA_enhanced": "\n\nBegin with visible joint-driven departure from Picture 1, keep only the requested body and object motion observable through the middle, then progressively converge on Picture 2 in the final frames. Enrich continuity, balance, contact, and secondary response without inventing a spin, dance, particle effect, dramatic performance, or extra transformation. Separate pose progression from appearance interpolation and avoid an appearance-only morph."
+  },
+  "enhance_addendum": "\n\nENHANCED OUTPUT DEPTH\nThis is an action-development rewrite, not an appearance inventory. OUTPUT_BUDGET is the only active word-count instruction. Spend most detail on requested events. For each shot, make the opening state, preparation, physical execution, observable secondary response, and stable end state distinct on the timeline. Make locomotion legible through displacement and weight transfer; make interaction legible through approach, contact, changing motion, and the requested ending. Use one slight motivated reframe when the anchor crop hides essential motion. Enrich continuity and staging, never plot. Mention anchor appearance only as needed for identity and action. Silently verify definite hands, objects, contact, no unsupported storage or clothing, and unchanged events and shots.",
+  "base": "\n\nBASE OUTPUT\nUse the three locked fields in this order: integrated_multimodal_description, overall_soundscape, non_diegetic_music. Begin the main field with [Shot 1]. Begin each later shot naturally as [Shot N] At MM:SS.mmm, the shot cuts to ... unless another transition is explicit. Base modes never define or use <Subject N>. Put an ordinary visible identity before every speaker ID, for example the girl (S1).",
+  "common_addendum": "\n\nDIALOGUE ACROSS CUTS\nWhen one vocal line continues across a cut, put <scenetrans> at both connecting points, keep the same speaker ID, and state that the audio continues across the cut. Use <cutoff> only when the video ending truncates the line.",
+  "video_reference_common": "\n\nVIDEO REFERENCE CORE\nDefine each <Video N> as a source asset, never as a person or Subject. Ordered-frame evidence covers visuals only and never establishes source audio. Explicit target instructions override conflicting source evidence. Apply only the selected preset module; do not transfer facts assigned to another video role.",
+  "video_reference_roles": {
+    "none": "\n\nVIDEO PRESET: NONE\nFollow only the user-defined relationship for the assigned video. Use evidence only where it supports that relationship. Do not assume editing, continuation, motion, camera, cut, style, or audio transfer.",
+    "video_editing": "\n\nVIDEO PRESET: EDITING\nTreat the assigned video as the source being edited. Distinguish complete entity replacement from attribute-only editing. Complete entity replacement preserves performance, timing, position, motion paths, contacts, scene role, environment, objects, composition, camera, cuts, lighting continuity, and final state, but does not preserve that entity's source identity, face, body appearance, hair, clothing, or accessories unless explicitly retained. Attribute-only editing changes only named attributes and preserves other evidenced attributes. Cover every evidenced ACTION_TIMELINE interval in order, including later beats and the final pose; wording may be compact but no interval may be omitted.",
+    "video_continuation": "\n\nVIDEO PRESET: CONTINUATION\nContinue directly from the assigned video's evidenced ending. Preserve final positions, pose, gaze, object state, contact, motion direction and momentum, camera behavior, lighting, and environment. Do not replay, summarize, or restart earlier source actions.",
+    "motion": "\n\nVIDEO PRESET: MOTION\nTransfer only evidenced subject motion and timing: pose progression, direction, speed, rhythm, contacts, interaction timing, and final motion state. Do not transfer source identity, clothing, environment, style, lighting, composition, camera, cuts, or audio unless separately requested.",
+    "camera": "\n\nVIDEO PRESET: CAMERA\nTransfer only evidenced framing progression, viewpoint, camera movement type, direction, amplitude, speed, stabilization, and tracking relationship. Do not transfer source subjects, actions, setting, style, lighting, cuts, or audio. If camera motion cannot be distinguished from subject motion, do not invent it.",
+    "cuts_rhythm": "\n\nVIDEO PRESET: CUTS AND RHYTHM\nTransfer only supported shot count, cut timing, segment duration, viewpoint changes, event placement, pacing, and transition type, applying that structure to target content. Do not transfer source identity, detailed motion, environment, style, lighting, camera motion, or audio beyond the evidenced edit structure."
+  },
+  "audio_reference_common": "\n\nAUDIO REFERENCE CORE\nDefine each <Audio N> as an audio asset, never as a person or Subject. Audio numbering is independent of Picture and Video numbering. Sound contained in an ordinary <Video N> is not an <Audio N> and is not transferred unless separately enabled as audio. The model has no direct audio analysis evidence: infer no speaker, words, language, instruments, genre, effects, ambience, or signal content beyond explicit user metadata. Apply only the selected preset module. Route spoken or sung words to the applicable shot, non-verbal ambience and effects to overall_soundscape, audience-only score to non_diegetic_music, and music with a visible in-scene source to the shot timeline.",
+  "audio_reference_roles": {
+    "none": "\n\nAUDIO PRESET: NONE\nFollow only the user-defined relationship for the assigned audio. Do not assume signal reuse, voice transfer, dialogue, lyrics, effects, ambience, music, rhythm, or timing. If its relationship is not described, keep the label defined but make no unsupported content claim.",
+    "full_signal_copy": "\n\nAUDIO PRESET: FULL SIGNAL COPY\nTreat the complete assigned source-audio signal as the target video's complete audio for the available target duration. Use fully_copy. Do not replace, remix, separate, embellish, or invent layers. State the reuse relationship concisely without claiming unheard content.",
+    "partial_signal_copy": "\n\nAUDIO PRESET: PARTIAL SIGNAL COPY\nReuse only the interval, layers, or elements explicitly selected by the user and use partially_copy. Preserve their requested placement and timing. Do not claim that unspecified source layers are copied, and do not identify unheard content.",
+    "voice_delivery": "\n\nAUDIO PRESET: VOICE AND DELIVERY\nReference only explicitly described voice timbre, accent, emotion, pace, delivery, and vocal texture. Use reference, not a copy marker. Bind it to a defined target <Subject N> (Sx) only when the user identifies that speaker. Never copy or invent source words, dialogue, lyrics, music, ambience, or effects.",
+    "dialogue_lyrics": "\n\nAUDIO PRESET: DIALOGUE OR LYRICS REUSE\nReuse only exact words explicitly supplied by the user or reliable transcription evidence and use partially_copy. Put the exact content once in <d>[Language] ...</d> in the applicable shot with a stable speaker when known. Never infer, translate, correct, paraphrase, extend, or fabricate unavailable words. If no exact text is supplied, state only that the assigned source vocal content is reused without inventing a transcript.",
+    "sound_ambience": "\n\nAUDIO PRESET: SOUND EFFECTS AND AMBIENCE\nReference only explicitly described effects, ambience, room tone, acoustic space, and their timing. Use reference and route concise non-verbal content to overall_soundscape or beside its visible cause when synchronization matters. Do not transfer dialogue, lyrics, music, or an entire source signal.",
+    "music_rhythm": "\n\nAUDIO PRESET: MUSIC AND RHYTHM\nReference only explicitly described instrumentation, tempo, meter, beat, rhythm, dynamics, structure, and musical mood. Use reference and never claim source-signal copying. Put audience-only music in non_diegetic_music; put music with an established visible in-scene source in the applicable shot. Do not transfer dialogue, lyrics, effects, or ambience."
+  },
+  "mode_addenda": {
+    "FL2VA": "\n\nFL2VA IDENTITY LOCK\nKeep different people, characters, and objects separate unless morphing or transformation is explicit. A hit, fall, entrance, exit, or cut never authorizes trait transfer. Do not keep a Picture 1-only entity visibly present in the final composition when that would contradict Picture 2. Bind Picture 2 traits only to the matching final-frame entity. Use no <Subject N> labels, put a visible identity before every speaker ID, and avoid contradictory framing terms.",
+    "REF2VA": ""
+  },
+  "modes": {
+    "T2VA": "\n\nMODE: T2VA\nBuild the complete audiovisual timeline from text only. Emit no image-alignment sentence or unresolved asset label. Expand each configured shot into concise chronological action with enough subject, setting, camera, and directly implied sound detail to make it renderable. Add neutral spatial detail only when needed for continuity; do not invent a new plot, performance, consequence, or target-wide style. Keep the amount of detail proportional to duration and action complexity.",
+    "I2VA": "\n\nMODE: I2VA\nStart with the exact alignment line supplied by FINAL MODE LOCK, followed by one blank line and the Base fields. Picture 1 is the complete literal frame at 0.00 seconds. Treat its observable visual medium and rendering style as part of the opening anchor unless the user explicitly requests a style change. Establish the action-relevant anchors: subject identity, visible clothing and construction, pose, support and contact, composition, environment, and key objects. Preserve every visible surface, foreground object, support, obstacle, and spatial relationship that the requested action touches, passes behind or in front of, or depends on. Do not replace the evidenced setting with a generic room, office, studio, or gradient background. Avoid unrelated inventory and never infer hidden content, demographics, intent, or future action.\n\nContinue from the actual opening state through action onset, necessary physical development, and a stable result. Keep hands, body, fabric, objects, contact, and occlusion coherent. An initially absent object may enter the frame only through a physically plausible visible path; do not claim it came from an unestablished table, pocket, container, or location. Never invent a target or aiming direction. Preserve an explicit direction; otherwise use only a neutral direction supported by the request and composition. The framing must contain the complete action path. Keep the camera static when it does; if an object or body movement would leave the crop, use one slight pullback, tilt, pan, or tracking adjustment to keep the action and final pose visible. For about five seconds, prefer one central action and no more than three connected beats. Do not add unrequested outcomes, injuries, reactions, debris, or unrelated sounds. Use about 110-160 English words for a simple action, 150-210 when contact objects or spatial staging require it, and at most about 240 for a genuinely complex action.",
+    "FL2VA": "\n\nMODE: FL2VA\nStart with the exact alignment line supplied by FINAL MODE LOCK, one blank line, then the Base fields. Picture 1 is the complete opening frame and Picture 2 is the complete frame reached only at the effective end. Their observable media and rendering styles are endpoint evidence. Preserve a shared style when consistent; if they differ, describe only the requested transition needed to reach Picture 2. Treat both images as visual anchors rather than appearance inventories. Describe the shortest coherent path: action timing, pose and object-state changes, explicit transformation, necessary camera behavior, background continuity, and final convergence.\n\nUse exactly the configured shots and prefer one continuous shot when the input contains one. Unless required otherwise, keep framing, scale, perspective, background, and lighting stable with a static camera or one small motivated adjustment. Use minimal motion and never invent a full rotation, orbit, dramatic performance, hybrid identity, duplicated object, or extra limb. Narrow differences progressively and stabilize on the exact Picture 2 composition only in the final frames. A simple one-shot interpolation is usually 80-150 English words.",
+    "L2VA": "\n\nMODE: L2VA\nStart with the exact alignment line supplied by FINAL MODE LOCK, followed by one blank line and the Base fields. Picture 1 is only the exact final frame, including its observable visual medium and rendering style. Infer one plausible preceding state from the user's request, then show the shortest physically coherent path toward the reference. Progressively narrow differences in subject state, pose, objects, viewpoint, lighting, style, and composition; do not treat Picture 1 as the opening, reach it early, or narrate it as a detached inventory. Use exactly the configured shots and one coherent framing unless the request requires a change. Hold the exact referenced final state briefly at the effective end. A simple one-shot convergence is usually 80-150 English words.",
+    "REF2VA": "\n\nMODE: REF2VA\nUse the six locked sections in order as plain text, never JSON.\n\nLABELS\nUse <Subject N> for reusable visible content. Define each image-derived Subject in one line with visible identity traits allowed by its strength, ending with derived from <Picture N>. Weak keeps broad identity cues. Normal keeps the core identifiable appearance but may adapt secondary details. Strong keeps salient appearance and that Subject's source medium or rendering style; it does not transfer source environment, composition, camera, lighting, scene-wide palette, pose, or action. Never blend different Strong Subject styles. Do not define a standalone Picture unless it is a configured frame anchor. Use <Video N> only for source-video structure, editing, or continuation, and <Audio N> only for an enabled audio relationship. Define only locked labels, number each label type independently, and keep their meanings stable.\n\nSUMMARY AND RETENTION\nBegin summary with one bracketed list of applicable task types joined by +: keyframe completion, reference generation, video editing, video continuation, audio reuse, or audio reference. Follow with one short paragraph using only defined labels. In retention_analysis, write one concise line per locked label with its applicable shots, then exactly its locked output marker and a short preservation description. Output only fixed markers such as fully_preserved, partially_preserved, or weak_reference. Never print the UI strength words weak, normal, or strong, never print an equals sign, and never describe the mapping between strength and marker. New target action or setting is not a fidelity loss. Never put speaker IDs there.\n\nDESCRIPTION\nThe explicit request owns target action and setting. Weak and Normal Subjects do not transfer source style. Strong style stays local to that Subject. If target style is unspecified, begin detailed_description directly with [Shot 1]. At each Subject's first appearance, state only role-relevant traits, frame position, current action, and, for Strong only, retained source style; later reuse the label without redefining it. Preserve requested actions in order and keep interactions, anatomy, contact, scale, and identity coherent. Begin later shots as [Shot N] At MM:SS.mmm, followed by new shot content; the timestamp establishes an ordinary cut, while any special transition must be explicit. Do not invent bystanders, props, dialogue, or outcomes. Scale detail to duration and complexity; never repeat identity inventories.\n\nDIALOGUE AND AUDIO\nA referenced visible speaker is <Subject N> (Sx). Use one complete vocal clause with exact <d> content and one short scene-specific lip-sync statement; do not announce the same speech twice. Keep overall_soundscape video-wide and free of shot labels, timestamps, dialogue, singing, and non-diegetic music. Put audience-only score only in non_diegetic_music."
+  }
+}
diff --git a/test_minimax_h3_prompter.py b/test_minimax_h3_prompter.py
new file mode 100644
index 0000000..e3a27ea
--- /dev/null
+++ b/test_minimax_h3_prompter.py
@@ -0,0 +1,2606 @@
+import importlib.util
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+
+MODULE_PATH = Path(__file__).parent / "nodes" / "minimax_h3_prompter.py"
+SPEC = importlib.util.spec_from_file_location("minimax_h3_prompter_under_test", MODULE_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class MinimaxH3PrompterTests(unittest.TestCase):
+    def compile(self, payload):
+        return MODULE.compile_project(json.dumps(payload))
+
+    def test_duration_uses_h3_frame_grid(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A cyclist stops."}],
+        })
+        self.assertEqual(result["effective_frames"], 124)
+        self.assertEqual(result["effective_frames"] % 17, 5)
+        self.assertFalse(any("17k+5 grid" in warning for warning in result["warnings"]))
+        self.assertTrue(result["video_prompt"].startswith("INPUT DATA ONLY"))
+        self.assertIn("mode: T2VA", result["video_prompt"])
+        self.assertIn("SHOT_PLAN:\n[Shot 1]", result["video_prompt"])
+        self.assertIn("when_music_unspecified: output non_diegetic_music: N/A", result["video_prompt"])
+
+    def test_saved_enhancement_survives_subsequent_input_changes(self):
+        saved = "integrated_multimodal_description: [Shot 1] Saved enhanced result."
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A newly edited raw action."}],
+            "enhanced_prompt": saved,
+        })
+        self.assertIn("A newly edited raw action.", result["draft_video_prompt"])
+        self.assertEqual(result["enhanced_prompt"], saved)
+        self.assertEqual(result["video_prompt"], saved)
+
+    def test_qwen_enhance_toggle_is_normalized_and_defaults_off(self):
+        default_project, _warnings = MODULE.normalize_project({})
+        enabled_project, _warnings = MODULE.normalize_project({"enhance": True})
+        self.assertFalse(default_project["enhance"])
+        self.assertTrue(enabled_project["enhance"])
+
+    def test_qwen_rich_enhance_contract_expands_without_changing_events(self):
+        contract = MODULE.ENHANCED_COMMON_LLM_SYSTEM_RULES + MODULE.SYSTEM_PROMPT_CONFIG["enhance_addendum"]
+        self.assertIn("creative cinematic rewriter", contract)
+        self.assertIn("early-to-middle-to-late progression", contract)
+        self.assertIn("Track which hand holds every object", contract)
+        self.assertIn("action-development rewrite", contract)
+        self.assertIn("Spend most detail on requested events", contract)
+        self.assertIn("locomotion legible through displacement and weight transfer", contract)
+        self.assertIn("no unsupported storage or clothing", contract)
+        self.assertIn("non_diegetic_music", contract)
+
+    def test_korean_i2va_style_repetition_and_visibility_are_compiled_as_locks(self):
+        result = self.compile({
+            "mode": "I2VA",
+            "enhance": True,
+            "shots": [{
+                "duration": 5,
+                "visual_action": (
+                    "여자 캐릭터가 카메라를 향해 걸어온다. "
+                    "남자가 양손으로 여자 캐릭터의 가슴을 주무른다. 3D 애니메이션."
+                ),
+            }],
+            "references": [{"type": "picture", "role": "first_frame", "filename": "frame.png"}],
+        })
+        prompt = result["draft_video_prompt"]
+        self.assertIn("TARGET_STYLE_LOCK:\ncanonical_style: 3D CG animation", prompt)
+        self.assertIn("REFERENCE_MEDIUM_CONTRACT:", prompt)
+        self.assertIn("exclude_incompatible_source_presentation", prompt)
+        self.assertIn("semantic_lock: translate faithfully", prompt)
+        self.assertIn("motion_semantics_contract:", prompt)
+        self.assertIn("preserve the source verb at its original specificity", prompt)
+        self.assertIn("continuous or repeated motion", prompt)
+        self.assertIn("Preserve stated actors, limb or hand count, contact target", prompt)
+        self.assertIn("ACTION_VISIBILITY_LOCK:", prompt)
+        self.assertIn("recommended_english_words: 140-220", prompt)
+
+    def test_target_style_application_is_mode_aware(self):
+        cases = {
+            "I2VA": "begin Shot 1 with this style and maintain it throughout",
+            "FL2VA": "explicitly requested style transition",
+            "L2VA": "converge to Picture 1's exact final-frame medium",
+            "REF2VA": "preserve a conflicting source medium only when mixed-media treatment is explicitly requested",
+        }
+        references = {
+            "I2VA": [{"type": "picture", "role": "first_frame", "filename": "a.png"}],
+            "FL2VA": [
+                {"type": "picture", "role": "first_frame", "filename": "a.png"},
+                {"type": "picture", "role": "last_frame", "filename": "b.png"},
+            ],
+            "L2VA": [{"type": "picture", "role": "last_frame", "filename": "a.png"}],
+            "REF2VA": [{"type": "picture", "role": "subject_identity", "strength": "strong", "filename": "a.png"}],
+        }
+        for mode, expected in cases.items():
+            with self.subTest(mode=mode):
+                result = self.compile({
+                    "mode": mode,
+                    "shots": [{"duration": 5, "visual_action": "A character moves in 3D animation."}],
+                    "references": references[mode],
+                })
+                self.assertIn(expected, result["draft_video_prompt"])
+                self.assertIn("material_policy:", result["draft_video_prompt"])
+
+    def test_optional_qwen_input_locks_are_omitted_when_not_applicable(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A lamp remains on."}],
+        })
+        prompt = result["draft_video_prompt"]
+        self.assertNotIn("TARGET_STYLE_LOCK:", prompt)
+        self.assertNotIn("REFERENCE_MEDIUM_CONTRACT:", prompt)
+        self.assertIn("motion_semantics_contract:", prompt)
+        self.assertNotIn("ACTION_VISIBILITY_LOCK:", prompt)
+        self.assertNotIn("OUTPUT_BUDGET:", prompt)
+
+    def test_auto_mode_resolves_from_exact_reference_layout(self):
+        cases = [
+            ([], "T2VA"),
+            ([{"type": "picture", "role": "first_frame"}], "I2VA"),
+            ([
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ], "FL2VA"),
+            ([{"type": "picture", "role": "last_frame"}], "L2VA"),
+            ([{"type": "picture", "role": "reference"}], "REF2VA"),
+            ([{"type": "video", "role": "motion", "duration": 3}], "REF2VA"),
+            ([
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "subject_identity"},
+            ], "REF2VA"),
+        ]
+        for references, expected in cases:
+            with self.subTest(expected=expected):
+                result = self.compile({
+                    "mode": "AUTO",
+                    "shots": [{"duration": 5, "visual_action": "The subject moves."}],
+                    "references": references,
+                })
+                self.assertEqual(result["resolved_mode"], expected)
+                self.assertEqual(result["project"]["mode"], expected)
+                self.assertEqual(result["mode_selection"], "AUTO")
+                self.assertFalse(result["errors"])
+
+    def test_auto_mode_does_not_silently_ignore_extra_or_reversed_anchors(self):
+        for references in ([
+            {"type": "picture", "role": "last_frame"},
+            {"type": "picture", "role": "first_frame"},
+        ], [
+            {"type": "picture", "role": "first_frame"},
+            {"type": "picture", "role": "last_frame"},
+            {"type": "audio", "role": "sound_effect"},
+        ]):
+            with self.subTest(references=references):
+                result = self.compile({
+                    "mode": "AUTO",
+                    "shots": [{"duration": 5, "visual_action": "The subject moves."}],
+                    "references": references,
+                })
+                self.assertEqual(result["resolved_mode"], "REF2VA")
+
+    def test_manual_mode_selection_remains_available(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A cyclist stops."}],
+            "references": [{"type": "picture", "role": "reference"}],
+        })
+        self.assertEqual(result["resolved_mode"], "T2VA")
+        self.assertEqual(result["mode_selection"], "T2VA")
+
+    def test_fl2va_requires_both_frame_roles(self):
+        invalid = self.compile({
+            "mode": "FL2VA",
+            "shots": [{"duration": 8, "visual_action": "Open an umbrella."}],
+            "references": [{"type": "picture", "role": "first_frame"}],
+        })
+        self.assertTrue(invalid["errors"])
+        self.assertIn("last_frame", invalid["errors"][0])
+
+        valid = self.compile({
+            "mode": "FL2VA",
+            "shots": [{"duration": 8, "visual_action": "Open an umbrella."}],
+            "references": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+        })
+        self.assertFalse(valid["errors"])
+        self.assertIn("mode: FL2VA", valid["video_prompt"])
+        self.assertIn("anchor: exact opening frame", valid["video_prompt"])
+        self.assertIn("anchor_time_seconds: 8.00", valid["video_prompt"])
+
+        wrong_order = self.compile({
+            "mode": "FL2VA",
+            "shots": [{"duration": 8, "visual_action": "Open an umbrella."}],
+            "references": [
+                {"type": "picture", "role": "last_frame"},
+                {"type": "picture", "role": "first_frame"},
+            ],
+        })
+        self.assertTrue(wrong_order["errors"])
+
+    def test_reference_labels_follow_per_type_order(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "The subject walks."}],
+            "references": [
+                {"type": "picture", "role": "subject_identity"},
+                {"type": "video", "role": "motion", "duration": 3},
+                {"type": "picture", "role": "subject_identity"},
+                {"type": "audio", "role": "voice_timbre"},
+            ],
+        })
+        prompt = result["video_prompt"]
+        self.assertLess(prompt.index("<Subject 1>"), prompt.index("<Video 1>"))
+        self.assertLess(prompt.index("<Video 1>"), prompt.index("<Subject 2>"))
+        self.assertIn("<Subject 1>\nsource: <Picture 1>", prompt)
+        self.assertIn("<Subject 2>\nsource: <Picture 2>", prompt)
+        self.assertIn("<Audio 1>\nsource: <Audio 1>", prompt)
+        self.assertIn("role: voice_delivery", prompt)
+        self.assertIn("REFERENCE_PLAN:", prompt)
+        self.assertNotIn("subject_definitions:", prompt)
+
+    def test_generic_picture_becomes_a_reusable_weak_subject(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "A woman sits on a chair."}],
+            "references": [{
+                "type": "picture",
+                "role": "reference",
+                "description": "A cute anime girl",
+            }],
+        })
+        prompt = result["video_prompt"]
+        self.assertNotIn("reference reference", prompt)
+        self.assertIn("<Subject 1>\nsource: <Picture 1>", prompt)
+        self.assertIn("retention_output_marker: weak_reference", prompt)
+        self.assertIn("broad subject appearance similarity only", prompt)
+        self.assertIn("exclude source setting, style, composition, camera, lighting, palette, pose, and action", prompt)
+        self.assertNotIn("\n<Picture 1> is", prompt)
+
+    def test_subject_strength_maps_to_h3_retention_marker_and_contract(self):
+        cases = {
+            "weak": ("weak_reference", "broad subject appearance similarity only"),
+            "normal": ("partially_preserved", "core subject identity and primary visible appearance"),
+            "strong": ("fully_preserved", "complete visible subject identity and appearance plus that subject's source visual medium/rendering style"),
+        }
+        for strength, (marker, contract) in cases.items():
+            with self.subTest(strength=strength):
+                result = self.compile({
+                    "mode": "REF2VA",
+                    "shots": [{"duration": 5, "visual_action": "@hero walks."}],
+                    "references": [{
+                        "type": "picture", "role": "subject_identity",
+                        "strength": strength, "alias": "hero",
+                    }],
+                })
+                prompt = result["draft_video_prompt"]
+                self.assertIn("role: subject_identity", prompt)
+                self.assertIn(f"input_strength_for_definition_scope_only: {strength}", prompt)
+                self.assertIn(f"retention_output_marker: {marker}", prompt)
+                self.assertIn(f"contract: {contract}", prompt)
+                if strength == "strong":
+                    self.assertIn("preserve the style independently per subject", prompt)
+                    self.assertIn("exclude source setting, composition", prompt)
+                else:
+                    self.assertIn("exclude source setting, style, composition", prompt)
+
+    def test_reference_alias_is_normalized_and_replaced(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero dances on the floor."}],
+            "references": [{
+                "type": "picture",
+                "role": "subject_identity",
+                "alias": "hero",
+                "description": "A red-haired anime heroine",
+            }],
+        })
+        self.assertEqual(result["project"]["references"][0]["alias"], "@hero")
+        self.assertNotIn("@hero", result["video_prompt"])
+        self.assertIn("<Subject 1> dances on the floor.", result["video_prompt"])
+
+    def test_reference_alias_spaces_are_normalized_and_duplicates_rejected(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero_girl waves."}],
+            "references": [
+                {"type": "picture", "role": "subject_identity", "alias": "hero girl"},
+                {"type": "audio", "role": "voice_timbre", "alias": "@hero_girl"},
+            ],
+        })
+        self.assertEqual(result["project"]["references"][0]["alias"], "@hero_girl")
+        self.assertTrue(any("aliases must be unique" in error for error in result["errors"]))
+
+    def test_reference_alias_replacement_respects_token_boundary_and_case(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@HERO waves beside @hero_extra."}],
+            "references": [{"type": "picture", "role": "subject_identity", "alias": "hero"}],
+        })
+        self.assertIn("<Subject 1> waves beside @hero_extra.", result["video_prompt"])
+
+    def test_video_alias_is_replaced_with_numbered_video_label(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "Follow @walkclip's camera movement."}],
+            "references": [{
+                "type": "video", "role": "camera", "alias": "walkclip", "duration": 5,
+            }],
+        })
+        self.assertEqual(result["project"]["references"][0]["alias"], "@walkclip")
+        self.assertNotIn("@walkclip", result["video_prompt"])
+        self.assertIn("Follow <Video 1>'s camera movement.", result["video_prompt"])
+
+    def test_reference_limits_are_errors(self):
+        references = [
+            {"type": "picture", "role": "reference", "description": str(index)}
+            for index in range(10)
+        ]
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "Test."}],
+            "references": references,
+        })
+        self.assertTrue(any("at most 9 reference images" in error for error in result["errors"]))
+
+    def test_legacy_dialogue_is_migrated_into_visual_action(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "visual_action": "A woman turns toward the camera",
+                "dialogue": "다시 시작하자.",
+                "dialogue_speaker": "S2",
+                "dialogue_language": "Korean",
+                "dialogue_mode": "voiceover",
+                "dialogue_delivery": "The woman with a calm low voice",
+            }],
+        })
+        prompt = result["video_prompt"]
+        self.assertIn(
+            "visual_action: A woman turns toward the camera\n"
+            "The woman with a calm low voice (S2) says in an "
+            "off-screen voiceover: <d>[Korean] 다시 시작하자.</d> while the corresponding "
+            "on-screen character's lips remain completely closed.",
+            prompt,
+        )
+        self.assertNotIn("dialogue", result["project"]["shots"][0])
+        self.assertNotIn("vocal_source:", prompt)
+        self.assertNotIn("verbatim_dialogue_or_lyrics:", prompt)
+
+    def test_dialogue_language_defaults_to_english(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "visual_action": "A speaker faces the camera.",
+                "dialogue": "Hello there.",
+            }],
+        })
+        self.assertIn(
+            "The on-screen speaker (S1) says: "
+            "<d>[English] Hello there.</d>",
+            result["video_prompt"],
+        )
+
+    def test_prefabricated_dialogue_is_rebuilt_with_speaker_and_language_contract(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "dialogue": "<d>[Korean] 방구 발싸!</d>",
+                "dialogue_speaker": "S1",
+                "dialogue_language": "English",
+            }],
+        })
+        self.assertIn(
+            "visual_action: The on-screen speaker (S1) says: "
+            "<d>[Korean] 방구 발싸!</d>",
+            result["video_prompt"],
+        )
+
+    def test_malformed_prefabricated_dialogue_tag_is_rewrapped(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "dialogue": "<d>Hello"}],
+        })
+        self.assertIn(
+            "visual_action: The on-screen speaker (S1) says: "
+            "<d>[English] Hello</d>",
+            result["video_prompt"],
+        )
+
+    def test_visible_text_is_safely_quoted(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visible_text": 'Say "hello"\nnow'}],
+        })
+        self.assertIn(
+            r'visual_action: A visible on-screen text element reads "Say \"hello\" now".',
+            result["video_prompt"],
+        )
+        self.assertNotIn("visible_text", result["project"]["shots"][0])
+
+    def test_visual_action_is_the_only_dialogue_and_visible_text_ui(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertIn("Visual / action / camera / dialogue / text / sound / music", source)
+        self.assertNotIn('data-el="raw-preview"', source)
+        self.assertNotIn('<span class="mmh3p-label">Raw prompt</span>', source)
+        self.assertIn(".mmh3p-visual-action-field { flex:1 1 auto; min-height:0", source)
+        self.assertIn("height:100%; min-height:0; resize:none; overflow:auto", source)
+        self.assertIn(".mmh3p-main > .mmh3p-grid { flex:1 1 0; min-height:0; }", source)
+        self.assertIn(".mmh3p-references-panel { display:flex; flex-direction:column; min-height:0", source)
+        self.assertIn(".mmh3p-reference-list { flex:1 1 auto; height:auto; min-height:0", source)
+        self.assertNotIn('<div class="mmh3p-label">Selected shot</div>', source)
+        prompt_index = source.index('<div class="mmh3p-label">Prompt</div>')
+        enhanced_index = source.index('<span class="mmh3p-label">Generated Prompt</span>')
+        references_index = source.index('<div class="mmh3p-label">References</div>')
+        self.assertLess(prompt_index, enhanced_index)
+        self.assertLess(enhanced_index, references_index)
+        for field in (
+            "dialogue_speaker", "dialogue_language", "dialogue_mode",
+            "dialogue_delivery", "dialogue", "visible_text", "camera_framing",
+            "camera_angle", "camera_motion", "transition",
+        ):
+            self.assertNotIn(f'data-shot="{field}"', source)
+
+    def test_visual_action_dialogue_and_visible_text_receive_dynamic_content_locks(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "visual_action": '여성이 총을 쏘며 "총 발싸!"라고 말하고 간판에는 "OPEN"이라고 쓰여 있다.',
+            }],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("INPUT-DERIVED CONTENT LOCKS", llm_prompt)
+        self.assertIn(
+            "vocal lock: copy this block character-for-character, including every space and punctuation mark:",
+            llm_prompt,
+        )
+        self.assertIn("Use speaker ID (S1) once before the block", llm_prompt)
+        self.assertIn("Precede (S1) with a visible speaker identity", llm_prompt)
+        self.assertIn("never begin the clause with bare (S1)", llm_prompt)
+        self.assertIn("Never copy this instruction, a checklist", llm_prompt)
+        self.assertNotIn("any gunshot, impact, abrupt recoil", llm_prompt)
+        self.assertIn('visible text: preserve "OPEN" verbatim', llm_prompt)
+
+    def test_unquoted_vocal_cue_still_locks_the_first_speaker_id(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "여성이 총발사라고 말한다."}],
+        })
+        self.assertIn(
+            "[Shot 1] contains explicit vocal content in visual_action: the first vocal source must use (S1)",
+            result["llm_prompt"],
+        )
+
+    def test_legacy_audio_fields_migrate_to_unified_visual_action(self):
+        result = self.compile({
+            "version": 13,
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "visual_action": "A door closes.",
+                "diegetic_sound": "A synchronized wooden door slam.",
+            }],
+            "overall_soundscape": "Quiet indoor room tone with distant ventilation.",
+            "non_diegetic_music": "Slow sparse piano at a low volume.",
+        })
+        prompt = result["video_prompt"]
+        action = result["project"]["shots"][0]["visual_action"]
+        shot_sound = "Synchronized physical sound: A synchronized wooden door slam."
+        soundscape = "Overall soundscape: Quiet indoor room tone with distant ventilation."
+        music = "Non-diegetic music: Slow sparse piano at a low volume."
+        self.assertIn(shot_sound, action)
+        self.assertIn(soundscape, action)
+        self.assertIn(music, action)
+        self.assertIn(shot_sound, prompt)
+        self.assertIn(soundscape, prompt)
+        self.assertIn(music, prompt)
+        self.assertIn("AUDIO_POLICY:", prompt)
+        self.assertNotIn("AUDIO_INPUTS:", prompt)
+        self.assertNotIn("diegetic_sound", result["project"]["shots"][0])
+        self.assertNotIn("overall_soundscape", result["project"])
+        self.assertNotIn("non_diegetic_music", result["project"])
+
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertNotIn('data-shot="diegetic_sound"', source)
+        self.assertNotIn('data-project="overall_soundscape"', source)
+        self.assertNotIn('data-project="non_diegetic_music"', source)
+        self.assertNotIn("mmh3p-audio-grid", source)
+        self.assertIn("dialogue / text / sound / music", source)
+
+    def test_python_normalization_uses_ui_minimum_shot_duration(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "requested_duration": 0.1,
+            "shots": [{"duration": 0.1}],
+        })
+        self.assertEqual(result["project"]["requested_duration"], 0.25)
+        self.assertEqual(result["project"]["shots"][0]["duration"], 0.25)
+
+    def test_duration_fitting_preserves_each_shot_minimum(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "requested_duration": 4,
+            "shots": [{"duration": 0.25}, {"duration": 9.75}],
+        })
+        durations = [shot["duration"] for shot in result["project"]["shots"]]
+        self.assertAlmostEqual(sum(durations), 4.0)
+        self.assertGreaterEqual(min(durations), MODULE.MIN_SHOT_DURATION)
+
+    def test_invalid_enums_are_normalized_with_warnings(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{
+                "duration": 5,
+                "dialogue": "Hello",
+                "dialogue_speaker": "S99",
+                "dialogue_language": "Klingon",
+                "dialogue_mode": "whisper",
+                "transition": "teleport",
+            }],
+            "references": [{"type": "audio", "role": "first_frame"}],
+        })
+        shot = result["project"]["shots"][0]
+        self.assertNotIn("transition", shot)
+        self.assertIn("The on-screen speaker (S1) says: <d>[English] Hello</d>", shot["visual_action"])
+        self.assertNotIn("dialogue_speaker", shot)
+        self.assertEqual(result["project"]["references"][0]["role"], "none")
+        self.assertTrue(any("normalized" in warning for warning in result["warnings"]))
+
+    def test_project_version_mismatch_warns_and_uses_current_schema(self):
+        result = self.compile({
+            "version": 999,
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "Test."}],
+        })
+        self.assertEqual(result["project"]["version"], MODULE.CURRENT_PROJECT_VERSION)
+        self.assertTrue(any("Project version" in warning for warning in result["warnings"]))
+
+    def test_removed_picture_roles_migrate_to_weak_reference(self):
+        for removed_role in ("environment", "style", "storyboard"):
+            with self.subTest(role=removed_role):
+                result = self.compile({
+                    "version": 8,
+                    "mode": "REF2VA",
+                    "shots": [{"duration": 5, "visual_action": "A subject walks."}],
+                    "references": [{"type": "picture", "role": removed_role}],
+                })
+                self.assertEqual(result["project"]["references"][0]["role"], "subject_identity")
+                self.assertEqual(result["project"]["references"][0]["strength"], "weak")
+                self.assertIn("retention_output_marker: weak_reference", result["draft_video_prompt"])
+                self.assertFalse(any("role=" in warning for warning in result["warnings"]))
+
+    def test_frontend_picture_role_list_contains_only_supported_choices(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertIn('data-ref-type="picture" type="button">+ Image</button>', source)
+        self.assertIn('data-ref-type="audio" type="button">+ Audio</button>', source)
+        self.assertIn('data-ref-type="video" type="button">+ Video</button>', source)
+        self.assertNotIn('data-el="new-ref-type"', source)
+        self.assertNotIn('>+ Reference</button>', source)
+        self.assertIn(
+            'picture: ["first_frame", "last_frame", "subject_identity"]', source,
+        )
+        self.assertNotIn('reference: "Reference (weak)"', source)
+        self.assertIn('const SUBJECT_STRENGTHS = ["weak", "normal", "strong"]', source)
+        self.assertIn('first_frame: "First frame"', source)
+        self.assertIn('last_frame: "Last frame"', source)
+        self.assertNotIn('first_frame: "First frame anchor"', source)
+        self.assertNotIn('last_frame: "Last frame anchor"', source)
+        self.assertIn('strength.className = "subject-strength"', source)
+        self.assertIn('strengthRow.className = "mmh3p-subject-strength-row"', source)
+        self.assertIn('strengthRow.append(strengthLabel, strength, alias)', source)
+        self.assertIn('body.append(strengthRow)', source)
+        self.assertIn('if (ref.type === "video") controls.append(role, alias, del)', source)
+        self.assertIn('else if (ref.type === "audio") controls.append(role, alias, del)', source)
+        self.assertIn('full_signal_copy: "Full audio reuse"', source)
+        self.assertIn('voice_delivery: "Voice / delivery"', source)
+        self.assertIn('controls.classList.add("video-metadata")', source)
+        self.assertNotIn('duration.placeholder = "seconds"', source)
+        self.assertIn('ref.duration = actualDuration > 0 ? Math.min(15, actualDuration) : 0', source)
+        self.assertIn('const VIDEO_UPLOAD_ENDPOINT = "/toyxyz/minimax_h3_prompter/upload-video"', source)
+        self.assertIn('const VIDEO_VIEW_ENDPOINT = "/toyxyz/minimax_h3_prompter/video"', source)
+        self.assertIn("const VIDEO_UPLOAD_CHUNK_BYTES = 4 * 1024 * 1024", source)
+        self.assertIn('ref.type === "video" && ref.video_filename && Number(ref.duration) > 0', source)
+        self.assertIn('if (file) await this.uploadReferenceVideo(ref, file)', source)
+        self.assertIn('if (file) await this.uploadReferenceAudio(ref, file)', source)
+        self.assertIn('async uploadReferenceAudio(ref, file)', source)
+        self.assertIn('audio_filename: String(ref?.audio_filename || "")', source)
+        self.assertIn('body: file.slice(start, end)', source)
+        self.assertIn('"Content-Type": "application/octet-stream"', source)
+        self.assertIn('else controls.append(role, del)', source)
+        self.assertNotIn('controls.append(role, strength, alias, del)', source)
+        self.assertIn(
+            'video: ["none", "video_editing", "video_continuation", "motion", "camera", "cuts_rhythm"]',
+            source,
+        )
+        self.assertIn('"none", "full_signal_copy", "partial_signal_copy", "voice_delivery"', source)
+        self.assertIn('const REFERENCE_TYPE_LABELS = { picture: "Image", video: "Video", audio: "Audio" }', source)
+        self.assertIn('const label = `<${REFERENCE_TYPE_LABELS[ref.type]} ${counts[ref.type]}>`', source)
+        self.assertNotIn('<option value="picture">Picture</option>', source)
+        self.assertIn('const role = document.createElement("select")', source)
+        self.assertIn('none: "None"', source)
+        self.assertIn('video_editing: "Video editing"', source)
+        self.assertIn('video_continuation: "Video continuation"', source)
+        self.assertIn('motion: "Motion / action timing"', source)
+        self.assertIn('camera: "Camera movement"', source)
+        self.assertIn('cuts_rhythm: "Cuts / rhythm / temporal structure"', source)
+        self.assertNotIn('voice_timbre: "Voice timbre"', source)
+        self.assertNotIn('full_signal_copy: "Full signal copy"', source)
+        self.assertIn('alias.placeholder = "alias"', source)
+        self.assertNotIn('alias.placeholder = "@alias"', source)
+        self.assertIn('event.key === "ArrowDown" || event.key === "ArrowUp"', source)
+        self.assertIn('event.key === "Enter" || event.key === "Tab"', source)
+        self.assertIn('button.classList.toggle("active", active)', source)
+        self.assertIn('this.insertMention(entry.alias, mention)', source)
+        self.assertIn('commit(refresh = true) {', source)
+        self.assertNotIn('invalidateEnhancement', source)
+        self.assertNotIn('this.project.enhanced_prompt = ""', source)
+        self.assertNotIn('data-action="copy-raw"', source)
+        self.assertNotIn("copyRawPrompt()", source)
+        self.assertNotIn('environment: "Environment"', source)
+        self.assertNotIn('style: "Visual style"', source)
+        self.assertNotIn('storyboard: "Storyboard"', source)
+
+    def test_legacy_audio_roles_migrate_to_audio_presets(self):
+        expected = {
+            "reference": "none",
+            "voice_timbre": "voice_delivery",
+            "dialogue": "dialogue_lyrics",
+            "music_style": "music_rhythm",
+            "sound_effect": "sound_ambience",
+            "partial_signal_copy": "partial_signal_copy",
+            "full_signal_copy": "full_signal_copy",
+        }
+        for legacy_role, normalized_role in expected.items():
+            with self.subTest(role=legacy_role):
+                result = self.compile({
+                    "version": 10,
+                    "mode": "REF2VA",
+                    "shots": [{"duration": 5, "visual_action": "A person walks."}],
+                    "references": [{
+                        "type": "audio", "role": legacy_role,
+                        "description": "Use the supplied audio according to this description.",
+                    }],
+                })
+                self.assertEqual(result["project"]["references"][0]["role"], normalized_role)
+                self.assertIn(f"role: {normalized_role}", result["draft_video_prompt"])
+
+    def test_video_reference_presets_are_normalized_and_compiled(self):
+        expected = {
+            "reference": ("none", "reference generation"),
+            "motion": ("motion", "subject motion, action sequence, movement timing"),
+            "camera": ("camera", "camera movement, viewpoint, framing progression"),
+            "pacing": ("cuts_rhythm", "cut placement, pacing, rhythm, and temporal structure"),
+            "continuation": ("video_continuation", "video continuation"),
+            "video_editing": ("video_editing", "video editing"),
+        }
+        for supplied_role, (normalized_role, expected_text) in expected.items():
+            with self.subTest(role=supplied_role):
+                result = self.compile({
+                    "version": MODULE.CURRENT_PROJECT_VERSION,
+                    "mode": "REF2VA",
+                    "shots": [{"duration": 5, "visual_action": "A person walks."}],
+                    "references": [{
+                        "type": "video", "role": supplied_role, "duration": 5,
+                        "description": "Use its temporal structure as described here.",
+                    }],
+                })
+                self.assertEqual(result["project"]["references"][0]["role"], normalized_role)
+                self.assertIn(f"role: {normalized_role}", result["draft_video_prompt"])
+                self.assertIn(expected_text, result["draft_video_prompt"])
+
+    def test_picture_analysis_metadata_never_enters_raw_prompt(self):
+        stale_analysis = "A very long automatic image analysis that must remain private."
+        result = self.compile({
+            "version": 7,
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero walks through a hotel corridor."}],
+            "references": [{
+                "id": "hero-ref", "type": "picture", "role": "reference", "alias": "hero",
+                "description": stale_analysis, "image_filename": "hero.png",
+            }],
+        })
+        self.assertEqual(result["project"]["references"][0]["description"], "")
+        self.assertNotIn(stale_analysis, result["draft_video_prompt"])
+        self.assertIn("<Subject 1>\nsource: <Picture 1>", result["draft_video_prompt"])
+        self.assertFalse(any("Project version 7" in warning for warning in result["warnings"]))
+
+    def test_raw_prompt_uses_qwen_data_contract_for_every_mode(self):
+        cases = {
+            "T2VA": [],
+            "I2VA": [{"type": "picture", "role": "first_frame", "image_filename": "first.png"}],
+            "FL2VA": [
+                {"type": "picture", "role": "first_frame", "image_filename": "first.png"},
+                {"type": "picture", "role": "last_frame", "image_filename": "last.png"},
+            ],
+            "L2VA": [{"type": "picture", "role": "last_frame", "image_filename": "last.png"}],
+            "REF2VA": [{
+                "type": "picture", "role": "subject_identity", "alias": "hero",
+                "image_filename": "hero.png",
+            }],
+        }
+        for mode, references in cases.items():
+            with self.subTest(mode=mode):
+                action = "@hero walks." if mode == "REF2VA" else "The subject walks."
+                result = self.compile({
+                    "mode": mode,
+                    "shots": [{"duration": 5, "visual_action": action}],
+                    "references": references,
+                })
+                prompt = result["draft_video_prompt"]
+                self.assertTrue(prompt.startswith("INPUT DATA ONLY"))
+                self.assertIn(f"mode: {mode}", prompt)
+                self.assertIn("requested_duration_seconds: 5.00", prompt)
+                self.assertIn("effective_duration_seconds: 5.17", prompt)
+                self.assertIn("SHOT_PLAN:\n[Shot 1]", prompt)
+                self.assertIn("STYLE_POLICY:", prompt)
+                self.assertIn("when_unspecified: omit any target-wide style", prompt)
+                self.assertIn("AUDIO_POLICY:", prompt)
+                self.assertIn("source: infer audio intent only", prompt)
+                self.assertNotIn("AUDIO_INPUTS:", prompt)
+                self.assertNotIn("integrated_multimodal_description:", prompt)
+                self.assertNotIn("subject_definitions:", prompt)
+        ref_prompt = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero walks."}],
+            "references": [{
+                "type": "picture", "role": "subject_identity", "alias": "hero",
+                "image_filename": "hero.png",
+            }],
+        })["draft_video_prompt"]
+        self.assertIn("<Subject 1>\nsource: <Picture 1>", ref_prompt)
+        self.assertIn("retention_output_marker: fully_preserved", ref_prompt)
+        self.assertIn("visual_action: <Subject 1> walks.", ref_prompt)
+
+    def test_keyframe_raw_plans_preserve_reference_style_by_mode(self):
+        cases = {
+            "I2VA": ([{"type": "picture", "role": "first_frame"}], "exact opening-frame anchor"),
+            "FL2VA": ([
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ], "endpoint evidence"),
+            "L2VA": ([{"type": "picture", "role": "last_frame"}], "exact final-frame anchor"),
+        }
+        for mode, (references, phrase) in cases.items():
+            with self.subTest(mode=mode):
+                prompt = self.compile({
+                    "mode": mode,
+                    "shots": [{"duration": 5, "visual_action": "The subject moves."}],
+                    "references": references,
+                })["draft_video_prompt"]
+                self.assertIn(phrase, prompt)
+
+    def test_frontend_does_not_persist_reference_analysis_results(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertNotIn("ref.description = item.analysis", source)
+        self.assertIn('description: type === "picture" ? ""', source)
+
+    def test_system_prompt_forbids_unrequested_video_style_in_every_mode(self):
+        for mode in ("T2VA", "I2VA", "FL2VA", "L2VA", "REF2VA"):
+            with self.subTest(mode=mode):
+                prompt = MODULE.MODE_LLM_SYSTEM_PROMPTS[mode]
+                self.assertIn("Use a target-wide style only when the user explicitly requests it", prompt)
+                self.assertIn("When no target style or keyframe style applies", prompt)
+        for mode in ("I2VA", "FL2VA", "L2VA"):
+            with self.subTest(keyframe_style_mode=mode):
+                self.assertIn("observable visual medium", MODULE.MODE_LLM_SYSTEM_PROMPTS[mode])
+        self.assertIn("Weak and Normal do not transfer source style", MODULE.MODE_LLM_SYSTEM_PROMPTS["REF2VA"])
+        self.assertIn(
+            "begin detailed_description directly with [Shot 1]",
+            MODULE.MODE_LLM_SYSTEM_PROMPTS["REF2VA"],
+        )
+        self.assertIn(
+            "Picture 1 is the complete literal frame at 0.00 seconds",
+            MODULE.MODE_LLM_SYSTEM_PROMPTS["I2VA"],
+        )
+
+    def test_system_prompts_are_loaded_from_json_config(self):
+        config_path = MODULE_PATH.parent / "minimax_h3_system_prompts.json"
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+        self.assertEqual(config, MODULE.SYSTEM_PROMPT_CONFIG)
+        self.assertEqual(
+            set(config["modes"]),
+            {"T2VA", "I2VA", "FL2VA", "L2VA", "REF2VA"},
+        )
+        for mode, mode_rules in config["modes"].items():
+            expected = config["common"]
+            expected += config["action_semantics"]
+            expected += config["static_asset_rules"]["common"]
+            expected += config["common_addendum"]
+            if mode != "REF2VA":
+                expected += config["base"]
+            expected += mode_rules
+            expected += config["mode_addenda"].get(mode, "")
+            if mode == "FL2VA":
+                expected += config["static_asset_rules"]["FL2VA"]
+            self.assertEqual(MODULE.MODE_LLM_SYSTEM_PROMPTS[mode], expected)
+            enhanced_expected = config["common_enhanced"]
+            enhanced_expected += config["action_semantics"]
+            enhanced_expected += config["static_asset_rules"]["common"]
+            enhanced_expected += config["static_asset_rules"]["enhanced"]
+            enhanced_expected += config["common_addendum"]
+            if mode != "REF2VA":
+                enhanced_expected += config["base"]
+            enhanced_expected += mode_rules
+            enhanced_expected += config["mode_addenda"].get(mode, "")
+            if mode == "FL2VA":
+                enhanced_expected += config["static_asset_rules"]["FL2VA"]
+                enhanced_expected += config["static_asset_rules"]["FL2VA_enhanced"]
+            enhanced_expected += config["enhance_addendum"]
+            self.assertEqual(MODULE.ENHANCED_MODE_LLM_SYSTEM_PROMPTS[mode], enhanced_expected)
+
+    def test_static_character_motion_rules_cover_standard_and_enhanced_fl2va(self):
+        standard = MODULE.MODE_LLM_SYSTEM_PROMPTS["FL2VA"]
+        enhanced = MODULE.ENHANCED_MODE_LLM_SYSTEM_PROMPTS["FL2VA"]
+        self.assertIn("reference pose is fixed only at its assigned anchor time", standard)
+        self.assertIn("appearance-only morph", standard)
+        self.assertIn("visible joint-driven departure from Picture 1", enhanced)
+        self.assertIn("Drive hair, clothing, ribbons", enhanced)
+
+    def test_explicit_target_style_and_repeated_action_semantics_are_locked(self):
+        for prompt in (
+            MODULE.MODE_LLM_SYSTEM_PROMPTS["I2VA"],
+            MODULE.ENHANCED_MODE_LLM_SYSTEM_PROMPTS["I2VA"],
+        ):
+            self.assertIn("3D animation overrides a photographed collectible presentation", prompt)
+            self.assertIn("Obey TARGET_STYLE_LOCK", prompt)
+            self.assertIn("weaken a repeated action into one contact or static hold", prompt)
+            self.assertIn("insert unsupported clothing over the named contact target", prompt)
+
+    def test_system_prompt_lengths_stay_qwen38_friendly(self):
+        self.assertLessEqual(len(MODULE.COMMON_LLM_SYSTEM_RULES), 6000)
+        for mode, prompt in MODULE.MODE_LLM_SYSTEM_PROMPTS.items():
+            with self.subTest(mode=mode):
+                self.assertLessEqual(len(prompt), 8800)
+                lock = MODULE._single_pass_output_lock(
+                    mode, 5.17, 2, [1, 2],
+                    {"label_plan": {"<Subject 1>": {}}} if mode == "REF2VA" else None,
+                    [],
+                )
+                combined = len(MODULE._mode_prompt_preamble(mode)) + len(prompt) + len(lock) + 4
+                self.assertLessEqual(combined, 10100)
+        for mode, prompt in MODULE.ENHANCED_MODE_LLM_SYSTEM_PROMPTS.items():
+            with self.subTest(enhanced_mode=mode):
+                self.assertLessEqual(len(prompt), 10200)
+
+    def test_ref2va_prompt_rejects_literal_retention_placeholder(self):
+        prompt = MODULE.MODE_LLM_SYSTEM_PROMPTS["REF2VA"]
+        self.assertNotIn("fixed_marker", prompt)
+        self.assertIn("with its applicable shots, then exactly its locked output marker", prompt)
+        self.assertIn("Never print the UI strength words weak, normal, or strong", prompt)
+        self.assertIn("never print an equals sign", prompt)
+
+    def test_base_modes_forbid_ref2va_subject_labels(self):
+        for mode in ("T2VA", "I2VA", "FL2VA", "L2VA"):
+            with self.subTest(mode=mode):
+                prompt = MODULE.MODE_LLM_SYSTEM_PROMPTS[mode]
+                self.assertIn("Base modes never define or use <Subject N>", prompt)
+                self.assertIn("the girl (S1)", prompt)
+
+    def test_ref2va_system_prompt_has_compact_compliance_contract(self):
+        prompt = MODULE.MODE_LLM_SYSTEM_PROMPTS["REF2VA"]
+        self.assertIn("Define each image-derived Subject in one line", prompt)
+        self.assertIn("derived from <Picture N>", prompt)
+        self.assertIn("Begin summary with one bracketed list", prompt)
+        self.assertIn("free of shot labels", prompt)
+        self.assertIn("do not announce the same speech twice", prompt)
+
+    def test_node_exposes_generated_prompt_length_and_ordered_picture_outputs(self):
+        self.assertEqual(
+            MODULE.MinimaxH3Prompter.RETURN_NAMES,
+            ("generated_prompt", "length")
+            + tuple(f"image_{index}" for index in range(1, 10))
+            + tuple(f"video_{index}" for index in range(1, 4))
+            + tuple(f"audio_{index}" for index in range(1, 4)),
+        )
+        self.assertEqual(MODULE.MinimaxH3Prompter.RETURN_TYPES[:2], ("STRING", "INT"))
+        self.assertEqual(len(MODULE.MinimaxH3Prompter.RETURN_TYPES), 17)
+
+    def test_node_first_output_is_only_the_saved_enhanced_prompt(self):
+        node = MODULE.MinimaxH3Prompter()
+        project = {
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A woman opens a door."}],
+            "enhanced_prompt": "enhanced result only",
+        }
+        outputs = node.compile(json.dumps(project))
+        self.assertEqual(outputs[0], "enhanced result only")
+        self.assertIsInstance(outputs[1], int)
+        self.assertEqual(len(outputs), 17)
+        self.assertEqual(tuple(outputs[2].shape), (1, 64, 64, 3))
+        node = MODULE.MinimaxH3Prompter()
+        output = node.compile(json.dumps({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A static establishing shot"}],
+        }))
+        self.assertEqual(len(output), 17)
+        self.assertEqual(output[0], "")
+        self.assertIsInstance(output[1], int)
+
+    def test_auto_run_is_disabled_by_default(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A person walks."}],
+        })
+        self.assertFalse(result["project"]["auto_run"])
+
+    def test_auto_run_executes_enhancement_inside_node_compile(self):
+        project = {
+            "mode": "T2VA",
+            "auto_run": True,
+            "shots": [{"duration": 5, "visual_action": "A person walks."}],
+            "enhanced_prompt": "stale saved prompt",
+        }
+        node = MODULE.MinimaxH3Prompter()
+        with (
+            mock.patch.object(
+                MODULE, "enhance_project",
+                return_value={"enhanced_prompt": "queue enhanced prompt"},
+            ) as enhance,
+            mock.patch.object(MODULE, "_reference_media_outputs", return_value=()),
+        ):
+            outputs = node.compile(json.dumps(project))
+        self.assertEqual(outputs["result"][0], "queue enhanced prompt")
+        self.assertEqual(outputs["ui"]["auto_run_prompt"], ["queue enhanced prompt"])
+        enhance.assert_called_once()
+
+    def test_auto_run_ui_is_queue_integrated_not_browser_triggered(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertIn('data-el="auto-run"', source)
+        self.assertIn('this.project.auto_run = this.els["auto-run"].checked', source)
+        self.assertIn('showAutoRunPrompt(message?.auto_run_prompt)', source)
+        self.assertNotIn(
+            'this.els["auto-run"].addEventListener("change", () => this.enhancePrompt()',
+            source,
+        )
+
+    def test_enhance_toggle_is_left_of_generate_and_qwen_only(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        toggle_index = source.index('data-el="enhance"')
+        generate_index = source.index('data-action="enhance"')
+        self.assertLess(toggle_index, generate_index)
+        self.assertIn('this.project.enhance = this.els.enhance.checked', source)
+        self.assertIn('Enhance mode is available only with Qwen3.8', source)
+
+    def test_picture_outputs_follow_picture_reference_order(self):
+        first = object()
+        second = object()
+        loaded = []
+
+        def fake_load(reference):
+            loaded.append(reference["image_filename"])
+            return first if len(loaded) == 1 else second
+
+        project = {
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "Two subjects walk."}],
+            "references": [
+                {"type": "picture", "role": "subject_identity", "image_filename": "first.png"},
+                {"type": "audio", "role": "sound_effect", "description": "Footsteps"},
+                {"type": "picture", "role": "subject_identity", "image_filename": "second.png"},
+            ],
+        }
+        with mock.patch.object(MODULE, "_load_reference_image_tensor", side_effect=fake_load):
+            outputs = MODULE.MinimaxH3Prompter().compile(json.dumps(project))
+        self.assertEqual(loaded, ["first.png", "second.png"])
+        self.assertIs(outputs[2], first)
+        self.assertIs(outputs[3], second)
+
+    def test_frontend_shows_one_image_slot_per_picture_reference(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertIn("syncReferenceOutputs()", source)
+        self.assertIn('this.project.references.filter(ref => ref.type === "picture").length', source)
+        self.assertIn('this.project.references.filter(ref => ref.type === "video").length', source)
+        self.assertIn('this.project.references.filter(ref => ref.type === "audio").length', source)
+        self.assertIn('this.node.addOutput(`image_${mediaIndex + 1}`, "IMAGE")', source)
+        self.assertIn('this.node.addOutput(`video_${mediaIndex - pictureCount + 1}`, "VIDEO")', source)
+        self.assertIn('this.node.addOutput(`audio_${mediaIndex - pictureCount - videoCount + 1}`, "AUDIO")', source)
+        self.assertIn("this.node.removeOutput(this.node.outputs.length - 1)", source)
+
+    def test_llm_prompt_uses_mode_specific_english_system_prompt(self):
+        expected_phrases = {
+            "T2VA": "MODE: T2VA",
+            "I2VA": "MODE: I2VA",
+            "FL2VA": "MODE: FL2VA",
+            "L2VA": "MODE: L2VA",
+            "REF2VA": "MODE: REF2VA",
+        }
+        references = {
+            "T2VA": [],
+            "I2VA": [{"type": "picture", "role": "first_frame"}],
+            "FL2VA": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+            "L2VA": [{"type": "picture", "role": "last_frame"}],
+            "REF2VA": [{"type": "picture", "role": "subject_identity", "alias": "hero"}],
+        }
+        for mode, phrase in expected_phrases.items():
+            with self.subTest(mode=mode):
+                result = self.compile({
+                    "mode": mode,
+                    "shots": [{"duration": 5, "visual_action": "A person walks forward."}],
+                    "references": references[mode],
+                })
+                self.assertIn(phrase, result["llm_prompt"])
+                self.assertTrue(result["llm_prompt"].endswith(result["video_prompt"]))
+                self.assertIn("PRIORITY\n1. Explicit user actions", result["llm_prompt"])
+                self.assertIn("Minimal detail needed to make the request renderable", result["llm_prompt"])
+                self.assertIn("When rules conflict, the higher priority wins", result["llm_prompt"])
+
+    def test_llm_system_prompt_requires_sentence_level_enrichment(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A woman opens a door."}],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("concise chronological action", llm_prompt)
+        self.assertIn("show only the intermediate motion needed to make it physically legible", llm_prompt)
+
+    def test_fl2va_system_prompt_prioritizes_endpoints_over_appearance_reconstruction(self):
+        result = self.compile({
+            "mode": "FL2VA",
+            "shots": [{"duration": 5, "visual_action": "The character transforms continuously."}],
+            "references": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("Picture 1 is the complete opening frame", llm_prompt)
+        self.assertIn("Treat both images as visual anchors rather than appearance inventories", llm_prompt)
+        self.assertIn("never invent a full rotation, orbit, dramatic performance", llm_prompt)
+        self.assertIn("usually 80-150 English words", llm_prompt)
+        self.assertIn("Picture 2 is the complete frame reached only at the effective end", llm_prompt)
+        self.assertIn("Do not keep a Picture 1-only entity visibly present", llm_prompt)
+        self.assertIn("Use no <Subject N> labels", llm_prompt)
+        self.assertIn("Picture 2 is reached only at the effective end time", llm_prompt)
+        self.assertIn("Never reveal the completed Picture 2 at the start of the final shot", llm_prompt)
+        self.assertIn("A hit, fall, entrance, exit, or cut never authorizes trait transfer", llm_prompt)
+        self.assertIn("put a visible identity before every speaker ID", llm_prompt)
+        self.assertIn("Begin each later shot naturally as [Shot N] At MM:SS.mmm,", llm_prompt)
+        self.assertIn("Never morph one character into another", llm_prompt)
+        self.assertIn("Bind Picture 2 traits only to the entity", llm_prompt)
+        self.assertIn("Preserve every explicit SHOT_PLAN action in order; omit none", llm_prompt)
+        self.assertIn("overall_soundscape must not repeat or summarize speech", llm_prompt)
+
+    def test_fl2va_raw_plan_locks_picture_two_to_the_final_instant(self):
+        result = self.compile({
+            "mode": "FL2VA",
+            "shots": [
+                {"duration": 2.5, "visual_action": "The first character speaks."},
+                {"duration": 2.5, "visual_action": "The second character enters."},
+            ],
+            "references": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+        })
+        raw = result["draft_video_prompt"]
+        self.assertIn("ENDPOINT_CONTRACT:", raw)
+        self.assertIn("Picture 2 is not the opening state of the final shot", raw)
+        self.assertIn("Do not merge identities or transfer clothing", raw)
+        self.assertIn("Punch, hit, fall, enter, exit, and cut are not transformation requests", raw)
+        self.assertIn("entity_binding: the entity visible in Picture 1 owns only Picture 1 traits", raw)
+        self.assertIn("If the final shot introduces an entity matching Picture 2", raw)
+        self.assertIn("opening_state: continue the incomplete transition", raw)
+        self.assertIn("entity_continuity: an entering entity that matches Picture 2 is the same final-frame entity", raw)
+        self.assertIn("required_end_state: exact whole-frame match to Picture 2 at 5.17 seconds", raw)
+        self.assertEqual(raw.count("action_contract: preserve every explicit action above in the same order; omit none"), 2)
+        self.assertIn("required_output_header: [Shot 2] At 00:02.583,", raw)
+
+    def test_saved_enhancement_becomes_video_prompt_without_rewriting_llm_input(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "A woman opens a door."}],
+            "enhanced_prompt": "integrated_multimodal_description: enhanced result",
+        })
+        self.assertEqual(result["video_prompt"], "integrated_multimodal_description: enhanced result")
+        self.assertNotEqual(result["draft_video_prompt"], result["video_prompt"])
+        self.assertTrue(result["llm_prompt"].endswith(result["draft_video_prompt"]))
+
+    def test_enhance_model_list_exposes_qwen38_and_lightx2v(self):
+        with tempfile.TemporaryDirectory() as root:
+            for name in ("writer.gguf", "adapter-LoRA.gguf", "model-mmproj.gguf", "draft.gguf"):
+                Path(root, name).write_bytes(b"x")
+            models = MODULE.list_enhance_models([root])
+        self.assertEqual(len(models), 2)
+        self.assertEqual(models[0]["id"], MODULE.DEFAULT_ENHANCE_MODEL_ID)
+        self.assertEqual(models[1]["id"], MODULE.LIGHTX2V_MODEL_ID)
+
+    def test_model_bundle_list_exposes_qwen_and_lightx2v(self):
+        with tempfile.TemporaryDirectory() as root:
+            Path(root, MODULE.DEFAULT_ENHANCE_MODEL_FILE).write_bytes(b"qwen")
+            Path(root, MODULE.QWEN_IMAGE_MMPROJ_FILE).write_bytes(b"qwen-projector")
+            models = MODULE.list_image_models([root])
+        self.assertEqual(len(models), 2)
+        self.assertEqual(models[0]["id"], MODULE.DEFAULT_IMAGE_MODEL_ID)
+        self.assertTrue(models[0]["label"].startswith("JonathanColetti/Qwen3.8-27B-Uncensored-GGUF · Q4_K_M + Vision F16"))
+        self.assertTrue(models[0]["label"].endswith("VRAM ≈ 20–22 GB"))
+        self.assertTrue(models[0]["installed"])
+        self.assertFalse(models[1]["installed"])
+        self.assertEqual(models[1]["supported_modes"], ["T2VA", "I2VA", "FL2VA", "L2VA"])
+        self.assertIn("R2V unsupported", models[1]["label"])
+        self.assertIn("Q8_0 + Vision F16", models[1]["label"])
+        self.assertEqual(models[1]["runtime"], "llama.cpp-gguf")
+
+    def test_normalize_project_preserves_supported_image_model_selection(self):
+        project, _warnings = MODULE.normalize_project({"image_model": MODULE.QWEN_IMAGE_MODEL_ID})
+        self.assertEqual(project["image_model"], MODULE.QWEN_IMAGE_MODEL_ID)
+
+    def test_normalize_project_preserves_lightx2v_selection(self):
+        project, _warnings = MODULE.normalize_project({
+            "enhance_model": MODULE.LIGHTX2V_MODEL_ID,
+            "image_model": MODULE.LIGHTX2V_MODEL_ID,
+        })
+        self.assertEqual(project["enhance_model"], MODULE.LIGHTX2V_MODEL_ID)
+        self.assertEqual(project["image_model"], MODULE.LIGHTX2V_MODEL_ID)
+
+    def test_normalize_project_migrates_legacy_lightx2v_selection(self):
+        project, _warnings = MODULE.normalize_project({
+            "enhance_model": MODULE.LEGACY_LIGHTX2V_MODEL_ID,
+            "image_model": MODULE.LEGACY_LIGHTX2V_MODEL_ID,
+        })
+        self.assertEqual(project["enhance_model"], MODULE.LIGHTX2V_MODEL_ID)
+        self.assertEqual(project["image_model"], MODULE.LIGHTX2V_MODEL_ID)
+
+    def test_lightx2v_messages_preserve_direct_image_order(self):
+        with tempfile.TemporaryDirectory() as root:
+            first = Path(root, "first.png")
+            last = Path(root, "last.png")
+            first.write_bytes(b"first")
+            last.write_bytes(b"last")
+            messages = MODULE._lightx2v_messages(
+                "Two states connect.", "fl2av", "adaptive", 5,
+                [str(first), str(last)],
+            )
+        user_content = messages[1]["content"]
+        images = [item["image_url"]["url"] for item in user_content if item["type"] == "image_url"]
+        self.assertEqual(len(images), 2)
+        self.assertIn("Zmlyc3Q=", images[0])
+        self.assertIn("bGFzdA==", images[1])
+        self.assertIn("task: fl2av", user_content[-1]["text"])
+
+    def test_lightx2v_rejects_ref2va_before_model_download(self):
+        with self.assertRaisesRegex(ValueError, "does not support R2V/REF2VA"):
+            MODULE.enhance_project({
+                "mode": "REF2VA",
+                "shots": [{"duration": 5, "visual_action": "@hero walks."}],
+                "references": [{
+                    "type": "picture", "role": "subject_identity", "alias": "hero",
+                    "strength": "normal",
+                }],
+            }, MODULE.LIGHTX2V_MODEL_ID, MODULE.LIGHTX2V_MODEL_ID)
+
+    def test_qwen_vision_bundle_reuses_writer_model(self):
+        with tempfile.TemporaryDirectory() as root:
+            model = Path(root, MODULE.DEFAULT_ENHANCE_MODEL_FILE)
+            projector = Path(root, MODULE.QWEN_IMAGE_MMPROJ_FILE)
+            model.write_bytes(b"qwen")
+            projector.write_bytes(b"vision")
+            with mock.patch.object(MODULE, "_llm_roots", return_value=[root]):
+                resolved = MODULE._resolve_image_model(MODULE.QWEN_IMAGE_MODEL_ID)
+        self.assertEqual(resolved, (str(model.resolve()), str(projector.resolve())))
+
+    def test_qwen_download_progress_counts_only_missing_projector(self):
+        with tempfile.TemporaryDirectory() as root:
+            model = Path(root, MODULE.DEFAULT_ENHANCE_MODEL_FILE)
+            model.write_bytes(b"qwen")
+            downloaded = Path(root, MODULE.QWEN_IMAGE_MMPROJ_FILE)
+            calls = []
+
+            def fake_download(repo, filename, local_dir, component_size, completed_size, bundle_size, progress):
+                calls.append((filename, completed_size, bundle_size))
+                downloaded.write_bytes(b"vision")
+                return str(downloaded)
+
+            with (
+                mock.patch.dict(sys.modules, {"huggingface_hub": SimpleNamespace()}),
+                mock.patch.object(MODULE, "_llm_roots", return_value=[root]),
+                mock.patch.object(MODULE, "_download_image_component", side_effect=fake_download),
+            ):
+                MODULE._resolve_image_model(MODULE.QWEN_IMAGE_MODEL_ID)
+        self.assertEqual(calls, [(
+            MODULE.QWEN_IMAGE_MMPROJ_FILE, 0, MODULE.QWEN_IMAGE_MMPROJ_SIZE,
+        )])
+
+    def test_lightx2v_download_reports_live_bytes_and_explicit_completion(self):
+        with tempfile.TemporaryDirectory() as root:
+            events = []
+
+            def fake_download(repo, filename, local_dir, component_size,
+                              completed_size, bundle_size, progress):
+                self.assertEqual(repo, MODULE.LIGHTX2V_MODEL_REPO)
+                if progress:
+                    progress(
+                        stage="downloading", message=f"Downloading {filename}",
+                        downloaded=completed_size + component_size // 2, total=bundle_size,
+                    )
+                path = Path(local_dir, filename)
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_bytes(b"gguf")
+                return str(path)
+
+            with (
+                mock.patch.object(MODULE, "_llm_roots", return_value=[root]),
+                mock.patch.dict(sys.modules, {"huggingface_hub": SimpleNamespace()}),
+                mock.patch.object(MODULE, "_download_image_component", side_effect=fake_download),
+            ):
+                model_path, mmproj_path = MODULE._resolve_lightx2v_model(
+                    lambda **values: events.append(values)
+                )
+
+        byte_events = [event for event in events if event.get("stage") == "downloading"]
+        self.assertTrue(any(0 < event.get("downloaded", 0) < event.get("total", 0) for event in byte_events))
+        self.assertEqual(byte_events[-1]["downloaded"], byte_events[-1]["total"])
+        self.assertTrue(model_path.endswith(MODULE.LIGHTX2V_MODEL_FILE))
+        self.assertTrue(mmproj_path.endswith(MODULE.LIGHTX2V_MMPROJ_FILE))
+
+    def test_llm_output_cleanup_removes_reasoning_and_fence(self):
+        cleaned = MODULE._clean_llm_output("<think>hidden</think>\n```text\nfinal prompt\n```")
+        self.assertEqual(cleaned, "final prompt")
+
+    def test_llm_output_cleanup_extracts_marked_prompt_from_cli_noise(self):
+        noisy = "Loading model...\nllama.cpp banner\n<H3_PROMPT>\nfinal prompt\n</H3_PROMPT>\nExiting..."
+        self.assertEqual(MODULE._clean_llm_output(noisy), "final prompt")
+
+    def test_llm_output_cleanup_removes_legacy_interactive_cli_noise(self):
+        noisy = "Loading model...\navailable commands:\n\n> echoed input ... (truncated)\nfinal prompt\n\nExiting..."
+        self.assertEqual(MODULE._clean_llm_output(noisy), "final prompt")
+
+    def test_reference_image_metadata_is_preserved(self):
+        result = self.compile({
+            "references": [{
+                "type": "picture", "role": "subject_identity", "image_filename": "person.png",
+                "image_subfolder": "toyxyz_h3_references", "image_type": "input",
+            }],
+        })
+        ref = result["project"]["references"][0]
+        self.assertEqual(ref["image_filename"], "person.png")
+        self.assertEqual(ref["image_subfolder"], "toyxyz_h3_references")
+
+    def test_reference_video_metadata_is_preserved(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "Edit @clip."}],
+            "references": [{
+                "type": "video", "role": "video_editing", "alias": "clip", "duration": 5,
+                "video_filename": "source.mp4", "video_subfolder": "toyxyz_h3_references",
+            }],
+        })
+        ref = result["project"]["references"][0]
+        self.assertEqual(ref["video_filename"], "source.mp4")
+        self.assertEqual(ref["video_subfolder"], "toyxyz_h3_references")
+        self.assertIn("pending duration-limited ordered-frame analysis", result["draft_video_prompt"])
+        self.assertIn("analysis_leading_duration_seconds: 5.00", result["draft_video_prompt"])
+        self.assertNotIn("source_duration_seconds: 5.00", result["draft_video_prompt"])
+
+    def test_reference_audio_upload_metadata_is_preserved(self):
+        result = self.compile({
+            "mode": "REF2VA",
+            "references": [{
+                "type": "audio", "alias": "music",
+                "audio_filename": "source.wav", "audio_subfolder": "toyxyz_h3_references",
+            }],
+        })
+        ref = result["project"]["references"][0]
+        self.assertEqual(ref["audio_filename"], "source.wav")
+        self.assertEqual(ref["audio_subfolder"], "toyxyz_h3_references")
+
+    def test_video_reference_system_prompt_loads_only_selected_preset_modules(self):
+        project, _warnings = MODULE.normalize_project({
+            "mode": "REF2VA",
+            "references": [
+                {"type": "video", "role": "video_editing"},
+                {"type": "video", "role": "camera"},
+            ],
+        })
+        prompt = MODULE._video_reference_system_modules(project)
+        self.assertIn("VIDEO REFERENCE CORE", prompt)
+        self.assertIn("<Video 1>=video_editing", prompt)
+        self.assertIn("<Video 2>=camera", prompt)
+        self.assertIn("VIDEO PRESET: EDITING", prompt)
+        self.assertIn("complete entity replacement", prompt)
+        self.assertIn("every evidenced ACTION_TIMELINE interval", prompt)
+        self.assertIn("VIDEO PRESET: CAMERA", prompt)
+        self.assertNotIn("VIDEO PRESET: CONTINUATION", prompt)
+        self.assertNotIn("VIDEO PRESET: MOTION", prompt)
+
+    def test_audio_reference_system_prompt_loads_only_selected_preset_modules(self):
+        project, _warnings = MODULE.normalize_project({
+            "mode": "REF2VA",
+            "references": [
+                {"type": "audio", "role": "voice_delivery"},
+                {"type": "audio", "role": "music_rhythm"},
+            ],
+        })
+        prompt = MODULE._audio_reference_system_modules(project)
+        self.assertIn("AUDIO REFERENCE CORE", prompt)
+        self.assertIn("<Audio 1>=voice_delivery", prompt)
+        self.assertIn("<Audio 2>=music_rhythm", prompt)
+        self.assertIn("AUDIO PRESET: VOICE AND DELIVERY", prompt)
+        self.assertIn("AUDIO PRESET: MUSIC AND RHYTHM", prompt)
+        self.assertNotIn("AUDIO PRESET: FULL SIGNAL COPY", prompt)
+        self.assertNotIn("AUDIO PRESET: DIALOGUE OR LYRICS REUSE", prompt)
+
+    def test_audio_presets_map_to_locked_retention_and_task_types(self):
+        expected = {
+            "none": ("reference", "audio reference"),
+            "full_signal_copy": ("fully_copy", "audio reuse"),
+            "partial_signal_copy": ("partially_copy", "audio reuse"),
+            "voice_delivery": ("reference", "audio reference"),
+            "dialogue_lyrics": ("partially_copy", "audio reuse"),
+            "sound_ambience": ("reference", "audio reference"),
+            "music_rhythm": ("reference", "audio reference"),
+        }
+        for role, (marker, task_type) in expected.items():
+            with self.subTest(role=role):
+                project, _warnings = MODULE.normalize_project({
+                    "mode": "REF2VA",
+                    "references": [{
+                        "type": "audio", "role": role,
+                        "audio_filename": "source.wav",
+                        "description": "Apply this audio relationship to the target.",
+                    }],
+                })
+                model = MODULE._reference_model(project)
+                self.assertEqual(model["label_plan"]["<Audio 1>"]["marker"], marker)
+                self.assertIn(task_type, model["task_types"])
+
+    def test_signal_reuse_requires_uploaded_audio(self):
+        project, warnings = MODULE.normalize_project({
+            "mode": "REF2VA",
+            "references": [{"type": "audio", "role": "full_signal_copy"}],
+        })
+        errors, _warnings = MODULE.validate_project(project, warnings)
+        self.assertTrue(any("requires an uploaded audio file" in error for error in errors))
+
+    def test_video_analysis_does_not_make_source_appearance_mandatory_edit_continuity(self):
+        prompt = MODULE._video_analysis_prompt("video_editing", 5.0, [0.0, 2.5, 4.95])
+        self.assertIn("Keep source appearance only in SUBJECTS", prompt)
+        self.assertIn("do not mark identity, body appearance, hair, clothing, or accessories", prompt)
+
+    def test_video_analysis_uses_only_requested_leading_duration_and_ordered_frames(self):
+        calls = {}
+
+        class FakeSession:
+            model_path = "qwen.gguf"
+            mmproj_path = "vision.gguf"
+
+            def analyze_images(self, image_paths, captions, prompt):
+                calls["paths"] = list(image_paths)
+                calls["captions"] = list(captions)
+                calls["prompt"] = prompt
+                return "<VIDEO_ANALYSIS>ordered temporal evidence</VIDEO_ANALYSIS>"
+
+        def fake_extract(_video_path, duration, output_dir):
+            calls["duration"] = duration
+            paths = []
+            for index in range(3):
+                path = Path(output_dir, f"frame-{index:03d}.jpg")
+                path.write_bytes(b"jpeg")
+                paths.append(str(path))
+            return paths, [0.0, 1.5, 2.95]
+
+        with (
+            mock.patch.object(MODULE, "_resolve_uploaded_video", return_value="source.mp4"),
+            mock.patch.object(MODULE, "_probe_video_duration", return_value=3.0),
+            mock.patch.object(MODULE, "_extract_video_analysis_frames", side_effect=fake_extract),
+        ):
+            result = MODULE.analyze_reference_video(
+                {"filename": "source.mp4"}, "video_editing", 5.0,
+                session=FakeSession(),
+            )
+        self.assertEqual(calls["duration"], 3.0)
+        self.assertEqual(calls["captions"][0], "Frame 1 at 0.000 seconds.")
+        self.assertEqual(calls["captions"][-1], "Frame 3 at 2.950 seconds.")
+        self.assertIn("chronologically ordered samples from the first 3.000 seconds", calls["prompt"])
+        self.assertIn("scoped edit", calls["prompt"])
+        self.assertEqual(result["analysis"], "ordered temporal evidence")
+        self.assertEqual(result["analyzed_duration"], "3.000")
+        self.assertEqual(result["frame_count"], "3")
+
+    def test_video_output_resamples_to_24fps_and_exact_target_frame_count(self):
+        from fractions import Fraction
+        import torch
+
+        source_video = mock.Mock()
+        trimmed_video = mock.Mock()
+        components = SimpleNamespace(
+            images=torch.arange(155, dtype=torch.float32).reshape(155, 1, 1, 1),
+            audio={
+                "waveform": torch.ones((1, 48000 * 8), dtype=torch.float32),
+                "sample_rate": 48000,
+            },
+            frame_rate=Fraction(30),
+        )
+        trimmed_video.get_components.return_value = components
+        trimmed_video.get_bit_depth.return_value = 10
+        source_video.as_trimmed.return_value = trimmed_video
+        created_video = object()
+        captured = {}
+
+        def create_video(output_components, bit_depth=8):
+            captured["components"] = output_components
+            captured["bit_depth"] = bit_depth
+            return created_video
+
+        with (
+            mock.patch.object(MODULE, "_resolve_uploaded_video", return_value="source.mp4"),
+            mock.patch("comfy_api.latest.InputImpl.VideoFromFile", return_value=source_video) as loader,
+            mock.patch("comfy_api.latest.InputImpl.VideoFromComponents", side_effect=create_video),
+        ):
+            output = MODULE._load_reference_video(
+                {"video_filename": "source.mp4", "video_subfolder": ""},
+                124,
+            )
+        self.assertIs(output, created_video)
+        loader.assert_called_once_with("source.mp4")
+        source_video.as_trimmed.assert_called_once_with(
+            0.0, 124 / MODULE.MODEL_FPS, strict_duration=False,
+        )
+        self.assertEqual(captured["components"].images.shape[0], 124)
+        self.assertEqual(captured["components"].images[-1].item(), 154)
+        self.assertEqual(captured["components"].frame_rate, Fraction(24))
+        self.assertEqual(captured["components"].audio["waveform"].shape[-1], 248000)
+        self.assertEqual(captured["bit_depth"], 10)
+
+    def test_short_video_is_not_padded_to_target_frame_count(self):
+        from fractions import Fraction
+        import torch
+
+        source_video = mock.Mock()
+        trimmed_video = mock.Mock()
+        trimmed_video.get_components.return_value = SimpleNamespace(
+            images=torch.zeros((60, 1, 1, 3), dtype=torch.float32),
+            audio=None,
+            frame_rate=Fraction(30),
+        )
+        trimmed_video.get_bit_depth.return_value = 8
+        source_video.as_trimmed.return_value = trimmed_video
+        captured = {}
+
+        def create_video(output_components, bit_depth=8):
+            captured["components"] = output_components
+            return object()
+
+        with (
+            mock.patch.object(MODULE, "_resolve_uploaded_video", return_value="short.mp4"),
+            mock.patch("comfy_api.latest.InputImpl.VideoFromFile", return_value=source_video),
+            mock.patch("comfy_api.latest.InputImpl.VideoFromComponents", side_effect=create_video),
+        ):
+            MODULE._load_reference_video(
+                {"video_filename": "short.mp4", "video_subfolder": ""}, 124,
+            )
+        self.assertEqual(captured["components"].images.shape[0], 48)
+        self.assertEqual(captured["components"].frame_rate, Fraction(24))
+
+    def test_prompt_generation_job_cancel_sets_event_and_calls_active_stopper(self):
+        job_id = "cancel-test-job"
+        stopped = []
+        event = MODULE._begin_enhance_job(job_id)
+        try:
+            MODULE._set_enhance_stopper(job_id, lambda: stopped.append(True))
+            self.assertTrue(MODULE._cancel_enhance_job(job_id))
+            self.assertTrue(event.is_set())
+            self.assertEqual(stopped, [True])
+            self.assertEqual(MODULE._get_enhance_job(job_id)["stage"], "cancelled")
+        finally:
+            MODULE._finish_enhance_job(job_id)
+
+    def test_audio_output_trims_to_the_same_target_duration(self):
+        import torch
+
+        sample_rate = 48000
+        source = torch.ones((2, sample_rate * 8), dtype=torch.float32)
+        with (
+            mock.patch.object(MODULE, "_resolve_uploaded_audio", return_value="source.wav"),
+            mock.patch("comfy_extras.nodes_audio.load", return_value=(source, sample_rate)),
+        ):
+            output = MODULE._load_reference_audio(
+                {"audio_filename": "source.wav", "audio_subfolder": ""},
+                124 / MODULE.MODEL_FPS,
+            )
+        expected_samples = round((124 / MODULE.MODEL_FPS) * sample_rate)
+        self.assertEqual(output["sample_rate"], sample_rate)
+        self.assertEqual(tuple(output["waveform"].shape), (1, 2, expected_samples))
+
+    def test_short_audio_is_not_padded_past_its_available_samples(self):
+        import torch
+
+        sample_rate = 44100
+        source = torch.ones((1, sample_rate * 2), dtype=torch.float32)
+        with (
+            mock.patch.object(MODULE, "_resolve_uploaded_audio", return_value="short.wav"),
+            mock.patch("comfy_extras.nodes_audio.load", return_value=(source, sample_rate)),
+        ):
+            output = MODULE._load_reference_audio(
+                {"audio_filename": "short.wav", "audio_subfolder": ""},
+                124 / MODULE.MODEL_FPS,
+            )
+        self.assertEqual(output["waveform"].shape[-1], sample_rate * 2)
+
+    def test_reference_analysis_cleanup_extracts_only_marked_text(self):
+        noisy = "Loading model...\n<REFERENCE_ANALYSIS>observable English details</REFERENCE_ANALYSIS>\nExiting..."
+        self.assertEqual(MODULE._clean_reference_analysis(noisy), "observable English details")
+
+    def test_reference_analysis_cleanup_accepts_missing_closing_marker(self):
+        noisy = "Loading model...\ncommands...\n<REFERENCE_ANALYSIS>\nobservable English details"
+        self.assertEqual(MODULE._clean_reference_analysis(noisy), "observable English details")
+
+    def test_webp_reference_is_temporarily_converted_for_vision_backend(self):
+        from PIL import Image
+
+        with tempfile.TemporaryDirectory() as root:
+            source = Path(root, "reference.webp")
+            Image.new("RGB", (8, 6), (240, 120, 30)).save(source, format="WEBP")
+            with MODULE._vision_compatible_image(str(source)) as converted:
+                converted_path = Path(converted)
+                self.assertNotEqual(converted_path, source)
+                self.assertEqual(converted_path.suffix.lower(), ".png")
+                self.assertTrue(converted_path.is_file())
+                with Image.open(converted_path) as prepared:
+                    self.assertEqual(prepared.size, (8, 6))
+            self.assertFalse(converted_path.exists())
+            self.assertTrue(source.exists())
+
+    def test_reference_analysis_requires_visual_medium_and_rendering_style_for_every_role(self):
+        for role in ("reference", "subject_identity", "first_frame", "last_frame"):
+            with self.subTest(role=role):
+                prompt = MODULE._reference_analysis_prompt(role)
+                self.assertIn("VISUAL_MEDIUM:", prompt)
+                self.assertIn("exactly the eight labeled lines", prompt)
+                self.assertIn("2D anime illustration", prompt)
+                self.assertIn("3D CGI render", prompt)
+                self.assertIn("physical collectible figurine photograph", prompt)
+                self.assertIn("Keep style separate from identity facts", prompt)
+                self.assertIn("never guess a production method", prompt)
+
+    def test_reference_analysis_uses_image_and_mmproj(self):
+        progress_events = []
+        with tempfile.TemporaryDirectory() as root:
+            Path(root, "image.png").write_bytes(b"image")
+            fake_folder_paths = SimpleNamespace(get_input_directory=lambda: root)
+
+            def fake_run(command, **kwargs):
+                self.assertIn("--image", command)
+                self.assertIn("--mmproj", command)
+                self.assertIn("stable identity", command[command.index("-p") + 1].lower())
+                self.assertIn("Never infer or label nationality, ethnicity, race, age", command[command.index("-p") + 1])
+                self.assertIn("Do not use speculative alternatives joined by or", command[command.index("-p") + 1])
+                self.assertIn("crop boundaries, visible body range", command[command.index("-p") + 1])
+                self.assertIn("VISUAL_MEDIUM:", command[command.index("-p") + 1])
+                self.assertIn("POSE_SUPPORT_CONTACT:", command[command.index("-p") + 1])
+                self.assertIn("ACTION_RELEVANT_OBJECTS:", command[command.index("-p") + 1])
+                return SimpleNamespace(
+                    returncode=0,
+                    stdout="<REFERENCE_ANALYSIS>stable observable details</REFERENCE_ANALYSIS>",
+                    stderr="",
+                )
+
+            with (
+                mock.patch.dict(sys.modules, {"folder_paths": fake_folder_paths}),
+                mock.patch.object(MODULE, "_resolve_image_model", return_value=("vision.gguf", "mmproj.gguf")),
+                mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+                mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+            ):
+                result = MODULE.analyze_reference_image(
+                    {"filename": "image.png", "_analysis_index": 1, "_analysis_total": 2},
+                    "subject_identity",
+                    progress=lambda **values: progress_events.append(values),
+                )
+        self.assertEqual(result["analysis"], "stable observable details")
+        self.assertEqual(progress_events[-1]["stage"], "reference_analysis")
+        self.assertIn("1/2", progress_events[-1]["message"])
+        self.assertIn("subject_identity", progress_events[-1]["message"])
+
+    def test_qwen_reference_analysis_disables_thinking(self):
+        with tempfile.TemporaryDirectory() as root:
+            Path(root, "image.png").write_bytes(b"image")
+            fake_folder_paths = SimpleNamespace(get_input_directory=lambda: root)
+
+            def fake_run(command, **kwargs):
+                self.assertIn("--jinja", command)
+                self.assertEqual(command[command.index("--reasoning") + 1], "off")
+                self.assertEqual(
+                    command[command.index("--chat-template-kwargs") + 1],
+                    '{"enable_thinking":false}',
+                )
+                return SimpleNamespace(
+                    returncode=0,
+                    stdout="<REFERENCE_ANALYSIS>Qwen vision details</REFERENCE_ANALYSIS>",
+                    stderr="",
+                )
+
+            with (
+                mock.patch.dict(sys.modules, {"folder_paths": fake_folder_paths}),
+                mock.patch.object(MODULE, "_resolve_image_model", return_value=("qwen.gguf", "vision.gguf")),
+                mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+                mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+            ):
+                result = MODULE.analyze_reference_image(
+                    {"filename": "image.png"}, "first_frame", MODULE.QWEN_IMAGE_MODEL_ID,
+                )
+        self.assertEqual(result["analysis"], "Qwen vision details")
+
+    def test_enhance_project_runs_selected_model_with_chat_messages(self):
+        def fake_run(command, **kwargs):
+            self.assertIn("--single-turn", command)
+            self.assertIn("--chat-template-kwargs", command)
+            self.assertEqual(
+                command[command.index("--chat-template-kwargs") + 1],
+                '{"enable_thinking":false}',
+            )
+            system_path = command[command.index("-sysf") + 1]
+            system_text = Path(system_path).read_text(encoding="utf-8")
+            self.assertTrue(system_text.startswith("ACTIVE MODE: T2VA"))
+            self.assertIn("Minimal detail needed to make the request renderable", system_text)
+            self.assertIn("FINAL MODE LOCK — T2VA", system_text)
+            self.assertIn("<H3_PROMPT>", system_text)
+            user_data = command[command.index("-p") + 1]
+            self.assertTrue(user_data.startswith("INPUT DATA ONLY"))
+            self.assertIn("mode: T2VA", user_data)
+            self.assertIn("visual_action: A woman opens a door.", user_data)
+            self.assertIn("--log-disable", command)
+            self.assertEqual(command[command.index("--top-k") + 1], "20")
+            self.assertEqual(command[command.index("-n") + 1], "1800")
+            return SimpleNamespace(returncode=0, stdout="<H3_PROMPT>\nintegrated_multimodal_description: [Shot 1] enhanced H3 prompt\n\noverall_soundscape: N/A\n\nnon_diegetic_music: N/A\n</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "T2VA",
+                "shots": [{"duration": 5, "visual_action": "A woman opens a door."}],
+            }, "local:model.gguf")
+        self.assertIn("[Shot 1] enhanced H3 prompt", result["enhanced_prompt"])
+
+    def test_enhance_project_returns_fl2va_model_output_without_normalizing_it(self):
+        def fake_run(command, **kwargs):
+            output = (
+                "Picture 1 anchors the visual state at 0.00 seconds, and Picture 2 anchors the end.\n\n"
+                "integrated_multimodal_description: [Shot 1] The exact state in Picture 1 transitions "
+                "continuously into Picture 2 while the static framing remains unchanged.\n\n"
+                "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+            )
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{output}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "FL2VA",
+                "requested_duration": 5,
+                "shots": [{"duration": 5, "visual_action": "The character transforms continuously."}],
+                "references": [
+                    {"type": "picture", "role": "first_frame"},
+                    {"type": "picture", "role": "last_frame"},
+                ],
+            }, "local:model.gguf")
+
+        expected = (
+            "How the reference pictures align with the target video — "
+            "Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; "
+            "Picture 2 (from Shot 1) aligns with the 5.17-second mark of the target video."
+        )
+        self.assertTrue(result["enhanced_prompt"].startswith("Picture 1 anchors the visual state"))
+        self.assertIn("Picture 2 anchors the end", result["enhanced_prompt"])
+
+    def test_base_normalizer_moves_i2va_alignment_outside_main_field(self):
+        malformed = (
+            "integrated_multimodal_description: For the target video, at 0.00 seconds into the target "
+            "video, <Picture 1> (from [Shot 1]) is fully referenced.\n\n"
+            "[Shot 1] The subject begins moving after the anchored frame.\n\n"
+            "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+        )
+        normalized = MODULE._normalize_base_enhanced_prompt(malformed, "I2VA", 5.17, 1)
+        self.assertTrue(normalized.startswith(MODULE.I2VA_ALIGNMENT_INSTRUCTION + "\n\n"))
+        self.assertIn(
+            "integrated_multimodal_description: [Shot 1] The subject begins moving",
+            normalized,
+        )
+        self.assertEqual(normalized.count(MODULE.I2VA_ALIGNMENT_INSTRUCTION), 1)
+        self.assertEqual(MODULE._base_prompt_structure_issues(normalized, "I2VA", 5.17, 1), [])
+
+    def test_i2va_semantic_validator_finds_unsupported_inference(self):
+        prompt = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] A young East Asian woman reaches "
+            "below the frame for an unseen object, raises a revolver, and produces bone fragments.\n\n"
+            "overall_soundscape: A hiss of smoke.\n\nnon_diegetic_music: N/A"
+        )
+        issues = MODULE._i2va_semantic_issues(
+            prompt,
+            "The subject raises a weapon while remaining in the visible frame.",
+        )
+        joined = " ".join(issues)
+        self.assertIn("age", joined)
+        self.assertIn("ethnicity", joined)
+        self.assertIn("hidden or off-frame source", joined)
+        self.assertIn("weapon type", joined)
+        self.assertIn("graphic effects", joined)
+        self.assertIn("smoke sound", joined)
+
+    def test_i2va_validator_does_not_treat_vision_inference_as_user_authority(self):
+        prompt = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] A photorealistic medium shot frames "
+            "a young woman and crops at her mid-thighs. Her glistening skin suggests body oil or water. "
+            "She raises a handgun, then her head snaps sideways due to the impact and her body begins "
+            "to slump.\n\noverall_soundscape: A gunshot and the soft thud of the woman's head snapping "
+            "sideways.\n\nnon_diegetic_music: N/A"
+        )
+        issues = MODULE._i2va_semantic_issues(
+            prompt,
+            "[Shot 1] A woman raises a handgun.",
+            "A young woman has glistening skin that may be covered in oil or water.",
+        )
+        joined = " ".join(issues)
+        self.assertIn("age", joined)
+        self.assertIn("speculative alternatives", joined)
+        self.assertIn("observable facts", joined)
+        self.assertIn("mid-thigh crop", joined)
+        self.assertIn("physical consequences", joined)
+
+    def test_i2va_validator_respects_explicit_korean_user_details(self):
+        prompt = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] A young woman moves as blood appears.\n\n"
+            "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+        )
+        issues = MODULE._i2va_semantic_issues(
+            prompt,
+            "[Shot 1] 젊은 여성이 움직이고 피가 나온다.",
+        )
+        joined = " ".join(issues)
+        self.assertNotIn("age", joined)
+        self.assertNotIn("graphic effects", joined)
+
+    def test_enhance_project_does_not_retry_i2va_fidelity_violations(self):
+        calls = []
+
+        def fake_run(command, **kwargs):
+            prompt = command[command.index("-p") + 1]
+            temperature = command[command.index("--temp") + 1]
+            calls.append((prompt, temperature))
+            if len(calls) == 1:
+                output = (
+                    "integrated_multimodal_description: For the target video, at 0.00 seconds into the "
+                    "target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\n"
+                    "[Shot 1] A young woman reaches below the frame for an unseen revolver, then raises it.\n\n"
+                    "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+                )
+            else:
+                self.assertIn("Correct only the listed I2VA fidelity violations", prompt)
+                output = (
+                    MODULE.I2VA_ALIGNMENT_INSTRUCTION
+                    + "\n\nintegrated_multimodal_description: [Shot 1] The subject remains in the anchored "
+                    "composition. The weapon first enters the visible frame, then rises smoothly.\n\n"
+                    "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+                )
+            return SimpleNamespace(
+                returncode=0,
+                stdout=f"<H3_PROMPT>{output}</H3_PROMPT>",
+                stderr="",
+            )
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "I2VA",
+                "shots": [{"duration": 5, "visual_action": "The subject raises a weapon."}],
+                "references": [{"type": "picture", "role": "first_frame"}],
+            }, "local:model.gguf")
+
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(calls[0][1], "0.22")
+        self.assertIn("young", result["enhanced_prompt"].lower())
+        self.assertIn("unseen", result["enhanced_prompt"].lower())
+
+    def test_i2va_deterministic_cleanup_repairs_repeated_framing_and_reaction_errors(self):
+        invalid = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] A medium shot frames the subject and "
+            "crops at her mid-thighs. She fires, and her head snaps sharply to her left side due to "
+            "the impact as her body begins to slump.\n\noverall_soundscape: Ocean waves are punctuated "
+            "by a gunshot and the soft thud of the woman's head snapping sideways.\n\n"
+            "non_diegetic_music: N/A"
+        )
+        cleaned = MODULE._sanitize_i2va_semantics(
+            invalid,
+            "[Shot 1] The subject fires.",
+        )
+        self.assertIn("medium-full shot", cleaned)
+        self.assertIn("She fires.", cleaned)
+        self.assertIn("punctuated by a gunshot.", cleaned)
+        self.assertNotIn("head snaps", cleaned.lower())
+        self.assertNotIn("slump", cleaned.lower())
+        self.assertNotIn("soft thud", cleaned.lower())
+        self.assertEqual(
+            MODULE._i2va_semantic_issues(cleaned, "[Shot 1] The subject fires."),
+            [],
+        )
+
+    def test_i2va_deterministic_cleanup_removes_repeated_speculation(self):
+        invalid = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] Her skin has strong highlights, "
+            "suggesting the application of body oil or water. The lighting is bright and direct, "
+            "likely from the upper left, casting defined shadows. She remains centered.\n\n"
+            "overall_soundscape: Ocean waves.\n\nnon_diegetic_music: N/A"
+        )
+        cleaned = MODULE._sanitize_i2va_semantics(invalid, "[Shot 1] She remains centered.")
+        lowered = cleaned.lower()
+        self.assertNotIn("suggesting", lowered)
+        self.assertNotIn("likely", lowered)
+        self.assertNotIn("oil or water", lowered)
+        self.assertIn("Her skin has strong highlights.", cleaned)
+        self.assertIn("The lighting is bright and direct.", cleaned)
+        self.assertIn("She remains centered.", cleaned)
+        self.assertEqual(
+            MODULE._i2va_semantic_issues(cleaned, "[Shot 1] She remains centered."),
+            [],
+        )
+
+    def test_enhance_project_does_not_apply_i2va_cleanup(self):
+        calls = []
+        invalid = (
+            MODULE.I2VA_ALIGNMENT_INSTRUCTION
+            + "\n\nintegrated_multimodal_description: [Shot 1] A medium shot frames the subject, "
+            "cropping at her mid-thighs. She performs the requested action, and the impact causes "
+            "her head to jerk sharply to her left side. Her body remains upright but sways slightly "
+            "from the force of the movement.\n\noverall_soundscape: A sharp sound.\n\n"
+            "non_diegetic_music: N/A"
+        )
+
+        def fake_run(command, **kwargs):
+            calls.append(command[command.index("-p") + 1])
+            return SimpleNamespace(
+                returncode=0,
+                stdout=f"<H3_PROMPT>{invalid}</H3_PROMPT>",
+                stderr="",
+            )
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "I2VA",
+                "shots": [{"duration": 5, "visual_action": "The subject performs the requested action."}],
+                "references": [{"type": "picture", "role": "first_frame"}],
+            }, "local:model.gguf")
+
+        self.assertEqual(len(calls), 1)
+        self.assertIn("medium shot", result["enhanced_prompt"])
+        self.assertIn("head to jerk", result["enhanced_prompt"].lower())
+        self.assertIn("sways slightly", result["enhanced_prompt"].lower())
+
+    def test_enhance_project_supplies_reference_image_analysis_as_explicit_context(self):
+        analysis_calls = []
+
+        def fake_analyze(image, role, model_id, progress=None):
+            analysis_calls.append((image, role, model_id))
+            return {
+                "analysis": "A woman with long silver hair and a red coat.",
+                "model_path": "vision.gguf",
+                "mmproj_path": "mmproj.gguf",
+            }
+
+        def fake_run(command, **kwargs):
+            user_prompt = command[command.index("-p") + 1]
+            system_text = Path(command[command.index("-sysf") + 1]).read_text(encoding="utf-8")
+            self.assertTrue(system_text.startswith("ACTIVE MODE: REF2VA FULL-REFERENCE"))
+            self.assertIn("FINAL MODE LOCK — REF2VA", system_text)
+            self.assertIn("Use exactly these labels in order: <Subject 1>", system_text)
+            self.assertIn("never use `integrated_multimodal_description:`", system_text)
+            self.assertEqual(command[command.index("--top-k") + 1], "20")
+            self.assertEqual(command[command.index("-n") + 1], "3072")
+            self.assertTrue(user_prompt.startswith("INPUT DATA ONLY"))
+            self.assertIn("mode: REF2VA", user_prompt)
+            self.assertIn("<Subject 1>\nsource: <Picture 1>", user_prompt)
+            self.assertIn("role: subject_identity", user_prompt)
+            self.assertIn("long silver hair and a red coat", user_prompt)
+            self.assertNotIn("REFERENCE IMAGE ANALYSIS:", user_prompt)
+            self.assertNotIn("RAW H3 PROMPT TO EXPAND:", user_prompt)
+            self.assertNotIn("Stale analysis from an earlier role", user_prompt)
+            return SimpleNamespace(
+                returncode=0,
+                stdout="<H3_PROMPT>subject_definitions:\n<Subject 1> is defined from <Picture 1>.\n\nsummary:\n[reference generation] The target video uses <Subject 1>.\n\nretention_analysis:\n<Subject 1>: fully_preserved - retained.\n\ndetailed_description:\n[Shot 1] <Subject 1> turns toward the camera with image evidence.\n\noverall_soundscape:\nQuiet room tone and soft movement sounds.\n\nnon_diegetic_music:\nN/A</H3_PROMPT>",
+                stderr="",
+            )
+
+        with (
+            mock.patch.object(MODULE, "_start_persistent_image_server", side_effect=RuntimeError("disabled in test")),
+            mock.patch.object(MODULE, "analyze_reference_image", side_effect=fake_analyze),
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "REF2VA",
+                "shots": [{"duration": 5, "visual_action": "@hero turns toward the camera."}],
+                "references": [{
+                    "id": "hero-ref", "type": "picture", "role": "subject_identity", "alias": "@hero",
+                    "description": "Stale analysis from an earlier role.",
+                    "image_filename": "hero.png", "image_subfolder": "toyxyz_h3_references",
+                }],
+            }, "local:model.gguf", "qwen3.8-vision")
+        self.assertIn("[Shot 1] <Subject 1> turns toward the camera with image evidence", result["enhanced_prompt"])
+        self.assertEqual(result["reference_analyses"][0]["id"], "hero-ref")
+        self.assertEqual(result["reference_analyses"][0]["analysis"], "A woman with long silver hair and a red coat.")
+        self.assertEqual(result["reference_analyses"][0]["filename"], "hero.png")
+        self.assertEqual(len(analysis_calls), 1)
+        self.assertEqual(analysis_calls[0][1:], ("subject_identity", "qwen3.8-vision"))
+
+    def test_frontend_logs_complete_vision_analysis_after_enhancement(self):
+        source = (MODULE_PATH.parent.parent / "web" / "minimax_h3_prompter.js").read_text(encoding="utf-8")
+        self.assertIn("Vision analysis for ${label} [role=${role}]", source)
+        self.assertIn('item.analysis || "No analysis text returned."', source)
+        self.assertIn('"analysis"', source)
+
+    def test_enhance_project_reuses_one_persistent_server_for_three_images(self):
+        class FakeSession:
+            def __init__(self):
+                self.closed = 0
+
+            def close(self):
+                self.closed += 1
+
+        session = FakeSession()
+        analysis_calls = []
+
+        def fake_server_analysis(image, role, active_session, progress=None):
+            analysis_calls.append((image["filename"], role, active_session))
+            return {"analysis": f"Observable traits from {image['filename']}."}
+
+        labels = ("<Subject 1>", "<Subject 2>", "<Subject 3>")
+        enhanced = (
+            "subject_definitions:\n"
+            "<Subject 1> is guidance derived from <Picture 1>.\n"
+            "<Subject 2> is guidance derived from <Picture 2>.\n"
+            "<Subject 3> is guidance derived from <Picture 3>.\n\n"
+            "summary:\n[reference generation] The target uses <Subject 1>, <Subject 2>, and <Subject 3>.\n\n"
+            "retention_analysis:\n"
+            "<Subject 1>: weak_reference - broad similarity only.\n"
+            "<Subject 2>: weak_reference - broad similarity only.\n"
+            "<Subject 3>: weak_reference - broad similarity only.\n\n"
+            "detailed_description:\n[Shot 1] <Subject 1>, <Subject 2>, and <Subject 3> move together.\n\n"
+            "overall_soundscape:\nSoft movement sounds and room tone.\n\n"
+            "non_diegetic_music:\nN/A"
+        )
+
+        def fake_run(command, **kwargs):
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{enhanced}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_start_persistent_image_server", return_value=session) as start_server,
+            mock.patch.object(MODULE, "_analyze_reference_image_with_server", side_effect=fake_server_analysis),
+            mock.patch.object(MODULE, "analyze_reference_image") as cli_analysis,
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "REF2VA",
+                "shots": [{"duration": 5, "visual_action": "Three subjects move together."}],
+                "references": [
+                    {"id": f"ref-{index}", "type": "picture", "role": "reference",
+                     "image_filename": f"image-{index}.png"}
+                    for index in range(1, 4)
+                ],
+            }, "local:model.gguf")
+        start_server.assert_called_once()
+        self.assertEqual(len(analysis_calls), 3)
+        self.assertTrue(all(call[2] is session for call in analysis_calls))
+        cli_analysis.assert_not_called()
+        self.assertEqual(session.closed, 1)
+        self.assertTrue(all(label in result["enhanced_prompt"] for label in labels))
+
+    def test_llama_server_image_request_uses_openai_multimodal_payload(self):
+        class FakeResponse:
+            status = 200
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *_args):
+                return False
+
+            def read(self):
+                return json.dumps({
+                    "choices": [{"message": {"content": "<REFERENCE_ANALYSIS>Visible facts.</REFERENCE_ANALYSIS>"}}],
+                }).encode("utf-8")
+
+        session = MODULE._LlamaServerSession("llama-server", "model.gguf", "mmproj.gguf")
+        with tempfile.TemporaryDirectory() as temp_dir:
+            image_path = Path(temp_dir) / "test.png"
+            image_path.write_bytes(b"not-a-real-png")
+            with mock.patch.object(MODULE.urllib.request, "urlopen", return_value=FakeResponse()) as request:
+                output = session.analyze_image(str(image_path), "Analyze this image.")
+        payload = json.loads(request.call_args.args[0].data.decode("utf-8"))
+        content = payload["messages"][0]["content"]
+        self.assertEqual(content[0], {"type": "text", "text": "Analyze this image."})
+        self.assertTrue(content[1]["image_url"]["url"].startswith("data:image/png;base64,"))
+        self.assertIn("Visible facts", output)
+
+    def test_enhance_project_does_not_correct_an_invented_second_shot(self):
+        calls = []
+
+        def fake_run(command, **kwargs):
+            calls.append(command[command.index("-p") + 1])
+            if len(calls) == 1:
+                output = "integrated_multimodal_description: [Shot 1] First. [Shot 2] At 00:04.500, invented cut.\n\noverall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+            else:
+                self.assertIn("SHOT TOPOLOGY LOCK", calls[-1].upper())
+                output = "integrated_multimodal_description: [Shot 1] First, with all detail retained in one continuous shot.\n\noverall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{output}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "T2VA",
+                "shots": [{"duration": 5, "visual_action": "A woman walks along a beach."}],
+            }, "local:model.gguf")
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(MODULE._prompt_shot_numbers(result["enhanced_prompt"]), [1, 2])
+
+    def test_enhance_project_does_not_correct_ref_weak_role_overreach(self):
+        calls = []
+
+        def fake_analyze(image, role, model_id, progress=None):
+            return {
+                "analysis": "An anime illustration of a blonde woman on a beach beside ocean waves.",
+                "model_path": "vision.gguf", "mmproj_path": "mmproj.gguf",
+            }
+
+        def fake_run(command, **kwargs):
+            prompt_text = command[command.index("-p") + 1]
+            calls.append(prompt_text)
+            if len(calls) == 1:
+                output = (
+                    "subject_definitions:\n<Subject 1> is a blonde woman derived from <Picture 1>.\n\n"
+                    "summary:\n[reference generation] Use <Subject 1> for character identity and styling guidance.\n\n"
+                    "retention_analysis:\n<Subject 1>: weak_reference - retain blonde hair, a white bikini, "
+                    "white sandals, and wet skin.\n\n"
+                    "detailed_description:\nThe target uses an anime illustration style.\n"
+                    "[Shot 1] <Subject 1> walks through a hotel corridor with ocean waves behind her.\n\n"
+                    "overall_soundscape:\nFootsteps and room tone.\n\nnon_diegetic_music:\nN/A"
+                )
+            else:
+                self.assertIn("weak_reference", prompt_text)
+                self.assertIn("does not transfer source environment", prompt_text)
+                self.assertIn("does not transfer source style", prompt_text)
+                output = (
+                    "subject_definitions:\n<Subject 1> is reusable appearance guidance derived from <Picture 1>.\n\n"
+                    "summary:\n[reference generation] The target uses <Subject 1> as weak appearance guidance.\n\n"
+                    "retention_analysis:\n<Subject 1>: weak_reference - use broad similarity in selected wardrobe traits.\n\n"
+                    "detailed_description:\nThe target uses a clean digital-video presentation. "
+                    "The source metadata mentions [Shot 1], while <Subject 1> walks steadily through "
+                    "the requested hotel corridor.\n\n"
+                    "overall_soundscape:\nSoft footsteps and quiet indoor room tone.\n\nnon_diegetic_music:\nN/A"
+                )
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{output}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_start_persistent_image_server", side_effect=RuntimeError("disabled in test")),
+            mock.patch.object(MODULE, "analyze_reference_image", side_effect=fake_analyze),
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "REF2VA",
+                "shots": [{"duration": 5, "visual_action": "A woman walks through a hotel corridor."}],
+                "references": [{
+                    "type": "picture", "role": "reference",
+                    "image_filename": "reference.png", "image_subfolder": "toyxyz_h3_references",
+                }],
+            }, "local:model.gguf")
+        self.assertEqual(len(calls), 1)
+        self.assertIn("styling guidance", result["enhanced_prompt"])
+        self.assertIn("ocean waves", result["enhanced_prompt"])
+        self.assertEqual(MODULE._prompt_shot_numbers(result["enhanced_prompt"]), [1])
+
+    def test_enhance_project_does_not_repair_ref_summary_or_shot_header(self):
+        calls = []
+
+        def fake_run(command, **kwargs):
+            calls.append(command[command.index("-p") + 1])
+            output = (
+                "subject_definitions:\n<Subject 1> is reusable guidance derived from <Picture 1>.\n\n"
+                "summary:\n[Reference Generation Task] The target uses <Subject 1> as weak appearance guidance.\n\n"
+                "retention_analysis:\n<Subject 1>: weak_reference - use broad visual similarity only.\n\n"
+                "detailed_description:\nThe target uses a clean digital-video presentation. "
+                "<Subject 1> walks through the requested hotel corridor.\n\n"
+                "overall_soundscape:\nSoft footsteps and quiet indoor room tone.\n\n"
+                "non_diegetic_music:\nN/A"
+            )
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{output}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "REF2VA",
+                "shots": [{"duration": 5, "visual_action": "A person walks through a hotel corridor."}],
+                "references": [{"type": "picture", "role": "reference"}],
+            }, "local:model.gguf")
+        self.assertEqual(len(calls), 1)
+        self.assertIn("summary:\n[Reference Generation Task]", result["enhanced_prompt"])
+        self.assertEqual(MODULE._prompt_shot_numbers(result["enhanced_prompt"]), [])
+
+    def test_enhance_project_does_not_recover_missing_first_header(self):
+        calls = []
+
+        def output(weak_detail):
+            retention = (
+                "retain red hair, a grey jacket, black boots, and gold buttons"
+                if weak_detail else "use broad similarity in selected appearance traits"
+            )
+            return (
+                "subject_definitions:\n<Subject 1> is reusable guidance derived from <Picture 1>.\n\n"
+                "summary:\n[reference generation] The target uses <Subject 1> as weak appearance guidance.\n\n"
+                f"retention_analysis:\n<Subject 1>: weak_reference - {retention}.\n\n"
+                "detailed_description:\nThe target uses a clean digital-video presentation. "
+                "<Subject 1> walks through the corridor in the opening shot.\n"
+                "[Shot 2] At 00:02.500, cut to a new shot. <Subject 1> stops near a door.\n\n"
+                "overall_soundscape:\nSoft footsteps and quiet room tone.\n\n"
+                "non_diegetic_music:\nN/A"
+            )
+
+        def fake_run(command, **kwargs):
+            calls.append(command[command.index("-p") + 1])
+            generated = output(weak_detail=len(calls) == 1)
+            return SimpleNamespace(returncode=0, stdout=f"<H3_PROMPT>{generated}</H3_PROMPT>", stderr="")
+
+        with (
+            mock.patch.object(MODULE, "_resolve_enhance_model", return_value="model.gguf"),
+            mock.patch.object(MODULE, "_find_llama_cli", return_value="llama-cli"),
+            mock.patch.object(MODULE.subprocess, "run", side_effect=fake_run),
+        ):
+            result = MODULE.enhance_project({
+                "mode": "REF2VA", "requested_duration": 5,
+                "shots": [
+                    {"duration": 2.5, "visual_action": "A person walks through a corridor."},
+                    {"duration": 2.5, "visual_action": "The person stops near a door."},
+                ],
+                "references": [{"type": "picture", "role": "reference"}],
+            }, "local:model.gguf")
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(MODULE._prompt_shot_numbers(result["enhanced_prompt"]), [2])
+
+    def test_shot_parser_ignores_inline_reference_to_existing_shot(self):
+        prompt = (
+            "integrated_multimodal_description: [Shot 1] Picture 1 comes from [Shot 1] and anchors the opening. "
+            "[Shot 2] At 00:03.000, the camera cuts closer.\n\n"
+            "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+        )
+        self.assertEqual(MODULE._prompt_shot_numbers(prompt), [1, 2])
+
+    def test_shot_parser_still_detects_duplicate_line_header(self):
+        prompt = (
+            "integrated_multimodal_description: [Shot 1] First block.\n"
+            "[Shot 1] Duplicate block.\n\n"
+            "overall_soundscape: N/A\n\nnon_diegetic_music: N/A"
+        )
+        self.assertEqual(MODULE._prompt_shot_numbers(prompt), [1, 1])
+
+    def test_ref_structure_validator_rejects_source_label_leak_and_marker_drift(self):
+        compiled = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero walks through a corridor."}],
+            "references": [{
+                "type": "picture", "role": "subject_identity", "alias": "hero",
+                "description": "A person in a red coat.",
+            }],
+        })
+        plan = MODULE._reference_model(compiled["project"])["label_plan"]
+        invalid = (
+            "subject_definitions:\n<Subject 1> is derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] Use <Picture 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - retain it.\n\n"
+            "detailed_description:\n[Shot 1] <Picture 1> walks.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        issues = MODULE._ref_prompt_structure_issues(invalid, plan)
+        self.assertTrue(any("fully_preserved" in issue for issue in issues))
+        self.assertTrue(any("source-only" in issue for issue in issues))
+        self.assertTrue(any("summary must mention" in issue for issue in issues))
+        self.assertTrue(any("detailed_description must apply" in issue for issue in issues))
+
+    def test_ref_structure_validator_requires_subject_provenance(self):
+        compiled = self.compile({
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero walks."}],
+            "references": [{"type": "picture", "role": "subject_identity", "alias": "hero"}],
+        })
+        plan = MODULE._reference_model(compiled["project"])["label_plan"]
+        prompt = (
+            "subject_definitions:\n<Subject 1> is a person in a red coat.\n\n"
+            "summary:\n[reference generation] Use <Subject 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: fully_preserved - preserve the visible identity.\n\n"
+            "detailed_description:\n[Shot 1] <Subject 1> walks.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        issues = MODULE._ref_prompt_structure_issues(prompt, plan)
+        self.assertTrue(any("must cite its source asset <Picture 1>" in issue for issue in issues))
+
+    def test_ref_normalizer_restores_the_required_six_section_order(self):
+        shuffled = (
+            "summary:\n[reference generation] Use <Subject 1>.\n\n"
+            "subject_definitions:\n<Subject 1> is derived from <Picture 1>.\n\n"
+            "detailed_description:\n[Shot 1] <Subject 1> walks.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - retain selected traits.\n\n"
+            "non_diegetic_music:\nN/A\n\noverall_soundscape:\nFootsteps."
+        )
+        normalized = MODULE._normalize_ref_enhanced_prompt(shuffled)
+        positions = [normalized.index(f"{field}:") for field in MODULE.REF_PROMPT_FIELDS]
+        self.assertEqual(positions, sorted(positions))
+
+    def test_ref_normalizer_locks_task_prefix_and_recovers_single_shot(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is derived from <Picture 1>.\n\n"
+            "summary:\n[invalid task] Use <Subject 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - broad similarity only.\n\n"
+            "detailed_description:\nA clean digital-video style. The subject walks forward.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        normalized = MODULE._normalize_ref_enhanced_prompt(
+            prompt, ["reference generation"], [1],
+        )
+        self.assertIn("summary:\n[reference generation] Use <Subject 1>.", normalized)
+        self.assertIn("A clean digital-video style.\n[Shot 1] The subject walks forward.", normalized)
+
+    def test_ref_normalizer_does_not_confuse_inline_shot_reference_with_header(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] Use <Subject 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - broad similarity only.\n\n"
+            "detailed_description:\nA clean digital-video style. The source metadata mentions [Shot 1], "
+            "and <Subject 1> walks forward.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        normalized = MODULE._normalize_ref_enhanced_prompt(
+            prompt, ["reference generation"], [1],
+        )
+        self.assertEqual(MODULE._prompt_shot_numbers(normalized), [1])
+
+    def test_ref_normalizer_recovers_first_header_when_later_headers_exist(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] Use <Subject 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - broad similarity only.\n\n"
+            "detailed_description:\nA clean digital-video style. <Subject 1> walks in the opening shot.\n"
+            "[Shot 2] At 00:02.500, cut to a new shot. <Subject 1> stops.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        normalized = MODULE._normalize_ref_enhanced_prompt(
+            prompt, ["reference generation"], [1, 2],
+        )
+        self.assertEqual(MODULE._prompt_shot_numbers(normalized), [1, 2])
+        self.assertIn("A clean digital-video style.\n[Shot 1]", normalized)
+
+    def test_ref_semantic_validator_rejects_inferred_demographics_and_empty_action_audio(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is a young Japanese woman.\n\n"
+            "summary:\n[reference generation] Use <Subject 1>.\n\n"
+            "retention_analysis:\n<Subject 1>: weak_reference - retain selected traits.\n\n"
+            "detailed_description:\n[Shot 1] <Subject 1> walks.\n\n"
+            "overall_soundscape:\nN/A\n\nnon_diegetic_music:\nN/A"
+        )
+        project = {"user_request": "", "constraints": "", "verbatim_content": "", "references": [], "shots": [{
+            "visual_action": "A person walks.", "dialogue": "", "visible_text": "", "diegetic_sound": "",
+        }], "overall_soundscape": "", "non_diegetic_music": ""}
+        issues = MODULE._ref_prompt_semantic_issues(prompt, project, "A person walks.")
+        self.assertTrue(any("demographic" in issue for issue in issues))
+        self.assertTrue(any("overall_soundscape" in issue for issue in issues))
+
+    def test_ref_semantic_validator_enforces_weak_role_scope(self):
+        prompt = (
+            "subject_definitions:\n"
+            "<Subject 1> is a woman with blonde hair and a white bikini derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] The target uses <Subject 1> for character identity and styling guidance.\n\n"
+            "retention_analysis:\n"
+            "<Subject 1>: weak_reference - retain the blonde hair, blue eyes, white bikini, white sandals, and wet skin.\n\n"
+            "detailed_description:\n"
+            "The target uses an anime illustration style with a cool color palette.\n"
+            "[Shot 1] <Subject 1> walks through a hotel corridor while ocean waves remain visible behind her.\n\n"
+            "overall_soundscape:\nSoft footsteps and indoor room tone.\n\nnon_diegetic_music:\nN/A"
+        )
+        project = {
+            "user_request": "", "constraints": "", "verbatim_content": "",
+            "shots": [{
+                "visual_action": "A woman walks through a hotel corridor.", "dialogue": "",
+                "visible_text": "", "diegetic_sound": "",
+            }],
+            "references": [{
+                "id": "ref-1", "type": "picture", "role": "reference", "alias": "",
+                "description": "An anime illustration of a blonde woman on a beach beside ocean waves.",
+                "duration": 0, "image_filename": "", "image_subfolder": "", "image_type": "input",
+            }],
+            "overall_soundscape": "", "non_diegetic_music": "",
+        }
+        issues = MODULE._ref_prompt_semantic_issues(
+            prompt, project, "A woman walks through a hotel corridor.",
+        )
+        self.assertTrue(any("exhaustive or identity-preserving" in issue for issue in issues))
+        self.assertTrue(any("weak appearance guidance only" in issue for issue in issues))
+        self.assertTrue(any("does not transfer source environment" in issue for issue in issues))
+        self.assertTrue(any("does not transfer source style" in issue for issue in issues))
+
+    def test_ref_subject_identity_allows_independent_target_style_declaration(self):
+        prompt = (
+            "subject_definitions:\n"
+            "<Subject 1> is a woman in a red coat derived from <Picture 1>.\n"
+            "<Subject 2> is a man in a blue jacket derived from <Picture 2>.\n\n"
+            "summary:\n[reference generation] The target uses <Subject 1> and <Subject 2> for subject identity.\n\n"
+            "retention_analysis:\n"
+            "<Subject 1>: fully_preserved - preserve the visible identity and clothing.\n"
+            "<Subject 2>: fully_preserved - preserve the visible identity and clothing.\n\n"
+            "detailed_description:\n"
+            "The target video uses a cinematic presentation with natural lighting.\n"
+            "[Shot 1] <Subject 1> and <Subject 2> walk through a hotel corridor.\n\n"
+            "overall_soundscape:\nSoft footsteps and indoor room tone.\n\n"
+            "non_diegetic_music:\nN/A"
+        )
+        project = {
+            "user_request": "", "constraints": "", "verbatim_content": "",
+            "shots": [{
+                "visual_action": "Two people walk through a hotel corridor.", "dialogue": "",
+                "visible_text": "", "diegetic_sound": "",
+            }],
+            "references": [
+                {"id": "ref-1", "type": "picture", "role": "subject_identity", "alias": "",
+                 "description": "A cinematic portrait with natural lighting.", "duration": 0},
+                {"id": "ref-2", "type": "picture", "role": "subject_identity", "alias": "",
+                 "description": "A cinematic illustration with natural lighting.", "duration": 0},
+            ],
+            "overall_soundscape": "", "non_diegetic_music": "",
+        }
+        issues = MODULE._ref_prompt_semantic_issues(
+            prompt, project, "Two people walk through a hotel corridor.",
+        )
+        self.assertFalse(any("does not transfer source style" in issue for issue in issues))
+
+    def test_ref_normal_subject_identity_rejects_explicit_source_style_transfer(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is a woman derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] The target uses <Subject 1> for subject identity.\n\n"
+            "retention_analysis:\n"
+            "<Subject 1>: fully_preserved - preserve the visible identity and clothing.\n\n"
+            "detailed_description:\n"
+            "The target video uses <Subject 1>'s cinematic style and natural lighting.\n"
+            "[Shot 1] <Subject 1> walks through a hotel corridor.\n\n"
+            "overall_soundscape:\nSoft footsteps and indoor room tone.\n\n"
+            "non_diegetic_music:\nN/A"
+        )
+        project = {
+            "user_request": "", "constraints": "", "verbatim_content": "",
+            "shots": [{
+                "visual_action": "A woman walks through a hotel corridor.", "dialogue": "",
+                "visible_text": "", "diegetic_sound": "",
+            }],
+            "references": [{
+                "id": "ref-1", "type": "picture", "role": "subject_identity", "alias": "",
+                "strength": "normal",
+                "description": "A cinematic portrait with natural lighting.", "duration": 0,
+            }],
+            "overall_soundscape": "", "non_diegetic_music": "",
+        }
+        issues = MODULE._ref_prompt_semantic_issues(
+            prompt, project, "A woman walks through a hotel corridor.",
+        )
+        self.assertTrue(any("does not transfer source style" in issue for issue in issues))
+
+    def test_ref_strong_subject_identity_allows_source_style_transfer(self):
+        prompt = (
+            "subject_definitions:\n<Subject 1> is a cel-shaded woman derived from <Picture 1>.\n\n"
+            "summary:\n[reference generation] The target uses <Subject 1>.\n\n"
+            "retention_analysis:\n"
+            "<Subject 1>: fully_preserved - preserve identity and source rendering style.\n\n"
+            "detailed_description:\n"
+            "[Shot 1] <Subject 1> retains <Subject 1>'s cel-shaded rendering style while walking through a corridor.\n\n"
+            "overall_soundscape:\nFootsteps.\n\nnon_diegetic_music:\nN/A"
+        )
+        project = {
+            "user_request": "", "constraints": "", "verbatim_content": "",
+            "shots": [{"visual_action": "A woman walks through a corridor."}],
+            "references": [{
+                "id": "ref-1", "type": "picture", "role": "subject_identity", "alias": "",
+                "strength": "strong", "description": "A cel-shaded illustration.", "duration": 0,
+            }],
+        }
+        issues = MODULE._ref_prompt_semantic_issues(
+            prompt, project, "A woman walks through a corridor.",
+        )
+        self.assertFalse(any("does not transfer source style" in issue for issue in issues))
+
+    def test_llm_system_prompt_includes_base_guide_rules(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [{"duration": 5, "visual_action": "Two people speak while walking."}],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("Use a cut only when the configured next shot reveals new subject", llm_prompt)
+        self.assertIn("Every later shot starts at its supplied timestamp", llm_prompt)
+        self.assertIn("Place a synchronized physical sound beside its visible cause", llm_prompt)
+        self.assertIn("Infer only concise ambience and physical sounds directly implied", llm_prompt)
+        self.assertIn("BGM, soundtrack, or score", llm_prompt)
+        self.assertIn("otherwise output N/A", llm_prompt)
+        self.assertIn("without shot labels, timestamps", llm_prompt)
+        self.assertIn("instrumentation, tempo, rhythm, and dynamics", llm_prompt)
+        self.assertIn("Do not invent identities, demographics, backstory", llm_prompt)
+        self.assertIn("show only the intermediate motion needed to make it physically legible", llm_prompt)
+        self.assertIn("Return the final prompt only", llm_prompt)
+        self.assertIn("PRIORITY\n1. Explicit user actions", llm_prompt)
+        self.assertIn("Omit unsupported details instead of guessing", llm_prompt)
+        self.assertIn("visible mouth movement synchronizes with the line", llm_prompt)
+        self.assertIn("ends when the line ends", llm_prompt)
+        self.assertIn("off-screen voiceover", llm_prompt)
+        self.assertIn("Give speech a readable beat", llm_prompt)
+        self.assertIn("unless the user explicitly requests simultaneity", llm_prompt)
+        self.assertIn("SHOT_PLAN visual_action is the unified source", llm_prompt)
+        self.assertIn("Write spoken dialogue as", llm_prompt)
+        self.assertIn("never translate, paraphrase, duplicate, or add words", llm_prompt)
+        self.assertIn("Visible text uses exact double-quoted characters", llm_prompt)
+        self.assertIn("must be correct in the final output", llm_prompt)
+
+    def test_ref_llm_system_prompt_includes_reference_guide_rules(self):
+        result = self.compile({
+            "version": 16,
+            "mode": "REF2VA",
+            "shots": [{"duration": 5, "visual_action": "@hero walks."}],
+            "references": [{"type": "picture", "role": "subject_identity", "strength": "normal", "alias": "hero"}],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("Do not define a standalone Picture unless it is a configured frame anchor", llm_prompt)
+        self.assertIn("number each label type independently", llm_prompt)
+        self.assertIn("<Subject N> (Sx)", llm_prompt)
+        self.assertIn("Define each image-derived Subject in one line", llm_prompt)
+        self.assertIn("RETENTION OUTPUT MARKERS:", llm_prompt)
+        self.assertIn("<Subject 1> uses partially_preserved", llm_prompt)
+        self.assertNotIn("normal = partially_preserved", llm_prompt)
+        self.assertIn("must be correct in the final output", llm_prompt)
+        self.assertIn("ACTIVE MODE: REF2VA FULL-REFERENCE", llm_prompt)
+        self.assertIn("FINAL MODE LOCK — REF2VA", llm_prompt)
+        self.assertIn("never use `integrated_multimodal_description:`", llm_prompt)
+
+    def test_base_mode_system_prompts_include_guide_transition_sequences(self):
+        cases = {
+            "T2VA": "concise chronological action",
+            "I2VA": "actual opening state through action onset, necessary physical development, and a stable result",
+            "FL2VA": "Picture 1 is the complete opening frame and Picture 2 is the complete frame reached only at the effective end",
+            "L2VA": "Infer one plausible preceding state from the user's request",
+        }
+        references = {
+            "T2VA": [],
+            "I2VA": [{"type": "picture", "role": "first_frame"}],
+            "FL2VA": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+            "L2VA": [{"type": "picture", "role": "last_frame"}],
+        }
+        for mode, phrase in cases.items():
+            with self.subTest(mode=mode):
+                result = self.compile({
+                    "mode": mode,
+                    "shots": [{"duration": 5, "visual_action": "A subject moves."}],
+                    "references": references[mode],
+                })
+                self.assertIn(phrase, result["llm_prompt"])
+
+    def test_i2va_system_prompt_locks_first_frame_and_physical_continuity(self):
+        result = self.compile({
+            "mode": "I2VA",
+            "shots": [{"duration": 5, "visual_action": "The subject performs one action."}],
+            "references": [{"type": "picture", "role": "first_frame"}],
+        })
+        llm_prompt = result["llm_prompt"]
+        self.assertIn("Picture 1 is the complete literal frame at 0.00 seconds", llm_prompt)
+        self.assertIn("observable visual medium and rendering style as part of the opening anchor", llm_prompt)
+        self.assertIn("visible clothing and construction", llm_prompt)
+        self.assertIn("pose, support and contact", llm_prompt)
+        self.assertIn("Preserve every visible surface, foreground object, support, obstacle", llm_prompt)
+        self.assertIn("Do not replace the evidenced setting with a generic room", llm_prompt)
+        self.assertIn("actual opening state through action onset, necessary physical development, and a stable result", llm_prompt)
+        self.assertIn("An initially absent object may enter the frame only through a physically plausible visible path", llm_prompt)
+        self.assertIn("Never invent a target or aiming direction", llm_prompt)
+        self.assertIn("The framing must contain the complete action path", llm_prompt)
+        self.assertIn("use one slight pullback, tilt, pan, or tracking adjustment", llm_prompt)
+        self.assertIn("no more than three connected beats", llm_prompt)
+        self.assertIn("Do not add unrequested outcomes, injuries, reactions", llm_prompt)
+        self.assertIn("110-160 English words", llm_prompt)
+        self.assertIn("150-210 when contact objects or spatial staging require it", llm_prompt)
+
+    def test_reference_analysis_captures_action_relevant_construction(self):
+        prompt = MODULE._reference_analysis_prompt("first_frame")
+        self.assertIn("fasteners, seams, layers, openings", prompt)
+        self.assertIn("POSE_SUPPORT_CONTACT:", prompt)
+        self.assertIn("ACTION_RELEVANT_OBJECTS:", prompt)
+        self.assertIn("foreground obstacles", prompt)
+
+    def test_shots_are_fitted_to_fixed_timeline_duration(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "requested_duration": 6,
+            "shots": [
+                {"duration": 5, "visual_action": "First action."},
+                {"duration": 5, "visual_action": "Second action."},
+            ],
+        })
+        durations = [shot["duration"] for shot in result["project"]["shots"]]
+        self.assertAlmostEqual(sum(durations), 6.0)
+        self.assertAlmostEqual(durations[0], 3.0)
+        self.assertAlmostEqual(durations[1], 3.0)
+        self.assertFalse(any("Shot durations total" in error for error in result["errors"]))
+
+    def test_legacy_camera_controls_migrate_into_unified_visual_action(self):
+        result = self.compile({
+            "version": 14,
+            "mode": "T2VA",
+            "shots": [{
+                "duration": 5,
+                "visual_action": "A runner crosses the finish line.",
+                "camera_framing": "Cowboy Shot",
+                "camera_angle": "Low Angle Shot",
+                "camera_motion": "Tracking Shot",
+            }],
+        })
+        prompt = result["video_prompt"]
+        shot = result["project"]["shots"][0]
+        self.assertNotIn("camera_framing", shot)
+        self.assertNotIn("camera_angle", shot)
+        self.assertNotIn("camera_motion", shot)
+        self.assertIn("The composition uses a cowboy shot", shot["visual_action"])
+        self.assertIn("The camera uses a low angle", shot["visual_action"])
+        self.assertIn("The camera tracks the moving subject", shot["visual_action"])
+        self.assertIn("CAMERA_POLICY:", prompt)
+        self.assertIn("choose framing that contains the largest required visible action and final state", prompt)
+        self.assertIn("otherwise use one motivated reframe", prompt)
+        self.assertNotIn("camera_framing:", prompt)
+        self.assertNotIn("camera_angle:", prompt)
+        self.assertNotIn("camera_motion:", prompt)
+
+    def test_empty_shots_use_grammatical_continuity_text(self):
+        result = self.compile({
+            "mode": "FL2VA",
+            "requested_duration": 5,
+            "shots": [
+                {"duration": 2.5},
+                {"duration": 1.25},
+                {"duration": 1.25},
+            ],
+            "references": [
+                {"type": "picture", "role": "first_frame"},
+                {"type": "picture", "role": "last_frame"},
+            ],
+        })
+        description = result["video_prompt"]
+        self.assertIn("[Shot 2]\ntime_range_seconds: 2.583-3.875", description)
+        self.assertIn("[Shot 3]\ntime_range_seconds: 3.875-5.167", description)
+        self.assertNotIn("transition:", description)
+
+    def test_configured_shot_boundaries_are_defined_by_camera_policy(self):
+        result = self.compile({
+            "mode": "T2VA",
+            "shots": [
+                {"duration": 2.5, "visual_action": "A woman walks along the beach."},
+                {"duration": 2.5, "visual_action": "The woman turns toward the camera."},
+            ],
+        })
+        prompt = result["video_prompt"]
+        self.assertIn("visual_action: The woman turns toward the camera.", prompt)
+        self.assertIn("each configured shot after Shot 1 is an ordinary cut", prompt)
+        self.assertNotIn("transition: cut", prompt)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/web/minimax_h3_prompter.js b/web/minimax_h3_prompter.js
new file mode 100644
index 0000000..b32b2d1
--- /dev/null
+++ b/web/minimax_h3_prompter.js
@@ -0,0 +1,1684 @@
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+
+const NODE_NAME = "MinimaxH3Prompter";
+const ENDPOINT = "/toyxyz/minimax_h3_prompter/compile";
+const MODELS_ENDPOINT = "/toyxyz/minimax_h3_prompter/models";
+const ENHANCE_ENDPOINT = "/toyxyz/minimax_h3_prompter/enhance";
+const ENHANCE_STATUS_ENDPOINT = "/toyxyz/minimax_h3_prompter/enhance/status";
+const ENHANCE_CANCEL_ENDPOINT = "/toyxyz/minimax_h3_prompter/enhance/cancel";
+const VIDEO_UPLOAD_ENDPOINT = "/toyxyz/minimax_h3_prompter/upload-video";
+const VIDEO_VIEW_ENDPOINT = "/toyxyz/minimax_h3_prompter/video";
+const VIDEO_UPLOAD_CHUNK_BYTES = 4 * 1024 * 1024;
+const DEFAULT_ENHANCE_MODEL = "hf:JonathanColetti/Qwen3.8-27B-Uncensored-GGUF/Qwen3.8-27B-Uncensored-Q4_K_M.gguf";
+const DEFAULT_MODEL_BUNDLE = "hf:JonathanColetti/Qwen3.8-27B-Uncensored-GGUF/Q4_K_M+vision-f16";
+const LEGACY_LIGHTX2V_MODEL = "hf:lightx2v/MiniMax-H3-Prompt-Rewriter-LoRA-8B";
+const LIGHTX2V_MODEL = "hf:indhic-ai/MiniMax_H3-Prompt_Rewriter-8B-LORA-Merged-GGUF/Q8_0+vision-f16";
+// Includes the model selector/enhancement controls without forcing the whole
+// editor into a nested scrollbar. Long reference lists and prompt previews
+// retain their own scoped scroll areas.
+const UI_HEIGHT = 770;
+const UI_WIDTH = 1380;
+const NODE_HEIGHT = UI_HEIGHT + 95;
+const MIN_SHOT_DURATION = 0.25;
+const CURRENT_PROJECT_VERSION = 20;
+const MAX_REFERENCES = { picture: 9, video: 3, audio: 3, total: 12 };
+const SHOT_SNAP_SECONDS = 0.05;
+const MODES = ["AUTO", "T2VA", "I2VA", "FL2VA", "L2VA", "REF2VA"];
+const LEGACY_DIALOGUE_LANGUAGES = [
+  "Arabic", "Chinese", "English", "French", "German", "Italian",
+  "Japanese", "Korean", "Portuguese", "Russian", "Spanish",
+];
+const REFERENCE_ROLES = {
+  picture: ["first_frame", "last_frame", "subject_identity"],
+  video: ["none", "video_editing", "video_continuation", "motion", "camera", "cuts_rhythm"],
+  audio: [
+    "none", "full_signal_copy", "partial_signal_copy", "voice_delivery",
+    "dialogue_lyrics", "sound_ambience", "music_rhythm",
+  ],
+};
+const REFERENCE_TYPE_LABELS = { picture: "Image", video: "Video", audio: "Audio" };
+const SUBJECT_STRENGTHS = ["weak", "normal", "strong"];
+const SUBJECT_STRENGTH_LABELS = { weak: "Weak", normal: "Normal", strong: "Strong" };
+const REFERENCE_ROLE_LABELS = {
+  first_frame: "First frame",
+  last_frame: "Last frame",
+  subject_identity: "Subject",
+  none: "None",
+  video_editing: "Video editing",
+  video_continuation: "Video continuation",
+  motion: "Motion / action timing",
+  camera: "Camera movement",
+  cuts_rhythm: "Cuts / rhythm / temporal structure",
+  full_signal_copy: "Full audio reuse",
+  partial_signal_copy: "Partial audio reuse",
+  voice_delivery: "Voice / delivery",
+  dialogue_lyrics: "Dialogue / lyrics reuse",
+  sound_ambience: "Sound / ambience",
+  music_rhythm: "Music / rhythm",
+};
+const REFERENCE_ROLE_HELP = {
+  first_frame: "The picture strictly anchors the opening frame.",
+  last_frame: "The picture strictly anchors the final frame.",
+  subject_identity: "Use the image as a Subject; choose Weak, Normal, or Strong preservation separately.",
+  none: "No preset relationship. Describe the intended use freely below.",
+  video_editing: "Directly edit the source video while preserving the source elements specified below.",
+  video_continuation: "Continue naturally from the ending state of the source video.",
+  motion: "Reference the source video's subject motion, action timing, and movement rhythm only.",
+  camera: "Reference the source video's camera movement and viewpoint behavior only.",
+  cuts_rhythm: "Reference the source video's cuts, pacing, rhythm, and temporal structure only.",
+  full_signal_copy: "Reuse the complete source audio signal for the available target duration.",
+  partial_signal_copy: "Reuse only the source interval or audio layers specified below.",
+  voice_delivery: "Reference voice timbre, accent, emotion, pace, and delivery without copying words.",
+  dialogue_lyrics: "Reuse exact supplied or transcribed dialogue or lyrics without inventing unavailable words.",
+  sound_ambience: "Reference described sound effects, ambience, room tone, and acoustic character.",
+  music_rhythm: "Reference described instrumentation, tempo, beat, rhythm, dynamics, or structure.",
+};
+
+const AUDIO_DESCRIPTION_PLACEHOLDERS = {
+  none: "Describe how this audio should guide the target in English",
+  full_signal_copy: "Describe where the complete source audio should be used",
+  partial_signal_copy: "Specify the interval or audio layers to reuse",
+  voice_delivery: "Specify the target speaker and voice or delivery traits to reference",
+  dialogue_lyrics: "Provide the exact dialogue or lyrics and where they should occur",
+  sound_ambience: "Describe the sound effects, ambience, timing, or acoustic character to reference",
+  music_rhythm: "Describe the instrumentation, tempo, rhythm, dynamics, or structure to reference",
+};
+
+const DEFAULT_PROJECT = () => ({
+  version: CURRENT_PROJECT_VERSION,
+  mode: "AUTO",
+  requested_duration: 5,
+  user_request: "",
+  shots: [{
+    id: crypto.randomUUID?.() || `shot-${Date.now()}`,
+    duration: 5,
+    visual_action: "",
+  }],
+  references: [],
+  constraints: "",
+  verbatim_content: "",
+  enhance_model: DEFAULT_ENHANCE_MODEL,
+  image_model: DEFAULT_MODEL_BUNDLE,
+  auto_run: false,
+  enhance: false,
+  enhanced_prompt: "",
+});
+
+function hideWidget(widget) {
+  if (!widget) return;
+  widget.hidden = true;
+  widget.options ||= {};
+  widget.options.hidden = true;
+  if (!window.LiteGraph || !window.LiteGraph.vueNodesMode) {
+    widget.computeSize = () => [0, -4];
+    widget.draw = () => {};
+  }
+  if (widget.element) widget.element.style.display = "none";
+}
+
+function uid(prefix) {
+  return crypto.randomUUID?.() || `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function clampNumber(value, fallback, min = -Infinity, max = Infinity) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.min(max, Math.max(min, number)) : fallback;
+}
+
+function normalizeAlias(value) {
+  const alias = String(value || "").trim().replace(/^@+/, "")
+    .replace(/\s+/g, "_").replace(/[^\p{L}\p{N}_-]/gu, "");
+  return alias ? `@${alias}` : "";
+}
+
+function inferAutoMode(references) {
+  if (!references.length) return "T2VA";
+  const signature = references.map(ref => `${ref.type}:${ref.role}`);
+  if (signature.length === 1 && signature[0] === "picture:first_frame") return "I2VA";
+  if (signature.length === 2
+      && signature[0] === "picture:first_frame"
+      && signature[1] === "picture:last_frame") return "FL2VA";
+  if (signature.length === 1 && signature[0] === "picture:last_frame") return "L2VA";
+  return "REF2VA";
+}
+
+function fitShotDurations(shots, requestedDuration) {
+  if (!shots.length) return;
+  const target = Math.max(requestedDuration, shots.length * MIN_SHOT_DURATION);
+  const distributable = target - shots.length * MIN_SHOT_DURATION;
+  const weights = shots.map(shot => Math.max(0, Number(shot.duration) - MIN_SHOT_DURATION));
+  const weightTotal = weights.reduce((sum, value) => sum + value, 0);
+  shots.forEach((shot, index) => {
+    const share = weightTotal > 0 ? weights[index] / weightTotal : 1 / shots.length;
+    shot.duration = MIN_SHOT_DURATION + distributable * share;
+  });
+}
+
+function migrateLegacyShotContent(shot, index = 0) {
+  const parts = [String(shot?.visual_action || "").trim()].filter(Boolean);
+  let dialogue = String(shot?.dialogue || "").trim();
+  if (dialogue) {
+    let language = LEGACY_DIALOGUE_LANGUAGES.includes(String(shot?.dialogue_language || ""))
+      ? String(shot.dialogue_language) : "English";
+    const wrapped = dialogue.match(/^<d>\s*(?:\[([^\]\r\n]+)\]\s*)?([\s\S]*?)\s*<\/d>$/i);
+    if (wrapped) {
+      if (LEGACY_DIALOGUE_LANGUAGES.includes(wrapped[1])) language = wrapped[1];
+      dialogue = wrapped[2];
+    } else {
+      dialogue = dialogue.replace(/<\/?d>/gi, "").trim();
+    }
+    const speaker = /^S[1-6]$/i.test(String(shot?.dialogue_speaker || ""))
+      ? String(shot.dialogue_speaker).toUpperCase() : "S1";
+    const delivery = String(shot?.dialogue_delivery || "").trim() || "The on-screen speaker";
+    const mode = ["spoken", "voiceover", "singing"].includes(String(shot?.dialogue_mode || "").toLowerCase())
+      ? String(shot.dialogue_mode).toLowerCase() : "spoken";
+    if (mode === "voiceover") {
+      parts.push(`${delivery} (${speaker}) says in an off-screen voiceover: <d>[${language}] ${dialogue}</d> while the corresponding on-screen character's lips remain completely closed.`);
+    } else if (mode === "singing") {
+      parts.push(`${delivery} (${speaker}) sings: <d>[${language}] ${dialogue}</d>`);
+    } else {
+      parts.push(`${delivery} (${speaker}) says: <d>[${language}] ${dialogue}</d>`);
+    }
+  }
+  const visibleText = String(shot?.visible_text || "").trim();
+  if (visibleText) {
+    const escaped = visibleText.replaceAll("\\", "\\\\").replaceAll('"', '\\"')
+      .replaceAll("\r", " ").replaceAll("\n", " ");
+    parts.push(`A visible on-screen text element reads "${escaped}".`);
+  }
+  const legacySound = String(shot?.diegetic_sound || "").trim();
+  if (legacySound) parts.push(`Synchronized physical sound: ${legacySound}`);
+  const framing = String(shot?.camera_framing || "").trim();
+  const angle = String(shot?.camera_angle || "").trim();
+  const motion = String(shot?.camera_motion || "").trim();
+  if (framing) parts.push(`Camera framing: ${framing}.`);
+  if (angle) parts.push(`Camera angle: ${angle}.`);
+  if (motion) parts.push(`Camera motion: ${motion}.`);
+  const transition = String(shot?.transition || "").trim().toLowerCase();
+  if (index > 0 && ["cross-dissolve", "fade", "wipe"].includes(transition)) {
+    parts.push(`Transition into this shot with a ${transition}.`);
+  }
+  return parts.join("\n");
+}
+
+function normalizeProject(value) {
+  let raw = value;
+  if (typeof raw === "string") {
+    try { raw = JSON.parse(raw); } catch { raw = {}; }
+  }
+  if (!raw || typeof raw !== "object") raw = {};
+  const project = DEFAULT_PROJECT();
+  project.mode = MODES.includes(String(raw.mode || "").toUpperCase()) ? String(raw.mode).toUpperCase() : "AUTO";
+  project.user_request = String(raw.user_request || "");
+  project.constraints = String(raw.constraints || "");
+  project.verbatim_content = String(raw.verbatim_content || "");
+  const savedEnhanceModel = String(raw.enhance_model || "") === LEGACY_LIGHTX2V_MODEL
+    ? LIGHTX2V_MODEL : String(raw.enhance_model || "");
+  const savedImageModel = String(raw.image_model || "") === LEGACY_LIGHTX2V_MODEL
+    ? LIGHTX2V_MODEL : String(raw.image_model || "");
+  project.enhance_model = [DEFAULT_ENHANCE_MODEL, LIGHTX2V_MODEL].includes(savedEnhanceModel)
+    ? savedEnhanceModel : DEFAULT_ENHANCE_MODEL;
+  project.image_model = [DEFAULT_MODEL_BUNDLE, LIGHTX2V_MODEL].includes(savedImageModel)
+    ? savedImageModel : DEFAULT_MODEL_BUNDLE;
+  project.auto_run = raw.auto_run === true;
+  project.enhance = raw.enhance === true;
+  project.enhanced_prompt = String(raw.enhanced_prompt || "");
+  if (Array.isArray(raw.shots) && raw.shots.length) {
+    project.shots = raw.shots.map((shot, index) => ({
+      id: String(shot?.id || uid(`shot-${index + 1}`)),
+      duration: clampNumber(shot?.duration, 1, MIN_SHOT_DURATION, 60),
+      visual_action: migrateLegacyShotContent(shot, index),
+    }));
+  } else {
+    project.shots[0].duration = clampNumber(raw.requested_duration, 5, 0.1, 60);
+  }
+  const legacyAudio = [];
+  if (String(raw.overall_soundscape || "").trim()) {
+    legacyAudio.push(`Overall soundscape: ${String(raw.overall_soundscape).trim()}`);
+  }
+  if (String(raw.non_diegetic_music || "").trim()) {
+    legacyAudio.push(`Non-diegetic music: ${String(raw.non_diegetic_music).trim()}`);
+  }
+  if (legacyAudio.length) {
+    project.shots[0].visual_action = [project.shots[0].visual_action, ...legacyAudio].filter(Boolean).join("\n");
+  }
+  project.references = Array.isArray(raw.references) ? raw.references.map((ref, index) => {
+    const type = ["picture", "video", "audio"].includes(ref?.type) ? ref.type : "picture";
+    const suppliedRole = String(ref?.role || "").toLowerCase();
+    let role = REFERENCE_ROLES[type].includes(suppliedRole) ? suppliedRole : "reference";
+    let strength = String(ref?.strength || "").toLowerCase();
+    if (type === "picture") {
+      if (["reference", "environment", "style", "storyboard"].includes(suppliedRole)) {
+        role = "subject_identity"; strength = "weak";
+      } else if (suppliedRole === "subject_identity") {
+        role = "subject_identity";
+        strength = SUBJECT_STRENGTHS.includes(strength) ? strength : "strong";
+      } else if (!["first_frame", "last_frame"].includes(suppliedRole)) {
+        role = "subject_identity";
+        strength = SUBJECT_STRENGTHS.includes(strength) ? strength : "normal";
+      } else {
+        role = suppliedRole; strength = "normal";
+      }
+    } else if (type === "video") {
+      const legacyVideoRoles = {
+        reference: "none", continuation: "video_continuation", pacing: "cuts_rhythm",
+      };
+      role = REFERENCE_ROLES.video.includes(suppliedRole)
+        ? suppliedRole : (legacyVideoRoles[suppliedRole] || "none");
+    } else if (type === "audio") {
+      const legacyAudioRoles = {
+        reference: "none", voice_timbre: "voice_delivery", dialogue: "dialogue_lyrics",
+        music_style: "music_rhythm", sound_effect: "sound_ambience",
+        signal_copy: "partial_signal_copy",
+      };
+      role = REFERENCE_ROLES.audio.includes(suppliedRole)
+        ? suppliedRole : (legacyAudioRoles[suppliedRole] || "none");
+    }
+    return {
+      id: String(ref?.id || uid(`ref-${index + 1}`)),
+      type,
+      role,
+      strength: SUBJECT_STRENGTHS.includes(strength) ? strength : "normal",
+      alias: normalizeAlias(ref?.alias),
+      // Image analysis belongs only to the active Enhance request. Version 7
+      // persisted it here, which made Raw Prompt change after enhancement.
+      description: type === "picture" ? "" : String(ref?.description || ""),
+      duration: clampNumber(ref?.duration, 0, 0, 60),
+      image_filename: String(ref?.image_filename || ""),
+      image_subfolder: String(ref?.image_subfolder || "").replaceAll("\\", "/").replace(/^\/+|\/+$/g, ""),
+      image_type: "input",
+      video_filename: String(ref?.video_filename || ""),
+      video_subfolder: String(ref?.video_subfolder || "").replaceAll("\\", "/").replace(/^\/+|\/+$/g, ""),
+      video_type: "input",
+      audio_filename: String(ref?.audio_filename || ""),
+      audio_subfolder: String(ref?.audio_subfolder || "").replaceAll("\\", "/").replace(/^\/+|\/+$/g, ""),
+      audio_type: "input",
+    };
+  }) : [];
+  const shotTotal = project.shots.reduce((sum, shot) => sum + shot.duration, 0);
+  const requestedDuration = clampNumber(
+    raw.requested_duration,
+    shotTotal || 5,
+    project.shots.length * MIN_SHOT_DURATION,
+    60,
+  );
+  if (shotTotal > 0 && Math.abs(shotTotal - requestedDuration) > 0.0005) {
+    fitShotDurations(project.shots, requestedDuration);
+  }
+  project.requested_duration = requestedDuration;
+  return project;
+}
+
+function installStyles() {
+  if (document.getElementById("mmh3-prompter-styles")) return;
+  const style = document.createElement("style");
+  style.id = "mmh3-prompter-styles";
+  style.textContent = `
+    .mmh3p { --bg:#181a1d; --panel:#202329; --line:#383d46; --soft:#2b3038; --text:#e4e7eb;
+      --muted:#949ba7; --accent:#65b9ff; --warn:#e7b35c; --error:#ff7272; color:var(--text);
+      width:100%; height:100%; min-height:0; box-sizing:border-box; display:grid;
+      grid-template-rows:minmax(0,1fr) 92px; gap:8px;
+      padding:8px; background:var(--bg); font:12px Inter,system-ui,sans-serif; overflow:hidden;
+      position:relative; }
+    .mmh3p * { box-sizing:border-box; }
+    .mmh3p-workspace { width:100%; height:100%; min-height:0; display:grid;
+      grid-template-columns:minmax(760px,1fr) minmax(380px,.44fr); gap:8px; }
+    .mmh3p-main { min-width:0; min-height:0; display:flex; flex-direction:column; gap:8px; overflow:hidden; }
+    .mmh3p-main > .mmh3p-panel { flex:0 0 auto; }
+    .mmh3p-main > .mmh3p-grid { flex:1 1 0; min-height:0; }
+    .mmh3p-row { display:flex; gap:7px; align-items:center; min-width:0; }
+    .mmh3p-grow { flex:1; min-width:0; }
+    .mmh3p-panel { background:var(--panel); border:1px solid var(--line); border-radius:7px; padding:8px; }
+    .mmh3p-label { color:var(--muted); font-size:10px; font-weight:700; letter-spacing:.06em; text-transform:uppercase; }
+    .mmh3p input,.mmh3p select,.mmh3p textarea,.mmh3p button { color:var(--text); background:var(--soft);
+      border:1px solid #464c57; border-radius:4px; font:inherit; outline:none; }
+    .mmh3p input,.mmh3p select { height:27px; padding:3px 7px; }
+    .mmh3p textarea { width:100%; padding:7px; resize:vertical; min-height:55px; line-height:1.35; }
+    .mmh3p button { min-height:27px; padding:4px 9px; cursor:pointer; }
+    .mmh3p button:hover { border-color:var(--accent); }
+    .mmh3p button.active { color:#06131d; background:var(--accent); border-color:var(--accent); }
+    .mmh3p-top { flex-wrap:wrap; }
+    .mmh3p-badge { padding:4px 7px; background:#15171a; border:1px solid var(--line); border-radius:12px;
+      color:var(--muted); font:11px ui-monospace,Consolas,monospace; white-space:nowrap; }
+    .mmh3p-badge.error { color:var(--error); border-color:#713b43; background:#211518; }
+    .mmh3p-toolbar { justify-content:space-between; }
+    .mmh3p-timeline { height:112px; display:flex; align-items:stretch; gap:3px; padding-top:18px;
+      position:relative; overflow-x:auto; }
+    .mmh3p-ruler { position:absolute; left:0; right:0; top:0; color:#707784; font-size:9px;
+      display:flex; justify-content:space-between; pointer-events:none; }
+    .mmh3p-shot { min-width:100px; position:relative; padding:7px; border:1px solid #46505c;
+      border-radius:5px; background:#182630; overflow:hidden; cursor:pointer; display:flex; flex-direction:column; gap:5px; }
+    .mmh3p-shot.selected { border-color:var(--accent); box-shadow:0 0 0 1px var(--accent) inset; }
+    .mmh3p-shot.dragging { opacity:.45; }
+    .mmh3p-shot-title { font-weight:700; color:#d9efff; white-space:nowrap; }
+    .mmh3p-shot-summary { color:#aeb8c4; font-size:10px; overflow:hidden; line-height:1.25; }
+    .mmh3p-shot-duration { margin-left:auto; padding:2px 6px; border-radius:10px; color:#a9d8ff;
+      background:#111a21; border:1px solid #364653; font:10px ui-monospace,Consolas,monospace; }
+    .mmh3p-resize-handle { position:absolute; z-index:5; top:0; right:0; width:11px; height:100%;
+      cursor:col-resize; touch-action:none; }
+    .mmh3p-resize-handle::after { content:""; position:absolute; top:8px; bottom:8px; left:5px;
+      width:2px; border-radius:2px; background:#65b9ff; opacity:.45; }
+    .mmh3p-resize-handle:hover::after,.mmh3p-resize-handle.active::after { opacity:1; width:3px; }
+    .mmh3p.resizing,.mmh3p.resizing * { cursor:col-resize !important; user-select:none !important; }
+    .mmh3p-grid { display:grid; grid-template-columns:1fr 1fr; gap:8px; min-height:0;
+      align-items:stretch; overflow:hidden; }
+    .mmh3p-grid > .mmh3p-panel { min-height:0; height:100%; overflow:hidden; }
+    .mmh3p-editor { display:flex; flex-direction:column; gap:6px; min-height:0; overflow:hidden; }
+    .mmh3p-visual-action-field { flex:1 1 auto; min-height:0; display:flex; flex-direction:column; }
+    .mmh3p-visual-action-field .mmh3p-mention-wrap { flex:1 1 auto; height:auto; min-height:0; }
+    .mmh3p-visual-action-field .mmh3p-mention-wrap textarea { height:100%; min-height:0; resize:none; overflow:auto; }
+    .mmh3p-field { display:flex; flex-direction:column; gap:3px; }
+    .mmh3p-field span { color:var(--muted); font-size:10px; }
+    .mmh3p-editor textarea { min-height:44px; }
+    .mmh3p-mention-wrap { position:relative; width:100%; min-height:58px; background:var(--soft);
+      border:1px solid #464c57; border-radius:4px; overflow:visible; }
+    .mmh3p-mention-wrap:focus-within { border-color:var(--accent); }
+    .mmh3p-mention-wrap textarea { position:relative; z-index:2; display:block; width:100%; min-height:56px;
+      margin:0; border:0; border-radius:0; background:transparent; resize:vertical; caret-color:var(--text); }
+    .mmh3p-mention-backdrop { position:absolute; z-index:1; inset:0; padding:7px; overflow:hidden;
+      color:transparent; white-space:pre-wrap; overflow-wrap:anywhere; pointer-events:none; line-height:1.35; }
+    .mmh3p-mention-backdrop mark { color:transparent; background:rgba(101,185,255,.28);
+      border:1px solid rgba(101,185,255,.75); border-radius:4px; box-shadow:0 0 0 1px rgba(9,31,47,.45); }
+    .mmh3p-caret-mirror { position:absolute; z-index:-1; left:0; top:0; visibility:hidden;
+      pointer-events:none; white-space:pre-wrap; overflow-wrap:anywhere; word-break:break-word; }
+    .mmh3p-caret-marker { display:inline; }
+    .mmh3p-mention-menu { position:absolute; z-index:50; display:none; left:0; top:100%;
+      width:min(430px,100%); min-width:260px;
+      max-height:190px; overflow:auto; padding:4px; background:#15191e; border:1px solid #53606e;
+      border-radius:6px; box-shadow:0 8px 24px rgba(0,0,0,.5); }
+    .mmh3p-mention-menu.open { display:block; }
+    .mmh3p-mention-item { display:flex; align-items:center; gap:8px; width:100%; border:0 !important;
+      background:transparent !important; text-align:left; padding:7px 8px !important; }
+    .mmh3p-mention-item:hover,
+    .mmh3p-mention-item.active { background:#263746 !important; }
+    .mmh3p-mention-token { color:#9bd5ff; font:11px ui-monospace,Consolas,monospace; font-weight:700; }
+    .mmh3p-mention-meta { color:var(--muted); font-size:10px; overflow:hidden; text-overflow:ellipsis;
+      white-space:nowrap; }
+    .mmh3p-mention-empty { color:var(--muted); padding:8px; }
+    .mmh3p-reference-head { margin-bottom:8px; display:flex; flex-wrap:wrap; align-items:flex-start; justify-content:space-between; gap:7px 10px; }
+    .mmh3p-reference-title { min-width:0; }
+    .mmh3p-enhance-actions { margin-left:auto; display:flex; align-items:center; gap:7px; }
+    .mmh3p-enhance-actions [data-action="enhance"] {
+      box-sizing:border-box; width:112px; min-width:112px; max-width:112px; flex:0 0 112px;
+      white-space:nowrap; text-align:center;
+    }
+    .mmh3p-auto-run { display:flex; align-items:center; gap:5px; color:var(--muted); font-size:10px;
+      white-space:nowrap; cursor:pointer; user-select:none; }
+    .mmh3p-auto-run input { width:14px; height:14px; margin:0; accent-color:var(--accent); cursor:pointer; }
+    .mmh3p-auto-run:has(input:checked) { color:#a9d8ff; }
+    .mmh3p-reference-actions { flex:0 1 auto; display:flex; flex-wrap:wrap; justify-content:flex-end; align-items:center; gap:5px; }
+    .mmh3p-reference-actions button { white-space:nowrap; }
+    .mmh3p-reference-help { margin-top:2px; color:var(--muted); font-size:9px; line-height:1.3; }
+    .mmh3p-references-panel { display:flex; flex-direction:column; min-height:0; overflow:hidden; }
+    .mmh3p-reference-list { flex:1 1 auto; height:auto; min-height:0; overflow-y:auto; overflow-x:hidden;
+      display:flex; flex-direction:column; gap:6px; }
+    .mmh3p-ref { box-sizing:border-box; width:100%; min-width:0; display:grid; grid-template-columns:96px minmax(0,1fr); gap:9px; align-items:stretch;
+      padding:7px; background:#191c20; border:1px solid #343944; border-radius:6px; }
+    .mmh3p-ref-label { grid-column:1/-1; display:block; min-width:0; padding:0 2px 5px;
+      border-bottom:1px solid #303640; color:#a9d8ff;
+      font:600 10px ui-monospace,Consolas,monospace; white-space:nowrap; }
+    .mmh3p-ref input,.mmh3p-ref select { box-sizing:border-box; width:100%; min-width:0; max-width:100%; font-size:10px; height:25px; }
+    .mmh3p-ref textarea { box-sizing:border-box; width:100%; max-width:100%; min-height:48px; resize:vertical; font-size:10px; }
+    .mmh3p-ref-preview { min-width:0; height:96px; border:1px solid #3e4651; border-radius:5px;
+      background:#111419; overflow:hidden; display:flex; align-items:center; justify-content:center; color:var(--muted);
+      font-size:9px; text-align:center; cursor:pointer; }
+    .mmh3p-ref-preview:hover { border-color:var(--accent); color:#cce9ff; }
+    .mmh3p-ref-preview img,.mmh3p-ref-preview video { width:100%; height:100%; object-fit:contain; object-position:center; display:block; }
+    .mmh3p-ref-preview audio { width:92%; max-width:100%; }
+    .mmh3p-ref-body { min-width:0; display:flex; flex-direction:column; gap:5px; }
+    .mmh3p-ref.picture .mmh3p-ref-body { justify-content:center; }
+    .mmh3p-ref-controls { min-width:0; display:grid; grid-template-columns:minmax(130px,1fr) 30px;
+      gap:5px; align-items:center; }
+    .mmh3p-ref-controls.metadata-alias { grid-template-columns:minmax(130px,1fr) minmax(80px,.65fr) 30px; }
+    .mmh3p-ref-controls.video-metadata { grid-template-columns:minmax(0,1.4fr) minmax(0,.7fr) 30px; }
+    .mmh3p-subject-strength-row { display:grid; grid-template-columns:auto minmax(72px,.7fr) minmax(90px,1fr); gap:7px;
+      align-items:center; padding-top:1px; }
+    .mmh3p-subject-strength-row span { color:var(--muted); font-size:9px; font-weight:700;
+      letter-spacing:.04em; text-transform:uppercase; }
+    .mmh3p-ref-controls button { white-space:nowrap; font-size:10px; }
+    .mmh3p-ref .delete { color:#ff9797; padding:2px; }
+    .mmh3p-preview-column { min-width:0; min-height:0; height:100%; display:grid;
+      grid-template-rows:minmax(0,1fr); }
+    .mmh3p-preview-panel { min-width:0; min-height:0; display:flex; flex-direction:column; }
+    .mmh3p-preview { flex:1 1 auto; height:auto; min-height:0; max-height:none; overflow:auto; margin:0; padding:8px;
+      white-space:pre-wrap; word-break:break-word; background:#121416; border:1px solid #30353d;
+      border-radius:5px; color:#ccd2da; font:10px/1.42 ui-monospace,Consolas,monospace; }
+    .mmh3p-preview-head { justify-content:space-between; margin-bottom:6px; }
+    .mmh3p-log-panel { min-width:0; min-height:0; display:flex; flex-direction:column; }
+    .mmh3p-log { flex:1; min-height:0; overflow:auto; margin-top:6px; padding:6px 8px;
+      white-space:pre-wrap; word-break:break-word; color:#a9d1ad; background:#121416;
+      border:1px solid #30353d; border-radius:5px; font:10px/1.4 ui-monospace,Consolas,monospace; }
+    .mmh3p-log-line.error { color:var(--error); }
+    .mmh3p-log-line.warning { color:var(--warn); }
+    .mmh3p-log-line.download { color:#8dceff; }
+    .mmh3p-log-line.analysis { color:#b9dcff; padding:4px 6px; border-left:2px solid #5798ce; }
+    .mmh3p-empty { color:#777f8b; padding:14px; text-align:center; border:1px dashed #3c424c; border-radius:5px; }
+    @media (max-width:850px) { .mmh3p-grid { grid-template-columns:1fr; }
+      .mmh3p-ref { grid-template-columns:76px minmax(0,1fr); }
+      .mmh3p-ref-controls { grid-template-columns:minmax(110px,1fr) 28px; }
+      .mmh3p-ref-controls.metadata-alias { grid-template-columns:minmax(110px,1fr) minmax(72px,.6fr) 28px; }
+      .mmh3p-ref-controls.video-metadata { grid-template-columns:minmax(0,1.25fr) minmax(0,.65fr) 28px; }
+      .mmh3p-subject-strength-row { grid-template-columns:auto minmax(66px,.7fr) minmax(76px,1fr); } }
+  `;
+  document.head.appendChild(style);
+}
+
+class PrompterUI {
+  constructor(node, root, stateWidget) {
+    this.node = node;
+    this.root = root;
+    this.stateWidget = stateWidget;
+    this.project = normalizeProject(stateWidget?.value);
+    this.selectedShotId = this.project.shots[0]?.id;
+    this.previewData = null;
+    this.autoRunPreview = null;
+    this.compileTimer = null;
+    this.compileController = null;
+    this.enhanceController = null;
+    this.enhanceJobId = "";
+    this.modelBundles = [];
+    this.compileSequence = 0;
+    this.mentionSelectionIndex = 0;
+    this.mentionMenuSignature = "";
+    this.visibleMentionEntries = [];
+    this.build();
+    this.render();
+    this.commit(false);
+    this.loadModels();
+  }
+
+  build() {
+    this.root.className = "mmh3p";
+    this.root.innerHTML = `
+      <div class="mmh3p-workspace">
+      <div class="mmh3p-main">
+      <div class="mmh3p-panel mmh3p-row mmh3p-top">
+        <span class="mmh3p-label">Mode</span><select data-el="mode"></select>
+        <span class="mmh3p-label">Duration</span><input data-el="duration" type="number" min="0.1" max="60" step="0.1" style="width:76px">
+        <span class="mmh3p-badge" data-el="effective">calculating</span>
+        <span class="mmh3p-badge" data-el="path">fl2va</span>
+      </div>
+      <div class="mmh3p-panel mmh3p-row">
+        <span class="mmh3p-label">Model</span>
+        <select class="mmh3p-grow" data-el="model-bundle"><option value="">Loading Qwen3.8 bundle…</option></select>
+        <span class="mmh3p-badge" data-el="model-status"></span>
+      </div>
+      <div class="mmh3p-panel">
+        <div class="mmh3p-row mmh3p-toolbar">
+          <div class="mmh3p-row"><button data-action="add-shot">+ Shot</button><button data-action="delete-shot">Delete Shot</button></div>
+        </div>
+        <div class="mmh3p-label" style="margin-top:6px">Drag a shot boundary to resize adjacent shots · double-click to split them evenly</div>
+        <div class="mmh3p-timeline" data-el="timeline"><div class="mmh3p-ruler"><span>0s</span><span data-el="ruler-end">5.00s</span></div></div>
+      </div>
+      <div class="mmh3p-grid">
+        <div class="mmh3p-panel mmh3p-editor">
+          <div class="mmh3p-label">Prompt</div>
+          <div class="mmh3p-field mmh3p-visual-action-field"><span>Visual / action / camera / dialogue / text / sound / music — type @ to insert a reference alias</span>
+            <div class="mmh3p-mention-wrap">
+              <div class="mmh3p-mention-backdrop" data-el="visual-action-highlight"></div>
+              <textarea data-el="visual-action" spellcheck="true" placeholder="Describe visuals, actions, camera framing or movement, transitions, dialogue, visible text, sound, or music naturally in context."></textarea>
+              <div class="mmh3p-caret-mirror" data-el="caret-mirror"></div>
+              <div class="mmh3p-mention-menu" data-el="mention-menu" role="listbox"></div>
+            </div>
+          </div>
+        </div>
+        <div class="mmh3p-panel mmh3p-preview-panel">
+          <div class="mmh3p-row mmh3p-preview-head">
+            <span class="mmh3p-label">Generated Prompt</span>
+            <div class="mmh3p-enhance-actions">
+              <label class="mmh3p-auto-run" title="Use richer Qwen3.8 interpretation and expansion while preserving the requested events">
+                <input data-el="enhance" type="checkbox"><span>Enhance</span>
+              </label>
+              <button data-action="enhance" type="button">Generate Prompt</button>
+              <label class="mmh3p-auto-run" title="Generate the prompt as part of the ComfyUI queue when this node executes">
+                <input data-el="auto-run" type="checkbox"><span>Auto Run</span>
+              </label>
+            </div>
+          </div>
+          <pre class="mmh3p-preview" data-el="preview">Compiling…</pre>
+        </div>
+      </div>
+      </div>
+      <div class="mmh3p-preview-column">
+        <div class="mmh3p-panel mmh3p-references-panel">
+          <div class="mmh3p-reference-head">
+            <div class="mmh3p-reference-title">
+              <div class="mmh3p-label">References</div>
+              <div class="mmh3p-reference-help">Drag to reorder. Image, video, and audio numbering follows each type's downstream slot order.</div>
+            </div>
+            <div class="mmh3p-reference-actions">
+              <button data-action="add-ref" data-ref-type="picture" type="button">+ Image</button>
+              <button data-action="add-ref" data-ref-type="audio" type="button">+ Audio</button>
+              <button data-action="add-ref" data-ref-type="video" type="button">+ Video</button>
+            </div>
+          </div>
+          <div class="mmh3p-reference-list" data-el="references"></div>
+        </div>
+      </div>
+      </div>
+      <div class="mmh3p-panel mmh3p-log-panel">
+        <span class="mmh3p-label">Execution log</span>
+        <div class="mmh3p-log" data-el="log" aria-live="polite"></div>
+      </div>`;
+
+    this.els = Object.fromEntries([...this.root.querySelectorAll("[data-el]")].map(el => [el.dataset.el, el]));
+    MODES.forEach(mode => this.els.mode.add(new Option(mode === "AUTO" ? "Auto" : mode, mode)));
+    this.bind();
+  }
+
+  bind() {
+    this.els.mode.addEventListener("change", () => { this.project.mode = this.els.mode.value; this.commit(); this.renderHeader(); });
+    this.els.duration.addEventListener("change", () => {
+      const minimumTimeline = this.project.shots.length * MIN_SHOT_DURATION;
+      const target = clampNumber(this.els.duration.value, 5, minimumTimeline, 60);
+      fitShotDurations(this.project.shots, target);
+      this.commit(); this.render();
+    });
+    this.root.querySelector('[data-action="add-shot"]').addEventListener("click", () => this.addShot());
+    this.root.querySelector('[data-action="delete-shot"]').addEventListener("click", () => this.deleteShot());
+    this.root.querySelectorAll('[data-action="add-ref"]').forEach(button => {
+      button.addEventListener("click", () => this.addReference(button.dataset.refType));
+    });
+    this.root.querySelector('[data-action="enhance"]').addEventListener("click", () => this.enhancePrompt());
+    this.els.enhance.addEventListener("change", () => {
+      this.project.enhance = this.els.enhance.checked;
+      this.commit(false);
+      this.appendLog(
+        `Enhance ${this.project.enhance ? "enabled" : "disabled"}; Qwen3.8 will ${this.project.enhance ? "expand the prompt with richer contextual detail" : "use the standard concise generation mode"}.`,
+        "enhance-mode",
+      );
+    });
+    this.els["auto-run"].addEventListener("change", () => {
+      this.project.auto_run = this.els["auto-run"].checked;
+      this.commit(false);
+      this.appendLog(
+        `Auto Run ${this.project.auto_run ? "enabled" : "disabled"}; prompt generation ${this.project.auto_run ? "will run" : "will not run"} during ComfyUI queue execution.`,
+        "auto-run",
+      );
+    });
+    this.els["model-bundle"].addEventListener("change", () => {
+      const bundleId = this.els["model-bundle"].value || DEFAULT_MODEL_BUNDLE;
+      const profile = this.modelBundles.find(model => model.id === bundleId);
+      this.project.enhance_model = profile?.enhance_model || DEFAULT_ENHANCE_MODEL;
+      this.project.image_model = profile?.image_model || bundleId;
+      this.commit(false);
+      this.updateModelCompatibility(true);
+    });
+    this.root.querySelectorAll("[data-project]").forEach(input => input.addEventListener("input", () => {
+      this.project[input.dataset.project] = input.value;
+      this.commit();
+    }));
+    this.bindMentionEditor();
+  }
+
+  bindMentionEditor() {
+    const editor = this.els["visual-action"];
+    let composing = false;
+    const updateShot = (commitChange = true) => {
+      const shot = this.selectedShot();
+      if (!shot) return;
+      shot.visual_action = editor.value;
+      this.syncMentionHighlight();
+      this.renderMentionMenu();
+      if (commitChange) { this.commit(); this.renderTimeline(); }
+    };
+    editor.addEventListener("compositionstart", () => { composing = true; });
+    editor.addEventListener("compositionend", () => { composing = false; updateShot(true); });
+    editor.addEventListener("input", () => updateShot(!composing));
+    editor.addEventListener("click", () => this.renderMentionMenu());
+    editor.addEventListener("keyup", event => {
+      if (!["Escape", "ArrowDown", "ArrowUp", "Enter", "Tab"].includes(event.key)) this.renderMentionMenu();
+    });
+    editor.addEventListener("keydown", event => {
+      if (event.key === "Escape") {
+        this.hideMentionMenu();
+        return;
+      }
+      const menuOpen = this.els["mention-menu"].classList.contains("open");
+      if (!menuOpen || !this.visibleMentionEntries.length) return;
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault();
+        const direction = event.key === "ArrowDown" ? 1 : -1;
+        this.mentionSelectionIndex = (
+          this.mentionSelectionIndex + direction + this.visibleMentionEntries.length
+        ) % this.visibleMentionEntries.length;
+        this.updateMentionSelection();
+        return;
+      }
+      if (event.key === "Enter" || event.key === "Tab") {
+        const mention = this.currentMention();
+        const entry = this.visibleMentionEntries[this.mentionSelectionIndex];
+        if (!mention || !entry) return;
+        event.preventDefault();
+        this.insertMention(entry.alias, mention);
+      }
+    });
+    editor.addEventListener("scroll", () => {
+      this.syncMentionHighlight();
+      if (this.els["mention-menu"].classList.contains("open")) this.renderMentionMenu();
+    });
+    editor.addEventListener("blur", () => setTimeout(() => this.hideMentionMenu(), 120));
+  }
+
+  currentMention() {
+    const editor = this.els["visual-action"];
+    const end = editor.selectionStart ?? 0;
+    const before = editor.value.slice(0, end);
+    const match = before.match(/@[\p{L}\p{N}_-]*$/u);
+    if (!match) return null;
+    const start = end - match[0].length;
+    if (start > 0 && /[\p{L}\p{N}_@-]/u.test(before[start - 1])) return null;
+    return { start, end, query: match[0].slice(1).toLowerCase() };
+  }
+
+  mentionEntries() {
+    const counts = { picture: 0, video: 0, audio: 0 };
+    const seen = new Set();
+    const entries = [];
+    this.project.references.forEach(ref => {
+      counts[ref.type] += 1;
+      const alias = normalizeAlias(ref.alias);
+      if (alias.length < 2 || seen.has(alias.toLowerCase())) return;
+      seen.add(alias.toLowerCase());
+      const labelName = REFERENCE_TYPE_LABELS[ref.type];
+      entries.push({
+        alias,
+        label: `<${labelName} ${counts[ref.type]}>`,
+        role: String(ref.role || "reference").replaceAll("_", " "),
+        strength: ref.type === "picture" && ref.role === "subject_identity" ? ref.strength : "",
+        description: String(ref.description || ""),
+      });
+    });
+    return entries;
+  }
+
+  renderMentionMenu() {
+    const mention = this.currentMention();
+    const menu = this.els["mention-menu"];
+    if (!mention || document.activeElement !== this.els["visual-action"]) {
+      this.hideMentionMenu(); return;
+    }
+    const entries = this.mentionEntries().filter(entry =>
+      entry.alias.slice(1).toLowerCase().includes(mention.query)
+    );
+    const signature = `${mention.start}:${mention.query}:${entries.map(entry => entry.alias).join("|")}`;
+    if (signature !== this.mentionMenuSignature) {
+      this.mentionSelectionIndex = 0;
+      this.mentionMenuSignature = signature;
+    }
+    this.visibleMentionEntries = entries;
+    this.mentionSelectionIndex = Math.min(this.mentionSelectionIndex, Math.max(0, entries.length - 1));
+    menu.replaceChildren();
+    if (!entries.length) {
+      const empty = document.createElement("div");
+      empty.className = "mmh3p-mention-empty";
+      empty.textContent = this.project.references.some(ref => ref.alias)
+        ? "No matching aliases" : "No aliases yet — enter a name in References";
+      menu.appendChild(empty);
+    } else {
+      entries.forEach((entry, index) => {
+        const button = document.createElement("button"); button.type = "button";
+        button.className = `mmh3p-mention-item${index === this.mentionSelectionIndex ? " active" : ""}`;
+        button.setAttribute("role", "option");
+        button.setAttribute("aria-selected", index === this.mentionSelectionIndex ? "true" : "false");
+        const token = document.createElement("span"); token.className = "mmh3p-mention-token"; token.textContent = entry.alias;
+        const meta = document.createElement("span"); meta.className = "mmh3p-mention-meta";
+        meta.textContent = `${entry.label} · ${entry.role}${entry.strength ? ` (${entry.strength})` : ""}${entry.description ? ` · ${entry.description}` : ""}`;
+        button.append(token, meta);
+        button.addEventListener("mousedown", event => event.preventDefault());
+        button.addEventListener("mouseenter", () => {
+          this.mentionSelectionIndex = index;
+          this.updateMentionSelection();
+        });
+        button.addEventListener("click", () => this.insertMention(entry.alias, mention));
+        menu.appendChild(button);
+      });
+    }
+    menu.classList.add("open");
+    this.positionMentionMenu(mention);
+  }
+
+  updateMentionSelection() {
+    const buttons = [...this.els["mention-menu"].querySelectorAll(".mmh3p-mention-item")];
+    buttons.forEach((button, index) => {
+      const active = index === this.mentionSelectionIndex;
+      button.classList.toggle("active", active);
+      button.setAttribute("aria-selected", active ? "true" : "false");
+    });
+    buttons[this.mentionSelectionIndex]?.scrollIntoView({ block: "nearest" });
+  }
+
+  positionMentionMenu(mention) {
+    const editor = this.els["visual-action"];
+    const mirror = this.els["caret-mirror"];
+    const menu = this.els["mention-menu"];
+    const style = getComputedStyle(editor);
+    mirror.style.width = `${editor.clientWidth}px`;
+    mirror.style.minHeight = `${editor.offsetHeight}px`;
+    mirror.style.boxSizing = style.boxSizing;
+    mirror.style.padding = style.padding;
+    mirror.style.border = style.border;
+    mirror.style.font = style.font;
+    mirror.style.letterSpacing = style.letterSpacing;
+    mirror.style.lineHeight = style.lineHeight;
+    mirror.style.tabSize = style.tabSize;
+    mirror.style.textAlign = style.textAlign;
+    mirror.style.textIndent = style.textIndent;
+    mirror.style.textTransform = style.textTransform;
+    mirror.style.wordSpacing = style.wordSpacing;
+    mirror.style.whiteSpace = style.whiteSpace;
+    mirror.style.overflowWrap = style.overflowWrap;
+    mirror.style.wordBreak = style.wordBreak;
+    mirror.replaceChildren(document.createTextNode(editor.value.slice(0, mention.start)));
+    const marker = document.createElement("span");
+    marker.className = "mmh3p-caret-marker";
+    marker.textContent = editor.value.slice(mention.start, mention.end) || "@";
+    mirror.appendChild(marker);
+    const lineHeight = Number.parseFloat(style.lineHeight) || Number.parseFloat(style.fontSize) * 1.35 || 18;
+    const desiredLeft = marker.offsetLeft - editor.scrollLeft;
+    const desiredTop = marker.offsetTop - editor.scrollTop + lineHeight + 3;
+    const maxLeft = Math.max(0, editor.clientWidth - menu.offsetWidth);
+    menu.style.left = `${Math.max(0, Math.min(maxLeft, desiredLeft))}px`;
+    menu.style.top = `${Math.max(lineHeight, desiredTop)}px`;
+  }
+
+  insertMention(alias, mention) {
+    const editor = this.els["visual-action"];
+    editor.setRangeText(`${alias} `, mention.start, mention.end, "end");
+    const shot = this.selectedShot();
+    if (shot) shot.visual_action = editor.value;
+    this.syncMentionHighlight();
+    this.hideMentionMenu();
+    editor.focus();
+    this.commit(); this.renderTimeline();
+  }
+
+  hideMentionMenu() {
+    this.els["mention-menu"]?.classList.remove("open");
+    this.visibleMentionEntries = [];
+    this.mentionMenuSignature = "";
+    this.mentionSelectionIndex = 0;
+  }
+
+  syncMentionHighlight() {
+    const editor = this.els["visual-action"];
+    const backdrop = this.els["visual-action-highlight"];
+    if (!editor || !backdrop) return;
+    const text = editor.value;
+    const regex = /@[\p{L}\p{N}_-]+/gu;
+    let cursor = 0;
+    const nodes = [];
+    for (const match of text.matchAll(regex)) {
+      if (match.index > cursor) nodes.push(document.createTextNode(text.slice(cursor, match.index)));
+      const mark = document.createElement("mark"); mark.textContent = match[0]; nodes.push(mark);
+      cursor = match.index + match[0].length;
+    }
+    if (cursor < text.length) nodes.push(document.createTextNode(text.slice(cursor)));
+    if (text.endsWith("\n")) nodes.push(document.createTextNode(" "));
+    backdrop.replaceChildren(...nodes);
+    backdrop.scrollTop = editor.scrollTop;
+    backdrop.scrollLeft = editor.scrollLeft;
+  }
+
+  totalDuration() { return this.project.shots.reduce((sum, shot) => sum + Number(shot.duration || 0), 0); }
+  selectedShot() { return this.project.shots.find(shot => shot.id === this.selectedShotId) || this.project.shots[0]; }
+
+  addShot() {
+    const selected = this.selectedShot();
+    if (!selected || selected.duration < MIN_SHOT_DURATION * 2) return;
+    const selectedIndex = this.project.shots.findIndex(item => item.id === selected.id);
+    const firstHalf = selected.duration / 2;
+    selected.duration = firstHalf;
+    const shot = {
+      id: uid("shot"), duration: firstHalf, visual_action: "",
+    };
+    this.project.shots.splice(selectedIndex + 1, 0, shot);
+    this.selectedShotId = shot.id; this.commit(); this.render();
+  }
+
+  deleteShot() {
+    if (this.project.shots.length <= 1) return;
+    const index = this.project.shots.findIndex(shot => shot.id === this.selectedShotId);
+    const removed = this.project.shots.splice(Math.max(0, index), 1)[0];
+    const recipientIndex = index > 0 ? index - 1 : 0;
+    this.project.shots[recipientIndex].duration += removed.duration;
+    this.selectedShotId = this.project.shots[recipientIndex].id;
+    this.commit(); this.render();
+  }
+
+  addReference(type) {
+    if (!REFERENCE_ROLES[type]) return;
+    const typeCount = this.project.references.filter(ref => ref.type === type).length;
+    if (typeCount >= MAX_REFERENCES[type] || this.project.references.length >= MAX_REFERENCES.total) return;
+    this.project.references.push({
+      id: uid("ref"), type, role: REFERENCE_ROLES[type][0], strength: "normal", alias: "", description: "", duration: 0,
+      image_filename: "", image_subfolder: "", image_type: "input",
+      video_filename: "", video_subfolder: "", video_type: "input",
+      audio_filename: "", audio_subfolder: "", audio_type: "input",
+    });
+    this.commit(); this.renderReferences(); this.renderHeader();
+  }
+
+  commit(refresh = true) {
+    this.project.requested_duration = Number(this.totalDuration().toFixed(3));
+    if (this.stateWidget) {
+      this.stateWidget.value = JSON.stringify(this.project);
+      try { this.stateWidget.callback?.(this.stateWidget.value); } catch {}
+    }
+    this.node.properties ||= {};
+    this.node.properties.minimax_h3_project_version = CURRENT_PROJECT_VERSION;
+    this.node.setDirtyCanvas?.(true, true);
+    if (refresh) this.scheduleCompile();
+  }
+
+  appendLog(message, key = "", kind = "") {
+    if (!this.els.log || !message) return;
+    let line = key ? this.els.log.querySelector(`[data-log-key="${CSS.escape(key)}"]`) : null;
+    if (!line) {
+      line = document.createElement("div");
+      line.className = "mmh3p-log-line";
+      if (key) line.dataset.logKey = key;
+      this.els.log.appendChild(line);
+    }
+    line.className = `mmh3p-log-line${kind ? ` ${kind}` : ""}`;
+    const timestamp = new Date().toLocaleTimeString("en-GB", {
+      hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false,
+    });
+    line.textContent = `[${timestamp}] ${message}`;
+    // Moving an updated keyed entry to the end keeps the visible log in true
+    // chronological order instead of retaining its original insertion slot.
+    this.els.log.appendChild(line);
+    while (this.els.log.children.length > 80) this.els.log.firstElementChild?.remove();
+    this.els.log.scrollTop = this.els.log.scrollHeight;
+  }
+
+  async pollEnhanceProgress(jobId, controller) {
+    let lastStage = "";
+    while (!controller.signal.aborted) {
+      try {
+        const response = await api.fetchApi(`${ENHANCE_STATUS_ENDPOINT}?job_id=${encodeURIComponent(jobId)}`, {
+          signal: controller.signal,
+        });
+        const data = await response.json();
+        const job = data.job || {};
+        if (job.stage === "downloading") {
+          const downloaded = Number(job.downloaded || 0);
+          const total = Number(job.total || 0);
+          const percent = total > 0 ? Math.min(100, downloaded / total * 100) : 0;
+          this.appendLog(
+            `Downloading model: ${(downloaded / 1e9).toFixed(2)} / ${(total / 1e9).toFixed(2)} GB (${percent.toFixed(1)}%)`,
+            "enhance-download",
+            "download",
+          );
+        } else if (job.stage === "reference_analysis") {
+          this.appendLog(job.message || "Analyzing registered visual references.", "enhance-reference-analysis");
+        } else if (job.stage && job.stage !== lastStage) {
+          this.appendLog(job.message || job.stage, `enhance-${job.stage}`, job.stage === "error" ? "error" : "");
+        }
+        lastStage = job.stage || lastStage;
+        if (["complete", "error"].includes(job.stage)) return;
+      } catch (error) {
+        if (error?.name === "AbortError") return;
+      }
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  }
+
+  async loadModels() {
+    const select = this.els["model-bundle"];
+    const button = this.root.querySelector('[data-action="enhance"]');
+    try {
+      const response = await api.fetchApi(MODELS_ENDPOINT);
+      const data = await response.json();
+      if (!response.ok || data.status !== "success") throw new Error(data.message || "Could not list models");
+      this.modelBundles = data.image_models || [];
+      select.replaceChildren();
+      this.modelBundles.forEach(model => select.add(new Option(model.label, model.id)));
+      if (!this.modelBundles.length) throw new Error("No prompt generation model is available");
+      const savedBundle = this.modelBundles.some(model => model.id === this.project.image_model)
+        ? this.project.image_model : DEFAULT_MODEL_BUNDLE;
+      select.value = savedBundle;
+      const selected = this.modelBundles.find(model => model.id === savedBundle);
+      this.project.enhance_model = selected?.enhance_model || DEFAULT_ENHANCE_MODEL;
+      this.project.image_model = selected?.image_model || savedBundle;
+      this.commit(false);
+      this.updateModelCompatibility(false);
+      this.appendLog(`${this.modelBundles.length} prompt generation model bundle(s) available.`, "models");
+    } catch (error) {
+      select.replaceChildren(new Option("Qwen3.8 + Vision F16 bundle unavailable", ""));
+      button.disabled = true;
+      button.title = error.message || String(error);
+      this.appendLog(`Model list failed: ${error.message || error}`, "models", "error");
+    }
+  }
+
+  updateModelCompatibility(writeLog = false) {
+    const button = this.root.querySelector('[data-action="enhance"]');
+    const bundleId = this.els["model-bundle"]?.value || this.project.image_model || DEFAULT_MODEL_BUNDLE;
+    const profile = this.modelBundles.find(model => model.id === bundleId);
+    const mode = this.project.mode === "AUTO" ? inferAutoMode(this.project.references) : this.project.mode;
+    const supported = !profile?.supported_modes?.length || profile.supported_modes.includes(mode);
+    const status = this.els["model-status"];
+    const qwenEnhanceAvailable = (profile?.enhance_model || DEFAULT_ENHANCE_MODEL) === DEFAULT_ENHANCE_MODEL;
+    if (this.els.enhance) {
+      this.els.enhance.disabled = !qwenEnhanceAvailable;
+      this.els.enhance.closest("label").title = qwenEnhanceAvailable
+        ? "Use richer Qwen3.8 interpretation and expansion while preserving the requested events"
+        : "Enhance mode is available only with Qwen3.8";
+    }
+    if (status) {
+      status.textContent = supported ? "ready" : `${mode} unsupported`;
+      status.classList.toggle("error", !supported);
+    }
+    if (button && !this.enhanceController) {
+      button.disabled = !supported;
+      button.title = supported ? "" : `${profile?.label || "Selected model"} does not support ${mode}.`;
+    }
+    if (!supported && writeLog) {
+      this.appendLog(
+        `The selected LightX2V 8B rewriter does not support ${mode}. Select Qwen3.8 for R2V/REF2VA.`,
+        "model-compatibility", "error",
+      );
+    }
+    return supported;
+  }
+
+  async enhancePrompt() {
+    const button = this.root.querySelector('[data-action="enhance"]');
+    if (this.enhanceController) {
+      await this.cancelPromptGeneration();
+      return;
+    }
+    const originalLabel = button.textContent;
+    if (!this.updateModelCompatibility(true)) return;
+    const selectedBundle = this.els["model-bundle"].value || DEFAULT_MODEL_BUNDLE;
+    const modelInfo = this.modelBundles.find(model => model.id === selectedBundle);
+    const selectedModel = modelInfo?.enhance_model || DEFAULT_ENHANCE_MODEL;
+    const selectedImageModel = modelInfo?.image_model || selectedBundle;
+    const needsImageAnalysis = this.project.references.some(ref =>
+      ref.type === "picture" && ref.image_filename
+    );
+    const needsVideoAnalysis = this.project.references.some(ref =>
+      ref.type === "video" && ref.video_filename && Number(ref.duration) > 0
+    );
+    const needsVisualAnalysis = needsImageAnalysis || needsVideoAnalysis;
+    const missingBytes = Number(modelInfo?.text_size || 0)
+      + (needsVisualAnalysis ? Number(modelInfo?.vision_size || 0) : 0);
+    if (missingBytes > 0) {
+      const sizeGb = (missingBytes / 1e9).toFixed(2);
+      const purpose = needsVisualAnalysis ? "generate the prompt and analyze its visual references" : "generate the prompt";
+      if (!window.confirm(`Download ${sizeGb} GB for ${modelInfo?.label || "Qwen3.8 + Vision F16"} and ${purpose}?`)) return;
+    }
+    clearTimeout(this.compileTimer);
+    this.compileController?.abort();
+    this.enhanceController?.abort();
+    const controller = new AbortController();
+    this.enhanceController = controller;
+    const jobId = crypto.randomUUID?.() || `enhance-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    this.enhanceJobId = jobId;
+    button.disabled = false;
+    button.textContent = "Stop";
+    button.title = "Stop the current prompt generation";
+    const sourceProject = JSON.stringify({ ...this.project, enhanced_prompt: "" });
+    this.appendLog("Prompt generation started.", `enhance-start-${jobId}`);
+    const progressPromise = this.pollEnhanceProgress(jobId, controller);
+    try {
+      const response = await api.fetchApi(ENHANCE_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          project_data: sourceProject,
+          model: selectedModel,
+          image_model: selectedImageModel,
+          job_id: jobId,
+        }),
+        signal: controller.signal,
+      });
+      const data = await response.json();
+      if (!response.ok || data.status !== "success") throw new Error(data.message || "Prompt generation failed");
+      if (JSON.stringify({ ...this.project, enhanced_prompt: "" }) !== sourceProject) {
+        throw new Error("The project changed while prompt generation was running; the stale result was discarded.");
+      }
+      if (data.reference_analyses?.length) {
+        const count = data.reference_analyses.length;
+        this.appendLog(
+          `Analyzed ${count} visual reference asset${count === 1 ? "" : "s"} using ${count === 1 ? "its" : "their"} assigned role${count === 1 ? "" : "s"}.`,
+          `enhance-reference-result-${jobId}`,
+        );
+        data.reference_analyses.forEach((item, index) => {
+          const label = item.label || `Picture ${index + 1}`;
+          const role = item.role || "unknown";
+          const filename = item.filename ? ` — ${item.filename}` : "";
+          this.appendLog(
+            `Vision analysis for ${label} [role=${role}]${filename}\n${item.analysis || "No analysis text returned."}`,
+            `enhance-reference-analysis-result-${jobId}-${item.id || index}`,
+            "analysis",
+          );
+        });
+      }
+      this.project.enhance_model = data.model;
+      this.project.image_model = selectedBundle;
+      this.project.enhanced_prompt = data.enhanced_prompt;
+      this.autoRunPreview = null;
+      if (modelInfo) modelInfo.installed = true;
+      this.commit(false);
+      this.renderReferences();
+      await this.compile();
+      this.appendLog("Generated prompt is ready.", `enhance-result-${jobId}`);
+    } catch (error) {
+      if (error?.name === "AbortError") return;
+      this.appendLog(`Prompt generation failed: ${error.message || error}`, `enhance-error-${jobId}`, "error");
+    } finally {
+      controller.abort();
+      await progressPromise;
+      if (this.enhanceController === controller) this.enhanceController = null;
+      if (this.enhanceJobId === jobId) this.enhanceJobId = "";
+      button.textContent = originalLabel;
+      this.updateModelCompatibility(false);
+    }
+  }
+
+  async cancelPromptGeneration() {
+    const controller = this.enhanceController;
+    const jobId = this.enhanceJobId;
+    if (!controller) return;
+    const button = this.root.querySelector('[data-action="enhance"]');
+    button.disabled = true;
+    button.textContent = "Stopping…";
+    this.appendLog("Stopping prompt generation.", `enhance-cancel-${jobId}`);
+    try {
+      if (jobId) {
+        await api.fetchApi(ENHANCE_CANCEL_ENDPOINT, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ job_id: jobId }),
+        });
+      }
+    } catch (error) {
+      this.appendLog(`Stop request failed: ${error.message || error}`, `enhance-cancel-error-${jobId}`, "error");
+    } finally {
+      controller.abort();
+      this.appendLog("Prompt generation stopped.", `enhance-cancelled-${jobId}`);
+    }
+  }
+
+  scheduleCompile() {
+    clearTimeout(this.compileTimer);
+    this.compileTimer = setTimeout(() => this.compile(), 300);
+  }
+
+  async compile() {
+    const sequence = ++this.compileSequence;
+    this.compileController?.abort();
+    const controller = new AbortController();
+    this.compileController = controller;
+    this.appendLog("Updating raw prompt from the current node inputs…", "compile");
+    try {
+      const response = await api.fetchApi(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ project_data: JSON.stringify(this.project) }),
+        signal: controller.signal,
+      });
+      const data = await response.json();
+      if (sequence !== this.compileSequence) return;
+      if (!response.ok || data.status !== "success") throw new Error(data.message || "Compilation failed");
+      this.previewData = data;
+      this.resolvedMode = data.resolved_mode || inferAutoMode(this.project.references);
+      this.els.effective.textContent = `${data.effective_frames}f / ${Number(data.effective_duration).toFixed(2)}s`;
+      const validationLine = this.els.log?.querySelector('[data-log-key="validation"]');
+      if (data.errors.length) {
+        this.appendLog(`Validation failed: ${data.errors.join(" | ")}`, "validation", "error");
+      } else if (data.warnings.length) {
+        this.appendLog(`Validation warning: ${data.warnings.join(" | ")}`, "validation", "warning");
+      } else {
+        validationLine?.remove();
+      }
+      this.renderPreview();
+      this.renderHeader();
+      this.appendLog("Node inputs updated.", "compile");
+    } catch (error) {
+      if (error?.name === "AbortError" || sequence !== this.compileSequence) return;
+      this.appendLog(`Input update failed: ${error.message || error}`, "compile", "error");
+    } finally {
+      if (sequence === this.compileSequence) this.compileController = null;
+    }
+  }
+
+  render() {
+    this.renderHeader(); this.renderTimeline(); this.renderShotEditor(); this.renderReferences();
+    this.scheduleCompile();
+  }
+
+  renderHeader() {
+    this.els.mode.value = this.project.mode;
+    this.els["auto-run"].checked = this.project.auto_run === true;
+    this.els.enhance.checked = this.project.enhance === true;
+    this.els.duration.value = this.totalDuration().toFixed(2);
+    const resolvedMode = this.project.mode === "AUTO"
+      ? inferAutoMode(this.project.references)
+      : this.project.mode;
+    this.els.path.textContent = this.project.mode === "AUTO"
+      ? `auto → ${resolvedMode.toLowerCase()}`
+      : resolvedMode.toLowerCase();
+    this.els["ruler-end"].textContent = `${this.totalDuration().toFixed(2)}s`;
+    this.root.querySelector('[data-action="add-shot"]').disabled =
+      !this.selectedShot() || this.selectedShot().duration < MIN_SHOT_DURATION * 2;
+    this.root.querySelectorAll('[data-action="add-ref"]').forEach(button => {
+      const refType = button.dataset.refType;
+      const refTypeCount = this.project.references.filter(ref => ref.type === refType).length;
+      button.disabled =
+        refTypeCount >= MAX_REFERENCES[refType] || this.project.references.length >= MAX_REFERENCES.total;
+      button.title = button.disabled
+        ? `Reference limit reached (${refTypeCount}/${MAX_REFERENCES[refType]}, total ${this.project.references.length}/${MAX_REFERENCES.total})`
+        : `Add ${REFERENCE_TYPE_LABELS[refType].toLowerCase()} reference (${refTypeCount}/${MAX_REFERENCES[refType]})`;
+    });
+    if (this.modelBundles.length) this.updateModelCompatibility(false);
+  }
+
+  renderTimeline() {
+    this.els.timeline.querySelectorAll(".mmh3p-shot").forEach(el => el.remove());
+    const total = Math.max(0.1, this.totalDuration());
+    this.project.shots.forEach((shot, index) => {
+      const card = document.createElement("div");
+      card.className = `mmh3p-shot${shot.id === this.selectedShotId ? " selected" : ""}`;
+      card.dataset.shotId = shot.id;
+      card.draggable = true;
+      card.style.flex = `${Math.max(0.1, shot.duration) / total} 1 0`;
+      const head = document.createElement("div"); head.className = "mmh3p-row";
+      const title = document.createElement("span"); title.className = "mmh3p-shot-title"; title.textContent = `Shot ${index + 1}`;
+      const duration = document.createElement("span"); duration.className = "mmh3p-shot-duration";
+      duration.textContent = `${shot.duration.toFixed(2)}s`;
+      head.append(title, duration);
+      const summary = document.createElement("div"); summary.className = "mmh3p-shot-summary";
+      summary.textContent = shot.visual_action || "Click to describe this shot.";
+      card.append(head, summary);
+      card.addEventListener("click", () => { this.selectedShotId = shot.id; this.renderTimeline(); this.renderShotEditor(); });
+      card.addEventListener("dragstart", event => {
+        if (this.root.classList.contains("resizing")) { event.preventDefault(); return; }
+        event.dataTransfer.setData("text/plain", shot.id); card.classList.add("dragging");
+      });
+      card.addEventListener("dragend", () => card.classList.remove("dragging"));
+      card.addEventListener("dragover", event => event.preventDefault());
+      card.addEventListener("drop", event => {
+        event.preventDefault();
+        const sourceId = event.dataTransfer.getData("text/plain");
+        const from = this.project.shots.findIndex(item => item.id === sourceId);
+        const to = this.project.shots.findIndex(item => item.id === shot.id);
+        if (from >= 0 && to >= 0 && from !== to) {
+          const [moved] = this.project.shots.splice(from, 1); this.project.shots.splice(to, 0, moved);
+          this.commit(); this.renderTimeline();
+        }
+      });
+      if (index < this.project.shots.length - 1) {
+        const handle = document.createElement("div");
+        handle.className = "mmh3p-resize-handle";
+        handle.title = "Drag to resize the two adjacent shots";
+        handle.addEventListener("pointerdown", event => this.beginShotResize(event, index, handle));
+        handle.addEventListener("dblclick", event => {
+          event.preventDefault(); event.stopPropagation();
+          const pairTotal = this.project.shots[index].duration + this.project.shots[index + 1].duration;
+          this.project.shots[index].duration = pairTotal / 2;
+          this.project.shots[index + 1].duration = pairTotal / 2;
+          this.commit(); this.renderTimeline();
+        });
+        card.appendChild(handle);
+      }
+      this.els.timeline.appendChild(card);
+    });
+  }
+
+  beginShotResize(event, index, handle) {
+    event.preventDefault(); event.stopPropagation();
+    if (index < 0 || index >= this.project.shots.length - 1) return;
+    const leftShot = this.project.shots[index];
+    const rightShot = this.project.shots[index + 1];
+    const pairTotal = leftShot.duration + rightShot.duration;
+    if (pairTotal < MIN_SHOT_DURATION * 2) return;
+    const startX = event.clientX;
+    const startLeft = leftShot.duration;
+    const timelineWidth = Math.max(1, this.els.timeline.getBoundingClientRect().width);
+    const secondsPerPixel = this.totalDuration() / timelineWidth;
+    this.root.classList.add("resizing"); handle.classList.add("active");
+    handle.setPointerCapture?.(event.pointerId);
+
+    const onMove = moveEvent => {
+      let nextLeft = startLeft + (moveEvent.clientX - startX) * secondsPerPixel;
+      nextLeft = Math.round(nextLeft / SHOT_SNAP_SECONDS) * SHOT_SNAP_SECONDS;
+      nextLeft = Math.max(MIN_SHOT_DURATION, Math.min(pairTotal - MIN_SHOT_DURATION, nextLeft));
+      leftShot.duration = nextLeft;
+      rightShot.duration = pairTotal - nextLeft;
+      const leftCard = this.els.timeline.querySelector(`[data-shot-id="${leftShot.id}"]`);
+      const rightCard = this.els.timeline.querySelector(`[data-shot-id="${rightShot.id}"]`);
+      if (leftCard && rightCard) {
+        leftCard.style.flex = `${leftShot.duration / this.totalDuration()} 1 0`;
+        rightCard.style.flex = `${rightShot.duration / this.totalDuration()} 1 0`;
+        leftCard.querySelector(".mmh3p-shot-duration").textContent = `${leftShot.duration.toFixed(2)}s`;
+        rightCard.querySelector(".mmh3p-shot-duration").textContent = `${rightShot.duration.toFixed(2)}s`;
+      }
+    };
+    const onUp = upEvent => {
+      handle.releasePointerCapture?.(upEvent.pointerId);
+      handle.removeEventListener("pointermove", onMove);
+      handle.removeEventListener("pointerup", onUp);
+      handle.removeEventListener("pointercancel", onUp);
+      this.root.classList.remove("resizing"); handle.classList.remove("active");
+      this.commit(); this.renderHeader(); this.renderTimeline();
+    };
+    handle.addEventListener("pointermove", onMove);
+    handle.addEventListener("pointerup", onUp);
+    handle.addEventListener("pointercancel", onUp);
+  }
+
+  renderShotEditor() {
+    const shot = this.selectedShot();
+    if (!shot) return;
+    this.els["visual-action"].value = shot.visual_action || "";
+    this.syncMentionHighlight();
+    this.hideMentionMenu();
+  }
+
+  renderReferences() {
+    this.syncReferenceOutputs();
+    const container = this.els.references; container.replaceChildren();
+    if (!this.project.references.length) {
+      const empty = document.createElement("div"); empty.className = "mmh3p-empty";
+      empty.textContent = "No references. Add metadata in the exact downstream order for each media type."; container.appendChild(empty); return;
+    }
+    const counts = { picture: 0, video: 0, audio: 0 };
+    this.project.references.forEach(ref => {
+      counts[ref.type] += 1;
+      const label = `<${REFERENCE_TYPE_LABELS[ref.type]} ${counts[ref.type]}>`;
+      const row = document.createElement("div"); row.className = `mmh3p-ref ${ref.type}`;
+      row.draggable = true;
+      row.title = "Drag to reorder references";
+      const labelEl = document.createElement("span"); labelEl.className = "mmh3p-ref-label"; labelEl.textContent = label;
+      const role = document.createElement("select");
+      if (role) {
+        REFERENCE_ROLES[ref.type].forEach(value => {
+          const words = value.replaceAll("_", " ");
+          role.add(new Option(REFERENCE_ROLE_LABELS[value] || words.charAt(0).toUpperCase() + words.slice(1), value));
+        });
+        role.value = ref.role;
+        role.title = REFERENCE_ROLE_HELP[ref.role] || "How this reference should influence the generated video";
+      }
+      const strength = document.createElement("select");
+      strength.className = "subject-strength";
+      SUBJECT_STRENGTHS.forEach(value => strength.add(new Option(SUBJECT_STRENGTH_LABELS[value], value)));
+      strength.value = SUBJECT_STRENGTHS.includes(ref.strength) ? ref.strength : "normal";
+      strength.title = "Weak: broad similarity; Normal: core identity; Strong: complete visible appearance and the subject's source visual style";
+      const alias = document.createElement("input"); alias.placeholder = "alias";
+      alias.value = String(ref.alias || "").replace(/^@+/, "");
+      const desc = ref.type === "picture" ? null : document.createElement("textarea");
+      if (desc) {
+        desc.className = "desc";
+        desc.placeholder = ref.type === "audio"
+          ? (AUDIO_DESCRIPTION_PLACEHOLDERS[ref.role] || AUDIO_DESCRIPTION_PLACEHOLDERS.none)
+          : "Describe how this video should guide the target in English";
+        desc.value = ref.description;
+      }
+      const del = document.createElement("button"); del.className = "delete"; del.textContent = "×"; del.title = "Delete reference";
+      const preview = document.createElement("div"); preview.className = "mmh3p-ref-preview";
+      const body = document.createElement("div"); body.className = "mmh3p-ref-body";
+      const controls = document.createElement("div"); controls.className = "mmh3p-ref-controls";
+      if (ref.type === "video" || ref.type === "audio") controls.classList.add("video-metadata");
+      const strengthRow = document.createElement("div"); strengthRow.className = "mmh3p-subject-strength-row";
+      const strengthLabel = document.createElement("span"); strengthLabel.textContent = "Strength";
+      strengthRow.append(strengthLabel, strength, alias);
+      const fileInput = document.createElement("input"); fileInput.type = "file";
+      fileInput.accept = ref.type === "video"
+        ? "video/mp4,video/webm,video/quicktime,video/x-matroska,video/x-msvideo,.m4v"
+        : ref.type === "audio"
+          ? "audio/wav,audio/mpeg,audio/flac,audio/ogg,audio/mp4,audio/aac,.m4a,.opus"
+        : "image/png,image/jpeg,image/webp,image/bmp";
+      fileInput.hidden = true;
+      if (ref.type === "picture") {
+        if (ref.image_filename) {
+          const img = document.createElement("img"); img.alt = `${label} preview`;
+          img.src = api.apiURL(`/view?${new URLSearchParams({
+            filename: ref.image_filename, subfolder: ref.image_subfolder || "", type: "input",
+          }).toString()}`);
+          preview.appendChild(img);
+          preview.title = "Click the preview to replace this image";
+        } else {
+          preview.textContent = "Click to add\nimage";
+          preview.title = "Click to upload a reference image";
+        }
+        preview.addEventListener("click", event => { event.stopPropagation(); fileInput.click(); });
+        fileInput.addEventListener("change", async () => {
+          const file = fileInput.files?.[0];
+          if (file) await this.uploadReferenceImage(ref, file);
+        });
+      } else if (ref.type === "video") {
+        if (ref.video_filename) {
+          const video = document.createElement("video");
+          video.muted = true; video.controls = true; video.preload = "metadata";
+          video.src = api.apiURL(`${VIDEO_VIEW_ENDPOINT}?${new URLSearchParams({
+            filename: ref.video_filename, subfolder: ref.video_subfolder || "",
+          }).toString()}`);
+          video.addEventListener("pointerdown", event => event.stopPropagation());
+          video.addEventListener("dblclick", event => {
+            event.stopPropagation(); fileInput.click();
+          });
+          preview.appendChild(video);
+          preview.title = "Double-click the video to replace it";
+        } else {
+          preview.textContent = "Click to add\nvideo";
+          preview.title = "Click to upload a reference video";
+        }
+        preview.addEventListener("click", event => {
+          if (event.target?.tagName === "VIDEO") return;
+          event.stopPropagation(); fileInput.click();
+        });
+        fileInput.addEventListener("change", async () => {
+          const file = fileInput.files?.[0];
+          if (file) await this.uploadReferenceVideo(ref, file);
+        });
+      } else if (ref.type === "audio") {
+        if (ref.audio_filename) {
+          const audio = document.createElement("audio");
+          audio.controls = true; audio.preload = "metadata";
+          audio.src = api.apiURL(`/view?${new URLSearchParams({
+            filename: ref.audio_filename, subfolder: ref.audio_subfolder || "", type: "input",
+          }).toString()}`);
+          audio.addEventListener("pointerdown", event => event.stopPropagation());
+          preview.appendChild(audio);
+          preview.title = "Double-click to replace this audio";
+          preview.addEventListener("dblclick", event => { event.stopPropagation(); fileInput.click(); });
+        } else {
+          preview.textContent = "Click to add\naudio";
+          preview.title = "Click to upload reference audio";
+        }
+        preview.addEventListener("click", event => {
+          if (event.target?.tagName === "AUDIO") return;
+          event.stopPropagation(); fileInput.click();
+        });
+        fileInput.addEventListener("change", async () => {
+          const file = fileInput.files?.[0];
+          if (file) await this.uploadReferenceAudio(ref, file);
+        });
+      }
+      if (role) {
+        role.addEventListener("change", () => {
+          ref.role = role.value;
+          if (ref.role === "subject_identity" && !SUBJECT_STRENGTHS.includes(ref.strength)) ref.strength = "normal";
+          role.title = REFERENCE_ROLE_HELP[ref.role] || "How this reference should influence the generated video";
+          if (ref.type === "picture") ref.description = "";
+          this.commit(); this.renderReferences(); this.renderHeader();
+        });
+      }
+      strength.addEventListener("change", () => {
+        ref.strength = strength.value;
+        this.commit();
+      });
+      if (desc) {
+        desc.addEventListener("input", () => { ref.description = desc.value; this.commit(); });
+      }
+      del.addEventListener("click", () => {
+        this.project.references = this.project.references.filter(item => item.id !== ref.id);
+        this.commit(); this.renderReferences(); this.renderHeader();
+      });
+      row.addEventListener("dragstart", event => { event.dataTransfer.setData("text/plain", ref.id); row.classList.add("dragging"); });
+      row.addEventListener("dragend", () => row.classList.remove("dragging"));
+      row.addEventListener("dragover", event => event.preventDefault());
+      row.addEventListener("drop", event => {
+        event.preventDefault();
+        const sourceId = event.dataTransfer.getData("text/plain");
+        const from = this.project.references.findIndex(item => item.id === sourceId);
+        const to = this.project.references.findIndex(item => item.id === ref.id);
+        if (from >= 0 && to >= 0 && from !== to) {
+          const [moved] = this.project.references.splice(from, 1);
+          this.project.references.splice(to, 0, moved);
+          this.commit(); this.renderReferences(); this.renderHeader();
+        }
+      });
+      alias.addEventListener("input", () => {
+        ref.alias = normalizeAlias(alias.value);
+        this.syncMentionHighlight();
+        this.commit();
+      });
+      alias.addEventListener("blur", () => {
+        alias.value = String(ref.alias || "").replace(/^@+/, "");
+        this.commit();
+      });
+      const showStrength = ref.type === "picture" && ref.role === "subject_identity";
+      if (ref.type === "video") controls.append(role, alias, del);
+      else if (ref.type === "audio") controls.append(role, alias, del);
+      else controls.append(role, del);
+      body.append(controls);
+      if (showStrength) body.append(strengthRow);
+      if (desc) body.append(desc);
+      body.append(fileInput);
+      row.append(labelEl, preview, body); container.appendChild(row);
+    });
+  }
+
+  syncReferenceOutputs() {
+    const fixedOutputCount = 2;
+    const pictureCount = Math.min(
+      MAX_REFERENCES.picture,
+      this.project.references.filter(ref => ref.type === "picture").length,
+    );
+    const videoCount = Math.min(
+      MAX_REFERENCES.video,
+      this.project.references.filter(ref => ref.type === "video").length,
+    );
+    const audioCount = Math.min(
+      MAX_REFERENCES.audio,
+      this.project.references.filter(ref => ref.type === "audio").length,
+    );
+    const targetOutputCount = fixedOutputCount + pictureCount + videoCount + audioCount;
+    this.node.outputs ||= [];
+    while (this.node.outputs.length > targetOutputCount) {
+      this.node.removeOutput(this.node.outputs.length - 1);
+    }
+    while (this.node.outputs.length < targetOutputCount) {
+      const mediaIndex = this.node.outputs.length - fixedOutputCount;
+      if (mediaIndex < pictureCount) this.node.addOutput(`image_${mediaIndex + 1}`, "IMAGE");
+      else if (mediaIndex < pictureCount + videoCount) {
+        this.node.addOutput(`video_${mediaIndex - pictureCount + 1}`, "VIDEO");
+      } else {
+        this.node.addOutput(`audio_${mediaIndex - pictureCount - videoCount + 1}`, "AUDIO");
+      }
+    }
+    if (this.node.outputs[0]) {
+      this.node.outputs[0].name = "generated_prompt";
+      this.node.outputs[0].type = "STRING";
+    }
+    if (this.node.outputs[1]) {
+      this.node.outputs[1].name = "length";
+      this.node.outputs[1].type = "INT";
+    }
+    for (let index = 0; index < pictureCount; index += 1) {
+      this.node.outputs[fixedOutputCount + index].name = `image_${index + 1}`;
+      this.node.outputs[fixedOutputCount + index].type = "IMAGE";
+    }
+    for (let index = 0; index < videoCount; index += 1) {
+      const output = this.node.outputs[fixedOutputCount + pictureCount + index];
+      output.name = `video_${index + 1}`;
+      output.type = "VIDEO";
+    }
+    for (let index = 0; index < audioCount; index += 1) {
+      const output = this.node.outputs[fixedOutputCount + pictureCount + videoCount + index];
+      output.name = `audio_${index + 1}`;
+      output.type = "AUDIO";
+    }
+    this.node._widgetSlotsDirty = true;
+    this.node.setDirtyCanvas?.(true, true);
+  }
+
+  async uploadReferenceImage(ref, file) {
+    this.appendLog(`Uploading reference image: ${file.name}`, `upload-${ref.id}`);
+    const body = new FormData();
+    body.append("image", file, file.name);
+    body.append("subfolder", "toyxyz_h3_references");
+    body.append("type", "input");
+    body.append("overwrite", "false");
+    try {
+      const response = await api.fetchApi("/upload/image", { method: "POST", body });
+      const data = await response.json();
+      if (!response.ok || !data.name) throw new Error(data.error || response.statusText || "Upload failed");
+      ref.image_filename = data.name;
+      ref.image_subfolder = data.subfolder || "toyxyz_h3_references";
+      ref.image_type = "input";
+      ref.description = "";
+      this.commit(); this.renderReferences();
+      this.appendLog(`Reference image uploaded: ${data.name}`, `upload-${ref.id}`);
+    } catch (error) {
+      this.appendLog(`Image upload failed: ${error.message || error}`, `upload-${ref.id}`, "error");
+    }
+  }
+
+  async uploadReferenceVideo(ref, file) {
+    this.appendLog(`Uploading reference video: ${file.name}`, `upload-${ref.id}`);
+    try {
+      const uploadId = globalThis.crypto?.randomUUID?.().replaceAll("-", "")
+        || `${Date.now()}${Math.random().toString(16).slice(2)}`;
+      const chunkCount = Math.max(1, Math.ceil(file.size / VIDEO_UPLOAD_CHUNK_BYTES));
+      let data = null;
+      for (let index = 0; index < chunkCount; index += 1) {
+        const start = index * VIDEO_UPLOAD_CHUNK_BYTES;
+        const end = Math.min(file.size, start + VIDEO_UPLOAD_CHUNK_BYTES);
+        const query = new URLSearchParams({
+          upload_id: uploadId,
+          filename: file.name,
+          chunk_index: String(index),
+          final: index === chunkCount - 1 ? "1" : "0",
+        });
+        const response = await api.fetchApi(`${VIDEO_UPLOAD_ENDPOINT}?${query}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/octet-stream" },
+          body: file.slice(start, end),
+        });
+        const responseText = await response.text();
+        try {
+          data = responseText ? JSON.parse(responseText) : {};
+        } catch (_error) {
+          throw new Error(`HTTP ${response.status}: ${responseText.slice(0, 300) || response.statusText || "Upload failed"}`);
+        }
+        if (!response.ok || data.status === "error") {
+          throw new Error(data.error || data.message || `HTTP ${response.status}: ${response.statusText || "Upload failed"}`);
+        }
+        this.appendLog(
+          `Uploading reference video: ${((index + 1) / chunkCount * 100).toFixed(1)}%`,
+          `upload-${ref.id}`,
+        );
+      }
+      if (!data?.name) throw new Error("Upload completed without a stored video name.");
+      ref.video_filename = data.name;
+      ref.video_subfolder = data.subfolder || "toyxyz_h3_references";
+      ref.video_type = "input";
+      const actualDuration = Number(data.duration || 0);
+      ref.duration = actualDuration > 0 ? Math.min(15, actualDuration) : 0;
+      this.commit(); this.renderReferences();
+      const analysisSuffix = ref.duration > 0
+        ? `; analyzing the first ${Number(ref.duration).toFixed(2)} seconds`
+        : "";
+      this.appendLog(`Reference video uploaded: ${data.name}${analysisSuffix}`, `upload-${ref.id}`);
+    } catch (error) {
+      this.appendLog(`Video upload failed: ${error.message || error}`, `upload-${ref.id}`, "error");
+    }
+  }
+
+  async uploadReferenceAudio(ref, file) {
+    this.appendLog(`Uploading reference audio: ${file.name}`, `upload-${ref.id}`);
+    const body = new FormData();
+    body.append("image", file, file.name);
+    body.append("subfolder", "toyxyz_h3_references");
+    body.append("type", "input");
+    body.append("overwrite", "false");
+    try {
+      const response = await api.fetchApi("/upload/image", { method: "POST", body });
+      const responseText = await response.text();
+      let data = {};
+      try { data = responseText ? JSON.parse(responseText) : {}; }
+      catch (_error) { throw new Error(`HTTP ${response.status}: ${responseText.slice(0, 300)}`); }
+      if (!response.ok || !data.name) throw new Error(data.error || response.statusText || "Upload failed");
+      ref.audio_filename = data.name;
+      ref.audio_subfolder = data.subfolder || "toyxyz_h3_references";
+      ref.audio_type = "input";
+      this.commit(); this.renderReferences();
+      this.appendLog(`Reference audio uploaded: ${data.name}`, `upload-${ref.id}`);
+    } catch (error) {
+      this.appendLog(`Audio upload failed: ${error.message || error}`, `upload-${ref.id}`, "error");
+    }
+  }
+
+  renderPreview() {
+    if (this.autoRunPreview) {
+      this.els.preview.textContent = this.autoRunPreview;
+      return;
+    }
+    if (!this.previewData) return;
+    this.els.preview.textContent = this.project.enhanced_prompt
+      ? this.previewData.video_prompt || this.project.enhanced_prompt
+      : "No generated prompt yet. Click Generate Prompt to create one.";
+  }
+
+  showAutoRunPrompt(value) {
+    const prompt = String(Array.isArray(value) ? value[0] || "" : value || "").trim();
+    if (!prompt) return;
+    this.autoRunPreview = prompt;
+    this.els.preview.textContent = prompt;
+    this.appendLog("Auto Run generated prompt is ready.", "auto-run-result");
+  }
+
+  load(value) {
+    this.project = normalizeProject(value);
+    this.autoRunPreview = null;
+    if (!this.project.shots.some(shot => shot.id === this.selectedShotId)) this.selectedShotId = this.project.shots[0]?.id;
+    this.render();
+  }
+}
+
+app.registerExtension({
+  name: "toyxyz.MinimaxH3Prompter",
+  async beforeRegisterNodeDef(nodeType, nodeData) {
+    if (nodeData.name !== NODE_NAME) return;
+    const originalCreated = nodeType.prototype.onNodeCreated;
+    nodeType.prototype.onNodeCreated = function () {
+      originalCreated?.apply(this, arguments);
+      if (this._minimaxH3PrompterUI) return;
+      installStyles();
+      const stateWidget = this.widgets?.find(widget => widget.name === "project_data");
+      hideWidget(stateWidget);
+      const root = document.createElement("div");
+      const domWidget = this.addDOMWidget("minimax_h3_prompter_ui", "minimax_h3_prompter_ui", root, {
+        getValue: () => "", setValue: () => {},
+        getMinHeight: () => UI_HEIGHT, getMaxHeight: () => UI_HEIGHT,
+      });
+      domWidget.serialize = false;
+      this._minimaxH3PrompterUI = new PrompterUI(this, root, stateWidget);
+      this.setSize([Math.max(this.size[0], UI_WIDTH), NODE_HEIGHT]);
+      this._widgetSlotsDirty = true;
+    };
+
+    const originalConfigured = nodeType.prototype.onConfigure;
+    nodeType.prototype.onConfigure = function (info) {
+      originalConfigured?.apply(this, arguments);
+      setTimeout(() => {
+        const widget = this.widgets?.find(item => item.name === "project_data");
+        hideWidget(widget);
+        this._minimaxH3PrompterUI?.load(widget?.value);
+        this.setSize([Math.max(this.size[0], UI_WIDTH), NODE_HEIGHT]);
+        this._widgetSlotsDirty = true;
+        this.setDirtyCanvas?.(true, true);
+      }, 0);
+    };
+
+    const originalExecuted = nodeType.prototype.onExecuted;
+    nodeType.prototype.onExecuted = function (message) {
+      originalExecuted?.apply(this, arguments);
+      this._minimaxH3PrompterUI?.showAutoRunPrompt(message?.auto_run_prompt);
+    };
+
+    const originalRemoved = nodeType.prototype.onRemoved;
+    nodeType.prototype.onRemoved = function () {
+      clearTimeout(this._minimaxH3PrompterUI?.compileTimer);
+      this._minimaxH3PrompterUI?.compileController?.abort();
+      this._minimaxH3PrompterUI?.enhanceController?.abort();
+      originalRemoved?.apply(this, arguments);
+    };
+  },
+});