@remixmate/cli 0.9.50 → 0.9.52

package/skills/render-video/scripts/render_video.py

@@ -7,8 +7,8 @@
   编译时间线，最终调用 Remotion 渲染引擎输出视频。
 
 用法:
-  python render_video.py --dsl video.dsl.json --template-id screen-walkthrough
-  python render_video.py --dsl video.dsl.json --template-id screen-walkthrough --resolve-only
+  python render_video.py --dsl video.dsl.json --template-id <templateId>
+  python render_video.py --dsl video.dsl.json --template-id <templateId> --resolve-only
   python render_video.py --render-plan video.render-plan.json
 
 环境变量:
@@ -53,7 +53,7 @@ _SHARED_LIB_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "template-
 # Single sys.path setup for both cross-skill import surfaces of the shared lib:
 #   - <shared>            for `video_dsl.runtime.*`
 #   - <shared>/scripts    for `registry_loader`, `match_template`,
-#                          `render_job_client`, `template_paths`
+#                          `render_job_client`, `countdown_spec`
 # Each deeper function used to repeat its own sys.path.insert; consolidating
 # here keeps the module's import side-effects in one place and matches
 # Python's "set up sys.path once at module top" idiom.
@@ -516,7 +516,7 @@ def _hydrate_dsl_payload(
 ) -> None:
     """按模板声明把源文件的每一页填进 ``customPayload``（就地改 dsl）。
 
-    只对声明了 ``capabilities.payloadHydration`` 的模板生效（目前 ppt-to-video）；
+    只对声明了 ``capabilities.payloadHydration`` 的模板生效；
     其余模板这里是零成本 no-op —— 声明驱动，不写 ``if template_id == X``（AGENTS.md）。
 
     失败一律 exit 2 并把「下一步做什么」打全：这条路上所有失败形态的共同点是
@@ -573,9 +573,12 @@ def _compose_image_prompts(dsl: dict, template_id: str | None) -> None:
         LogPrint(f"   {line}", file=sys.stderr)
 
 
-def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> None:
+def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int], step_field: Optional[str]) -> None:
     """动作条数与旁白句数不等时出声。
 
+    动作数组放在哪个字段由模板的 ``capabilities.stepAlignment.payloadField`` 声明
+    （``step_field``）；没声明的模板不检查。
+
     为什么值得单独打一条：这一类缺陷**渲得出来**。它不报错、不退非零、renderJob
     completed、漏斗记 rendered —— 2026-09-23 线上那条鸡兔同笼成片就是这样交付的，
     10 步板面配 10 句旁白，听起来该一一对应，实际板面在音频中点就走完了。
@@ -585,8 +588,9 @@ def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> No
     真正需要拦的是"作者以为一一对应、实际不是"，而那个判断只有作者做得了 ——
     所以这里给的是两个数字，不是一个结论。
     """
-    steps = ((entry.get("props") or {}).get("steps")
-             or (entry.get("props") or {}).get("beats"))
+    if not step_field:
+        return
+    steps = (entry.get("props") or {}).get(step_field)
     if not isinstance(steps, list) or not steps:
         return
     sentences = (sentence_indices[-1] + 1) if sentence_indices else 0
@@ -1360,7 +1364,12 @@ def resolve_assets(render_plan: dict, private_token: str, max_retries: int, time
     return render_plan
 
 
-def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_plan: dict) -> None:
+def _auto_highlight_map(
+    entry: dict,
+    narration_asset: Optional[dict],
+    render_plan: dict,
+    line_sync: dict[str, str],
+) -> None:
     """Auto-fill ``templateData.highlightMap`` for any template that uses
     structured ``{intro, items, outro}`` narration and ships per-line cards.
 
@@ -1371,6 +1380,10 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     this auto-fill. Adding a new template that follows the same pattern needs
     NO change to this function.
 
+    ``line_sync`` is the template's ``lineSyncSlides`` declaration (slideId →
+    card-array key). It caps the map at the card count so trailing outro lines
+    don't point past the last card; slides it doesn't list get no cap.
+
     Skipped silently when:
       - narration asset has no narrationLineCount (structured form wasn't used)
       - author already supplied a highlightMap (explicit wins)
@@ -1405,23 +1418,13 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     intro_lines = int(narration_asset.get("narrationIntroLines") or 0)
     item_count = line_count - intro_lines
     # outro counts toward line_count too; cap item_count at the authored
-    # items-array length so trailing outro lines don't spill into card
-    # indices.
-    # ⚠️ 这份键表必须与模板侧 utils/slidePayload.ts 的 CARD_ARRAY_KEYS 完全一致：
-    # 两处是同一算法的两份实现（这里是生产路径，那边是摊平 binder 形态下的本地兜底）。
-    # 2026-09-15 修复：此前这里少了 steps / annotations，于是 step-flow 与
-    # code-highlight 拿不到下面那行的上限裁剪，旁白带 outro 行时 highlightMap 会多出
-    # 一个指向数组外的下标 —— 那一行播放期间"全部卡片变暗、没有一张点亮"。
-    # 顺序也有意义：取第一个命中的键，新键一律追加在末尾。
-    # template-library 的 `pnpm validate:contracts` 现在会双向核对这两份表。
-    items_key = next(
-        (
-            k
-            for k in ("concepts", "pillars", "eras", "items", "steps", "annotations")
-            if isinstance(tdata.get(k), list)
-        ),
-        None,
-    )
+    # card-array length so trailing outro lines don't spill into card
+    # indices. 数组键读模板的 lineSyncSlides 声明（按 slideId），CLI 不保留键表副本
+    # —— 以前这里有一份模板 CARD_ARRAY_KEYS 的手抄，已经漂移过两次。
+    slide_id = props.get("slideId") or tdata.get("slideId")
+    items_key = line_sync.get(slide_id) if isinstance(slide_id, str) else None
+    if items_key and not isinstance(tdata.get(items_key), list):
+        items_key = None
     if items_key:
         item_count = min(item_count, len(tdata[items_key]))
 
@@ -1440,21 +1443,25 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     })
 
 
-def _template_default_tail_pad_frames(template_id: str, fps: int) -> int | None:
+def _timing_template(template_id: str) -> dict:
+    """排轴阶段要读的模板声明；取不到就返回空 dict，走全局默认，不因为这个挡渲染。"""
+    if not template_id:
+        return {}
+    try:
+        from registry_loader import get_template  # type: ignore
+        return get_template(template_id, include_all_statuses=True) or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def _template_default_tail_pad_frames(tpl: dict, fps: int) -> int | None:
     """模板声明的旁白尾巴默认值（``capabilities.defaultTailPadSec``），换算成帧。
 
     场景自己的 ``customPayload.tailPadSec`` 仍然优先；这里只替换全局 1.5s 兜底。
     为什么要模板级：逐场景设置靠模型照着 llmHint 抄，实际经常漏 —— 2026-09-24
     线上《狼来了》绘本每页结尾 1.9s 空白，86s 里 15s 没有声音。
     """
-    if not template_id:
-        return None
-    try:
-        from registry_loader import get_template  # type: ignore
-        tpl = get_template(template_id, include_all_statuses=True)
-    except Exception:  # noqa: BLE001 - 取不到模板就走全局默认，不因为这个挡渲染
-        return None
-    value = ((tpl or {}).get("capabilities") or {}).get("defaultTailPadSec")
+    value = (tpl.get("capabilities") or {}).get("defaultTailPadSec")
     if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
         return None
     return int(round(float(value) * fps))
@@ -1469,7 +1476,11 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
     assets_map = {a["assetId"]: a for a in render_plan["resolvedAssets"]}
     current_frame = 0
     adjusted = 0
-    default_tail_pad = _template_default_tail_pad_frames(render_plan.get("templateId", ""), fps)
+    from video_dsl.runtime.dsl_validator import line_sync_slides, step_alignment_field
+    timing_tpl = _timing_template(render_plan.get("templateId", ""))
+    line_sync = line_sync_slides(timing_tpl)
+    step_field = step_alignment_field(timing_tpl)
+    default_tail_pad = _template_default_tail_pad_frames(timing_tpl, fps)
     if default_tail_pad is None:
         default_tail_pad = int(fps * 1.5)
 
@@ -1533,7 +1544,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                         }
                         for i, s in enumerate(tts_subs)
                     ]
-                    _warn_step_sentence_mismatch(entry, sentence_indices)
+                    _warn_step_sentence_mismatch(entry, sentence_indices, step_field)
                 else:
                     # No TTS timestamps — re-distribute existing subtitle
                     # lines across the REAL audio duration, by character
@@ -1605,7 +1616,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             cursor += seg_frames
                         entry["subtitleSegments"] = new_subs
 
-        _auto_highlight_map(entry, narration_asset, render_plan)
+        _auto_highlight_map(entry, narration_asset, render_plan, line_sync)
 
         # Re-anchor subtitles for scenes that weren't handled in the narration block above.
         # This covers scenes without narration or with invalid duration.
@@ -2317,8 +2328,8 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  python render_video.py --dsl video.dsl.json --template-id html-slide
-  python render_video.py --dsl video.dsl.json --template-id html-slide --resolve-only
+  python render_video.py --dsl video.dsl.json --template-id <templateId>
+  python render_video.py --dsl video.dsl.json --template-id <templateId> --resolve-only
   python render_video.py --render-plan video.render-plan.json
         """,
     )
@@ -2328,7 +2339,7 @@ Examples:
     parser.add_argument(
         "--source-document-url", default=None,
         help="Source document URL (.pptx) for templates that build their per-scene payload from a "
-             "document (capabilities.payloadHydration, e.g. ppt-to-video). Overrides "
+             "document (capabilities.payloadHydration). Overrides "
              "meta.sourceDocument in the DSL. The layout data is fetched here and written into "
              "every scene's customPayload — it is deliberately never routed through the model.",
     )
@@ -2522,8 +2533,8 @@ Examples:
 
         # ── 按引用注入模板声明的大 payload（必须在校验之前）─────────────
         #
-        # ppt-to-video 这类模板的画面数据（customPayload.slide：一整页的节点树、
-        # 坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
+        # 按引用注入的模板画面数据（payloadHydration.payloadField 指定的字段：一整页
+        # 的节点树、坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
         # 而它体积大到不能过模型（一页几百 KB，23 页好几 MB）。所以 DSL 里只带一个
         # 引用（meta.sourceDocument），在这里把全量取回来填进每个场景。
         #

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V30",
+  "version": "V31",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

package/skills/template-registry/README.md

@@ -17,7 +17,7 @@ HTTP 拉取带磁盘缓存（TTL + ETag/304）；瞬时故障时降级复用同
 
 ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http` 透明拆封;静态 JSON endpoint 也支持(直接返回 registry 文档)。
 
-> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。monorepo 文件仅供 `check_contracts.py` / `sync_registry.py` 等 monorepo-only 维护脚本使用。
+> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。配套的 monorepo-only 维护脚本（`check_contracts.py` / `sync_registry.py`）也已随之删除，契约对账改由 template-library 的 `generateManifest` / `validate:contracts` 在上游负责。
 
 ## 新增模板工作流
 
@@ -30,17 +30,8 @@ ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http`
 
 ## 契约一致性
 
-template-library 仓库内置契约验证器,确保:
-
-- 每个 `template.json` 中引用的 `compositionId` 都存在于 remotion-renderer 的 `manifest.ts`
-- manifest 中的每个 compositionId 都被某个 `template.json` 引用
-- 所有 `template.json` 通过 JSON Schema 校验
-
-本地可运行 `check_contracts.py` 做跨仓库一致性检查(从 monorepo `<repo>/remotion-renderer/src/core/compositions/manifest.ts` 读 manifest):
-
-```bash
-python3 <SkillDir>/scripts/check_contracts.py
-```
+模板契约（schema、compositionId、slideSchemas、lineSyncSlides 等）由 template-library
+仓库自己的 `pnpm check:all` 校验。本仓不保留任何模板级校验或模板数据副本。
 
 ## 共享 Python 模块
 
@@ -48,12 +39,10 @@ python3 <SkillDir>/scripts/check_contracts.py
 
 | 模块 | 谁在用 | 作用 |
 |---|---|---|
-| `template_paths.py` | registry_loader / template_binder / gen-script / check_contracts | 统一计算 monorepo / template-library 路径,代替 4 个 caller 各自数 `..` |
 | `registry_loader.py` | template-registry / match_template / render-video / gen-script / dsl_validator | 加载 registry(HTTP + cache + file) |
 | `match_template.py` | render-video(`auto_bind_template`) | DSL → TemplateBinding 算法 |
 | `render_job_client.py` | render-video / export-jianying | ab-api renderJob HTTP 客户端 |
-| `check_contracts.py` | 维护脚本 | template-library ↔ remotion-renderer 契约校验 |
-| `sync_registry.py` | 维护脚本 | 把 registry 摘要落盘供 LLM prompt 使用 |
+| `countdown_spec.py` | gen-script / render-video | 解析 `capabilities.countdown` 声明 |
 
 sibling skill 通过 `sys.path.insert(0, "<…>/template-registry/scripts")` 然后直接 `import` 模块名,模式见 `render_video.py` 顶部的"Single sys.path setup"段。
 

package/skills/template-registry/SKILL.md

@@ -25,23 +25,7 @@ Stores every video-template definition, loads a template by **template-id**, and
 
 Template metadata is authored in the standalone **template-library** monorepo, published to ab-api, and served to the CLI over HTTP. At runtime template-registry loads the registry from a single source — the ab-api endpoint (see the env table below) — which returns every template definition (full slotMapping, compositions, etc.) including the caller's private/tenant templates.
 
-> The `template-library/packages/metadata/registry.json` file below is the authoring layout in the monorepo. It is **not** read at runtime anymore; only monorepo-only maintenance tooling (`check_contracts.py`, `sync_registry.py`) touches it directly.
-
-```
-template-library/packages/
-├── templates/src/
-│   ├── html-slide/        # Knowledge-board template
-│   │   ├── Composition.tsx
-│   │   └── template.json
-│   ├── image-slide/       # Basic image + narration template (includes the tech variant)
-│   │   └── ...
-│   ├── picture-book-en/   # English picture-book video template
-│   │   └── ...
-│   └── screen-walkthrough/ # Screen-recording walkthrough template
-│       └── ...
-└── metadata/
-    └── registry.json      # Aggregated registry (every template.json merged)
-```
+> Each template's `template.json` (authored in template-library, aggregated into `registry.json` there) is the single source of truth for everything template-specific: `llmHint`, `capabilities`, `customPayloadSchema`, `slideSchemas`, `slotMapping`. This skill and the rest of the CLI only implement the generic mechanisms those declarations drive — they never name individual templates, so read the template's own definition (see *Steps*) instead of looking for per-template rules here.
 
 ## Agent behavior: image URL handling
 
@@ -77,7 +61,8 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 > The Python binding logic that maps DSL → TemplateBinding lives in `scripts/match_template.py` but is **not exposed as a CLI** — it is only consumed as a Python library by `render-video`'s `render_video.py` via `import match_template`.
 
 1. **List available templates**: run `remixmate template-registry --list-templates` to view the templates in the registry along with their supported aspect ratios / style tags, and decide which `templateId` to pick.
-2. **Read that template's contract**: run `remixmate template-registry --template-id <id> --json-output` for the full definition (llmHint, `customPayloadSchema` with the legal `slideId` values, `slotMapping`, `variants`). The list view only carries a 200-char llmHint preview, which is not enough to author against.
+2. **Read that template's contract**: run `remixmate template-registry --template-id <id>` for the full definition (llmHint, `customPayloadSchema` with the legal `slideId` values, `slotMapping`, `variants`). The list view only carries a 200-char llmHint preview, which is not enough to author against. Read it **once per conversation** — it does not change between turns.
+2b. **Multi-layout templates: expand only the layouts you use.** For templates that ship `slideSchemas`, step 2 returns a per-layout **menu** (description, field names, card-list key / item fields / `maxItems`, and a `narration` note on layouts that must split narration into `items`). Choose layouts and draft the script from the menu; then, right before writing `templateData`, call once more with `--slide-id <id>` for every chosen layout (repeatable) to get their exact field schemas.
 3. **Write the DSL**: when generating the Video DSL, put the chosen `templateId` into `meta.templateId` (the canonical location). Use `meta.templateVariant` / `renderHints.templateVariant` to explicitly select a variant. The legacy `renderHints.templatePreference[0]` is still tolerated by `match_template.py` and `dsl_validator._pick_template_id` during transition, but new authors should write `meta.templateId`.
 4. **Produce the TemplateBinding**: there is no standalone CLI for DSL → TemplateBinding; `prepare_video_assets` calls `match_template.build_binding(template, dsl)` inline during the asset-resolution pipeline and embeds the binding into the RenderPlan it hands to the renderer — no separate `*.binding.json` file is written.
 
@@ -89,20 +74,6 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 remixmate template-registry --list-templates
 ```
 
-### Sync the registry cache (optional, used for offline / LLM prompt)
-
-```bash
-python3 <SkillDir>/scripts/sync_registry.py
-```
-
-`sync_registry.py` and `check_contracts.py` are **maintenance helpers** for template-library, not skill entry points. Keep invoking them directly via `python3`.
-
-### Verify template / Remotion contract consistency
-
-```bash
-python3 <SkillDir>/scripts/check_contracts.py
-```
-
 ### Build a binding locally (debug only, not part of the render pipeline)
 
 ```python
@@ -111,7 +82,7 @@ sys.path.insert(0, "<SkillDir>/scripts")
 from match_template import build_binding, load_full_template, load_registry
 
 dsl = json.load(open("my-video.dsl.json"))
-template = next(t for t in load_registry() if t["templateId"] == "image-slide")
+template = next(t for t in load_registry() if t["templateId"] == "<templateId>")
 binding = build_binding(load_full_template(template), dsl)
 print(json.dumps(binding, ensure_ascii=False, indent=2))
 ```
@@ -121,13 +92,14 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--list-templates` | List every available template as a **summary** (templateId / name / description / aspect ratios / language / status / styleTags / variantIds / the `capabilities` keys that drive authoring — `payloadStyle` / `needsNarration` / `durationStrategy` / `narrationDriver` — and llmHint truncated to 200 chars). | — |
-| `--template-id <id>` | Print that template's **full definition** — llmHint in full, `customPayloadSchema`, `slotMapping`, `compositions`, `variants`. Repeatable. | — |
+| `--template-id <id>` | Print that template's **full definition** — llmHint in full, `customPayloadSchema`, `slotMapping`, `compositions`, `variants` — as compact JSON. Multi-layout templates return `slideSchemas` as a menu. Repeatable. | — |
+| `--slide-id <slideId>` | With `--template-id`: expand these layouts' full `slideSchemas` (repeatable; `all` = every layout, large). Unknown ids fail with the legal list. | menu |
 | `--full` | List mode: emit full definitions instead of summaries. Refuses when the result would exceed 60 K characters. | off |
 | `--filter-tag` | Keep only templates whose `styleTags` match this substring (case-insensitive). | none |
 | `--filter-aspect` | Keep only templates declaring this aspect ratio (e.g. `9:16`). | none |
 | `--filter-language` | Keep only templates whose `contentLanguage` includes this code (`zh`/`en`); language-agnostic templates always show. | none |
 | `--include-beta` | Also show `status: beta` templates (same effect as `ENABLE_BETA_TEMPLATES=1`). | off |
-| `--json-output` | Emit `{ "templates": [...] }` instead of the table — summaries, or full definitions under `--template-id` / `--full`. | off |
+| `--json-output` | List mode: emit `{ "templates": [...] }` summaries (or full definitions with `--full`) instead of the table. Detail mode (`--template-id`) is always compact JSON. | off |
 
 ### List vs. detail
 
@@ -135,9 +107,12 @@ A registry row is 4–17 KB of JSON, so dumping every full definition at once ov
 
 ```bash
 remixmate template-registry --list-templates                         # choose
-remixmate template-registry --template-id html-slide --json-output   # then read its contract
+remixmate template-registry --template-id <templateId>                 # then read its contract (slide menu)
+remixmate template-registry --template-id <templateId> --slide-id key-points --slide-id timeline   # exact schemas of the chosen layouts
 ```
 
+Detail mode used to pretty-print, which nearly doubled the size (html-slide: 37 K → 65 K characters) and pushed the plain call past the agent's tool-result cap — the result was spilled to a file the agent cannot open, so it re-called with other flags, and re-read the whole contract on the next turn too (session review 2026-09-27). Output is now always compact, and `slideSchemas` — two thirds of a multi-layout template — is a menu until you name the layouts.
+
 This mirrors the list/detail split described in `scripts/registry_loader.py` (P1.2), realized CLI-side so it holds even while the backend still serves one merged registry payload.
 
 ## Props extraction rules
@@ -151,7 +126,7 @@ This mirrors the list/detail split described in `scripts/registry_loader.py` (P1
    - Two forms are supported: `{ from: "textLayers", role: "..." }` matches a textLayer by role; `{ from: "a.b.c" }` reads a value from the scene by dotted path.
 2. **`customPayload` full-field pass-through (no allowlist check)**
    - First `scene.customPayload.templateData.*` is injected; then `scene.customPayload.*` (except `templateData` itself). The latter overrides same-named values from the former, but neither can override fields already produced by propExtractors.
-   - This is the channel for templates such as html-slide that define their own sub-schema and need to pass `slideId` / `items` / `highlightMap`, etc.
+   - This is the channel for templates that define their own sub-schema (multi-layout templates pass `slideId`, their per-layout `templateData`, `highlightMap`, etc.).
    - `scene.templateData` (without the `customPayload` wrapper) is also recognized as a `templateData` source — equivalent shorthand.
    - **Note**: `requiredProps` / `optionalProps` are currently **just template-schema documentation**; they trigger no implicit pass-through. A field reaches `props` either through a propExtractor or through `customPayload`.
 
@@ -165,11 +140,11 @@ This mirrors the list/detail split described in `scripts/registry_loader.py` (P1
 
 **Common pitfall**: writing the same field in both `propExtractors` and `customPayload` — when they collide, `propExtractors` wins. Keep each field in exactly one place. `build_binding` now **detects this**: any prop name that is both declared in `propExtractors` and hit by `customPayload` pass-through (top-level, or `templateData` when the extractor reads from elsewhere) is recorded on the binding row as `dualChannelProps` and printed as a stderr warning; `test-template-pipeline.py` surfaces it as a non-fatal authoring warning. A field placed in its extractor's own declared source (e.g. extractor `from:"templateData.slideId"` + value in `templateData.slideId`) is **not** flagged — that is the legitimate source, not a double-write.
 
-> Historical issue: an early html-slide `point` slot declared `slideId` as `propExtractors.slideId={from:"templateData.slideId"}` and also marked it as `requiredProps`. But every existing DSL wrote `slideId` at `customPayload.slideId` (top-level, not inside templateData), so the propExtractor returned nothing and rendering fell back to the generic layout. The convention now is unified: **slideId flows through customPayload top-level pass-through**, propExtractors no longer declares it. New templates must follow the same convention.
+> Convention: **`slideId` flows through `customPayload` top-level pass-through**; templates do not declare it in `propExtractors`. An earlier template did both, the extractor read `templateData.slideId` while every DSL wrote `customPayload.slideId`, and every scene silently fell back to the generic layout.
 
-## Narration for multi-card scenes (html-slide template)
+## Narration for multi-card scenes (`lineSyncSlides`)
 
-When `html-slide` selects `demo-concept-overview` / `feature-grid` / `timeline` / `column-compare` (all "many-card sequential highlight" slides), you **must** use structured narration to avoid highlight/audio drift:
+A template that highlights cards one by one in step with the narration declares which layouts do so in `lineSyncSlides` (`slideId` → the `templateData` array holding the cards). For those layouts you **must** use structured narration, one line per card, to avoid highlight/audio drift:
 
 ```jsonc
 "audio": {
@@ -189,13 +164,13 @@ When `html-slide` selects `demo-concept-overview` / `feature-grid` / `timeline`
 ```
 
 Rules:
-- `items.length` must equal `customPayload.templateData.<concepts|items>.length` (demo-concept-overview uses `concepts`; the other three slides use `items`), otherwise `dsl_validator` rejects it.
-- Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns.
+- `items.length` must equal the length of `customPayload.templateData[lineSyncSlides[slideId]]`, otherwise `dsl_validator` rejects it.
+- Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns (capped at the declared card array's length). Template-specific exceptions (e.g. how an `outro` line should map) are in the template's `llmHint`.
 - If the author explicitly provides a `highlightMap`, the system keeps it as-is.
 - The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
 - `narration.languageBoost` (optional, also accepted at `global.narration`) pins the TTS language hint (`auto` / `Chinese` / `English` / …). Leave it unset unless auto-detection gets it wrong — the service applies its own default, and a scene-level value overrides the global one, exactly like `speed`.
 
-## Image sources (picture-book-en and every other template)
+## Image sources
 
 Image assets support two source forms:
 
@@ -232,16 +207,9 @@ Image assets support two source forms:
 - Local paths (`./image.png`, `/tmp/...`) are forbidden; HTTPS URLs only.
 - Both forms can be mixed inside the same DSL — each asset decides independently.
 
-## Picture-book narration rule (picture-book-en template)
-
-With `picture-book-en`, **narration reads English only, never Chinese**:
+## Template-declared narration and text-layer constraints
 
-- `audio.narration.text` and the corresponding `gen-voice` asset's `payload.text` **must contain only the English source** (ASCII letters + standard English punctuation); any CJK character or Chinese punctuation is forbidden.
-- The Chinese translation appears only on screen via `textLayers[role=subheadline].content` (mapped to `chineseTitle` / `chineseText`); it never enters TTS.
-- Layout is fixed:
-  - **Cover**: top half is the title area (English `englishTitle` on top in a large round-bold font; Chinese `chineseTitle` below in a smaller font); bottom half is the cover image / video.
-  - **Content page**: top half is the text area (English `englishText` on top in a large round-bold font; Chinese `chineseText` below); bottom half is the illustration.
-- `textLayers` role mapping is mandatory: `role=headline` carries the English text, `role=subheadline` carries the Chinese text.
+Some templates constrain what narration or on-screen text may contain — e.g. `capabilities.narrationLanguageStrict` (narration and its `gen-voice` text must be in one language) and `capabilities.textLayerRules` (which `textLayers` roles are required, and in which language). `dsl_validator` enforces the declarations; the template's `llmHint` explains how to write for them.
 
 ## Error handling
 

package/skills/template-registry/scripts/countdown_spec.py

@@ -29,10 +29,12 @@ The strategy carries the shape; the template carries every concrete value:
       "sceneStrategy": "countdown",
       "countdown": {
         "countProp": "topN",            // where the count goes in customPayload
-        "itemProp": "item",             // optional, default "item"
-        "indexProp": "rank",            // optional, default "rank"
+        "itemProp": "item",             // where one beat's item goes
+        "indexProp": "rank",            // the index field inside that item
         "legacyCountProps": ["totalItems"],
-        "openingSec": 2.5               // optional, default DEFAULT_OPENING_SEC
+        "openingSec": 2.5,              // optional, default DEFAULT_OPENING_SEC
+        "countPatterns": ["..."]        // optional: regexes that find a count stated
+                                        // in on-screen copy (group 1 = the number)
       }
     }
 
@@ -50,6 +52,8 @@ the count would fall back to "however many cards are present", and the
 
 from __future__ import annotations
 
+import re
+
 #: Opening budget when the template declares none. A generic "an opening is a
 #: beat, not a chapter" value — **not** any one template's measurement. It used
 #: to be 3 hardcoded in gen_script, taken from github-repo-rank's reference film
@@ -88,10 +92,23 @@ def resolve_countdown_spec(template: dict | None) -> dict | None:
         raise CountdownError(
             f"Template '{template_id}' declares capabilities.sceneStrategy=countdown but no "
             "capabilities.countdown.countProp. Declare which customPayload field carries the "
-            "item count (github-repo-rank uses \"topN\")."
+            "item count."
         )
     count_prop = count_prop.strip()
 
+    # itemProp / indexProp 同样必须声明：缺省值只能是某个具体模板的字段名，
+    # 那等于把那个模板写进 CLI。
+    names: dict[str, str] = {}
+    for key in ("itemProp", "indexProp"):
+        value = cfg.get(key)
+        if not isinstance(value, str) or not value.strip():
+            raise CountdownError(
+                f"Template '{template_id}' declares capabilities.sceneStrategy=countdown but no "
+                f"capabilities.countdown.{key}. Declare the customPayload field name — the CLI "
+                "does not guess one."
+            )
+        names[key] = value.strip()
+
     schema = (template or {}).get("customPayloadSchema")
     bounds = schema.get(count_prop) if isinstance(schema, dict) else None
     if not isinstance(bounds, dict):
@@ -119,6 +136,22 @@ def resolve_countdown_spec(template: dict | None) -> dict | None:
     legacy = cfg.get("legacyCountProps")
     legacy = [p for p in legacy if isinstance(p, str) and p.strip()] if isinstance(legacy, list) else []
 
+    patterns = []
+    for raw in cfg.get("countPatterns") or []:
+        try:
+            compiled = re.compile(raw, re.I) if isinstance(raw, str) else None
+        except re.error as exc:
+            raise CountdownError(
+                f"Template '{template_id}': countdown.countPatterns entry {raw!r} is not a valid "
+                f"regex ({exc})."
+            ) from None
+        if compiled is None or compiled.groups < 1:
+            raise CountdownError(
+                f"Template '{template_id}': countdown.countPatterns entry {raw!r} must be a regex "
+                "string with a capturing group for the number."
+            )
+        patterns.append(compiled)
+
     opening_sec = cfg.get("openingSec")
     if not (type(opening_sec) in (int, float) and opening_sec > 0):
         opening_sec = DEFAULT_OPENING_SEC
@@ -127,8 +160,9 @@ def resolve_countdown_spec(template: dict | None) -> dict | None:
         "template_id": template_id,
         "count_prop": count_prop,
         "legacy_count_props": legacy,
-        "item_prop": (cfg.get("itemProp") or "item").strip(),
-        "index_prop": (cfg.get("indexProp") or "rank").strip(),
+        "item_prop": names["itemProp"],
+        "index_prop": names["indexProp"],
+        "count_patterns": patterns,
         "minimum": minimum,
         "maximum": maximum,
         "default": default,
@@ -136,6 +170,22 @@ def resolve_countdown_spec(template: dict | None) -> dict | None:
     }
 
 
+def stated_counts(spec: dict, text: str) -> set[int]:
+    """Counts that on-screen copy states, found with the template's ``countPatterns``.
+
+    How a count is worded (``Top 5`` / ``前 5 名`` / ``5 个技巧``) is the
+    template's copy convention, so the patterns are declared there; a template
+    that declares none gets no check.
+    """
+    found: set[int] = set()
+    for pattern in spec.get("count_patterns") or []:
+        for match in pattern.finditer(text or ""):
+            for group in match.groups():
+                if group is not None and group.isdigit():
+                    found.add(int(group))
+    return found
+
+
 def resolve_count(spec: dict, requested: int | None, scene_count: int | None) -> int:
     """Validate a caller-supplied item count against the template's own bounds.