@remixmate/cli 0.9.49 → 0.9.51

package/README.md

@@ -259,32 +259,20 @@ npm run smoke
 # CLI unit tests (argv parser + skill schema)
 npm run test:cli
 
-# ── Template regression (after changing binding / timeline / template code) ──
-# L1 (contracts) + L2 (render-plan golden snapshots), full coverage, seconds,
-# no render and no generation API calls. Run this before/after touching shared
-# template plumbing to catch "did I break some OTHER template's binding?".
-npm run regress
-
-# Accept intended render-plan changes (rewrites L2 baselines):
-npm run regress:update
-
-# Run only the render-plan snapshot layer:
-npm run test:render-plan
-
-# Narration speed wiring (gen_script → render plan → gen-voice --speed).
-# Fully offline: no registry, no TTS call.
-npm run test:narration-speed
-
-# L3 — selective, real Remotion render of chosen template(s). NOT full-library
-# by design (rendering is slow + needs asset generation). Catches crashes /
-# black frames the static layers can't. Needs PRIV_TOKEN for narration TTS;
-# pass --stub-image-url to keep image-heavy renders cheap.
-npm run check:render -- --template spotlight-card --frame
-
-# Template defs come from the registry (ab-api HTTP + /tmp cache), exactly like
-# render_video in production. A warm cache or reachable ab-api is required.
-# In a multi-repo checkout the scripts auto-detect template-library; override
-# with AB_TEMPLATES_SRC=/path/to/template-library/packages/templates/src.
+# ── Unit tests for the Python pipeline ──
+# Fully offline. They exercise the CLI's generic mechanisms against the synthetic
+# templates in scripts/fixtures/ — never against a real template library, so
+# template changes cannot turn them red.
+npm run test:unit
+
+# ── Integration: run the CLI against a real template library ──
+# Validation, binding, RenderPlan and props contracts over every template (and
+# dsl-example) in AB_TEMPLATES_SRC. Names no template; needs no ab-api or login.
+AB_TEMPLATES_SRC=/path/to/template-library/packages/templates/src npm run integration
+
+# Selective real Remotion render of chosen template(s). Needs PRIV_TOKEN for
+# narration TTS; pass --stub-image-url to keep image-heavy renders cheap.
+AB_TEMPLATES_SRC=... npm run integration:render -- --template <id> --frame
 
 # Python skills forward --help to the underlying script:
 remixmate gen-script --help

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.49",
-  "generatedAt": "2026-09-26T14:13:13.805Z",
+  "version": "0.9.51",
+  "generatedAt": "2026-09-27T12:37:01.962Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -9,7 +9,7 @@
       "tier": "tool",
       "category": "consuming",
       "title": "Document Extraction",
-      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the per-page slide payload that templates declaring capabilities.payloadHydration (docKind pptx) render one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
       "triggers": [
         "Turn this PPT / slide deck into a video",
         "Extract text or speaker notes from a .pptx",
@@ -437,7 +437,7 @@
           },
           "scenes": {
             "type": "number",
-            "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (e.g. ppt-to-video), pass the page count you saw in doc_parse's summary."
+            "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (capabilities.payloadHydration), pass the page count you saw in doc_parse's summary."
           },
           "voice_id": {
             "type": "string",
@@ -447,13 +447,21 @@
             "type": "number",
             "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
           },
+          "variant": {
+            "type": "string",
+            "description": "Template visual variant id (a key of the template's variants; template_registry lists them as variantIds). Written to meta.templateVariant, which beats the fuzzy `style` match. **Must** pass when the user picked a style: the replicate card shows it as `名字（id）` — e.g. `视觉风格: 紫色科技（tech-purple）` or `板面颜色: 黑板（black-board）` → pass the id in the parentheses. Without it the choice is silently dropped. Requires template_id; an id the template does not declare is rejected."
+          },
+          "background_preset": {
+            "type": "string",
+            "description": "Scene background preset, one of the template's customPayloadSchema.background.preset values. Written to every scene's customPayload.background.preset. **Must** pass when the user picked a background: the replicate card shows `背景样式: 纯色（solid）` → pass `solid`. Without it the scene keeps the template default. Requires template_id; unsupported values are rejected. `image` / `video` also need customPayload.background.assetRef on each scene."
+          },
           "template_id": {
             "type": "string",
-            "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
+            "description": "Template id (from template_registry). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
           },
           "source_document_url": {
             "type": "string",
-            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills every scene's customPayload.slide. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
+            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills the customPayload field the template declares (payloadHydration.payloadField) on every scene. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
           },
           "headline": {
             "type": "string",
@@ -475,7 +483,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Per-scene visuals for a visual-overlay template (image-slide etc.) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
+            "description": "Per-scene visuals for a visual-overlay template (capabilities.payloadStyle=visual-overlay) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
           },
           "caption_lines": {
             "type": "array",
@@ -520,6 +528,8 @@
           "scenes",
           "voice_id",
           "speed",
+          "variant",
+          "background_preset",
           "template_id",
           "source_document_url",
           "headline",
@@ -784,7 +794,7 @@
           },
           "source_document_url": {
             "type": "string",
-            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into every scene's customPayload.slide; you neither author nor see it."
+            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into the customPayload field the template declares (payloadHydration.payloadField) on every scene; you neither author nor see it."
           },
           "binding_json": {
             "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.49",
+  "version": "0.9.51",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -20,29 +20,25 @@
     "list": "node dist/cli.js --list",
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
-    "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
     "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
     "test:web-read:browser": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read-browser.py",
-    "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
-    "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
-    "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
+    "test:template-look": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-template-look.py",
     "test:narration-tts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-tts.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
     "test:required-props": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-required-props.py",
-    "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
-    "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",
-    "test:contracts": "PYTHONDONTWRITEBYTECODE=1 python3 skills/template-registry/scripts/check_contracts.py",
-    "regress": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py",
-    "regress:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py --update",
-    "check:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/render-template-check.py",
     "clean": "node scripts/clean.mjs",
     "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
     "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
     "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
-    "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py",
     "test:image-prompt-compose": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-prompt-compose.py",
-    "test:picture-book-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-picture-book-contract.py"
+    "test:page-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-page-contracts.py",
+    "test:declared-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-declared-keys.py",
+    "test:payload-hydration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-payload-hydration.py",
+    "test:sentence-alignment": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-sentence-alignment.py",
+    "test:unit": "npm run -s test:narration-speed && npm run -s test:template-look && npm run -s test:narration-tts && npm run -s test:render-resume && npm run -s test:required-props && npm run -s test:countdown && npm run -s test:prepare-contracts && npm run -s test:image-sequence && npm run -s test:image-prompt-compose && npm run -s test:page-contracts && npm run -s test:declared-keys && npm run -s test:payload-hydration && npm run -s test:sentence-alignment",
+    "integration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/regress.py",
+    "integration:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/render-template-check.py"
   },
   "keywords": [
     "claude-code",

package/skills/doc-parse/SKILL.md

@@ -5,7 +5,7 @@ description: |
 
   Two layers, picked with `--fields`:
   - **content** — per-page `title`, `text[]`, and `rawNotes` (the speaker notes). Small, no base64. This is the narration source material.
-  - **layout** — the full `slide` payload the `ppt-to-video` template renders from: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. Large (icons are embedded as data URIs).
+  - **layout** — the full per-page `slide` payload: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. This is what templates declaring `capabilities.payloadHydration` with `docKind: pptx` render from. Large (icons are embedded as data URIs).
 
   Deterministic: the endpoint parses OOXML, it does **not** call a model. Notes come back verbatim — rewriting them into narration is your job, not the endpoint's.
 
@@ -14,7 +14,7 @@ description: |
   - Read / extract / summarize a .pptx, pull the text or the speaker notes out of a deck
   - Use a PowerPoint file as source material for a script
 
-  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain `customPayload.slide` — that payload never passes through you; see "Using the result".
+  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain the layout payload for a template — that payload never passes through you; see "Using the result".
 triggers:
   - Turn this PPT / slide deck into a video
   - Extract text or speaker notes from a .pptx
@@ -108,12 +108,12 @@ So the picture travels **by reference**:
 doc_parse  --url "https://…/deck.pptx"
 
 # 2. pass the SAME url to gen_script, plus one scene per page
-gen_script --template-id ppt-to-video \
+gen_script --template-id <templateId> \
            --source-document-url "https://…/deck.pptx" \
            --scenes 23
 ```
 
-`gen_script` records it at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.slide` before validation. You never see that data, and you never hand-write it.
+`<templateId>` is a template that declares `capabilities.payloadHydration` with `docKind: pptx`. `gen_script` records the URL at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.<payloadHydration.payloadField>` before validation. You never see that data, and you never hand-write it.
 
 What you *do* own from this result:
 
@@ -124,9 +124,9 @@ What you *do* own from this result:
 | `mode` + beat count per page | cut the narration into that many sentences |
 | `flags` | tell the user which elements the extractor could not reconstruct |
 
-Do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it by writing `customPayload.mode`. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+Do not second-guess `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). Whether and how a template lets you override it is in that template's `llmHint`.
 
-> If `prepare_video_assets` ever tells you `customPayload.slide (required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
+> If `prepare_video_assets` ever reports that hydrated field as `(required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
 
 **For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
 

package/skills/doc-parse/scripts/extract_via_render.py

@@ -16,8 +16,9 @@
 
 ⚠️ 关于 layout 层的用法，看清楚这一条：**它不是给你读的**。在 ab-agent 里模型没有
 任何文件读取工具（这是有意的安全收窄），所以落盘的那个文件你打不开。需要 layout 的
-模板（ppt-to-video）按引用取数：把同一个文档 URL 传给 ``gen_script --source-document-url``，
-渲染管线会自己把每一页填进 ``customPayload.slide``。见 SKILL.md「Using the result」。
+模板（声明了 capabilities.payloadHydration）按引用取数：把同一个文档 URL 传给
+``gen_script --source-document-url``，渲染管线会自己把每一页填进模板声明的 customPayload
+字段。见 SKILL.md「Using the result」。
 
 必要环境变量（由 ab-agent 自动注入）：
   RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）

package/skills/doc-parse/skill.json

@@ -4,7 +4,7 @@
   "tier": "tool",
   "category": "consuming",
   "title": "Document Extraction",
-  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the per-page slide payload that templates declaring capabilities.payloadHydration (docKind pptx) render one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
   "auth": "required",
   "envVars": [
     "RENDER_API_URL",

package/skills/gen-script/SKILL.md

@@ -64,12 +64,12 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 
 ### Document-driven templates: pass the source URL, don't author the payload
 
-Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` (today: `ppt-to-video`, which fills `customPayload.slide` from a `.pptx`).
+Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` — `payloadField` names the `customPayload` field the pipeline fills, `docKind` the kind of source file (e.g. `.pptx`).
 
 For those, pass **`--source-document-url`** — the same URL you gave `doc_parse`:
 
 ```bash
-gen_script --template-id ppt-to-video \
+gen_script --template-id <templateId> \
            --source-document-url "https://…/deck.pptx" \
            --scenes 23 --duration 600
 ```
@@ -93,7 +93,7 @@ If the count you need is above the template's maximum, say so and stop — do no
 
 ### Multi-layout templates: pick a layout per scene
 
-When a template's `customPayloadSchema.slideId.enum` holds more than one value (today `html-slide` and `html-slide-blackboard`, 16 layouts each), **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
+When a template's `customPayloadSchema.slideId.enum` holds more than one value, **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
 
 `gen_script.py` cannot make that choice: it emits the placeholder `"slideId": "__CHOOSE_SLIDE__"`, and the DSL validator rejects any DSL that still carries it, listing the legal values in the error. Replace every placeholder, and do not reuse one layout for the whole video.
 
@@ -103,7 +103,7 @@ A missing `slideId` is the quietest failure in the pipeline: the renderer drops
 
 Picking the layout is only half of it. Each layout reads its own field names out of `templateData`, and a field the layout does not read is **dropped without a word** — that slot renders empty, or shows the component's built-in placeholder text, and the render still reports success.
 
-This has shipped broken videos: a 7-scene deck wrote `items[].title` where `html-slide`'s `feature-grid` reads `name`, `items[].description` where `timeline-axis` reads `detail`, and `title` / `subtitle` / `ctaText` where `closing-cta` reads `headline` / `actionLine` / `ctaLabel` / `ctaUrl`. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render.
+This has shipped broken videos: a 7-scene deck guessed generic names (`title`, `description`, `ctaText`) where the chosen layouts read different ones. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render. Which names each layout reads is the template's fact; the template's `llmHint` calls out the usual traps.
 
 So: **copy the field names out of `slideSchemas[slideId]`.** The DSL validator now rejects unknown field names before any asset is generated and tells you the declared ones, but that check only fires for templates that ship `slideSchemas` — reading the contract is still the primary move, not the fallback.
 
@@ -257,7 +257,7 @@ Every URL the user gave becomes one carousel item, in order. How long each item
 ## Agent behavior: user-supplied images for scene-based templates (`--scene-images`)
 
 The section above covers `carousel-caption` templates. Templates whose `payloadStyle` is
-`visual-overlay` (image-slide and friends) have **real scenes**, each with its own background
+`visual-overlay` have **real scenes**, each with its own background
 image and its own narration — for those, user-supplied images go through `--scene-images`,
 not `--carousel-items`.
 
@@ -342,13 +342,13 @@ describes an `ai:` prompt as if it were a picture you have seen.
 
 ### Command example
 
-User: "用 image-slide 做一条讲 RAG 的视频，配图用这两张"
+User: "用这个模板做一条讲 RAG 的视频，配图用这两张"（a `visual-overlay` template）
 + two asset lines with `desc:`
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "三分钟看懂 RAG" \
-  --template-id image-slide \
+  --template-id <templateId> \
   --scene-images "https://cdn.example.com/a.png" \
   --scene-images "ai: 赛博朋克风格的服务器机房" \
   --scene-images "https://cdn.example.com/b.png"
@@ -388,14 +388,14 @@ Typical phrasings (non-exhaustive):
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "English picture-book story" \
-  --template-id picture-book-en \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/placeholder.jpg"
 ```
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "GitHub project tour" \
-  --template-id screen-walkthrough \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/img.jpg" \
   --stub-video-url "https://cdn.example.com/demo.mp4"
 ```
@@ -407,7 +407,7 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_script.py`; never hard-code paths.
 2. **Understand the request**: extract topic, duration, style, audience, etc.
 3. **If the user specifies a template, read it first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
-4. **Generate the DSL**: pick the right command or DSL shape for the target template (see the per-template commands below).
+4. **Generate the DSL**: pick the flags the target template's `capabilities` call for (see *Common CLI flags*); the template's `llmHint` says what to fill in afterwards.
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
 6. **User confirmation**: show the script summary and wait for confirmation, per the rules above.
 
@@ -454,6 +454,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--scenes` | Scene count. | auto-planned |
 | `--voice-id` | Narration voice id. | resolved from template + language fallback |
 | `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
+| `--variant` | Template visual variant id (a key of the template's `variants`; `template-registry --list-templates` prints them as `variantIds`). Written to `meta.templateVariant`, which takes precedence over the fuzzy `--style` match. Pass it whenever the user picked a style — the replicate card shows it as `名字（id）`, e.g. `视觉风格: 紫色科技（tech-purple）`; pass the id in the parentheses. Requires `--template-id`; unknown ids are rejected. | template default |
+| `--background-preset` | Scene background preset, one of the template's `customPayloadSchema.background.preset` values. Written to every scene's `customPayload.background.preset` (other keys of the template's default background are kept). Pass it whenever the user picked a background, e.g. `背景样式: 纯色（solid）` → `solid`. `image` / `video` also need `customPayload.background.assetRef`. Requires `--template-id`; unsupported values are rejected. | template default |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
 | `--validate` | Validate-only mode: only validate the input DSL. | — |
@@ -462,7 +464,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
 | `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates. Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
-| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template (image-slide etc.), mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
+| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template, mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
 | `--caption-lines` | Repeatable. On-screen caption line for `carousel-caption` templates → `customPayload.caption.lines`. Line limits and `**emphasis**` support are declared per template (see its `llmHint`). **Required** for `durationStrategy: fit-caption` templates — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles

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

@@ -36,7 +36,7 @@ if os.path.isdir(_TEMPLATE_DSL_DIR):
     sys.path.insert(0, os.path.abspath(os.path.join(_TEMPLATE_DSL_DIR, "..")))
 
 # Shared Python lib lives under skills/template-registry/scripts/ — the de-facto
-# cross-skill module location (registry_loader, template_paths, etc.). See
+# cross-skill module location (registry_loader, countdown_spec, etc.). See
 # AGENTS.md for the convention.
 _SHARED_SCRIPTS_DIR = os.path.join(
     os.path.dirname(__file__), "..", "..", "template-registry", "scripts"
@@ -54,6 +54,7 @@ try:
         resolve_count as resolve_countdown_count,
         resolve_countdown_spec,
         scene_payload as countdown_scene_payload,
+        stated_counts as countdown_stated_counts,
     )
     _HAS_COUNTDOWN = True
 except ImportError:
@@ -1267,31 +1268,18 @@ def _plan_countdown_scenes(spec: dict, count: int, duration: float, headline: st
     ]
 
 
-def _warn_on_count_mismatch(headline: str, subheadline: str, count: int) -> None:
+def _warn_on_count_mismatch(spec: dict, headline: str, subheadline: str, count: int) -> None:
     """画面文字里写的数量与实际节拍数不一致时出声提醒（不阻断、不改写）。
 
-    **刻意只 warn 不改写。** 这里曾经有一对 ``_rank_copy`` / ``_rank_title``，是
-    github-repo-rank 的 ``payload.ts`` 里 ``formatRankCopy`` / ``formatRankTitle``
-    的逐行 Python 移植 —— 同样的三个正则，在两个仓库、两种语言里各存一份。那是本文件
-    在 ``_echo_template_llm_hint`` 里写明要避免的事：**CLI 出机制，模板出内容**。标题
-    该怎么写、数量该以什么措辞出现（``Top 5`` / ``前 5 名`` / ``5 个项目``）是模板的
-    版式事实，真源是模板自己。
+    **刻意只 warn 不改写。** 标题该怎么写、数量以什么措辞出现是模板的版式事实，
+    模板在渲染时本来就会同步；手写 DSL、历史计划、ab-web 改过的标题都不经过
+    gen_script，所以这里替它改既不必要，也会静默改掉调用方给的文案。
 
-    去掉那份移植不会让成片出错：模板在渲染时本来就会同步（github-repo-rank 在
-    ``Opening.tsx`` / ``Cover.tsx`` 里做），而且它**必须**保留这个能力 —— 手写 DSL、
-    历史计划、ab-web 改过的标题都不经过 gen_script。CLI 这一份自始至终只影响用户在
-    确认脚本那一步看到的文字，为它复制一套会漂移的正则不值得。
-
-    换成告警的另一个好处：静默改写调用方给的文案本身就不妥（同 ``_warn_on_url_text_layer``
-    的分寸）。把数量告诉它，让它自己把文案写对，比替它改更不容易出意外。
-
-    这里认的措辞（``Top N`` / ``N 个项目`` / ``前 N 名``）只用来**发现不一致**，
-    不用来生成文案，所以它不构成一份需要跟模板同步的版式规则。
+    认哪些措辞由模板的 ``countdown.countPatterns`` 声明（见 countdown_spec），
+    CLI 不内置任何词表；没声明的模板不做这项检查。
     """
-    pattern = r"(?<![a-zA-Z0-9_])top\s*([0-9]+)(?![a-zA-Z0-9_])|(?:^|[^0-9])([0-9]+)\s*(?:个(?=\s*(?:开源项目|项目|仓库|工具))|(?=\s*名))"
     for flag, value in (("--headline", headline), ("--subheadline", subheadline)):
-        stated = {int(g) for match in re.finditer(pattern, value or "", flags=re.I)
-                  for g in match.groups() if g is not None}
+        stated = countdown_stated_counts(spec, value)
         if stated and count not in stated:
             print(
                 f"⚠️  {flag} says {sorted(stated)} item(s) but --item-count is {count}. "
@@ -1305,6 +1293,73 @@ def _warn_on_count_mismatch(headline: str, subheadline: str, count: int) -> None
             )
 
 
+def _template_background_presets(template_config: dict | None) -> list[str]:
+    """模板在 ``customPayloadSchema.background.preset`` 声明的背景取值（没声明 = 空表）。
+
+    背景词汇是**模板自己的**：同样叫「网格」，不同模板的取值名各不相同，默认值也
+    各不相同。所以这里只读声明，不在 CLI 里维护任何取值表。
+    """
+    schema = (template_config or {}).get("customPayloadSchema") or {}
+    background = schema.get("background") if isinstance(schema, dict) else None
+    props = background.get("properties") if isinstance(background, dict) else None
+    preset = props.get("preset") if isinstance(props, dict) else None
+    enum = preset.get("enum") if isinstance(preset, dict) else None
+    return [str(v) for v in enum] if isinstance(enum, list) else []
+
+
+def _apply_look(
+    dsl: dict,
+    template_config: dict | None,
+    template_id: str | None,
+    variant: str | None,
+    background_preset: str | None,
+) -> None:
+    """把用户选的视觉风格 / 背景样式写进 DSL（就地改）。
+
+    这两个值以前没有任何一跳能落进管线：复刻弹窗让用户选了，gen_script 却只写模板
+    默认背景，merge 模式又只替换旁白——成片照出、不报错，用户只觉得「好像没生效」。
+
+    - ``--variant`` → ``meta.templateVariant``：match_template 把它当**显式**选择，
+      优先于 meta.style 的模糊匹配，最终成为 inputProps.variantId；
+    - ``--background-preset`` → 每个场景 ``customPayload.background.preset``：
+      customPayload 原样透传给模板，模板读的正是这个字段。保留模板默认背景里的其它键。
+
+    取值不在模板声明里就直接退出：静默丢掉用户的选择，正是这里要修的那个 bug。
+    """
+    if not variant and not background_preset:
+        return
+    if not template_id or template_config is None:
+        raise ValueError("--variant / --background-preset need --template-id: the allowed values come from the template.")
+
+    if variant:
+        variants = list((template_config.get("variants") or {}).keys())
+        if variant not in variants:
+            raise ValueError(
+                f"--variant {variant!r} is not a variant of template {template_id!r}; "
+                f"choose one of: {', '.join(variants) or '(this template declares no variants)'}"
+            )
+        dsl.setdefault("meta", {})["templateVariant"] = variant
+
+    if background_preset:
+        presets = _template_background_presets(template_config)
+        if background_preset not in presets:
+            raise ValueError(
+                f"--background-preset {background_preset!r} is not supported by template {template_id!r}; "
+                f"choose one of: {', '.join(presets) or '(this template has no background option)'}"
+            )
+        for scene in dsl.get("scenes", []):
+            payload = scene.setdefault("customPayload", {})
+            existing = payload.get("background") if isinstance(payload.get("background"), dict) else {}
+            payload["background"] = {**existing, "preset": background_preset}
+        if background_preset in ("image", "video"):
+            print(
+                f"ℹ️  background preset {background_preset!r} needs a user asset: set "
+                f"customPayload.background.assetRef on each scene to that asset's id, "
+                f"otherwise the template falls back to its default background.",
+                file=sys.stderr,
+            )
+
+
 def build_dsl(
         topic: str,
         duration: int,
@@ -1393,7 +1448,7 @@ def build_dsl(
     _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(effective_headline, effective_subheadline, beat_count)
+        _warn_on_count_mismatch(countdown, effective_headline, effective_subheadline, beat_count)
 
     # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
     if payload_style == "carousel-caption":
@@ -1817,7 +1872,9 @@ def build_dsl(
             f"is only a placeholder.\n"
             f"   Write the full DSL yourself from the user's material (scenes, assets, visuals, "
             f"customPayload) and submit all of it to prepare_video_assets — it is used as-is, "
-            f"not merged onto this skeleton. Keep meta.templateId.",
+            f"not merged onto this skeleton. Keep meta.templateId, and copy meta.templateVariant and "
+            f"each scene's customPayload.background from this skeleton when present (they carry the "
+            f"user's --variant / --background-preset choice).",
             file=sys.stderr,
         )
 
@@ -1846,7 +1903,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). Recorded at "
+             "document (capabilities.payloadHydration). Recorded at "
              "meta.sourceDocument; prepare_video_assets then fetches the layout itself and fills "
              "every scene's customPayload. Pass the same URL you gave doc_parse. Without it such a "
              "template's DSL is rejected downstream.",
@@ -1875,6 +1932,19 @@ Examples:
         ),
     )
     parser.add_argument("--font-name", default=None, help="Human-readable font name. Logged and stored for display only; never used for rendering.")
+    parser.add_argument(
+        "--variant", default=None,
+        help="Template visual variant id (a key of the template's `variants`, listed as variantIds by "
+             "template-registry --list-templates). Written to meta.templateVariant, which overrides the "
+             "fuzzy --style match. When the user picked a style in the replicate card (shown as "
+             "`名字（id）`, e.g. `紫色科技（tech-purple）`), pass that id. Requires --template-id.",
+    )
+    parser.add_argument(
+        "--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.",
+    )
     parser.add_argument("--allow-digital-human", action="store_true", help="Allow digital-human assets")
     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.")
@@ -1920,7 +1990,7 @@ Examples:
         "--scene-images",
         action="append",
         default=None,
-        help="One scene's visual for a visual-overlay template (image-slide etc.). "
+        help="One scene's visual for a visual-overlay template (capabilities.payloadStyle). "
              "Can be repeated: --scene-images url1 --scene-images ai --scene-images url2. "
              "Each entry is either a URL (use that existing asset) or the literal 'ai' / "
              "'ai:<prompt>' (leave this scene to gen-image, optionally with the user's prompt). "
@@ -2073,6 +2143,17 @@ Examples:
         # as a message instead of a traceback.
         parser.error(str(exc))
 
+    try:
+        _apply_look(
+            dsl,
+            _load_template_config(args.template_id) if args.template_id else None,
+            args.template_id,
+            args.variant,
+            args.background_preset,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))
+
     # Post-process for --skip-asset-generation: rewrite all gen-voice / gen-digital-human
     # assets to be already-generated stubs. Image / video are already covered by the
     # stub_image_url / stub_video_url params threaded through build_dsl above.