voxflow 1.15.3 → 1.15.5

package/lib/stage-ui/slice/template.js

@@ -547,6 +547,112 @@ function renderSliceStageHtml({ sourcePath, port }) {
     .deck-toolbar button.copied {
       color: var(--good); border-color: var(--good);
     }
+    /* ─── Audition (▶) — voice picker + per-card play + status ────────────── */
+    .toolbar-divider {
+      width: 1px; align-self: stretch;
+      background: var(--border); margin: 2px 4px;
+    }
+    .voice-picker {
+      display: inline-flex; align-items: center; gap: 6px;
+      border: 1px solid var(--border); border-radius: 8px;
+      padding: 0 8px; font-size: 12px;
+    }
+    .voice-picker:focus-within { border-color: var(--accent); }
+    .voice-picker-icon { color: var(--muted); font-size: 12px; }
+    #voice-picker-input {
+      appearance: none; border: 0; background: transparent;
+      font: inherit; color: var(--text); font-size: 12px;
+      padding: 6px 0; width: 180px; outline: none;
+    }
+    .stage-card .card-actions button[data-action="audition"] .audition-icon {
+      display: inline-block; margin-right: 4px; font-size: 9px;
+    }
+    .stage-card .card-actions button[data-action="audition"].playing {
+      background: rgba(88,81,184,0.92); color: #fff;
+    }
+    .stage-card .card-actions button[data-action="audition"].loading {
+      background: rgba(0,0,0,0.45); color: #fff; cursor: progress;
+    }
+    .stage-card .card-actions button[data-action="audition"].error {
+      background: rgba(239,68,68,0.92); color: #fff;
+    }
+    .audition-status {
+      display: inline-flex; align-items: center;
+      font-size: 11px; color: var(--muted);
+      padding: 4px 10px; border-radius: 6px;
+      max-width: 320px;
+      overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    }
+    .audition-status[data-state="loading"] { color: var(--accent); }
+    .audition-status[data-state="cache"] {
+      color: var(--good); background: rgba(34,197,94,0.08);
+    }
+    .audition-status[data-state="error"] {
+      color: #b91c1c; background: rgba(239,68,68,0.08);
+    }
+    /* ─── Imagine (🎨) — per-card image gallery modal ─────────────────────── */
+    .stage-card .card-actions button[data-action="imagine"] .imagine-icon {
+      display: inline-block; margin-right: 4px; font-size: 10px;
+    }
+    .stage-card .card-actions button[data-action="imagine"] .imagine-count {
+      display: inline-block; margin-left: 4px;
+      padding: 1px 5px; border-radius: 8px;
+      background: rgba(255,255,255,0.25); font-size: 10px;
+      font-variant-numeric: tabular-nums;
+    }
+    .stage-card .card-actions button[data-action="imagine"][data-image-count="0"] {
+      opacity: 0.6;
+    }
+    .imagine-entry {
+      display: grid; gap: 10px;
+      padding: 14px 0; border-bottom: 1px solid var(--border);
+    }
+    .imagine-entry:last-child { border-bottom: 0; padding-bottom: 4px; }
+    .imagine-entry-meta {
+      display: flex; align-items: center; gap: 8px; flex-wrap: wrap;
+    }
+    .imagine-entry-id {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      font-size: 11px; font-weight: 600;
+      padding: 2px 8px; border-radius: 4px;
+      background: rgba(88,81,184,0.12); color: var(--accent);
+    }
+    .imagine-entry-aspect {
+      font-size: 10px; color: var(--muted);
+      letter-spacing: 0.06em; text-transform: uppercase;
+    }
+    .imagine-entry-prompt {
+      font-size: 12px; color: var(--text);
+      flex: 1 1 100%; min-width: 0;
+      line-height: 1.4;
+      word-break: break-word;
+    }
+    .imagine-entry-img {
+      max-width: 100%; max-height: 280px;
+      border: 1px solid var(--border); border-radius: 8px;
+      display: block; background: var(--surface-2);
+    }
+    .imagine-entry-img.loading {
+      opacity: 0.5;
+      animation: imagine-pulse 1.4s ease-in-out infinite;
+    }
+    @keyframes imagine-pulse {
+      0%, 100% { opacity: 0.4; }
+      50% { opacity: 0.7; }
+    }
+    .imagine-entry-error {
+      color: #b91c1c; font-size: 12px;
+      padding: 12px; border-radius: 8px;
+      background: rgba(239,68,68,0.08);
+    }
+    .imagine-entry-empty {
+      padding: 32px 16px; text-align: center;
+      color: var(--muted); font-size: 13px;
+    }
+    .imagine-entry-empty code {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      background: var(--surface-2); padding: 1px 5px; border-radius: 3px;
+    }
 
     .selection-fab {
       position: fixed; z-index: 50;
@@ -765,7 +871,14 @@ function renderSliceStageHtml({ sourcePath, port }) {
         <button id="copy-json-btn" type="button" disabled title="Copy raw deck.json to clipboard">Copy JSON</button>
         <button id="download-json-btn" type="button" disabled title="Save deck.json to disk">Download .json</button>
         <button id="copy-md-btn" type="button" disabled title="Copy as Markdown — paste into Notion / blog / 飞书">Copy as Markdown</button>
+        <span class="toolbar-divider" aria-hidden="true"></span>
+        <label class="voice-picker" title="Voice ID override (empty = let card.voiceover.voiceId or default win)">
+          <span class="voice-picker-icon" aria-hidden="true">♪</span>
+          <input id="voice-picker-input" type="text" placeholder="Voice (default)" spellcheck="false" autocomplete="off" aria-label="Voice override for audition" />
+        </label>
+        <span class="audition-status" id="audition-status" hidden aria-live="polite"></span>
       </div>
+      <audio id="audition-audio" preload="none"></audio>
       <div id="cards-pane" class="empty">Waiting for deck…</div>
     </section>
     <section>
@@ -785,6 +898,17 @@ function renderSliceStageHtml({ sourcePath, port }) {
     <span>✏</span><span>Edit selection with AI</span>
   </button>
 
+  <div class="modal-backdrop" id="imagine-modal" role="dialog" aria-modal="true" aria-labelledby="imagine-modal-title" hidden>
+    <div class="modal">
+      <div class="modal-header">
+        <h3 id="imagine-modal-title">Card images</h3>
+        <div class="grow"></div>
+        <button class="modal-close" id="imagine-modal-close" type="button" aria-label="Close">×</button>
+      </div>
+      <div class="modal-body" id="imagine-modal-body"></div>
+    </div>
+  </div>
+
   <div class="local-render-toast" id="local-render-toast" role="status" aria-live="polite">
     <div class="toast-head">
       <span>✓</span>
@@ -1018,6 +1142,204 @@ function renderSliceStageHtml({ sourcePath, port }) {
         copyTextToClipboard(formatCardAsText(card), btn);
       });
 
+      // ─── Per-card Audition (▶) — fetch /api/audition, play in <audio>. ────
+      // Voice override comes from the toolbar voice-picker input; empty input
+      // means let the server bridge resolve via the documented precedence
+      // (card.voiceover.voiceId → card.voiceId → SYNTHESIZE_DEFAULTS.voice).
+      // Status bar surfaces loading / cache HIT / upstream error so the user
+      // can spot quota or auth issues without opening browser devtools.
+      var auditionAudio = document.getElementById('audition-audio');
+      var auditionStatus = document.getElementById('audition-status');
+      var voicePickerInput = document.getElementById('voice-picker-input');
+      var currentAuditionBtn = null;
+
+      function setAuditionStatus(state, message) {
+        if (!auditionStatus) return;
+        if (!state) {
+          auditionStatus.hidden = true;
+          auditionStatus.removeAttribute('data-state');
+          auditionStatus.textContent = '';
+          return;
+        }
+        auditionStatus.hidden = false;
+        auditionStatus.dataset.state = state;
+        auditionStatus.textContent = message || '';
+      }
+
+      function resetAuditionBtn(btn) {
+        if (!btn) return;
+        btn.classList.remove('playing', 'loading', 'error');
+        var icon = btn.querySelector('.audition-icon');
+        if (icon) icon.textContent = '▶';
+      }
+
+      cardsPane.addEventListener('click', function (ev) {
+        var btn = ev.target.closest && ev.target.closest('[data-action="audition"]');
+        if (!btn || !currentDeck) return;
+        var idx = parseInt(btn.getAttribute('data-card-index'), 10);
+        if (!Number.isFinite(idx)) return;
+
+        // Click on the currently playing button = stop + reset.
+        if (currentAuditionBtn === btn && !auditionAudio.paused) {
+          auditionAudio.pause();
+          auditionAudio.currentTime = 0;
+          resetAuditionBtn(btn);
+          currentAuditionBtn = null;
+          setAuditionStatus(null);
+          return;
+        }
+        // Reset a previously playing button (if any) when starting a new one.
+        if (currentAuditionBtn && currentAuditionBtn !== btn) {
+          resetAuditionBtn(currentAuditionBtn);
+        }
+
+        currentAuditionBtn = btn;
+        btn.classList.remove('error');
+        btn.classList.add('loading');
+        var icon = btn.querySelector('.audition-icon');
+        if (icon) icon.textContent = '⟳';
+        setAuditionStatus('loading', 'Synthesizing card ' + (idx + 1) + '…');
+
+        var voiceOverride = (voicePickerInput && voicePickerInput.value.trim()) || '';
+        var url = '/api/audition?card=' + encodeURIComponent(idx)
+          + (voiceOverride ? '&voice=' + encodeURIComponent(voiceOverride) : '');
+
+        fetch(url, { method: 'GET', credentials: 'same-origin' })
+          .then(function (res) {
+            var cache = res.headers.get('X-Audition-Cache') || '';
+            if (!res.ok) {
+              return res.json().then(function (j) {
+                throw new Error((j && j.message) || ('HTTP ' + res.status));
+              }, function () {
+                throw new Error('HTTP ' + res.status);
+              });
+            }
+            return res.blob().then(function (blob) { return { blob: blob, cache: cache }; });
+          })
+          .then(function (out) {
+            var objectUrl = URL.createObjectURL(out.blob);
+            auditionAudio.src = objectUrl;
+            return auditionAudio.play().then(function () {
+              btn.classList.remove('loading');
+              btn.classList.add('playing');
+              if (icon) icon.textContent = '❚❚';
+              setAuditionStatus(
+                out.cache === 'HIT' ? 'cache' : 'loading',
+                out.cache === 'HIT' ? 'Cache hit — no quota used.' : 'Playing card ' + (idx + 1) + '.'
+              );
+            });
+          })
+          .catch(function (err) {
+            btn.classList.remove('loading', 'playing');
+            btn.classList.add('error');
+            if (icon) icon.textContent = '!';
+            setAuditionStatus('error', String(err && err.message || err));
+            setTimeout(function () {
+              if (currentAuditionBtn === btn) currentAuditionBtn = null;
+              resetAuditionBtn(btn);
+            }, 3000);
+          });
+      });
+
+      auditionAudio.addEventListener('ended', function () {
+        if (currentAuditionBtn) {
+          resetAuditionBtn(currentAuditionBtn);
+          currentAuditionBtn = null;
+        }
+        setAuditionStatus(null);
+      });
+      auditionAudio.addEventListener('error', function () {
+        if (currentAuditionBtn) {
+          currentAuditionBtn.classList.remove('loading', 'playing');
+          currentAuditionBtn.classList.add('error');
+          var ic = currentAuditionBtn.querySelector('.audition-icon');
+          if (ic) ic.textContent = '!';
+          currentAuditionBtn = null;
+        }
+        setAuditionStatus('error', 'Audio playback failed.');
+      });
+
+      // ─── Per-card Imagine (🎨) — open modal listing registered card.images. ─
+      // Click loads each image via /api/imagine which proxies hunyuan-image
+      // and caches by (prompt, aspect, quality) hash. <img> error handler
+      // surfaces backend errors (auth / quota / failed gen) inline.
+      var imagineModal = document.getElementById('imagine-modal');
+      var imagineModalBody = document.getElementById('imagine-modal-body');
+      var imagineModalClose = document.getElementById('imagine-modal-close');
+
+      function closeImagineModal() {
+        if (imagineModal) imagineModal.hidden = true;
+        if (imagineModalBody) imagineModalBody.innerHTML = '';
+      }
+
+      cardsPane.addEventListener('click', function (ev) {
+        var btn = ev.target.closest && ev.target.closest('[data-action="imagine"]');
+        if (!btn || !currentDeck) return;
+        var idx = parseInt(btn.getAttribute('data-card-index'), 10);
+        if (!Number.isFinite(idx)) return;
+        var cards = Array.isArray(currentDeck.cards) ? currentDeck.cards : [];
+        var card = cards[idx];
+        if (!card) return;
+        openImagineModal(idx, card);
+      });
+
+      function openImagineModal(cardIdx, card) {
+        if (!imagineModal || !imagineModalBody) return;
+        var images = Array.isArray(card.images) ? card.images : [];
+        if (images.length === 0) {
+          imagineModalBody.innerHTML =
+            '<div class="imagine-entry-empty">' +
+            'Card #' + (cardIdx + 1) + ' has no images registered.<br/>' +
+            'Add an entry to <code>cards[' + cardIdx + '].images: [{ id, prompt, aspect, quality }]</code> in deck.json.' +
+            '</div>';
+        } else {
+          imagineModalBody.innerHTML = images.map(function (img) {
+            if (!img || typeof img !== 'object') return '';
+            var src = '/api/imagine?card=' + encodeURIComponent(cardIdx) +
+                      '&img=' + encodeURIComponent(img.id || '');
+            var aspectStr = img.aspect ? '  ' + escapeHtml(img.aspect) : '';
+            var qualityStr = img.quality ? ' · ' + escapeHtml(img.quality) : '';
+            return '<div class="imagine-entry">' +
+                   '<div class="imagine-entry-meta">' +
+                     '<span class="imagine-entry-id">#' + escapeHtml(img.id || '?') + '</span>' +
+                     (aspectStr || qualityStr ? '<span class="imagine-entry-aspect">' + escapeHtml(aspectStr) + qualityStr + '</span>' : '') +
+                   '</div>' +
+                   '<div class="imagine-entry-prompt">' + escapeHtml(img.prompt || '') + '</div>' +
+                   '<img class="imagine-entry-img loading" alt="image for ' + escapeHtml(img.id || '') + '" loading="lazy" data-src="' + src + '" />' +
+                   '</div>';
+          }).join('');
+          // Wire up each <img> after insertion. We do it programmatically to
+          // attach load / error handlers without inline JS in the HTML
+          // (safer with the page-side escapeHtml + interpolation).
+          var imgs = imagineModalBody.querySelectorAll('img.imagine-entry-img');
+          imgs.forEach(function (el) {
+            var src = el.getAttribute('data-src');
+            el.addEventListener('load', function () { el.classList.remove('loading'); });
+            el.addEventListener('error', function () {
+              var msg = document.createElement('div');
+              msg.className = 'imagine-entry-error';
+              msg.textContent = 'Failed to load — check auth (voxflow login), quota, or prompt content.';
+              el.replaceWith(msg);
+            });
+            el.src = src;
+          });
+        }
+        imagineModal.hidden = false;
+      }
+
+      if (imagineModalClose) {
+        imagineModalClose.addEventListener('click', closeImagineModal);
+      }
+      if (imagineModal) {
+        imagineModal.addEventListener('click', function (e) {
+          // Click on backdrop (the modal-backdrop element itself, not its children) closes.
+          if (e.target === imagineModal) closeImagineModal();
+        });
+      }
+      document.addEventListener('keydown', function (e) {
+        if (e.key === 'Escape' && imagineModal && !imagineModal.hidden) closeImagineModal();
+      });
+
       // For highlighting cards that just changed on hot-reload, we keep a
       // hash of each card's stringified JSON. On the next deck event we
       // diff per-index and add the just-changed CSS class to whichever
@@ -1117,6 +1439,17 @@ function renderSliceStageHtml({ sourcePath, port }) {
           + '<div class="body">' + titleHtml + '</div>'
           + '<div class="accent-bar"></div>'
           + '<div class="card-actions">'
+              + '<button type="button" data-action="audition" data-card-index="' + i + '"'
+              + ' aria-label="Audition card ' + (i + 1) + ' voiceover" title="Play TTS preview — uses card.voiceover or card.narration, costs 100 quota first time then cached">'
+              + '<span class="audition-icon" aria-hidden="true">▶</span>Audition'
+              + '</button>'
+              + '<button type="button" data-action="imagine" data-card-index="' + i + '"'
+              + ' aria-label="Show generated images for card ' + (i + 1) + '"'
+              + ' title="View AI images registered on card.images — 200-500 quota first time per (prompt, aspect, quality), cached after"'
+              + ' data-image-count="' + (Array.isArray(card.images) ? card.images.length : 0) + '">'
+              + '<span class="imagine-icon" aria-hidden="true">🎨</span>Imagine'
+              + (Array.isArray(card.images) && card.images.length > 0 ? ' <span class="imagine-count">' + card.images.length + '</span>' : '')
+              + '</button>'
               + '<button type="button" data-action="copy-card" data-card-index="' + i + '"'
               + ' aria-label="Copy card ' + (i + 1) + ' as text">Copy text</button>'
           + '</div>'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voxflow",
-  "version": "1.15.3",
+  "version": "1.15.5",
   "description": "AI audio content creation CLI — stories, podcasts, narration, dubbing, transcription, translation, and video translation with TTS",
   "bin": {
     "voxflow": "./dist/index.js"

package/skills/voxflow-slice/SKILL.md

@@ -145,6 +145,85 @@ All cards require a non-empty `narration` string (TTS reads this; 30–60 zh cha
 }
 ```
 
+### Optional per-card `images` registry (Phase B)
+
+Any card kind may carry an `images: [{ id, prompt, aspect?, quality? }]`
+array of AI-generation recipes. The stage UI's 🎨 button resolves each
+entry through `/api/imagine` (proxies hunyuan-image, content-hash cached
+at `~/.config/voxflow/stage-image-cache/`); the first entry's resolved
+URL is used as the card's `slide.imageUrl` at render time, overriding any
+external `card.imageUrl`.
+
+```jsonc
+{
+  "kind": "body",
+  "caption": "...",
+  "narration": "...",
+  "figureKeyword": "growth-system",
+  "images": [
+    {
+      "id": "hero",                 // stable id ([a-zA-Z0-9_-]+, ≤64 chars, unique on card)
+      "prompt": "晨雾中的山脉，水墨风",   // ≤1000 chars
+      "aspect": "portrait",          // portrait | landscape | square (default: portrait)
+      "quality": "fast"              // fast (200 quota) | hd (500 quota)
+    }
+  ]
+}
+```
+
+Validator caps: `prompt` ≤ 1000 chars, `id` ≤ 64 chars matching `[a-zA-Z0-9_-]+`,
+at most 8 images per card, unique `id` within a card.
+
+### Optional per-card `el: "raw-html"` element (Phase C)
+
+V2 LayoutTree decks may carry a `{ el: "raw-html", html: "..." }` child to
+escape into arbitrary markup. The validator accepts strings up to 4096
+chars and `normalizeV2Children` maps the first occurrence to a `rawHtml`
+field on the V1 normalized output. **PaperSlide composition rendering of
+arbitrary HTML lands in a follow-up PR** — for now the composition
+silently skips the element, so a deck with raw-html validates + saves +
+edits cleanly but renders blank visually until the JSX side is updated.
+
+```jsonc
+{
+  "kind": "body",
+  "narration": "...",
+  "children": [
+    { "el": "heading", "text": "Custom panel" },
+    { "el": "raw-html", "html": "<div style='font-size:48px'>★</div>" }
+  ]
+}
+```
+
+On a body card, exactly one of `paper-figure` OR `raw-html` is required
+(both is rejected). Other kinds (title / quote / data / list) allow
+`raw-html` as a supplementary element.
+
+### Optional per-card `voiceover` override
+
+Any card kind may carry a nested `voiceover` object to tune its audio
+track. All four sub-fields are optional inside an optional object —
+absent ⇒ the renderer uses the job-level default voice with
+`card.narration` at 1× speed (back-compat with Phase 0 silent decks).
+
+```jsonc
+{
+  "kind": "body",
+  "caption": "短字幕",
+  "narration": "默认是 TTS 朗读的文本",
+  "voiceover": {
+    "enabled": true,             // false → this card is silent in the mp4
+    "voiceId": "v-female-R2s4N9qJ", // overrides the job-level default voice
+    "text": "口播稿可以跟字幕不一样",  // overrides narration for TTS only (visible caption unaffected)
+    "rate": 1.1                  // [0.5, 2.0], default 1.0
+  }
+}
+```
+
+Validator caps: `voiceover.text` ≤ 500 chars; `rate ∈ [0.5, 2.0]`.
+Render-time resolution precedence:
+`voiceover.voiceId → card.voiceId → job-level default`.
+
 > **Source of truth**: `backend/services/paper-slide/deck-validator.js` — caps live at lines 39–46 (QUOTE_TEXT_MAX, DATA_VALUE_MAX, LIST_ITEM_MAX_LEN, etc.). Read it if anything below seems ambiguous.
 
 ### Controlled `figureKeyword` list
@@ -225,6 +304,21 @@ These are the most common failure modes. The validator surfaces a clean error, b
 4. **`figureKeyword`** has no validator check on the keyword string itself (only that it's a string if present) — but **unknown keywords render as a default arrow**. Always pick from the controlled list.
 5. **`outro` card invariant** — at most one, must be last. `deck-validator.js:204–208`. Multiple outros = wiring bug, mid-deck outro = bug.
 
+## Quick start with curated templates
+
+When the user is new to Slice and wants something to copy from, point them
+at the curated gallery. Five hand-picked decks ship with the CLI and
+match the most common content shapes (product launch, founder lesson,
+data finding, incident review, quiet essay).
+
+```bash
+voxflow slice fork --list                    # browse the gallery
+voxflow slice fork product-launch            # copy the deck.json to cwd
+voxflow slice preview product-launch-deck.json   # iterate
+```
+
+The same gallery is browsable at `voxflow.studio/apps/slice/templates`.
+
 ## Hand-off
 
 After writing `deck.json`, tell the user:
@@ -232,12 +326,61 @@ After writing `deck.json`, tell the user:
 ```
 Wrote deck.json (<N> cards, theme: <theme-id>). Next:
 
-  voxflow slice render deck.json --output out.mp4    # render mp4 locally (~30s)
-  voxflow slice stage  deck.json                     # live preview in browser
+  voxflow slice preview deck.json                    # browser preview + per-card audition + 🎨 + render
+  voxflow slice render deck.json --output out.mp4    # one-shot mp4 from the terminal
 ```
 
 Do not run either command yourself unless the user asks.
 
+Both commands work fully offline for the visual side. **Audio (per-card
+TTS audition + render audio track) requires `voxflow login`** — 100 quota
+per unique `(voice, text)` clip, then cached at
+`~/.config/voxflow/stage-tts-cache/`. With no login, both commands fall
+back silently to a Phase-0-style silent video; pass `--no-audio` to
+`render` to suppress the audio pass entirely.
+
+## Multi-turn editing loop (Claude Code / Cursor / native `Edit`)
+
+When the user is iterating — "shorten card 2", "swap order", "different
+voice for card 3", "hear card 1 again" — they are **NOT** asking for a
+regen. Stay in this loop:
+
+```bash
+# Run once at the start of the session; auto-opens http://127.0.0.1:5180.
+# The page hot-reloads on every save of deck.json (~50 ms fs watcher).
+voxflow slice preview deck.json &
+```
+
+Then for every follow-up:
+
+| User intent | Your move | Cost |
+|---|---|---|
+| "card N is too long" | `Edit` `cards[N-1].caption` / `.narration` — page hot-reloads | 0 |
+| "swap card 2 and 3" | `Edit` the `cards` array order | 0 |
+| "different voice for card 3" | `Edit` `cards[2].voiceover.voiceId` — or tell user to paste a voiceId in the toolbar voice picker | 0 (Edit) |
+| "make card 4 silent" | `Edit` `cards[3].voiceover = { "enabled": false }` | 0 |
+| "口播说点不一样的" | `Edit` `cards[i].voiceover.text` so TTS reads override while caption stays | 0 |
+| "I want to hear card 3" | Tell user to click ▶ on card 3 in the browser; the toolbar shows cache hit / quota cost / error | 100 (first time per clip), 0 (cached) |
+| "regenerate the image on card 2" | `Edit` `cards[1].images[0].prompt` — user clicks 🎨 in stage to see the new variant | 200 (first time per prompt), 0 (cached) |
+| "give me a custom panel on card 4" | `Edit` `cards[3].children` to swap `paper-figure` for `raw-html` (V2 LayoutTree only) | 0 |
+| "render mp4" | Tell user: click **Render mp4 (local)** in the browser, OR `voxflow slice render deck.json` | TTS + image pass (cached if seen) + render |
+
+### Loop rules
+
+1. **Edit only the fields the user asked about.** Other cards must stay
+   byte-identical — the stage UI's diff highlight is the user's "what
+   changed" indicator. Touching extra fields breaks that signal.
+2. **Never re-run `voxflow slice <article>` during iteration** — that
+   costs 200 quota AND overwrites every user edit with a fresh LLM draft.
+3. **Re-validate after every save** by re-reading the file. If the user
+   says "page shows old content" or "red banner appeared", the JSON has a
+   syntax error (trailing comma, unbalanced quote) — open, fix, save.
+4. **Don't restart the preview server.** One process handles the whole
+   session; restarting wipes snapshot history.
+5. **Don't call `/api/audition` yourself.** It's user-driven via the ▶
+   button. Editing `cards[i].voiceover.voiceId` is enough — the next ▶
+   click picks up the new voice.
+
 ## Self-review checklist
 
 Before declaring the slice done:
@@ -254,6 +397,7 @@ Before declaring the slice done:
 - [ ] If the theme is `photo-feature` or `atmospheric` and the user provided per-card images, `imageUrl` starts with `https://`
 - [ ] No outro card unless the user explicitly asked for one
 - [ ] No React, TSX, or CSS files were created
+- [ ] If any card has a `voiceover` object, every key inside it (`enabled` / `voiceId` / `text` / `rate`) matches the schema (boolean / non-empty string ≤128 / string ≤500 / number in [0.5, 2.0])
 
 ## Anti-patterns
 

package/skills/voxflow-slice/templates/data-finding/deck.json

@@ -0,0 +1,40 @@
+{
+  "header": "数据发现",
+  "seriesTitle": "一个反直觉数字",
+  "seriesTagline": "看完你大概率会改方法",
+  "theme": "bold-poster",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["90%", "其实是错的"],
+      "narration": "我们查了一千个团队的工时表，发现一个反直觉的数字。"
+    },
+    {
+      "kind": "data",
+      "data": {
+        "value": "47",
+        "unit": "%",
+        "label": "时间花在等其他人决策"
+      },
+      "narration": "受访的产品经理里，平均 47% 的工时不是在做事，是在等其他人拍板。"
+    },
+    {
+      "kind": "body",
+      "caption": "瓶颈不在产能，在决策",
+      "figureKeyword": "decision-fork",
+      "narration": "团队越大，决策的链路越长，工时就越多地耗在等待。"
+    },
+    {
+      "kind": "body",
+      "caption": "把决策权下放到能做的人",
+      "figureKeyword": "owner-deadline",
+      "narration": "解法不复杂：明确谁能拍板，让 ta 不必再等上级签字。"
+    },
+    {
+      "kind": "body",
+      "caption": "47% 是可以拿回来的",
+      "figureKeyword": "growth-system",
+      "narration": "下调一层决策权之后，工时回收的中位数是 22%。值得动一下。"
+    }
+  ]
+}

package/skills/voxflow-slice/templates/founder-lesson/deck.json

@@ -0,0 +1,37 @@
+{
+  "header": "创业 · 复盘",
+  "seriesTitle": "一个人创业",
+  "seriesTagline": "回看一年前的自己",
+  "theme": "editorial-mag",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["最重要的事", "不是技术"],
+      "narration": "一年前我以为是技术决定生死，一年后才发现真正的决定者是别的。"
+    },
+    {
+      "kind": "body",
+      "caption": "把功能写得太多",
+      "figureKeyword": "stuck",
+      "narration": "前半年我加了二十个功能，用户记得的只有三个。剩下的成了我的债务。"
+    },
+    {
+      "kind": "body",
+      "caption": "把用户的话当作功能列表",
+      "figureKeyword": "problem-framing",
+      "narration": "用户说什么我就做什么，没意识到他们说的是问题，不是答案。"
+    },
+    {
+      "kind": "body",
+      "caption": "把孤独当作专注的代价",
+      "figureKeyword": "thinking",
+      "narration": "一个人写完所有代码，但没有人和我讨论方向，慢慢就走偏了。"
+    },
+    {
+      "kind": "body",
+      "caption": "现在每周强制和三个用户聊",
+      "figureKeyword": "team-alignment",
+      "narration": "现在每周固定和三个真实用户聊半小时，比写代码更影响下一步。"
+    }
+  ]
+}

package/skills/voxflow-slice/templates/incident-review/deck.json

@@ -0,0 +1,37 @@
+{
+  "header": "线上事故 · 复盘",
+  "seriesTitle": "一次三小时的宕机",
+  "seriesTagline": "我们认了，下次不会再这样",
+  "theme": "brutalist",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["3 小时宕机", "我们的复盘"],
+      "narration": "周二晚上九点，我们的服务挂了三个小时。这是怎么发生的。"
+    },
+    {
+      "kind": "body",
+      "caption": "一次例行发布触发了 OOM",
+      "figureKeyword": "risk-guardrail",
+      "narration": "晚上 21:08 上线了一个新功能，新代码在峰值流量下吃掉了所有内存。"
+    },
+    {
+      "kind": "body",
+      "caption": "告警没响，监控盲区",
+      "figureKeyword": "evidence-board",
+      "narration": "OOM 杀死了进程但没杀掉容器，健康检查仍然通过，告警延迟了 40 分钟。"
+    },
+    {
+      "kind": "body",
+      "caption": "回滚花了一小时，因为没演练过",
+      "figureKeyword": "timeline-review",
+      "narration": "我们有回滚脚本，但从来没真正跑过，第一次跑发现配置漂移了，又花一小时手动修。"
+    },
+    {
+      "kind": "body",
+      "caption": "三件改变：金丝雀、内存告警、月度演练",
+      "figureKeyword": "learning-loop",
+      "narration": "下个版本起：所有发布走 5% 金丝雀；监控加内存阈值；每月演练一次回滚。"
+    }
+  ]
+}