@remixmate/cli 0.12.9 → 0.13.1

package/skills/gen-script/scripts/gen_script.py

@@ -23,6 +23,7 @@ import os
 import sys
 import uuid
 from copy import deepcopy
+from dataclasses import dataclass
 from urllib.parse import urlsplit
 
 SCHEMA_PATH = os.environ.get(
@@ -581,6 +582,10 @@ def _template_primary_visual_type(template_config: dict | None) -> str:
     return "none"
 
 
+
+NARRATION_MODES = ("auto", "on", "off")
+
+
 def _template_needs_narration(template_config: dict | None) -> bool:
 
 
@@ -1045,6 +1050,29 @@ def _estimate_carousel_min_sec(carousel: dict, model: dict) -> float:
     return total - (n - 1) * transition_sec
 
 
+
+
+
+
+
+
+
+_DURATION_KINDS = ("typewriter", "slideshow", "frame-sequence")
+_LEGACY_DURATION_KINDS = {"caption": "typewriter", "carousel": "slideshow", "sequence": "frame-sequence"}
+
+
+def _duration_components(duration_model: dict | None, kind: str) -> list[tuple[str, dict]]:
+
+    out = []
+    for key, comp in (duration_model or {}).items():
+        if not isinstance(comp, dict):
+            continue
+        comp_kind = comp.get("kind") or _LEGACY_DURATION_KINDS.get(key)
+        if comp_kind == kind:
+            out.append((key, comp))
+    return out
+
+
 def _estimate_fit_caption_duration(
     custom_payload: dict, duration_model: dict | None, template_id: str | None
 ) -> float:
@@ -1060,35 +1088,39 @@ def _estimate_fit_caption_duration(
             f"⚠️  template '{template_id}' declares durationStrategy=fit-caption but no "
             "capabilities.durationModel, so gen_script cannot compute the fitted "
             "duration and falls back to the requested --duration.\n"
-            "   Fix in the template (not here): add capabilities.durationModel with the "
-            "component's own pacing numbers (headlineIntroSec / tailPaddingSec / "
-            "caption.{charsPerSec,lineGapMs,startDelayMs,tailHoldSec,maxLines} / "
-            "carousel.{transitionMs,defaultHoldSec,minPerImageSec,minPerVideoSec}).",
+            "   Fix in the template (not here): add capabilities.durationModel with "
+            "headlineIntroSec / tailPaddingSec plus one component per paced payload field, "
+            "keyed by that field: {kind: typewriter, charsPerSec, lineGapMs, startDelayMs, "
+            "tailHoldSec, maxLines} or {kind: slideshow, transitionMs, defaultHoldSec, "
+            "minPerImageSec, minPerVideoSec}.",
             file=sys.stderr,
         )
         return 0.0
-    caption_sec = _estimate_caption_natural_sec(
-        custom_payload.get("caption") or {}, duration_model.get("caption") or {}
-    )
-    carousel_sec = _estimate_carousel_min_sec(
-        custom_payload.get("carousel") or {}, duration_model.get("carousel") or {}
-    )
-    headline_intro = duration_model.get("headlineIntroSec", 0)
-    return max(headline_intro, caption_sec, carousel_sec) + duration_model.get("tailPaddingSec", 0)
+    parts = [duration_model.get("headlineIntroSec", 0)]
+    for key, comp in _duration_components(duration_model, "typewriter"):
+        parts.append(_estimate_caption_natural_sec(custom_payload.get(key) or {}, comp))
+    for key, comp in _duration_components(duration_model, "slideshow"):
+        parts.append(_estimate_carousel_min_sec(custom_payload.get(key) or {}, comp))
+    return max(parts) + duration_model.get("tailPaddingSec", 0)
 
 
-def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int = 30) -> float:
+def _estimate_fit_images_duration(custom_payload: dict, model: dict | None, fps: int = 30) -> float:
 
 
 
 
 
-    timing = (model or {}).get("sequence", {})
+
+    comps = _duration_components(model, "frame-sequence")
+    if not comps:
+        raise ValueError("fit-images requires a durationModel component of kind frame-sequence")
+    key, timing = comps[0]
+    sequence = custom_payload.get(key) or {}
     tiers = timing.get("holdSecByCount", [])
-    count = len(sequence["items"])
+    count = len(sequence.get("items") or [])
     rule_hold = next((tier["holdSec"] for tier in tiers if count <= tier["maxItems"]), None)
     if rule_hold is None:
-        raise ValueError("fit-images requires durationModel.sequence.holdSecByCount covering the image count")
+        raise ValueError(f"fit-images requires durationModel.{key}.holdSecByCount covering the item count")
 
 
     preset_timing = (timing.get("presets") or {}).get(sequence.get("preset")) or {}
@@ -1096,7 +1128,7 @@ def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int =
     transition_ms = sequence.get("transitionMs", preset_timing.get("transitionMs", timing.get("transitionMs")))
     margin = timing.get("minHoldMarginFrames")
     if transition_ms is None or margin is None:
-        raise ValueError("fit-images requires sequence transitionMs and durationModel.sequence.minHoldMarginFrames")
+        raise ValueError(f"fit-images requires {key}.transitionMs and durationModel.{key}.minHoldMarginFrames")
 
     min_frames = max(2, math.floor(transition_ms / 1000 * fps + 0.5)) + margin
 
@@ -1125,8 +1157,8 @@ def _probe_sequence_video_duration(url: str) -> float | None:
     return probe_video_duration(url)
 
 
-def _sequence_choice(sequence_schema: dict, key: str, value: str | None, flag: str,
-                     template_id: str, passthrough: str) -> str | None:
+def _media_option_choice(option_schema: dict, value: str | None, flag: str,
+                         template_id: str, passthrough: str) -> str | None:
 
 
 
@@ -1134,8 +1166,7 @@ def _sequence_choice(sequence_schema: dict, key: str, value: str | None, flag: s
 
     if not value or value == passthrough:
         return None
-    prop = (sequence_schema.get("properties") or {}).get(key) or {}
-    allowed = [str(v) for v in prop.get("enum") or []]
+    allowed = [str(v) for v in (option_schema or {}).get("enum") or []]
     if value not in allowed:
         raise ValueError(
             f"{flag} {value!r} is not supported by template {template_id!r}; "
@@ -1145,6 +1176,71 @@ def _sequence_choice(sequence_schema: dict, key: str, value: str | None, flag: s
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+_MEDIA_OPTION_FLAGS = {"preset": "--sequence-preset", "fit": "--sequence-fit"}
+_LEGACY_MEDIA_BINDINGS = {
+    "sequence": {
+        "itemsPath": "sequence.items",
+        "videoItem": {"type": "video"},
+        "videoDurationKey": "sourceDurationSec",
+        "captions": {"perItemKey": "caption"},
+        "requireItems": True,
+        "options": {"preset": {"none": "none", "replacesDefaults": True}, "fit": {"none": "auto"}},
+    },
+    "carousel": {
+        "itemsPath": "carousel.items",
+        "item": {"entrance": "random", "exit": "random"},
+        "videoItem": {"kind": "video", "muted": True},
+        "captions": {"linesPath": "caption.lines"},
+    },
+}
+
+
+def _resolve_media_binding(template_config: dict | None) -> dict:
+    caps = (template_config or {}).get("capabilities")
+    caps = caps if isinstance(caps, dict) else {}
+    binding = caps.get("mediaBinding")
+    if isinstance(binding, dict) and isinstance(binding.get("itemsPath"), str) and binding["itemsPath"]:
+        return deepcopy(binding)
+    defaults = caps.get("payloadDefaults") if isinstance(caps.get("payloadDefaults"), dict) else {}
+    legacy = "sequence" if isinstance(defaults.get("sequence"), dict) else "carousel"
+    return deepcopy(_LEGACY_MEDIA_BINDINGS[legacy])
+
+
+def _schema_at(template_config: dict | None, parts: list[str]) -> dict:
+
+    node = (template_config or {}).get("customPayloadSchema") or {}
+    for i, part in enumerate(parts):
+        if not isinstance(node, dict):
+            return {}
+        node = node.get(part) if i == 0 else (node.get("properties") or {}).get(part)
+    return node if isinstance(node, dict) else {}
+
+
+def _get_path(obj: dict, parts: list[str]):
+    for part in parts:
+        if not isinstance(obj, dict):
+            return None
+        obj = obj.get(part)
+    return obj
+
+
+
 PayloadWrites = list[tuple[list[str], object]]
 
 
@@ -1169,7 +1265,8 @@ def _build_carousel_caption_dsl(
     payload_defaults: dict,
     duration_strategy: str | None,
     duration_model: dict | None,
-    sequence_schema: dict | None = None,
+    media_binding: dict,
+    template_config: dict | None = None,
     sequence_preset: str | None = None,
     sequence_fit: str | None = None,
     payload_writes: PayloadWrites | None = None,
@@ -1180,33 +1277,51 @@ def _build_carousel_caption_dsl(
 
 
 
+
     defaults = deepcopy(payload_defaults or {})
-    sequence_mode = isinstance(defaults.get("sequence"), dict)
-    if sequence_mode and not carousel_items:
-        raise ValueError("Image sequence needs --carousel-items; caption text alone cannot supply images")
-    if sequence_mode and len(caption_lines) > len(carousel_items):
-        raise ValueError("Image sequence has more --caption-lines than images; use at most one caption per image")
-    if not sequence_mode and (sequence_preset not in (None, "none") or sequence_fit not in (None, "auto")):
-        raise ValueError(f"--sequence-preset / --sequence-fit only apply to image-sequence templates; {template_id!r} is not one")
-    if sequence_mode:
-        sequence_preset = _sequence_choice(sequence_schema or {}, "preset", sequence_preset,
-                                           "--sequence-preset", template_id, "none")
-        sequence_fit = _sequence_choice(sequence_schema or {}, "fit", sequence_fit,
-                                        "--sequence-fit", template_id, "auto")
+    binding = media_binding
+    items_parts = binding["itemsPath"].split(".")
+    container_parts = items_parts[:-1]
+    captions = binding.get("captions") if isinstance(binding.get("captions"), dict) else {}
+    per_item_caption = captions.get("perItemKey")
+    lines_parts = captions["linesPath"].split(".") if isinstance(captions.get("linesPath"), str) else None
+    options = binding.get("options") if isinstance(binding.get("options"), dict) else {}
+
+    if binding.get("requireItems") and not carousel_items:
+        raise ValueError("This template is driven by media items; pass --carousel-items (caption text alone cannot supply them)")
+    if per_item_caption and len(caption_lines) > len(carousel_items):
+        raise ValueError("More --caption-lines than --carousel-items; this template takes at most one caption per item")
+
+
+
+    picked: dict[str, str] = {}
+    for key, value in (("preset", sequence_preset), ("fit", sequence_fit)):
+        flag = _MEDIA_OPTION_FLAGS[key]
+        opt = options.get(key)
+        none_value = opt.get("none") if isinstance(opt, dict) else ("none" if key == "preset" else "auto")
+        if not isinstance(opt, dict) or not container_parts:
+            if value not in (None, none_value, "none", "auto"):
+                raise ValueError(f"{flag} is not an option of template {template_id!r} (no mediaBinding.options.{key})")
+            continue
+        choice = _media_option_choice(_schema_at(template_config, container_parts + [key]),
+                                      value, flag, template_id, none_value)
+        if choice:
+            picked[key] = choice
 
 
+    duration_key = binding.get("videoDurationKey")
     assets = []
-    carousel_asset_ids = []
+    media_assets = []
     video_seconds: dict[str, float] = {}
     for idx, url in enumerate(carousel_items):
         asset_id = f"carousel-img-{idx + 1:02d}"
 
         is_video = urlsplit(url).path.lower().endswith((".mp4", ".mov", ".webm", ".avi"))
-        if sequence_mode and is_video:
+        if duration_key and is_video:
             seconds = _probe_sequence_video_duration(url)
             if not seconds or seconds <= 0:
                 raise ValueError(
-                    f"Cannot read the duration of video {url!r}; an image sequence needs it to time the clip. "
+                    f"Cannot read the duration of video {url!r}; this template needs it to time the clip. "
                     f"Check the URL is reachable, or leave this video out."
                 )
             video_seconds[asset_id] = round(float(seconds), 3)
@@ -1217,7 +1332,7 @@ def _build_carousel_caption_dsl(
             "status": "generated",
             "url": url,
         })
-        carousel_asset_ids.append((asset_id, "video" if is_video else "image"))
+        media_assets.append((asset_id, "video" if is_video else "image"))
 
 
     narration_asset_id = "narration-scene-01"
@@ -1233,84 +1348,50 @@ def _build_carousel_caption_dsl(
         })
 
 
-    carousel_defaults = defaults.get("carousel", {})
-    carousel_config = {
-        "items": [],
-        **carousel_defaults,
-    }
-    for asset_id, kind in carousel_asset_ids:
-        item = {
-            "assetRef": asset_id,
-            "entrance": carousel_defaults.get("defaultEntrance", "random"),
-            "exit": carousel_defaults.get("defaultExit", "random"),
-        }
-        if kind == "video":
-            item["kind"] = "video"
-            item["muted"] = True
-        carousel_config["items"].append(item)
-
-
-    caption_defaults = defaults.get("caption", {})
-    caption_config = {
-        "lines": caption_lines if caption_lines else [],
-        **caption_defaults,
-    }
-
-    if caption_lines:
-        caption_config["lines"] = caption_lines
-
-
-
-
-
-
-
-
-
-
-    custom_payload = {
-        "carousel": carousel_config,
-        "caption": caption_config,
-    }
-    for key in ("background", "headlineStyle"):
-        if defaults.get(key):
-            custom_payload[key] = defaults[key]
-
 
 
 
-    if sequence_mode:
 
 
+    custom_payload = defaults
+    if container_parts:
+        container = custom_payload
+        for part in container_parts:
+            if not isinstance(container.get(part), dict):
+                container[part] = {}
+            container = container[part]
+        if any(isinstance(o, dict) and o.get("replacesDefaults") and k in picked for k, o in options.items()):
+            container.clear()
+        container.update(picked)
+    else:
+        container = custom_payload
+
+    item_extra = binding.get("item") if isinstance(binding.get("item"), dict) else {}
+    video_extra = binding.get("videoItem") if isinstance(binding.get("videoItem"), dict) else {}
+    container[items_parts[-1]] = [
+        {"assetRef": asset_id,
+         **item_extra,
+         **(video_extra if kind == "video" else {}),
+         **({duration_key: video_seconds[asset_id]} if duration_key and kind == "video" else {}),
+         **({per_item_caption: caption_lines[index]}
+            if per_item_caption and index < len(caption_lines) and caption_lines[index] else {})}
+        for index, (asset_id, kind) in enumerate(media_assets)
+    ]
+    if lines_parts:
 
-        sequence_config = {"preset": sequence_preset} if sequence_preset else defaults["sequence"]
-        if sequence_fit:
-            sequence_config["fit"] = sequence_fit
-        sequence_config["items"] = [
-            {"assetRef": asset_id,
-             **({"type": "video", "sourceDurationSec": video_seconds[asset_id]} if kind == "video" else {}),
-             **({"caption": caption_lines[index]} if index < len(caption_lines) and caption_lines[index] else {})}
-            for index, (asset_id, kind) in enumerate(carousel_asset_ids)
-        ]
-        custom_payload = {"sequence": sequence_config}
+        _write_payload(custom_payload, [(lines_parts, list(caption_lines))])
 
 
 
     _write_payload(custom_payload, payload_writes or [])
 
 
-    narration_text = _localize_label(output_language, "narration_opening",
-                                     label="", topic=_clip(topic, _PLACEHOLDER_TOPIC_CHARS), duration=duration)
-
-
 
 
 
     effective_duration = duration
     if duration_strategy == "fit-images":
-        if not sequence_mode:
-            raise ValueError("fit-images requires capabilities.payloadDefaults.sequence")
-        effective_duration = _estimate_fit_images_duration(custom_payload["sequence"], duration_model)
+        effective_duration = _estimate_fit_images_duration(custom_payload, duration_model)
     if duration_strategy == "fit-caption":
         est = _estimate_fit_caption_duration(custom_payload, duration_model, template_id)
         if est > 0:
@@ -1322,6 +1403,33 @@ def _build_carousel_caption_dsl(
             )
 
 
+
+
+    narration_text = _localize_label(
+        output_language, "narration_opening", label="", topic=_clip(topic, _PLACEHOLDER_TOPIC_CHARS),
+        duration=effective_duration,
+        budget=_budget_suffix(effective_duration, output_language, narration_speed, None),
+    )
+    narration_locks: list[str] = []
+    if narration_enabled and duration_strategy == "fit-images" and _schema_at(template_config, ["minDurationSec"]):
+
+
+
+        custom_payload["minDurationSec"] = effective_duration
+        narration_locks.append("customPayload.minDurationSec")
+
+
+
+
+        pacing_path = container_parts + ["pacing"]
+        pacing_schema = _schema_at(template_config, pacing_path)
+        explicit_pacing = any(parts == pacing_path for parts, _ in (payload_writes or []))
+        if (container_parts and not video_seconds and "fit-scene" in (pacing_schema.get("enum") or [])
+                and not explicit_pacing):
+            container["pacing"] = "fit-scene"
+            narration_locks.append("customPayload." + ".".join(container_parts + ["pacing"]))
+
+
     text_layers = [
         {"role": "headline", "content": headline, "animation": "slide-up"},
     ]
@@ -1378,6 +1486,8 @@ def _build_carousel_caption_dsl(
         "scenes": [scene],
         "transitions": {"default": "fade", "duration": 0.5},
     }
+    for path in narration_locks:
+        _lock_scene_path(dsl, path)
 
     return dsl
 
@@ -1785,7 +1895,7 @@ def _parse_payload_specs(template_config: dict, payload_specs: list[str] | None)
         key, sep, raw = spec.partition("=")
         parts = [p.strip() for p in key.split(".")]
         if not sep or not all(parts):
-            raise ValueError(f"--payload {spec!r}: expected KEY=VALUE, e.g. grade=四年级 or carousel.fit=cover")
+            raise ValueError(f"--payload {spec!r}: expected KEY=VALUE, e.g. <field>=<value> or <object>.<field>=<value>")
         raw = raw.strip()
         if not raw:
             raise ValueError(f"--payload {spec!r}: empty value; leave the flag out to keep the template default")
@@ -1901,130 +2011,64 @@ def _apply_avatar(
     _lock_scene_path(dsl, "visuals.avatar.assetRef")
 
 
-def build_dsl(
-        topic: str,
-        duration: int,
-        style: str,
-        ratio: str,
-        resolution: str,
-        voice_id: str,
-        font_id: str | None,
-        font_name: str | None,
-        scene_count: int | None,
-        allow_digital_human: bool,
-        allow_ai_video: bool,
-        speed: float | None = None,
-        template_id: str | None = None,
-        stub_image_url: str = "",
-        stub_video_url: str = "",
-        headline: str | None = None,
-        subheadline: str | None = None,
-        carousel_items: list[str] | None = None,
-        caption_lines: list[str] | None = None,
-        scene_images: list[str] | None = None,
-        item_count: int | None = None,
-        source_document_url: str | None = None,
-        variant: str | None = None,
-        sequence_preset: str | None = None,
-        sequence_fit: str | None = None,
-        payload_writes: PayloadWrites | None = None,
-        countdown_ending: bool = False,
-) -> dict:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+@dataclass(frozen=True)
+class _SkeletonContext:
 
 
 
 
 
+    template_config: dict | None
+    template_id: str | None
+    contract: dict
+    topic: str
+    style: str
+    ratio: str
+    output_language: str
+    primary_visual_type: str
+    has_visual: bool
+    needs_narration: bool
+    headline: str
+    subheadline: str
+    resolved_voice_id: str
+    narration_speed: float
+    tail_pad_sec: float | None
+    image_style_guide: dict
+    image_compose: bool
+    image_ratio: str
+    stub_image_url: str
+    stub_video_url: str
+    shared_background: bool
+    countdown: dict | None
+    beat_count: int | None
 
 
+def _require_carousel_content(
+        template_id: str | None,
+        contract: dict,
+        carousel_items: list[str] | None,
+        caption_lines: list[str] | None,
+) -> None:
 
 
 
 
 
-
-
-    template_config = _load_template_config(template_id) if template_id else None
-    contract = _resolve_contract(template_config)
-    countdown = contract["countdown"]
-    if countdown is None and item_count is not None:
-        raise ValueError(
-            "--item-count requires a template declaring capabilities.sceneStrategy=countdown"
-        )
-    beat_count = resolve_countdown_count(countdown, item_count, scene_count) if countdown else None
-
-    countdown_ending = bool(countdown_ending and countdown)
-    if countdown_ending and not _template_has_ending_slot(template_config):
-        raise ValueError(f"--ending-payload: template {template_id!r} has no ending slot")
-
-    primary_visual_type = contract["primary_visual_type"]
-    payload_style = contract["payload_style"]
-
-    has_visual = payload_style == "visual-overlay"
-
-
-    needs_narration = contract["needs_narration"]
-
-
-
-
-    output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
-    resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
-    narration_speed = _resolve_narration_speed(speed)
-    if resolved_voice_id != voice_id:
-        print(
-            f"ℹ️  voice resolution: cli={voice_id!r} → resolved={resolved_voice_id!r} "
-            f"(templateDefault={template_default_voice_id!r}, language={output_language})",
-            file=sys.stderr,
-        )
-
-
-    effective_headline = _normalize_linebreaks(headline) or topic
-    effective_subheadline = _normalize_linebreaks(subheadline)
-    _echo_template_llm_hint(template_config, template_id)
-    _warn_on_url_text_layer(effective_headline, effective_subheadline)
-    if beat_count is not None:
-        _warn_on_count_mismatch(countdown, effective_headline, effective_subheadline, beat_count)
-
-
-    if payload_style == "carousel-caption":
+    if not (carousel_items or []) and not (caption_lines or []):
         print(
-            f"ℹ️  contract: payloadStyle=carousel-caption for template {template_id}",
+            "❌ carousel-caption template "
+            f"'{template_id}' needs visual or text content, but received neither "
+            "--carousel-items nor --caption-lines.\n"
+            "   This template renders a carousel of user-supplied media; with no items "
+            "it produces a black, minimum-length (2s) clip.\n"
+            "   Fix: pass the user's image/video URLs via --carousel-items "
+            "(repeat the flag per item), e.g.\n"
+            "     gen_script.py --topic <topic> --template-id "
+            f"{template_id} --carousel-items <url1> --carousel-items <url2> ...\n"
+            "   Optionally add --caption-lines '<text>' for on-screen typewriter captions.",
             file=sys.stderr,
         )
-
-
-
-
-        if not (carousel_items or []) and not (caption_lines or []):
-            print(
-                "❌ carousel-caption template "
-                f"'{template_id}' needs visual or text content, but received neither "
-                "--carousel-items nor --caption-lines.\n"
-                "   This template renders a carousel of user-supplied media; with no items "
-                "it produces a black, minimum-length (2s) clip.\n"
-                "   Fix: pass the user's image/video URLs via --carousel-items "
-                "(repeat the flag per item), e.g.\n"
-                "     gen_script.py --topic <topic> --template-id "
-                f"{template_id} --carousel-items <url1> --carousel-items <url2> ...\n"
-                "   Optionally add --caption-lines '<text>' for on-screen typewriter captions.",
-                file=sys.stderr,
-            )
-            sys.exit(1)
+        sys.exit(1)
 
 
 
@@ -2032,65 +2076,43 @@ def build_dsl(
 
 
 
-        if contract["duration_strategy"] == "fit-caption" and not (caption_lines or []):
-            print(
-                "❌ template "
-                f"'{template_id}' is typewriter-driven (capabilities.durationStrategy="
-                "fit-caption), but --caption-lines is empty.\n"
-                "   For this template the bottom typewriter copy IS the content: it carries "
-                "the message and it decides the video length. With no lines the render "
-                "collapses to the carousel floor (~5s for 2 images) and shows no text at all.\n"
-                "   Fix: pass one --caption-lines '<text>' per line. If the user did not "
-                "supply the copy, WRITE IT YOURSELF from the material you researched "
-                "(repo README, page screenshots, the user's topic) and pass it — do not leave "
-                "it empty, and do not describe lines you never passed.\n"
-                "     gen_script.py --topic <topic> --template-id "
-                f"{template_id} --carousel-items <url> "
-                "--caption-lines '<line 1>' --caption-lines '<line 2>' ...",
-                file=sys.stderr,
-            )
-            sys.exit(1)
-        carousel_dsl = _build_carousel_caption_dsl(
-            template_id=template_id,
-            topic=topic,
-            headline=effective_headline,
-            subheadline=effective_subheadline,
-            carousel_items=carousel_items or [],
-            caption_lines=caption_lines or [],
-            duration=duration,
-            style=style,
-            ratio=ratio,
-            resolution=resolution,
-            output_language=output_language,
-            resolved_voice_id=resolved_voice_id,
-            narration_speed=narration_speed,
-            font_id=font_id,
-            font_name=font_name,
-            narration_enabled=needs_narration,
-            payload_defaults=contract["payload_defaults"],
-            duration_strategy=contract["duration_strategy"],
-            duration_model=contract["duration_model"],
-            sequence_schema=((template_config or {}).get("customPayloadSchema") or {}).get("sequence"),
-            sequence_preset=sequence_preset,
-            sequence_fit=sequence_fit,
-            payload_writes=payload_writes,
+    if contract["duration_strategy"] == "fit-caption" and not (caption_lines or []):
+        print(
+            "❌ template "
+            f"'{template_id}' is typewriter-driven (capabilities.durationStrategy="
+            "fit-caption), but --caption-lines is empty.\n"
+            "   For this template the bottom typewriter copy IS the content: it carries "
+            "the message and it decides the video length. With no lines the render "
+            "collapses to the carousel floor (~5s for 2 images) and shows no text at all.\n"
+            "   Fix: pass one --caption-lines '<text>' per line. If the user did not "
+            "supply the copy, WRITE IT YOURSELF from the material you researched "
+            "(repo README, page screenshots, the user's topic) and pass it — do not leave "
+            "it empty, and do not describe lines you never passed.\n"
+            "     gen_script.py --topic <topic> --template-id "
+            f"{template_id} --carousel-items <url> "
+            "--caption-lines '<line 1>' --caption-lines '<line 2>' ...",
+            file=sys.stderr,
         )
-        _enforce_supported_duration(carousel_dsl, template_config, template_id)
-        return carousel_dsl
-
-    if sequence_preset not in (None, "none") or sequence_fit not in (None, "auto"):
-        raise ValueError(f"--sequence-preset / --sequence-fit only apply to image-sequence templates; {template_id!r} is not one")
-
-
-
-
+        sys.exit(1)
 
 
-    provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
+def _plan_skeleton_scenes(
+        contract: dict,
+        countdown: dict | None,
+        beat_count: int | None,
+        topic: str,
+        duration: int,
+        scene_count: int | None,
+        output_language: str,
+        headline: str,
+        countdown_ending: bool,
+        provided_slots: list[str],
+        has_visual: bool,
+) -> list[dict]:
 
     if beat_count is not None:
         scene_plans = _plan_countdown_scenes(
-            countdown, beat_count, duration, effective_headline, ending=countdown_ending
+            countdown, beat_count, duration, headline, ending=countdown_ending
         )
     else:
         scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
@@ -2107,7 +2129,7 @@ def build_dsl(
         provided_slots
         and scene_count is None
         and contract["scene_strategy"] == "arc"
-        and primary_visual_type == "image"
+        and contract["primary_visual_type"] == "image"
         and has_visual
         and len(provided_slots) > len(scene_plans)
     ):
@@ -2119,236 +2141,212 @@ def build_dsl(
 
     if provided_slots and len(provided_slots) > len(scene_plans):
         print(
-            f"\u26a0\ufe0f  {len(provided_slots)} scene-image entries provided but the template "
+            f"⚠️  {len(provided_slots)} scene-image entries provided but the template "
             f"plans only {len(scene_plans)} scene(s); the extra "
             f"{len(provided_slots) - len(scene_plans)} will not be used. "
             f"Raise --scenes or pick a template with more scenes.",
             file=sys.stderr,
         )
-
-    assets = []
-    scenes = []
+    return scene_plans
 
 
+def _visual_asset_id(ctx: _SkeletonContext, scene_id: str) -> str:
 
+    if ctx.primary_visual_type == "video":
+        return f"video-{scene_id}"
+    if ctx.shared_background:
+        return "img-background"
+    return f"img-{scene_id}"
 
 
+def _plan_visual_asset(
+        ctx: _SkeletonContext, plan: dict, asset_id: str, slot: str, narration_text: str,
+) -> dict | None:
 
+    if ctx.primary_visual_type == "image":
+        slot_is_ai, slot_prompt = _parse_ai_slot(slot)
+        if slot and not slot_is_ai:
 
-    image_style_guide = (
-        resolve_style_guide(template_config, variant or "") if _HAS_ENHANCER else {}
-    )
-    image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
-    image_ratio = image_style_guide.get("ratio") or ratio
 
-    tail_pad_sec = _nb.template_tail_pad_sec(template_config) if _HAS_BUDGET else None
+            return {
+                "assetId": asset_id,
+                "type": "image",
+                "source": "existing",
+                "status": "generated",
+                "url": slot,
+            }
 
 
 
+        if ctx.stub_image_url:
+            return {
+                "assetId": asset_id,
+                "type": "image",
+                "source": "existing",
+                "status": "generated",
+                "url": ctx.stub_image_url,
+            }
+        if ctx.image_compose:
+            image_result = {"prompt": COMPOSE_SUBJECT_PLACEHOLDER}
+        elif ctx.shared_background:
 
-    shared_background = (
-        contract["background_strategy"] == "shared"
-        and primary_visual_type == "image"
-        and not provided_slots
-    )
-    shared_background_planned = False
-    for idx, plan in enumerate(scene_plans):
-        scene_id = f"scene-{idx + 1:02d}"
 
-        if primary_visual_type == "video":
-            visual_asset_id = f"video-{scene_id}"
-        elif shared_background:
-            visual_asset_id = "img-background"
+            image_result = generate_image_prompt(
+                "point", ctx.topic, ctx.style, narration_text="", style_guide=ctx.image_style_guide,
+            )
         else:
-            visual_asset_id = f"img-{scene_id}"
-        narration_asset_id = f"narration-{scene_id}" if needs_narration else None
-        narration_text = (
-            estimate_narration_text(
-                plan["label"], plan["purpose"], plan["duration"], topic, language=output_language,
-                speed=narration_speed, tail_pad_sec=tail_pad_sec,
+            image_result = generate_image_prompt(
+                plan["purpose"], ctx.topic, ctx.style,
+                narration_text=narration_text, style_guide=ctx.image_style_guide,
             )
-            if needs_narration else ""
-        )
-
 
-        scene_has_visual = has_visual and _slot_reads_visual(template_config, plan["purpose"])
 
 
-        if scene_has_visual and shared_background and shared_background_planned:
-            pass
-        elif scene_has_visual and primary_visual_type == "image":
-            if shared_background:
-                shared_background_planned = True
-            slot = provided_slots[idx] if idx < len(provided_slots) else ""
-            slot_is_ai, slot_prompt = _parse_ai_slot(slot)
-            if slot and not slot_is_ai:
 
 
-                assets.append({
-                    "assetId": visual_asset_id,
-                    "type": "image",
-                    "source": "existing",
-                    "status": "generated",
-                    "url": slot,
-                })
+        if slot_prompt:
+            image_result = {**image_result, "prompt": slot_prompt}
 
+        img_payload = {
+            "prompt": image_result["prompt"],
+            "model": os.environ.get("DEFAULT_IMAGE_MODEL", "doubao/doubao-seedream-5-0-260128"),
+            "ratio": ctx.image_ratio,
+        }
+        if "negativePrompt" in image_result:
+            img_payload["negativePrompt"] = image_result["negativePrompt"]
+        if "guidanceScale" in image_result:
+            img_payload["guidanceScale"] = image_result["guidanceScale"]
+        return {
+            "assetId": asset_id,
+            "type": "image",
+            "source": "gen-image",
+            "status": "planned",
+            "payload": img_payload,
+        }
 
+    if ctx.primary_visual_type == "video":
+        if ctx.stub_video_url:
+            return {
+                "assetId": asset_id,
+                "type": "video",
+                "source": "existing",
+                "status": "generated",
+                "url": ctx.stub_video_url,
+            }
 
-            elif stub_image_url:
-                assets.append({
-                    "assetId": visual_asset_id,
-                    "type": "image",
-                    "source": "existing",
-                    "status": "generated",
-                    "url": stub_image_url,
-                })
-            else:
-                if image_compose:
-                    image_result = {"prompt": COMPOSE_SUBJECT_PLACEHOLDER}
-                elif shared_background:
 
+        image_result = generate_image_prompt(plan["purpose"], ctx.topic, ctx.style, narration_text=narration_text)
+        return {
+            "assetId": asset_id,
+            "type": "video",
+            "source": "gen-video",
+            "status": "planned",
+            "payload": {
+                "prompt": image_result["prompt"],
 
-                    image_result = generate_image_prompt(
-                        "point", topic, style, narration_text="", style_guide=image_style_guide,
-                    )
-                else:
-                    image_result = generate_image_prompt(
-                        plan["purpose"], topic, style,
-                        narration_text=narration_text, style_guide=image_style_guide,
-                    )
 
+                "model": os.environ.get("DEFAULT_VIDEO_MODEL", "seedance"),
+                "ratio": ctx.ratio,
 
+                "duration": max(4, min(int(plan["duration"]), 15)),
+            },
+        }
+    return None
 
 
+def _visual_text_layers(ctx: _SkeletonContext, plan: dict) -> list[dict]:
 
-                if slot_prompt:
-                    image_result = {**image_result, "prompt": slot_prompt}
-
-                img_payload = {
-                    "prompt": image_result["prompt"],
-                    "model": os.environ.get("DEFAULT_IMAGE_MODEL", "doubao/doubao-seedream-5-0-260128"),
-                    "ratio": image_ratio,
-                }
-                if "negativePrompt" in image_result:
-                    img_payload["negativePrompt"] = image_result["negativePrompt"]
-                if "guidanceScale" in image_result:
-                    img_payload["guidanceScale"] = image_result["guidanceScale"]
-
-                assets.append({
-                    "assetId": visual_asset_id,
-                    "type": "image",
-                    "source": "gen-image",
-                    "status": "planned",
-                    "payload": img_payload,
-                })
-        elif scene_has_visual and primary_visual_type == "video":
-            if stub_video_url:
-                assets.append({
-                    "assetId": visual_asset_id,
-                    "type": "video",
-                    "source": "existing",
-                    "status": "generated",
-                    "url": stub_video_url,
-                })
-            else:
+    if ctx.contract["text_layer_rules"]:
+        return _placeholder_text_layers(ctx.contract["text_layer_rules"])
+    text_layers = []
+    if plan["purpose"] == "opening":
+        text_layers = [
+            {"role": "headline", "content": ctx.headline, "animation": "slide-up"},
+        ]
+        if ctx.subheadline:
+            text_layers.append({"role": "subheadline", "content": ctx.subheadline, "animation": "fade-in"})
+    elif plan["purpose"] == "point":
+        text_layers = [
+            {"role": "badge", "content": plan["label"], "animation": "slide-up"},
+        ]
 
 
-                image_result = generate_image_prompt(plan["purpose"], topic, style, narration_text=narration_text)
-                video_prompt = image_result["prompt"]
 
-                video_duration = max(4, min(int(plan["duration"]), 15))
-                vid_payload = {
-                    "prompt": video_prompt,
+        text_layers.insert(0, {"role": "headline", "content": ctx.headline, "animation": "fade-in"})
+        if ctx.subheadline:
+            text_layers.append({"role": "subheadline", "content": ctx.subheadline, "animation": "fade-in"})
+    elif plan["purpose"] == "cta":
+        text_layers = [
+            {"role": "headline", "content": _localize_label(ctx.output_language, "follow_us"), "animation": "fade-in"},
+        ]
+        if ctx.subheadline:
+            text_layers.append({"role": "subheadline", "content": ctx.subheadline, "animation": "fade-in"})
+    return text_layers
 
 
-                    "model": os.environ.get("DEFAULT_VIDEO_MODEL", "seedance"),
-                    "ratio": ratio,
-                    "duration": video_duration,
-                }
-                assets.append({
-                    "assetId": visual_asset_id,
-                    "type": "video",
-                    "source": "gen-video",
-                    "status": "planned",
-                    "payload": vid_payload,
-                })
+def _payload_text_layers(ctx: _SkeletonContext, plan: dict) -> list[dict]:
 
 
 
 
 
-        if needs_narration:
-            assets.append({
-                "assetId": narration_asset_id,
-                "type": "audio",
-                "source": "gen-voice",
-                "status": "planned",
-                "payload": {
-                    "voiceId": resolved_voice_id,
-                },
-            })
 
-        if scene_has_visual:
-            layout = "text-overlay" if plan["purpose"] in ("opening", "cta") else "full-visual"
-            text_layers = []
-            if plan["purpose"] == "opening":
-                text_layers = [
-                    {"role": "headline", "content": effective_headline, "animation": "slide-up"},
-                ]
-                if effective_subheadline:
-                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
-            elif plan["purpose"] == "point":
-                text_layers = [
-                    {"role": "badge", "content": plan["label"], "animation": "slide-up"},
-                ]
-
-
-
-                text_layers.insert(0, {"role": "headline", "content": effective_headline, "animation": "fade-in"})
-                if effective_subheadline:
-                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
-            elif plan["purpose"] == "cta":
-                text_layers = [
-                    {"role": "headline", "content": _localize_label(output_language, "follow_us"), "animation": "fade-in"},
-                ]
-                if effective_subheadline:
-                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
-            if contract["text_layer_rules"]:
-                text_layers = _placeholder_text_layers(contract["text_layer_rules"])
-
-            scene = {
-                "id": scene_id,
-                "purpose": plan["purpose"],
-                "duration": plan["duration"],
-                "layout": layout,
-                "visuals": {"background": {"assetRef": visual_asset_id}},
-                "textLayers": text_layers,
-                "animationHints": {
-                    "entrance": "fade",
-                    "motion": "kenburns-in" if idx % 2 == 0 else "kenburns-out",
-                },
-            }
-            if needs_narration:
-                scene["audio"] = {
-                    "narration": {
-                        "text": narration_text,
-                        "assetRef": narration_asset_id,
-
-                        "needsFill": True,
-                    },
-                }
-            scenes.append(scene)
-        else:
 
 
+    if ctx.contract["text_layer_rules"]:
+        return _placeholder_text_layers(ctx.contract["text_layer_rules"])
+    text_layers = []
+    if plan["purpose"] == "opening":
+        text_layers = [
+            {"role": "headline", "content": ctx.headline, "animation": "fade-in"},
+        ]
+        if ctx.subheadline:
+            text_layers.append({"role": "subheadline", "content": ctx.subheadline, "animation": "fade-in"})
+    elif plan["purpose"] == "point":
+        text_layers = [
+            {"role": "headline", "content": plan["label"], "animation": "slide-up"},
+        ]
+    elif plan["purpose"] == "cta":
+        text_layers = [
+            {"role": "headline", "content": _localize_label(ctx.output_language, "follow_us"), "animation": "zoom-in"},
+        ]
+        if ctx.subheadline:
+            text_layers.append({"role": "subheadline", "content": ctx.subheadline, "animation": "fade-in"})
+    return text_layers
 
 
+def _attach_narration(scene: dict, narration_text: str, narration_asset_id: str | None) -> dict:
 
+    if narration_asset_id:
+        scene["audio"] = {
+            "narration": {
+                "text": narration_text,
+                "assetRef": narration_asset_id,
 
+                "needsFill": True,
+            },
+        }
+    return scene
 
 
+def _visual_scene(
+        ctx: _SkeletonContext, idx: int, scene_id: str, plan: dict, visual_asset_id: str,
+) -> dict:
+    return {
+        "id": scene_id,
+        "purpose": plan["purpose"],
+        "duration": plan["duration"],
+        "layout": "text-overlay" if plan["purpose"] in ("opening", "cta") else "full-visual",
+        "visuals": {"background": {"assetRef": visual_asset_id}},
+        "textLayers": _visual_text_layers(ctx, plan),
+        "animationHints": {
+            "entrance": "fade",
+            "motion": "kenburns-in" if idx % 2 == 0 else "kenburns-out",
+        },
+    }
 
 
+def _payload_scene(ctx: _SkeletonContext, scene_id: str, plan: dict) -> dict:
 
 
 
@@ -2356,97 +2354,336 @@ def build_dsl(
 
 
 
-            _layout_cfg = (template_config or {}).get("capabilities") or {}
-            layout = _layout_cfg.get("defaultLayout") or template_id or "text-overlay"
 
 
 
 
 
 
-            text_layers = []
-            if plan["purpose"] == "opening":
-                text_layers = [
-                    {"role": "headline", "content": effective_headline, "animation": "fade-in"},
-                ]
-                if effective_subheadline:
-                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
-            elif plan["purpose"] == "point":
-                text_layers = [
-                    {"role": "headline", "content": plan["label"], "animation": "slide-up"},
-                ]
-            elif plan["purpose"] == "cta":
-                text_layers = [
-                    {"role": "headline", "content": _localize_label(output_language, "follow_us"), "animation": "zoom-in"},
-                ]
-                if effective_subheadline:
-                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
 
-            if contract["text_layer_rules"]:
-                text_layers = _placeholder_text_layers(contract["text_layer_rules"])
 
-            custom_payload = _build_custom_payload(template_config)
-            if beat_count is not None:
 
 
-                custom_payload.update(
-                    countdown_scene_payload(countdown, beat_count, plan.get("countdownIndex"))
-                )
+    layout_cfg = (ctx.template_config or {}).get("capabilities") or {}
+    scene = {
+        "id": scene_id,
+        "purpose": plan["purpose"],
+        "duration": plan["duration"],
+        "layout": layout_cfg.get("defaultLayout") or ctx.template_id or "text-overlay",
+        "textLayers": _payload_text_layers(ctx, plan),
+    }
+    custom_payload = _build_custom_payload(ctx.template_config)
+    if ctx.beat_count is not None:
 
-            scene = {
-                "id": scene_id,
-                "purpose": plan["purpose"],
-                "duration": plan["duration"],
-                "layout": layout,
-                "textLayers": text_layers,
-            }
 
+        custom_payload.update(
+            countdown_scene_payload(ctx.countdown, ctx.beat_count, plan.get("countdownIndex"))
+        )
 
-            if custom_payload:
-                scene["customPayload"] = custom_payload
-            if needs_narration:
-                scene["audio"] = {
-                    "narration": {
-                        "text": narration_text,
-                        "assetRef": narration_asset_id,
 
-                        "needsFill": True,
-                    },
-                }
-            scenes.append(scene)
+    if custom_payload:
+        scene["customPayload"] = custom_payload
+    return scene
 
-    dsl = {
+
+def _skeleton_document(
+        ctx: _SkeletonContext,
+        assets: list[dict],
+        scenes: list[dict],
+        *,
+        headline_given: bool,
+        duration: int,
+        resolution: str,
+        font_id: str | None,
+        font_name: str | None,
+) -> dict:
+
+    return {
         "version": "v1alpha1",
         "meta": {
-            "title": _video_title(effective_headline if headline else None, topic),
-            "topic": topic,
-            "headline": effective_headline,
-            "subheadline": effective_subheadline,
+            "title": _video_title(ctx.headline if headline_given else None, ctx.topic),
+            "topic": ctx.topic,
+            "headline": ctx.headline,
+            "subheadline": ctx.subheadline,
             "targetDuration": duration,
-            "language": LANGUAGE_TO_META[output_language],
-            "outputLanguage": output_language,
-            "style": style or "",
-            "description": _localize_label(output_language, "video_description", topic=topic, duration=duration),
+            "language": LANGUAGE_TO_META[ctx.output_language],
+            "outputLanguage": ctx.output_language,
+            "style": ctx.style or "",
+            "description": _localize_label(ctx.output_language, "video_description", topic=ctx.topic, duration=duration),
 
-            **({"characterSheet": ""} if image_compose and has_visual else {}),
+            **({"characterSheet": ""} if ctx.image_compose and ctx.has_visual else {}),
         },
         "global": {
-            "aspectRatio": ratio,
+            "aspectRatio": ctx.ratio,
             "resolution": resolution,
             "fps": 30,
 
 
-            "subtitle": {"enabled": needs_narration, "style": "bottom"},
-            **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if needs_narration else {}),
+            "subtitle": {"enabled": ctx.needs_narration, "style": "bottom"},
+            **({"narration": {"voiceId": ctx.resolved_voice_id, "speed": ctx.narration_speed}} if ctx.needs_narration else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
         "assets": assets,
         "scenes": scenes,
 
-        "transitions": {"default": contract["default_transition"] or "fade", "duration": 0.5},
+        "transitions": {"default": ctx.contract["default_transition"] or "fade", "duration": 0.5},
     }
 
+
+def build_dsl(
+        topic: str,
+        duration: int,
+        style: str,
+        ratio: str,
+        resolution: str,
+        voice_id: str,
+        font_id: str | None,
+        font_name: str | None,
+        scene_count: int | None,
+        allow_digital_human: bool,
+        allow_ai_video: bool,
+        speed: float | None = None,
+        template_id: str | None = None,
+        stub_image_url: str = "",
+        stub_video_url: str = "",
+        headline: str | None = None,
+        subheadline: str | None = None,
+        carousel_items: list[str] | None = None,
+        caption_lines: list[str] | None = None,
+        scene_images: list[str] | None = None,
+        item_count: int | None = None,
+        source_document_url: str | None = None,
+        variant: str | None = None,
+        sequence_preset: str | None = None,
+        sequence_fit: str | None = None,
+        payload_writes: PayloadWrites | None = None,
+        countdown_ending: bool = False,
+        narration: str = "auto",
+) -> dict:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+    template_config = _load_template_config(template_id) if template_id else None
+    contract = _resolve_contract(template_config)
+
+
+    if narration not in NARRATION_MODES:
+        raise ValueError(f"--narration must be one of {', '.join(NARRATION_MODES)}, got {narration!r}")
+    if narration != "auto":
+        contract["needs_narration"] = narration == "on"
+    countdown = contract["countdown"]
+    if countdown is None and item_count is not None:
+        raise ValueError(
+            "--item-count requires a template declaring capabilities.sceneStrategy=countdown"
+        )
+    beat_count = resolve_countdown_count(countdown, item_count, scene_count) if countdown else None
+
+    countdown_ending = bool(countdown_ending and countdown)
+    if countdown_ending and not _template_has_ending_slot(template_config):
+        raise ValueError(f"--ending-payload: template {template_id!r} has no ending slot")
+
+    primary_visual_type = contract["primary_visual_type"]
+    payload_style = contract["payload_style"]
+
+    has_visual = payload_style == "visual-overlay"
+
+
+    needs_narration = contract["needs_narration"]
+
+
+
+
+    output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
+    resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
+    narration_speed = _resolve_narration_speed(speed)
+    if resolved_voice_id != voice_id:
+        print(
+            f"ℹ️  voice resolution: cli={voice_id!r} → resolved={resolved_voice_id!r} "
+            f"(templateDefault={template_default_voice_id!r}, language={output_language})",
+            file=sys.stderr,
+        )
+
+
+    effective_headline = _normalize_linebreaks(headline) or topic
+    effective_subheadline = _normalize_linebreaks(subheadline)
+    _echo_template_llm_hint(template_config, template_id)
+    _warn_on_url_text_layer(effective_headline, effective_subheadline)
+    if beat_count is not None:
+        _warn_on_count_mismatch(countdown, effective_headline, effective_subheadline, beat_count)
+
+
+    if payload_style == "carousel-caption":
+        print(
+            f"ℹ️  contract: payloadStyle=carousel-caption for template {template_id}",
+            file=sys.stderr,
+        )
+        _require_carousel_content(template_id, contract, carousel_items, caption_lines)
+        carousel_dsl = _build_carousel_caption_dsl(
+            template_id=template_id,
+            topic=topic,
+            headline=effective_headline,
+            subheadline=effective_subheadline,
+            carousel_items=carousel_items or [],
+            caption_lines=caption_lines or [],
+            duration=duration,
+            style=style,
+            ratio=ratio,
+            resolution=resolution,
+            output_language=output_language,
+            resolved_voice_id=resolved_voice_id,
+            narration_speed=narration_speed,
+            font_id=font_id,
+            font_name=font_name,
+            narration_enabled=needs_narration,
+            payload_defaults=contract["payload_defaults"],
+            duration_strategy=contract["duration_strategy"],
+            duration_model=contract["duration_model"],
+            media_binding=_resolve_media_binding(template_config),
+            template_config=template_config,
+            sequence_preset=sequence_preset,
+            sequence_fit=sequence_fit,
+            payload_writes=payload_writes,
+        )
+        _enforce_supported_duration(carousel_dsl, template_config, template_id)
+        return carousel_dsl
+
+    if sequence_preset not in (None, "none") or sequence_fit not in (None, "auto"):
+        raise ValueError(f"--sequence-preset / --sequence-fit only apply to templates declaring mediaBinding.options; {template_id!r} does not")
+
+
+
+
+
+
+    provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
+    scene_plans = _plan_skeleton_scenes(
+        contract, countdown, beat_count, topic, duration, scene_count, output_language,
+        effective_headline, countdown_ending, provided_slots, has_visual,
+    )
+
+
+
+
+
+
+
+    image_style_guide = (
+        resolve_style_guide(template_config, variant or "") if _HAS_ENHANCER else {}
+    )
+    ctx = _SkeletonContext(
+        template_config=template_config,
+        template_id=template_id,
+        contract=contract,
+        topic=topic,
+        style=style,
+        ratio=ratio,
+        output_language=output_language,
+        primary_visual_type=primary_visual_type,
+        has_visual=has_visual,
+        needs_narration=needs_narration,
+        headline=effective_headline,
+        subheadline=effective_subheadline,
+        resolved_voice_id=resolved_voice_id,
+        narration_speed=narration_speed,
+        tail_pad_sec=_nb.template_tail_pad_sec(template_config) if _HAS_BUDGET else None,
+        image_style_guide=image_style_guide,
+        image_compose=_HAS_ENHANCER and is_compose_mode(image_style_guide),
+        image_ratio=image_style_guide.get("ratio") or ratio,
+        stub_image_url=stub_image_url,
+        stub_video_url=stub_video_url,
+
+
+
+
+        shared_background=(
+            contract["background_strategy"] == "shared"
+            and primary_visual_type == "image"
+            and not provided_slots
+        ),
+        countdown=countdown,
+        beat_count=beat_count,
+    )
+
+    assets = []
+    scenes = []
+    shared_background_planned = False
+    for idx, plan in enumerate(scene_plans):
+        scene_id = f"scene-{idx + 1:02d}"
+        visual_asset_id = _visual_asset_id(ctx, scene_id)
+        narration_asset_id = f"narration-{scene_id}" if needs_narration else None
+        narration_text = (
+            estimate_narration_text(
+                plan["label"], plan["purpose"], plan["duration"], topic, language=output_language,
+                speed=narration_speed, tail_pad_sec=ctx.tail_pad_sec,
+            )
+            if needs_narration else ""
+        )
+
+
+        scene_has_visual = has_visual and _slot_reads_visual(template_config, plan["purpose"])
+
+
+
+        if scene_has_visual and not (ctx.shared_background and shared_background_planned):
+            shared_background_planned = ctx.shared_background
+            slot = provided_slots[idx] if idx < len(provided_slots) else ""
+            visual_asset = _plan_visual_asset(ctx, plan, visual_asset_id, slot, narration_text)
+            if visual_asset:
+                assets.append(visual_asset)
+
+
+
+
+
+        if needs_narration:
+            assets.append({
+                "assetId": narration_asset_id,
+                "type": "audio",
+                "source": "gen-voice",
+                "status": "planned",
+                "payload": {
+                    "voiceId": resolved_voice_id,
+                },
+            })
+
+        scene = (
+            _visual_scene(ctx, idx, scene_id, plan, visual_asset_id)
+            if scene_has_visual else _payload_scene(ctx, scene_id, plan)
+        )
+        scenes.append(_attach_narration(scene, narration_text, narration_asset_id))
+
+    dsl = _skeleton_document(
+        ctx, assets, scenes,
+        headline_given=bool(headline), duration=duration, resolution=resolution,
+        font_id=font_id, font_name=font_name,
+    )
+
     if template_id:
         dsl["meta"]["templateId"] = template_id
 
@@ -2473,7 +2710,7 @@ def build_dsl(
     return dsl
 
 
-def main():
+def _build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="Video script generator — produces Video DSL v1alpha1 JSON",
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -2541,20 +2778,27 @@ Examples:
         "--background-preset", default=None,
         help="Scene background preset (one of the template's customPayloadSchema.background.preset enum). "
              "Written to every scene's customPayload.background.preset. When the user picked a background in "
-             "the replicate card (e.g. `纯色（solid）`), pass that id. Requires --template-id.",
+             "the replicate card (`<名称>（<id>）`), pass that id. Requires --template-id.",
     )
     parser.add_argument(
         "--sequence-preset", default=None,
-        help="Image-sequence style preset (one of the template's customPayloadSchema.sequence.preset enum, "
-             "e.g. vlog / news / poster / cinematic / fast-cut), written to customPayload.sequence.preset; "
-             "`none` keeps the template defaults. When the user picked a style preset in the replicate card "
-             "(e.g. `快剪（fast-cut）`), pass that id. Only for templates declaring payloadDefaults.sequence.",
+        help="Style preset for templates declaring capabilities.mediaBinding.options.preset (one of that "
+             "option's enum in customPayloadSchema), written next to the template's media list; `none` keeps "
+             "the template defaults. When the user picked a style preset in the replicate card "
+             "(`<名称>（<id>）`), pass that id.",
+    )
+    parser.add_argument(
+        "--narration", default="auto", choices=NARRATION_MODES,
+        help="Narration on / off, overriding the template's capabilities.needsNarration (auto = the template "
+             "decides). Templates where narration is optional default to none; pass `on` when the user picked "
+             "narration in the replicate card (`旁白: <名称>（narrated）`), so the skeleton gets narration slots, "
+             "a gen-voice asset and subtitles. `off` drops narration from a narrated template.",
     )
     parser.add_argument(
         "--sequence-fit", default=None,
-        help="How image-sequence media fill the frame (customPayloadSchema.sequence.fit enum: cover = fill and crop, "
-             "contain = show whole with a blurred backdrop), written to customPayload.sequence.fit; `auto` keeps "
-             "the template / preset default. When the user picked it in the replicate card, pass that id.",
+        help="Media fill mode for templates declaring capabilities.mediaBinding.options.fit (one of that "
+             "option's enum in customPayloadSchema); `auto` keeps the template / preset default. When the user "
+             "picked it in the replicate card, pass that id.",
     )
     parser.add_argument(
         "--background-asset", default=None,
@@ -2565,8 +2809,8 @@ Examples:
     )
     parser.add_argument(
         "--payload", action="append", default=None, metavar="KEY=VALUE",
-        help="Set a template customPayload field on every scene, e.g. --payload grade=四年级 "
-             "--payload carousel.fit=cover --payload templateData.revealMode=progressive. KEY is a dotted path "
+        help="Set a template customPayload field on every scene, e.g. --payload <field>=<value> "
+             "--payload <object>.<field>=<value>. KEY is a dotted path "
              "checked against the template's customPayloadSchema; VALUE is converted to its declared type "
              "(true/false, numbers) and checked against its enum / range. Repeatable. Requires --template-id.",
     )
@@ -2577,7 +2821,7 @@ Examples:
     )
     parser.add_argument("--allow-digital-human", action="store_true", help="Allow digital-human assets")
     parser.add_argument("--avatar-id", default=None, help="Digital-human avatar id (dh_xxx) for templates declaring capabilities.digitalHuman: adds one gen-digital-human asset referenced by every scene's visuals.avatar.assetRef (one continuous presenter driven by the narration). Placement stays the template default unless set with --payload digitalHuman.<field>=...")
-    parser.add_argument("--ending-payload", action="append", default=None, metavar="KEY=VALUE", help="Like --payload, but written only to the ending scene (e.g. recap.cta=关注我，每周更新开源热榜). On countdown templates it also appends the ending scene after #1. Repeatable.")
+    parser.add_argument("--ending-payload", action="append", default=None, metavar="KEY=VALUE", help="Like --payload, but written only to the ending scene (e.g. <object>.<field>=<closing line>). On countdown templates it also appends the ending scene after #1. Repeatable.")
     parser.add_argument("--allow-ai-video", action="store_true", help="Allow AI-generated video assets")
     parser.add_argument("--template-id", default=None, help="Template id. The template owns outputLanguage and may declare a defaultVoiceId.")
     parser.add_argument(
@@ -2624,12 +2868,11 @@ Examples:
         "--carousel-items",
         action="append",
         default=None,
-        help="Media URL for the template's carousel/gallery. Can be repeated: "
+        help="Media URL for the template's image/video list. Can be repeated: "
              "--carousel-items url1 --carousel-items url2. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
-             "these URLs are placed directly into "
-             "customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise "
-             "customPayload.carousel.items, as existing assets without AI image generation.",
+             "these URLs are placed directly into the list named by capabilities.mediaBinding.itemsPath, "
+             "as existing assets without AI image generation.",
     )
     parser.add_argument(
         "--scene-images",
@@ -2652,40 +2895,38 @@ Examples:
         help="On-screen caption line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
-             "these are placed into customPayload.caption.lines, or sequence.items[].caption "
-             "in image order when payloadDefaults.sequence is declared. "
+             "these go where capabilities.mediaBinding.captions says (one text block, or one caption "
+             "per media item in order). "
              "Line count limits and whether **emphasis** is parsed are declared per "
              "template — see the chosen template's llmHint.",
     )
+    return parser
 
-    args = parser.parse_args()
 
+def _run_validate(input_path: str | None) -> None:
 
+    if not input_path:
+        print("❌ validate mode requires --input", file=sys.stderr)
+        sys.exit(1)
+    if not os.path.exists(input_path):
+        print(f"❌ file not found: {input_path}", file=sys.stderr)
+        sys.exit(1)
+    with open(input_path, "r", encoding="utf-8") as f:
+        dsl = json.load(f)
+    errors, warnings = validate_authored_dsl(dsl)
+    for w in warnings:
+        print(f"⚠️  {w}", file=sys.stderr)
+    if errors:
+        print("❌ DSL validation failed:", file=sys.stderr)
+        for err in errors:
+            print(f"   - {err}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("✅ DSL validation passed")
+        return
 
-    if args.list_fonts:
-        from font_catalog import print_font_catalog
-        sys.exit(print_font_catalog())
 
-    if args.validate:
-        if not args.input:
-            print("❌ validate mode requires --input", file=sys.stderr)
-            sys.exit(1)
-        if not os.path.exists(args.input):
-            print(f"❌ file not found: {args.input}", file=sys.stderr)
-            sys.exit(1)
-        with open(args.input, "r", encoding="utf-8") as f:
-            dsl = json.load(f)
-        errors, warnings = validate_authored_dsl(dsl)
-        for w in warnings:
-            print(f"⚠️  {w}", file=sys.stderr)
-        if errors:
-            print("❌ DSL validation failed:", file=sys.stderr)
-            for err in errors:
-                print(f"   - {err}", file=sys.stderr)
-            sys.exit(1)
-        else:
-            print("✅ DSL validation passed")
-            return
+def _check_generation_args(args, parser: argparse.ArgumentParser) -> None:
 
     if not args.topic:
         print("❌ please provide --topic", file=sys.stderr)
@@ -2702,6 +2943,9 @@ Examples:
         sys.exit(1)
 
 
+def _resolve_template_selection(args) -> dict | None:
+
+
     try:
         template_selection = _template_selection(
             args.template_id, args.template_source, args.template_candidates,
@@ -2715,6 +2959,10 @@ Examples:
             "If the user did not name it, stop and let them confirm it before writing the script.",
             file=sys.stderr,
         )
+    return template_selection
+
+
+def _resolve_ratio(args) -> str:
 
 
 
@@ -2740,14 +2988,10 @@ Examples:
                     )
         else:
             resolved_ratio = "16:9"
-    args.ratio = resolved_ratio
+    return resolved_ratio
 
-    print(f"📝 generating video script...", file=sys.stderr)
-    print(f"   topic: {args.topic}", file=sys.stderr)
-    print(f"   duration: {args.duration}s", file=sys.stderr)
-    print(f"   ratio: {args.ratio}", file=sys.stderr)
-    if args.speed is not None:
-        print(f"   narration speed: {args.speed}x", file=sys.stderr)
+
+def _resolve_stub_urls(args) -> tuple[str, str]:
 
 
 
@@ -2779,6 +3023,10 @@ Examples:
             f"(image={stub_image_url}, video={stub_video_url}, audio=https://placeholder.local/stub.mp3)",
             file=sys.stderr,
         )
+    return stub_image_url, stub_video_url
+
+
+def _parse_payload_writes(args, parser: argparse.ArgumentParser) -> list:
 
     try:
 
@@ -2789,6 +3037,66 @@ Examples:
         )
     except ValueError as exc:
         parser.error(str(exc))
+    return payload_writes
+
+
+def _stub_generated_assets(dsl: dict, stub_video_url: str) -> None:
+
+
+
+    _AUDIO_STUB = "https://placeholder.local/stub.mp3"
+    _VIDEO_STUB = stub_video_url
+    for asset in dsl.get("assets", []):
+        src = asset.get("source")
+        if src in ("gen-voice",):
+            asset["source"] = "existing"
+            asset["status"] = "generated"
+            asset["url"] = _AUDIO_STUB
+
+        elif src in ("gen-digital-human",):
+            asset["source"] = "existing"
+            asset["status"] = "generated"
+            asset["url"] = _VIDEO_STUB
+
+
+def _check_output_language(dsl: dict) -> None:
+
+    expected_language = dsl.get("meta", {}).get("outputLanguage", DEFAULT_LANGUAGE)
+    if expected_language in ("en", "zh"):
+        narrations_for_check = [
+            ((scene.get("audio") or {}).get("narration") or {}).get("text", "")
+            for scene in dsl.get("scenes", [])
+        ]
+        _check_narration_language(narrations_for_check, expected_language)
+
+
+def main():
+    parser = _build_arg_parser()
+    args = parser.parse_args()
+
+
+
+    if args.list_fonts:
+        from font_catalog import print_font_catalog
+        sys.exit(print_font_catalog())
+
+    if args.validate:
+        _run_validate(args.input)
+        return
+
+    _check_generation_args(args, parser)
+    template_selection = _resolve_template_selection(args)
+    args.ratio = _resolve_ratio(args)
+
+    print(f"📝 generating video script...", file=sys.stderr)
+    print(f"   topic: {args.topic}", file=sys.stderr)
+    print(f"   duration: {args.duration}s", file=sys.stderr)
+    print(f"   ratio: {args.ratio}", file=sys.stderr)
+    if args.speed is not None:
+        print(f"   narration speed: {args.speed}x", file=sys.stderr)
+
+    stub_image_url, stub_video_url = _resolve_stub_urls(args)
+    payload_writes = _parse_payload_writes(args, parser)
 
     try:
         dsl = build_dsl(
@@ -2819,6 +3127,7 @@ Examples:
             sequence_fit=args.sequence_fit,
             payload_writes=payload_writes,
             countdown_ending=bool(args.ending_payload),
+            narration=args.narration,
         )
     except ValueError as exc:
 
@@ -2845,23 +3154,8 @@ Examples:
     if template_selection:
         dsl.setdefault("meta", {})["templateSelection"] = template_selection
 
-
-
-
     if args.skip_asset_generation:
-        _AUDIO_STUB = "https://placeholder.local/stub.mp3"
-        _VIDEO_STUB = stub_video_url
-        for asset in dsl.get("assets", []):
-            src = asset.get("source")
-            if src in ("gen-voice",):
-                asset["source"] = "existing"
-                asset["status"] = "generated"
-                asset["url"] = _AUDIO_STUB
-
-            elif src in ("gen-digital-human",):
-                asset["source"] = "existing"
-                asset["status"] = "generated"
-                asset["url"] = _VIDEO_STUB
+        _stub_generated_assets(dsl, stub_video_url)
 
     errors = validate_dsl(dsl)
     if errors:
@@ -2870,14 +3164,7 @@ Examples:
             print(f"   - {err}", file=sys.stderr)
         sys.exit(1)
 
-
-    expected_language = dsl.get("meta", {}).get("outputLanguage", DEFAULT_LANGUAGE)
-    if expected_language in ("en", "zh"):
-        narrations_for_check = [
-            ((scene.get("audio") or {}).get("narration") or {}).get("text", "")
-            for scene in dsl.get("scenes", [])
-        ]
-        _check_narration_language(narrations_for_check, expected_language)
+    _check_output_language(dsl)
 
     output_json = json.dumps(dsl, ensure_ascii=False, indent=2)
     print(output_json)