voxflow 1.15.0 → 1.15.2

package/lib/commands/slides/html-renderer.js

@@ -0,0 +1,338 @@
+/**
+ * Slides command — HTML layout renderers, theme CSS, and export builder.
+ */
+
+'use strict';
+
+// ─── HTML Escape ────────────────────────────────────────────────────────────
+
+function esc(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+// ─── Layout Renderers ──────────────────────────────────────────────────────
+
+const layoutRenderers = {
+
+  hero(c) {
+    return `<div class="slide-page slide-hero">
+      <h1>${esc(c.title)}</h1>
+      ${c.subtitle ? `<div class="slide-subtitle">${esc(c.subtitle)}</div>` : ''}
+    </div>`;
+  },
+
+  'title-bullets'(c) {
+    const items = (c.bullets || []).map(b => `<li>${esc(b)}</li>`).join('');
+    return `<div class="slide-page slide-title-bullets">
+      <h2>${esc(c.title)}</h2>
+      <ul class="slide-bullets">${items}</ul>
+    </div>`;
+  },
+
+  'two-column'(c) {
+    return `<div class="slide-page slide-two-column">
+      <h2>${esc(c.title)}</h2>
+      <div class="slide-columns">
+        <div class="slide-col">
+          <h3>${esc(c.left?.heading)}</h3>
+          <p>${esc(c.left?.text)}</p>
+        </div>
+        <div class="slide-col">
+          <h3>${esc(c.right?.heading)}</h3>
+          <p>${esc(c.right?.text)}</p>
+        </div>
+      </div>
+    </div>`;
+  },
+
+  'three-cards'(c) {
+    const cards = (c.cards || []).map(card => `
+      <div class="slide-card">
+        ${card.icon ? `<div class="slide-card-icon">${esc(card.icon)}</div>` : ''}
+        <h3>${esc(card.heading)}</h3>
+        <p>${esc(card.text)}</p>
+      </div>`).join('');
+    return `<div class="slide-page slide-three-cards">
+      <h2>${esc(c.title)}</h2>
+      <div class="slide-cards-grid">${cards}</div>
+    </div>`;
+  },
+
+  'image-left'(c) {
+    return `<div class="slide-page slide-image-split left">
+      <div class="slide-image-placeholder">IMG</div>
+      <div class="slide-image-content">
+        <h2>${esc(c.title)}</h2>
+        <p>${esc(c.text)}</p>
+      </div>
+    </div>`;
+  },
+
+  'image-right'(c) {
+    return `<div class="slide-page slide-image-split right">
+      <div class="slide-image-content">
+        <h2>${esc(c.title)}</h2>
+        <p>${esc(c.text)}</p>
+      </div>
+      <div class="slide-image-placeholder">IMG</div>
+    </div>`;
+  },
+
+  quote(c) {
+    return `<div class="slide-page slide-quote">
+      <blockquote>"${esc(c.quote)}"</blockquote>
+      <div class="slide-quote-author">— ${esc(c.author)}</div>
+      ${c.context ? `<div class="slide-quote-context">${esc(c.context)}</div>` : ''}
+    </div>`;
+  },
+
+  timeline(c) {
+    const events = (c.events || []).map(e => `
+      <div class="slide-timeline-event">
+        <div class="slide-timeline-year">${esc(e.year)}</div>
+        <div class="slide-timeline-text">${esc(e.text)}</div>
+      </div>`).join('');
+    return `<div class="slide-page slide-timeline">
+      <h2>${esc(c.title)}</h2>
+      <div class="slide-timeline-track">${events}</div>
+    </div>`;
+  },
+
+  stats(c) {
+    const items = c.stats || [];
+    const cols = Math.min(items.length, 4);
+    const statsHtml = items.map(s => `
+      <div class="slide-stat">
+        <div class="slide-stat-value">${esc(s.value)}</div>
+        <div class="slide-stat-label">${esc(s.label)}</div>
+      </div>`).join('');
+    return `<div class="slide-page slide-stats">
+      <h2>${esc(c.title)}</h2>
+      <div class="slide-stats-grid" data-cols="${cols}">${statsHtml}</div>
+    </div>`;
+  },
+
+  section(c) {
+    return `<div class="slide-page slide-section">
+      <h2>${esc(c.title)}</h2>
+      ${c.subtitle ? `<div class="slide-subtitle">${esc(c.subtitle)}</div>` : ''}
+    </div>`;
+  },
+};
+
+function renderSlideHTML(slide) {
+  const renderer = layoutRenderers[slide.layout] || layoutRenderers['title-bullets'];
+  return renderer(slide.content);
+}
+
+// ─── Theme CSS ─────────────────────────────────────────────────────────────
+
+const THEME_CSS = `
+/* Theme presets */
+.slides-style-midnight {
+  --slide-bg:#18181b;--slide-bg-alt:#27272a;--slide-accent:#2dd4bf;
+  --slide-accent-soft:rgba(45,212,191,0.15);--slide-text:#fafafa;
+  --slide-text-secondary:#a1a1aa;--slide-text-muted:#71717a;
+  --slide-border:#3f3f46;--slide-card-bg:#27272a;
+  --slide-hero-from:#18181b;--slide-hero-via:#1c1c22;--slide-hero-to:#18181b;
+}
+.slides-style-paper {
+  --slide-bg:#fafaf9;--slide-bg-alt:#f5f5f4;--slide-accent:#2563eb;
+  --slide-accent-soft:rgba(37,99,235,0.1);--slide-text:#1c1917;
+  --slide-text-secondary:#57534e;--slide-text-muted:#a8a29e;
+  --slide-border:#d6d3d1;--slide-card-bg:#ffffff;
+  --slide-hero-from:#f5f5f4;--slide-hero-via:#fafaf9;--slide-hero-to:#f5f5f4;
+}
+.slides-style-ember {
+  --slide-bg:#1c1917;--slide-bg-alt:#292524;--slide-accent:#f59e0b;
+  --slide-accent-soft:rgba(245,158,11,0.15);--slide-text:#fafaf9;
+  --slide-text-secondary:#a8a29e;--slide-text-muted:#78716c;
+  --slide-border:#44403c;--slide-card-bg:#292524;
+  --slide-hero-from:#1c1917;--slide-hero-via:#231f1b;--slide-hero-to:#1c1917;
+}
+.slides-style-forest {
+  --slide-bg:#14231a;--slide-bg-alt:#1a3024;--slide-accent:#4ade80;
+  --slide-accent-soft:rgba(74,222,128,0.12);--slide-text:#f0fdf4;
+  --slide-text-secondary:#86efac;--slide-text-muted:#4ade80;
+  --slide-border:#2d5a3e;--slide-card-bg:#1a3024;
+  --slide-hero-from:#14231a;--slide-hero-via:#182b20;--slide-hero-to:#14231a;
+}
+.slides-style-ocean {
+  --slide-bg:#0c1929;--slide-bg-alt:#132240;--slide-accent:#38bdf8;
+  --slide-accent-soft:rgba(56,189,248,0.12);--slide-text:#f0f9ff;
+  --slide-text-secondary:#7dd3fc;--slide-text-muted:#38bdf8;
+  --slide-border:#1e3a5f;--slide-card-bg:#132240;
+  --slide-hero-from:#0c1929;--slide-hero-via:#0f2035;--slide-hero-to:#0c1929;
+}
+
+/* Slide container */
+.slides-viewport { width:100vw;height:100vh;position:relative;overflow:hidden; background:var(--slide-bg); }
+.slide-page { position:absolute;inset:0;display:none;color:var(--slide-text); }
+.slide-page.active { display:flex; }
+
+.slide-hero { flex-direction:column;align-items:center;justify-content:center;text-align:center;
+  background:linear-gradient(135deg,var(--slide-hero-from),var(--slide-hero-via),var(--slide-hero-to));padding:10% 12%; }
+.slide-hero h1 { font-size:clamp(1.8rem,4vw,3.5rem);font-weight:700;line-height:1.2;margin-bottom:0.5em; }
+.slide-hero .slide-subtitle { font-size:clamp(1rem,1.8vw,1.5rem);color:var(--slide-accent); }
+
+.slide-title-bullets { flex-direction:column;justify-content:center;padding:8% 10%;background:var(--slide-bg); }
+.slide-title-bullets h2 { font-size:clamp(1.4rem,2.8vw,2.5rem);font-weight:700;margin-bottom:1.5em; }
+.slide-bullets { list-style:none;padding:0;display:flex;flex-direction:column;gap:0.8em; }
+.slide-bullets li { display:flex;align-items:flex-start;gap:0.6em;font-size:clamp(0.9rem,1.4vw,1.25rem);color:var(--slide-text-secondary);line-height:1.5; }
+.slide-bullets li::before { content:'';flex-shrink:0;width:8px;height:8px;margin-top:0.5em;border-radius:50%;background:var(--slide-accent); }
+
+.slide-two-column { flex-direction:column;justify-content:center;padding:8%;background:var(--slide-bg); }
+.slide-two-column h2 { font-size:clamp(1.4rem,2.8vw,2.5rem);font-weight:700;margin-bottom:1.2em; }
+.slide-columns { display:grid;grid-template-columns:1fr 1fr;gap:1.5em; }
+.slide-col { background:var(--slide-card-bg);border-radius:12px;padding:1.5em;border:1px solid var(--slide-border); }
+.slide-col h3 { font-size:clamp(0.9rem,1.3vw,1.15rem);font-weight:600;color:var(--slide-accent);margin-bottom:0.6em; }
+.slide-col p { font-size:clamp(0.8rem,1.1vw,1rem);color:var(--slide-text-secondary);line-height:1.6; }
+
+.slide-three-cards { flex-direction:column;align-items:center;justify-content:center;padding:6% 8%;background:var(--slide-bg); }
+.slide-three-cards h2 { font-size:clamp(1.4rem,2.8vw,2.5rem);font-weight:700;margin-bottom:1.2em;text-align:center; }
+.slide-cards-grid { display:grid;grid-template-columns:repeat(3,1fr);gap:1.2em;width:100%; }
+.slide-card { background:var(--slide-card-bg);border-radius:12px;padding:1.5em;text-align:center;border:1px solid var(--slide-border); }
+.slide-card-icon { font-size:2em;margin-bottom:0.5em; }
+.slide-card h3 { font-size:clamp(0.85rem,1.2vw,1.1rem);font-weight:600;margin-bottom:0.4em; }
+.slide-card p { font-size:clamp(0.75rem,1vw,0.9rem);color:var(--slide-text-muted);line-height:1.5; }
+
+.slide-image-split { background:var(--slide-bg); }
+.slide-image-split.left { flex-direction:row; }
+.slide-image-split.right { flex-direction:row-reverse; }
+.slide-image-placeholder { flex:1;display:flex;align-items:center;justify-content:center;background:var(--slide-bg-alt);font-size:3em;color:var(--slide-text-muted); }
+.slide-image-content { flex:1;display:flex;flex-direction:column;justify-content:center;padding:8%; }
+.slide-image-content h2 { font-size:clamp(1.2rem,2.2vw,2rem);font-weight:700;margin-bottom:0.8em; }
+.slide-image-content p { font-size:clamp(0.85rem,1.2vw,1.1rem);color:var(--slide-text-secondary);line-height:1.7; }
+
+.slide-quote { flex-direction:column;align-items:center;justify-content:center;text-align:center;padding:10% 12%;background:var(--slide-bg); }
+.slide-quote blockquote { font-size:clamp(1.2rem,2.2vw,2rem);font-weight:300;font-style:italic;line-height:1.6;max-width:80%;margin-bottom:1em; }
+.slide-quote .slide-quote-author { font-size:clamp(0.85rem,1.2vw,1.1rem);color:var(--slide-accent); }
+.slide-quote .slide-quote-context { font-size:clamp(0.75rem,1vw,0.9rem);color:var(--slide-text-muted);margin-top:0.3em; }
+
+.slide-timeline { flex-direction:column;justify-content:center;padding:8% 10%;background:var(--slide-bg); }
+.slide-timeline h2 { font-size:clamp(1.4rem,2.8vw,2.5rem);font-weight:700;margin-bottom:1.2em; }
+.slide-timeline-track { position:relative;padding-left:2em;border-left:2px solid var(--slide-accent);display:flex;flex-direction:column;gap:1.2em; }
+.slide-timeline-event { position:relative; }
+.slide-timeline-event::before { content:'';position:absolute;left:calc(-2em - 5px);top:0.35em;width:12px;height:12px;border-radius:50%;background:var(--slide-accent); }
+.slide-timeline-year { font-weight:700;color:var(--slide-accent);font-size:clamp(0.9rem,1.3vw,1.15rem); }
+.slide-timeline-text { color:var(--slide-text-secondary);margin-top:0.2em;font-size:clamp(0.8rem,1.1vw,1rem); }
+
+.slide-stats { flex-direction:column;align-items:center;justify-content:center;padding:8% 10%;background:var(--slide-bg); }
+.slide-stats h2 { font-size:clamp(1.4rem,2.8vw,2.5rem);font-weight:700;margin-bottom:1.5em;text-align:center; }
+.slide-stats-grid { display:grid;gap:2em;width:100%; }
+.slide-stats-grid[data-cols="2"] { grid-template-columns:1fr 1fr; }
+.slide-stats-grid[data-cols="3"] { grid-template-columns:1fr 1fr 1fr; }
+.slide-stats-grid[data-cols="4"] { grid-template-columns:1fr 1fr 1fr 1fr; }
+.slide-stat { text-align:center; }
+.slide-stat-value { font-size:clamp(1.8rem,3.5vw,3rem);font-weight:800;color:var(--slide-accent);margin-bottom:0.2em; }
+.slide-stat-label { font-size:clamp(0.8rem,1.1vw,1rem);color:var(--slide-text-muted); }
+
+.slide-section { flex-direction:column;align-items:center;justify-content:center;text-align:center;
+  background:linear-gradient(135deg,var(--slide-bg-alt),var(--slide-bg));padding:10%; }
+.slide-section h2 { font-size:clamp(1.8rem,3.5vw,3rem);font-weight:700;margin-bottom:0.3em; }
+.slide-section .slide-subtitle { font-size:clamp(0.9rem,1.5vw,1.3rem);color:var(--slide-text-muted); }
+`;
+
+// ─── Self-Contained HTML Export ─────────────────────────────────────────────
+
+function buildExportHTML(pptData, theme) {
+  const slides = pptData.slides || [];
+
+  const slidesHtml = slides.map((slide, i) => {
+    const durationMs = slide.audio?.durationMs || 5000;
+    const audioUrl = slide.audio?.dataUri || '';
+    const html = renderSlideHTML(slide);
+    const match = html.match(/class="slide-page ([^"]*)">([\s\S]*)<\/div>$/);
+    const layoutClass = match ? match[1] : '';
+    const innerHtml = match ? match[2] : html;
+
+    return `<section class="slide-page ${layoutClass}"
+      data-slide-id="${slide.id}" data-slide-index="${i}"
+      data-duration-ms="${durationMs}"
+      data-narration="${esc(slide.narration || '')}"
+      ${audioUrl ? `data-audio-url="${esc(audioUrl)}"` : ''}
+    >${innerHtml}</section>`;
+  }).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${esc(pptData.meta?.title || 'Presentation')}</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; overflow: hidden; }
+${THEME_CSS}
+.export-controls {
+  position: fixed; bottom: 0; left: 0; right: 0;
+  background: rgba(0,0,0,0.85); backdrop-filter: blur(8px);
+  padding: 10px 24px; display: flex; align-items: center; gap: 14px;
+  z-index: 100; border-top: 1px solid rgba(255,255,255,0.1);
+}
+.export-controls button {
+  background: none; border: 1px solid rgba(255,255,255,0.25);
+  color: #fff; padding: 6px 14px; border-radius: 6px; cursor: pointer; font-size: 13px;
+}
+.export-controls button:hover { background: rgba(255,255,255,0.1); }
+.export-progress { flex: 1; height: 3px; background: rgba(255,255,255,0.1); border-radius: 2px; overflow: hidden; cursor: pointer; }
+.export-progress-fill { height: 100%; background: var(--slide-accent); border-radius: 2px; width: 0%; transition: width 0.1s linear; }
+.export-counter { color: rgba(255,255,255,0.5); font-size: 13px; min-width: 50px; text-align: center; }
+.export-subtitle {
+  position: fixed; bottom: 60px; left: 50%; transform: translateX(-50%);
+  background: rgba(0,0,0,0.7); color: #fff; padding: 6px 20px; border-radius: 10px;
+  font-size: 15px; max-width: 80vw; text-align: center; opacity: 0; transition: opacity 0.3s; z-index: 100;
+}
+.export-subtitle.visible { opacity: 1; }
+</style>
+</head>
+<body>
+<div class="slides-viewport slides-style-${theme}">
+${slidesHtml}
+<div class="export-subtitle" id="subtitle"></div>
+</div>
+<div class="export-controls">
+  <button id="btn-prev">◀</button>
+  <button id="btn-play">▶ Play</button>
+  <button id="btn-next">▶</button>
+  <div class="export-progress" id="progress"><div class="export-progress-fill" id="progress-fill"></div></div>
+  <div class="export-counter" id="counter">1 / ${slides.length}</div>
+</div>
+<script>
+const pages=document.querySelectorAll('.slide-page'),total=pages.length;
+let idx=0,playing=false,timer=null,audio=null,progTimer=null;
+function show(i){pages.forEach(p=>p.classList.remove('active'));pages[i].classList.add('active');idx=i;
+document.getElementById('counter').textContent=(i+1)+' / '+total;
+const n=pages[i].dataset.narration,s=document.getElementById('subtitle');
+if(n){s.textContent=n;s.classList.add('visible')}else{s.classList.remove('visible')}}
+function prog(r){document.getElementById('progress-fill').style.width=(r*100)+'%'}
+function globalProg(si,sr){let t=0,b=0;pages.forEach((p,i)=>{const d=+p.dataset.durationMs||5000;t+=d;if(i<si)b+=d});
+return(b+(+pages[si].dataset.durationMs||5000)*sr)/t}
+async function playSlide(i){show(i);const d=+pages[i].dataset.durationMs||5000,u=pages[i].dataset.audioUrl;
+if(u){audio=new Audio(u);audio.play().catch(()=>{})}
+const st=Date.now();clearInterval(progTimer);progTimer=setInterval(()=>{prog(globalProg(i,Math.min((Date.now()-st)/d,1)))},50);
+return new Promise(r=>{timer=setTimeout(()=>{clearInterval(progTimer);r()},d)})}
+async function playAll(){playing=true;document.getElementById('btn-play').textContent='\\u23F8 Pause';
+for(let i=idx;i<total;i++){if(!playing)break;await playSlide(i)}stop()}
+function stop(){playing=false;clearTimeout(timer);clearInterval(progTimer);if(audio){audio.pause();audio=null}
+document.getElementById('btn-play').textContent='\\u25B6 Play'}
+document.getElementById('btn-play').onclick=()=>{if(playing)stop();else playAll()};
+document.getElementById('btn-prev').onclick=()=>{stop();show(Math.max(0,idx-1))};
+document.getElementById('btn-next').onclick=()=>{stop();show(Math.min(total-1,idx+1))};
+document.addEventListener('keydown',e=>{if(e.key==='ArrowRight'||e.key===' '){e.preventDefault();stop();show(Math.min(total-1,idx+1))}
+if(e.key==='ArrowLeft'){stop();show(Math.max(0,idx-1))}if(e.key==='Escape')stop()});
+document.getElementById('progress').onclick=e=>{const r=(e.clientX-e.target.getBoundingClientRect().left)/e.target.offsetWidth;
+stop();show(Math.min(total-1,Math.max(0,Math.floor(r*total))))};
+show(0);
+</script>
+</body>
+</html>`;
+}
+
+module.exports = { buildExportHTML, renderSlideHTML, esc };

package/lib/commands/slides/index.js

@@ -0,0 +1,345 @@
+/**
+ * VoxFlow CLI — Slides command
+ *
+ * Thin orchestrator: delegates to submodules for constants, LLM generation,
+ * TTS narration, and HTML rendering/export.
+ *
+ * Submodules:
+ *   ./constants.js      — themes, templates, system prompt
+ *   ./html-renderer.js  — layout renderers, CSS, HTML export builder
+ */
+
+'use strict';
+
+const fs = require('fs');
+const { SLIDES_DEFAULTS } = require('../../core/config');
+const { request, throwApiError, throwNetworkError } = require('../../core/http');
+const { chatCompletion } = require('../../core/llm-client');
+const { buildWav } = require('../../core/audio');
+const { BYTES_PER_MS } = require('../../core/timeline');
+const { startSpinner } = require('../../core/spinner');
+const {
+  VALID_THEMES, VALID_TEMPLATES, VALID_MODELS,
+  TEMPLATE_HINTS, TEMPLATE_STRUCTURES,
+  SLIDES_SYSTEM_PROMPT, VALID_MODEL_ALIASES,
+} = require('./constants');
+const { buildExportHTML } = require('./html-renderer');
+
+// ─── LLM Slide Generation ───────────────────────────────────────────────────
+
+async function generateSlides(apiBase, token, text, template, model) {
+  const templateHint = TEMPLATE_HINTS[template] || '';
+  const structure = TEMPLATE_STRUCTURES[template] || [];
+
+  let userContent = text;
+  if (templateHint) {
+    userContent += `\n\nTemplate hint: ${templateHint}`;
+  }
+  if (structure.length > 0) {
+    const structureDesc = structure.map((s, i) => `  Slide ${i + 1}: layout="${s.layout}" — ${s.hint}`).join('\n');
+    userContent += `\n\nSuggested structure:\n${structureDesc}`;
+  }
+
+  const messages = [
+    { role: 'system', content: SLIDES_SYSTEM_PROMPT },
+    { role: 'user', content: userContent },
+  ];
+
+  const modelPreset = VALID_MODEL_ALIASES.includes(model) ? model : 'swift';
+
+  const result = await chatCompletion({
+    apiBase,
+    token,
+    messages,
+    temperature: 0.7,
+    maxTokens: 4000,
+    modelPreset,
+  });
+
+  let jsonStr = result.content.trim();
+  const fenceMatch = jsonStr.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenceMatch) jsonStr = fenceMatch[1].trim();
+
+  const data = JSON.parse(jsonStr);
+
+  if (!data.slides || !Array.isArray(data.slides) || data.slides.length < 2) {
+    throw new Error('LLM returned invalid slide structure (need at least 2 slides)');
+  }
+
+  return { data, quota: result.quota };
+}
+
+// ─── TTS Synthesis ──────────────────────────────────────────────────────────
+
+async function synthesizeNarration(apiBase, token, text, voiceId, speed, index, total) {
+  process.stdout.write(`    TTS slide [${index + 1}/${total}]...`);
+
+  let status, data;
+  try {
+    ({ status, data } = await request(`${apiBase}/api/tts/synthesize`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      timeoutMs: 180_000,
+    }, {
+      text,
+      voiceId,
+      speed,
+      volume: 1.0,
+    }));
+  } catch (err) {
+    console.log(' FAIL');
+    throwNetworkError(err, apiBase);
+  }
+
+  if (status !== 200 || data.code !== 'success') {
+    console.log(' FAIL');
+    throwApiError(status, data, `TTS slide ${index + 1}`);
+  }
+
+  const pcmBuffer = Buffer.from(data.audio, 'base64');
+  const durationMs = Math.round(pcmBuffer.length / BYTES_PER_MS);
+  console.log(` OK (${(pcmBuffer.length / 1024).toFixed(0)} KB, ${(durationMs / 1000).toFixed(1)}s)`);
+  return { pcm: pcmBuffer, durationMs, quota: data.quota };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+async function slides(opts) {
+  const {
+    token,
+    api: apiBase,
+    text: inputText,
+    voice = SLIDES_DEFAULTS.voice,
+    speed = SLIDES_DEFAULTS.speed,
+    theme = SLIDES_DEFAULTS.theme,
+    template = SLIDES_DEFAULTS.template,
+    model = SLIDES_DEFAULTS.model,
+    noAudio = false,
+  } = opts;
+
+  const sigintHandler = () => {
+    console.log('\n\nGeneration cancelled.');
+    process.exit(0);
+  };
+  process.on('SIGINT', sigintHandler);
+
+  try {
+    const totalSteps = noAudio ? 2 : 3;
+    let stepNum = 1;
+
+    // Step 1: Generate slide data via LLM
+    console.log(`\n[${stepNum}/${totalSteps}] Generating slides from text...`);
+    console.log(`    Theme: ${theme}, Template: ${template}, Model: ${model}`);
+
+    const spinner = startSpinner('    Calling LLM...');
+    let slidesData;
+    let llmQuota = null;
+    try {
+      const result = await generateSlides(apiBase, token, inputText, template, model);
+      slidesData = result.data;
+      llmQuota = result.quota;
+      spinner.stop(`OK (${slidesData.slides.length} slides)`);
+    } catch (err) {
+      spinner.stop('FAIL');
+      throw new Error(`Slide generation failed: ${err.message}`);
+    }
+
+    const slideCount = slidesData.slides.length;
+    const layoutList = slidesData.slides.map(s => s.layout).join(', ');
+    console.log(`    Slides: ${slideCount} (${layoutList})`);
+
+    stepNum++;
+
+    // Step 2: TTS narration (optional)
+    let firstQuota = llmQuota;
+    let lastQuota = llmQuota;
+
+    if (!noAudio) {
+      const narrations = slidesData.slides.filter(s => s.narration);
+      console.log(`\n[${stepNum}/${totalSteps}] Synthesizing narration (${narrations.length} slides with narration)...`);
+
+      for (let i = 0; i < slidesData.slides.length; i++) {
+        const slide = slidesData.slides[i];
+        if (!slide.narration) {
+          slide.audio = { durationMs: 5000 };
+          continue;
+        }
+
+        const result = await synthesizeNarration(
+          apiBase, token, slide.narration, voice, speed, i, slideCount
+        );
+        if (!firstQuota && result.quota) firstQuota = result.quota;
+        lastQuota = result.quota;
+
+        const { wav } = buildWav([result.pcm], 0);
+        const dataUri = `data:audio/wav;base64,${wav.toString('base64')}`;
+
+        slide.audio = {
+          durationMs: result.durationMs,
+          dataUri,
+        };
+      }
+
+      stepNum++;
+    } else {
+      for (const slide of slidesData.slides) {
+        slide.audio = { durationMs: 5000 };
+      }
+    }
+
+    // Final: Generate HTML and save
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const outputPath = opts.output || `slides-${timestamp}.html`;
+
+    console.log(`\n[${stepNum}/${totalSteps}] Writing HTML...`);
+
+    const html = buildExportHTML(slidesData, theme);
+    fs.writeFileSync(outputPath, html, 'utf8');
+
+    const fileStat = fs.statSync(outputPath);
+    const fileSizeKb = (fileStat.size / 1024).toFixed(0);
+
+    console.log('\n=== Output ===');
+    console.log(`  File:     ${outputPath} (${fileSizeKb} KB)`);
+    console.log(`  Slides:   ${slideCount} (${layoutList})`);
+    console.log(`  Theme:    ${theme}`);
+    console.log(`  Template: ${template}`);
+    if (!noAudio) {
+      const totalDuration = slidesData.slides.reduce((sum, s) => sum + (s.audio?.durationMs || 5000), 0);
+      console.log(`  Duration: ${formatDuration(totalDuration)}`);
+    }
+    if (lastQuota) {
+      const quotaUsed = firstQuota && lastQuota
+        ? (firstQuota.remaining - lastQuota.remaining)
+        : slideCount * 100;
+      console.log(`  Quota:    ${quotaUsed} used, ${lastQuota.remaining ?? '?'} remaining`);
+    }
+    console.log('\n  Open in browser to view and present.');
+
+    return { outputPath, slideCount };
+  } finally {
+    process.removeListener('SIGINT', sigintHandler);
+  }
+}
+
+function formatDuration(ms) {
+  const totalSec = Math.round(ms / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min === 0) return `${sec}s`;
+  return `${min}m${sec.toString().padStart(2, '0')}s`;
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag, parseFloatFlag, parseBoolFlag, validateSpeed, runWithRetry } = require('../../core/args');
+  const { getToken, getTokenInfo } = require('../../core/auth');
+  const { API_BASE } = require('../../core/config');
+
+  const api = parseFlag(args, '--api') || API_BASE;
+  const explicitToken = parseFlag(args, '--token');
+
+  const speed = parseFloatFlag(args, '--speed');
+  const output = parseFlag(args, '--output', '-o');
+
+  validateSpeed(args, speed);
+
+  if (output) {
+    if (!output.toLowerCase().endsWith('.html')) {
+      console.error('Error: --output path must end with .html');
+      process.exit(1);
+    }
+  }
+
+  const theme = parseFlag(args, '--theme');
+  if (theme && !VALID_THEMES.includes(theme)) {
+    console.error(`Error: --theme must be one of: ${VALID_THEMES.join(', ')} (got: "${theme}")`);
+    process.exit(1);
+  }
+
+  const template = parseFlag(args, '--template');
+  if (template && !VALID_TEMPLATES.includes(template)) {
+    console.error(`Error: --template must be one of: ${VALID_TEMPLATES.join(', ')} (got: "${template}")`);
+    process.exit(1);
+  }
+
+  const model = parseFlag(args, '--model');
+  if (model && !VALID_MODELS.includes(model)) {
+    console.error(`Error: --model must be one of: ${VALID_MODELS.join(', ')} (got: "${model}")`);
+    process.exit(1);
+  }
+
+  let text = parseFlag(args, '--text');
+  if (!text) {
+    const valuedFlags = new Set([
+      '--text', '--voice', '--speed', '--theme', '--template',
+      '--model', '--output', '-o', '--token', '--api',
+    ]);
+    for (let i = 0; i < args.length; i++) {
+      if (args[i].startsWith('-')) {
+        if (valuedFlags.has(args[i])) i++;
+        continue;
+      }
+      text = args[i];
+      break;
+    }
+  }
+
+  if (!text) {
+    console.error('Error: No text provided. Usage: voxflow slides "your topic" [options]');
+    process.exit(1);
+  }
+
+  let token;
+  if (explicitToken) {
+    token = explicitToken;
+  } else {
+    token = await getToken({ api });
+    const info = getTokenInfo();
+    if (info) {
+      console.log(`\x1b[32mLogged in as ${info.email}\x1b[0m`);
+    }
+  }
+
+  const slidesOpts = {
+    token, api, text,
+    theme: theme || undefined,
+    template: template || undefined,
+    model: model || undefined,
+    voice: parseFlag(args, '--voice') || undefined,
+    speed, output,
+    noAudio: parseBoolFlag(args, '--no-audio'),
+  };
+
+  await runWithRetry(slides, slidesOpts, api, explicitToken);
+}
+
+const meta = {
+  slides: {
+    usage: '"topic" [opts]',
+    description: 'Generate AI presentation slides as HTML',
+    options: [
+      `<text>               Topic or text (positional arg or --text)`,
+      `--text <text>        Topic to generate slides about`,
+      `--voice <id>         TTS voice ID (default: ${SLIDES_DEFAULTS.voice})`,
+      `--speed <n>          TTS speed 0.5-2.0 (default: ${SLIDES_DEFAULTS.speed})`,
+      `--theme <name>       Theme: midnight, paper, ember, forest, ocean (default: ${SLIDES_DEFAULTS.theme})`,
+      `--template <name>    Template: product, report, tutorial, pitch, free (default: ${SLIDES_DEFAULTS.template})`,
+      `--model <id>         Model: swift, balanced, pro, creative (default: ${SLIDES_DEFAULTS.model})`,
+      `--no-audio           Skip TTS synthesis, generate slides only`,
+      `--output <path>      Output HTML file (default: ./slides-<timestamp>.html)`,
+    ],
+    examples: [
+      'voxflow slides "AI in Healthcare"',
+      'voxflow slides "Q4 Revenue Report" --template report --theme paper',
+      'voxflow slides "React Tutorial" --template tutorial --model balanced',
+      'voxflow slides "Startup Pitch" --template pitch --theme ocean --no-audio',
+    ],
+  },
+};
+
+module.exports = { slides, handle, meta, VALID_THEMES, VALID_TEMPLATES, VALID_MODELS };