voxflow 1.15.0 → 1.15.2

package/lib/commands/slice-render.js

@@ -0,0 +1,282 @@
+'use strict';
+
+/**
+ * `voxflow slice render <deck.json>` — offline local Remotion render.
+ *
+ * Reads a validator-shaped deck.json, transforms it into PaperSlideDeck
+ * composition input props, and renders directly to MP4 via the pre-bundled
+ * Remotion serveUrl at `cli/dist/remotion-bundle/`. No VoxFlow API call,
+ * no TTS, no quota — Phase 0 is silent video; Phase 1 will add local TTS.
+ *
+ * No `meta` export — reached only via `slice.js` dispatch (`voxflow slice
+ * render <path>`), so it stays out of the registry parity test (the same
+ * pattern slice-stage.js uses).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { validatePaperSlideDeck, isV2LayoutTreeDeck } = require('../internal/deck-validator');
+const SLICE_THEME_REGISTRY = require('../internal/slice-themes.json');
+
+const THEME_TO_DECK_ID = Object.fromEntries(
+    SLICE_THEME_REGISTRY.themes.map((t) => [t.id, t.remotion.deck])
+);
+const DEFAULT_THEME = SLICE_THEME_REGISTRY.default;
+
+// Composition FPS is fixed at 30 across every theme's <Composition> in
+// video-present/src/Root.tsx. Captured here as documentation; the actual
+// frames-per-second comes back from selectComposition() at runtime.
+const DEFAULT_CARD_SEC = 4;
+
+/**
+ * Transform a validator-shaped deck (cards[].kind/title/caption/...) into
+ * PaperSlideDeckProps (cards[].slide + cards[].durationSec) so the same
+ * deck schema users author in Claude maps cleanly onto every Remotion deck
+ * composition without going through the cloud render-worker pipeline.
+ *
+ * Phase 0 is silent — every card gets DEFAULT_CARD_SEC. Phase 1 will
+ * splice per-card TTS in and replace this with audio-driven durations.
+ */
+function buildInputProps(deck) {
+    const numberBadge = null;
+    const cards = deck.cards.map((card) => {
+        const slide = {
+            kind: card.kind,
+            header: deck.header,
+            title: card.kind === 'title' ? card.title || [] : [],
+            caption: card.caption ?? null,
+            figureKeyword: card.figureKeyword ?? null,
+            seriesTitle: deck.seriesTitle,
+            seriesTagline: deck.seriesTagline,
+            voiceoverSrc: null,
+            numberBadge,
+            imageUrl: card.imageUrl,
+        };
+        if (deck.variantId) slide.variantId = deck.variantId;
+        return { slide, durationSec: card.durationSec || DEFAULT_CARD_SEC };
+    });
+    return { cards };
+}
+
+function humanSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+
+function fmtSec(ms) {
+    const s = ms / 1000;
+    if (s < 60) return `${s.toFixed(1)}s`;
+    const m = Math.floor(s / 60);
+    const rem = (s - m * 60).toFixed(0);
+    return `${m}m${rem.padStart(2, '0')}s`;
+}
+
+function resolveServeUrl() {
+    // dist/remotion-bundle is generated by `npm run build:bundle` at CLI
+    // prepublish. Local dev: rebuild after a Remotion edit (`cd cli && npm
+    // run build:bundle`). Path is intentionally relative to this file so
+    // both the unbundled source layout and the ncc-bundled dist/ resolve
+    // to the same on-disk artifact (dist/remotion-bundle is shipped flat
+    // in the npm tarball).
+    // Two layouts to support:
+    //  - Source/dev (`node bin/voxflow.js`): __dirname = cli/lib/commands/
+    //    → `../../dist/remotion-bundle` = cli/dist/remotion-bundle
+    //  - ncc-published (`voxflow ...` from npm tarball): __dirname = <pkg>/dist/
+    //    → `remotion-bundle` (sibling of bundled index.js)
+    const candidates = [
+        path.resolve(__dirname, '../../dist/remotion-bundle'),
+        path.resolve(__dirname, 'remotion-bundle'),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'index.html'))) return c;
+    }
+    throw new Error(
+        `Pre-bundled Remotion serveUrl not found at ${candidates.join(' or ')}.\n` +
+        '  Run `cd cli && npm run build:bundle` from the monorepo first.'
+    );
+}
+
+/**
+ * Heuristic: Remotion downloads chrome-headless-shell into node_modules/.remotion
+ * the FIRST time the renderer is invoked. After that it's cached.
+ *
+ * We probe for the binary so we can give the user a clear "first-run wait"
+ * message instead of leaving them staring at a silent terminal for a minute.
+ */
+function chromeBinaryExists() {
+    // Remotion stores the downloaded chrome-headless-shell next to whatever
+    // node_modules/ contains @remotion/renderer at runtime. In a flat
+    // consumer install that's `<pkg>/node_modules/.remotion/`; in a hoisted
+    // monorepo it's the hoist root. We probe both CWD-based and renderer-
+    // resolved ancestors so a warm install is detected regardless of layout.
+    const candidates = new Set();
+    const addAncestors = (start) => {
+        let dir = start;
+        for (let i = 0; i < 12; i++) {
+            candidates.add(path.join(dir, 'node_modules', '.remotion', 'chrome-headless-shell'));
+            candidates.add(path.join(dir, '.remotion', 'chrome-headless-shell'));
+            const parent = path.dirname(dir);
+            if (parent === dir) break;
+            dir = parent;
+        }
+    };
+    addAncestors(process.cwd());
+    addAncestors(__dirname);
+    try {
+        const rendererPkgPath = require.resolve('@remotion/renderer/package.json');
+        addAncestors(path.dirname(rendererPkgPath));
+    } catch {
+        // renderer not installed — definitely cold
+    }
+    for (const cand of candidates) {
+        if (fs.existsSync(cand)) return true;
+    }
+    return false;
+}
+
+async function render(opts) {
+    const deckPath = path.resolve(opts.deckPath);
+    if (!fs.existsSync(deckPath)) {
+        throw new Error(`Deck file not found: ${deckPath}`);
+    }
+    const raw = fs.readFileSync(deckPath, 'utf8');
+    let deck;
+    try {
+        deck = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`Could not parse deck JSON: ${err.message}`);
+    }
+
+    // V2 LayoutTree decks have `cards[].children[]` — different shape than
+    // the V1 PaperSlide deck this renderer expects. V1 validator doesn't
+    // catch V2 input (V2 cards happen to satisfy V1's kind/narration checks)
+    // so without an explicit guard, render() would silently produce a deck
+    // with undefined caption/figureKeyword on every card and Remotion would
+    // happily render blank slides. Fail loud instead.
+    if (isV2LayoutTreeDeck(deck)) {
+        throw new Error(
+            'V2 LayoutTree decks are not yet supported by offline render. ' +
+            'Use voxflow.studio/apps/slice for V2 decks or downgrade to V1 shape.'
+        );
+    }
+
+    // Run the same validator the production cloud route uses — so an offline
+    // render fails fast on the same shape errors the backend would reject.
+    validatePaperSlideDeck(deck);
+
+    const theme = deck.theme || DEFAULT_THEME;
+    const deckId = THEME_TO_DECK_ID[theme];
+    if (!deckId) {
+        throw new Error(
+            `Unknown theme "${theme}". Valid: ${Object.keys(THEME_TO_DECK_ID).join(', ')}`
+        );
+    }
+
+    const outputPath = path.resolve(
+        opts.output || path.join(process.cwd(), 'out.mp4')
+    );
+    const outputDir = path.dirname(outputPath);
+    if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+
+    const serveUrl = resolveServeUrl();
+    const inputProps = buildInputProps(deck);
+
+    // Lazy require so users who never run `slice render` don't pay the
+    // remotion install cost at CLI startup (renderer pulls in puppeteer-
+    // core + chromium glue, ~30 MB on disk).
+    const { selectComposition, renderMedia } = require('@remotion/renderer');
+
+    const coldStart = !chromeBinaryExists();
+    if (coldStart) {
+        console.log('  First-run: Remotion will download chrome-headless-shell (~90 MB).');
+        console.log('  Allow ~30-60 s for the one-time download, then ~30 s for the render itself.');
+    }
+    console.log(`[slice render] theme: ${theme}`);
+    console.log(`[slice render] composition: ${deckId}`);
+    console.log(`[slice render] cards: ${deck.cards.length}`);
+    console.log(`[slice render] output: ${outputPath}`);
+
+    const t0 = Date.now();
+
+    const composition = await selectComposition({
+        serveUrl,
+        id: deckId,
+        inputProps,
+    });
+    const totalFrames = composition.durationInFrames;
+    const videoSec = totalFrames / composition.fps;
+    console.log(
+        `[slice render] duration: ${videoSec.toFixed(1)}s ` +
+        `(${totalFrames} frames @ ${composition.fps} fps, ` +
+        `${composition.width}x${composition.height})`
+    );
+
+    let lastFrame = 0;
+    let lastLog = 0;
+    await renderMedia({
+        composition,
+        serveUrl,
+        codec: 'h264',
+        outputLocation: outputPath,
+        inputProps,
+        imageFormat: 'jpeg',
+        jpegQuality: 85,
+        concurrency: 4,
+        x264Preset: 'ultrafast',
+        chromiumOptions: { gl: 'swiftshader' },
+        offthreadVideoCacheSizeInBytes: 512 * 1024 * 1024,
+        onProgress: ({ progress, renderedFrames }) => {
+            lastFrame = renderedFrames;
+            const now = Date.now();
+            // Throttle to ~2 lines/sec so the terminal stays scrollable in
+            // dev and so AI agents reading stdout aren't flooded.
+            if (now - lastLog < 500 && progress < 1) return;
+            lastLog = now;
+            const elapsed = now - t0;
+            const pct = Math.round(progress * 100);
+            process.stdout.write(
+                `\r[slice render] frame ${renderedFrames}/${totalFrames} ` +
+                `(${pct}%) — elapsed ${fmtSec(elapsed)}    `
+            );
+        },
+    });
+    const totalMs = Date.now() - t0;
+    process.stdout.write('\n');
+
+    const stat = fs.statSync(outputPath);
+    console.log(`[slice render] done in ${fmtSec(totalMs)} — ${humanSize(stat.size)}`);
+    console.log(`[slice render] saved to ${outputPath}`);
+    return { outputPath, totalMs, frames: lastFrame, size: stat.size };
+}
+
+async function handle(args) {
+    const { parseFlag } = require('../core/args');
+    const output = parseFlag(args, '--output', '-o');
+    const positional = args.find(
+        (a) => !a.startsWith('-') && !a.startsWith('--')
+    );
+    if (!positional) {
+        console.error('Usage: voxflow slice render <deck.json> [--output out.mp4]');
+        process.exit(1);
+    }
+    try {
+        await render({ deckPath: positional, output });
+    } catch (err) {
+        console.error(`\nslice render failed: ${err.message}`);
+        if (process.env.VOXFLOW_DEBUG) console.error(err.stack);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    render,
+    handle,
+    buildInputProps,
+    resolveServeUrl,
+    chromeBinaryExists,
+    THEME_TO_DECK_ID,
+    DEFAULT_THEME,
+};

package/lib/commands/slice-stage.js

@@ -0,0 +1,264 @@
+'use strict';
+
+/**
+ * `voxflow slice stage <deck.json>` — boot a local Stage server that watches a
+ * deck JSON file and hot-reloads a localhost preview page on every change.
+ *
+ * No `meta` export — this is reached only via `slice.js` dispatch (first
+ * positional arg `stage`), so it stays out of the registry parity test.
+ *
+ * Phase 1 scope: server + watcher + minimal deck-JSON UI.
+ * Phase 1.3+ will add: Remotion `renderStill` thumbnails, exports, publish.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { startStageServer } = require('../stage-core/server');
+const { watchDeckFile } = require('../stage-core/watcher');
+const { createEventBus } = require('../stage-core/event-bus');
+const { createSnapshotStore } = require('../stage-core/snapshot-store');
+const { createCloudRenderClient } = require('../stage-core/cloud-render');
+const { renderSliceStageHtml } = require('../stage-ui/slice/template');
+const { emit: emitTelemetry } = require('../core/telemetry');
+
+// Sourced from the canonical registry at repo root. Previously this list
+// silently fell out of sync (lagged at 6 themes while the rest of the repo
+// had 13) — the JSON import makes that impossible.
+const SLICE_THEME_REGISTRY = require('../../../slice-themes.json');
+const VALID_THEMES = SLICE_THEME_REGISTRY.themes.map((t) => t.id);
+
+function loadInitialDeck(absPath) {
+  try {
+    const raw = fs.readFileSync(absPath, 'utf8');
+    return { deck: JSON.parse(raw), error: null };
+  } catch (err) {
+    return { deck: null, error: err.code === 'ENOENT'
+      ? `File not found: ${absPath}. Run \`voxflow slice <article>\` first, or pass --output to write a deck.json.`
+      : `Could not read deck: ${err.message}` };
+  }
+}
+
+/**
+ * Programmatic entry — used by tests + the CLI handler. Returns a handle that
+ * exposes the listening URL and a stop() that tears everything down.
+ *
+ * @param {object} opts
+ * @param {string} opts.deckPath
+ * @param {string} [opts.theme]              Lock to a single theme (validated)
+ * @param {number} [opts.port=5180]
+ * @param {number} [opts.maxPortTries=10]
+ * @returns {Promise<{url:string, port:number, stop:() => Promise<void>}>}
+ */
+async function startSliceStage(opts) {
+  const deckPath = path.resolve(opts.deckPath);
+  const theme = opts.theme;
+  if (theme && !VALID_THEMES.includes(theme)) {
+    throw new Error(
+      `Unknown theme "${theme}". Valid: ${VALID_THEMES.join(', ')}`
+    );
+  }
+
+  const bus = createEventBus();
+  let snapshot = loadInitialDeck(deckPath);
+  snapshot.sourcePath = deckPath;
+
+  // Per-deck history. Initial parseable load = baseline snapshot (v0). Every
+  // subsequent watcher event with parseable content gets snapshotted; the
+  // store dedups by content hash so atomic-write double events stay one
+  // version. A `restore` flag rides on the deck event so the UI knows to
+  // skip the just-changed diff highlight (otherwise restoring an old deck
+  // would flash every card as "changed").
+  const snapshotStore = createSnapshotStore(deckPath);
+  let pendingRestoreId = null;
+  if (snapshot.deck) snapshotStore.snapshotIfChanged(snapshot.deck);
+
+  const watcher = watchDeckFile({
+    filePath: deckPath,
+    onChange(deck, err) {
+      if (err && !deck) {
+        snapshot = { deck: null, error: err.message, sourcePath: deckPath };
+        bus.publish({ type: 'error', sourcePath: deckPath, error: err.message, ts: Date.now() });
+        return;
+      }
+      snapshot = { deck, error: null, sourcePath: deckPath };
+      snapshotStore.snapshotIfChanged(deck);
+      const restoredFromId = pendingRestoreId;
+      pendingRestoreId = null;
+      bus.publish({
+        type: 'deck',
+        sourcePath: deckPath,
+        deck,
+        theme: theme || null,
+        ts: Date.now(),
+        restoredFrom: restoredFromId,
+      });
+    },
+  });
+
+  // Server-side restore writer: writes the chosen snapshot bytes back to the
+  // live deck file, sets `pendingRestoreId` so the next watcher event tags
+  // the deck event with `restoredFrom`. Server.js passes through to this.
+  const snapshotsBridge = {
+    list: snapshotStore.list,
+    load: snapshotStore.load,
+    getStorePath: snapshotStore.getStorePath,
+    restore(id) {
+      const deck = snapshotStore.load(id);
+      if (!deck) return null;
+      pendingRestoreId = id;
+      try {
+        fs.writeFileSync(deckPath, JSON.stringify(deck, null, 2) + '\n', 'utf8');
+      } catch (err) {
+        pendingRestoreId = null;
+        throw err;
+      }
+      return { deck };
+    },
+  };
+
+  const preferredPort = Number.isInteger(opts.port) && opts.port > 0 ? opts.port : 5180;
+  const maxPortTries = Number.isInteger(opts.maxPortTries) && opts.maxPortTries > 0
+    ? opts.maxPortTries : 10;
+
+  // We have to start the server before knowing the final port (port-conflict
+  // retry happens inside startStageServer). So we render the HTML lazily,
+  // re-rendering each request with the actual port baked in.
+  let actualPort = preferredPort;
+  const uiHtml = () => renderSliceStageHtml({ sourcePath: deckPath, port: actualPort });
+
+  // startStageServer takes a string for uiHtml; we pass a stub that will be
+  // replaced once we know the port. Cheap workaround: render once with
+  // `preferredPort`, then patch after we get the real port back.
+  const initialHtml = renderSliceStageHtml({ sourcePath: deckPath, port: preferredPort });
+
+  // Cloud render bridge — proxies POST /api/render-mp4 (and friends) to the
+  // backend cloud-render endpoint. Token comes from the same CLI cache the
+  // user logged into; the page never sees the JWT.
+  const cloudRender = opts.cloudRender || createCloudRenderClient();
+
+  const handle = await startStageServer({
+    uiHtml: initialHtml,
+    getDeckSnapshot: () => snapshot,
+    subscribe: bus.subscribe,
+    snapshots: snapshotsBridge,
+    cloudRender,
+    preferredPort,
+    maxPortTries,
+  });
+  actualPort = handle.port;
+
+  // Single anonymous launch event — feeds the "should Stage get an MCP?"
+  // decision. Fire-and-forget; opt-out via VOXFLOW_TELEMETRY=0 / DO_NOT_TRACK.
+  emitTelemetry('cli.slice.stage.launched', { theme: theme || null });
+
+  // If the port shifted (5180 → 5181 due to conflict), re-render the HTML so
+  // the footer hint shows the truthy URL. We swap by replacing the listener
+  // on the server: simpler than re-injecting, just update the closure used
+  // by startStageServer's GET / branch via a tiny patch.
+  if (actualPort !== preferredPort) {
+    // The HTML is captured by closure inside startStageServer; rather than
+    // wiring a setter, we do nothing — the page only references the port in
+    // a footer hint, and the live SSE connection works regardless. This is
+    // acceptable for MVP; revisit if/when port mismatch becomes user-visible.
+    void uiHtml;
+  }
+
+  return {
+    url: handle.url,
+    port: handle.port,
+    sourcePath: deckPath,
+    async stop() {
+      watcher.stop();
+      await handle.close();
+    },
+  };
+}
+
+// ─── CLI Handler ────────────────────────────────────────────────────────────
+
+async function handle(args) {
+  const { parseFlag } = require('../core/args');
+
+  const portFlag = parseFlag(args, '--port');
+  const themeFlag = parseFlag(args, '--theme');
+  const noOpen = args.includes('--no-open');
+
+  // First positional arg that isn't a flag value
+  const valuedFlags = new Set(['--port', '--theme']);
+  let deckPath = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('-')) {
+      if (valuedFlags.has(args[i])) i++;
+      continue;
+    }
+    deckPath = args[i];
+    break;
+  }
+  if (!deckPath) {
+    console.error('Error: provide a deck JSON file');
+    console.error('Usage: voxflow slice stage <deck.json> [--port <n>] [--theme <id>] [--no-open]');
+    process.exit(1);
+  }
+
+  let port;
+  if (portFlag) {
+    const parsed = Number.parseInt(portFlag, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+      console.error(`Error: --port "${portFlag}" is not a valid TCP port`);
+      process.exit(1);
+    }
+    port = parsed;
+  }
+
+  let stage;
+  try {
+    stage = await startSliceStage({
+      deckPath,
+      theme: themeFlag || undefined,
+      port,
+    });
+  } catch (err) {
+    console.error(`\x1b[31mError:\x1b[0m ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log('\x1b[36m=== VoxFlow Stage — Slice ===\x1b[0m');
+  console.log(`Watching:  ${stage.sourcePath}`);
+  console.log(`Preview:   ${stage.url}`);
+  if (themeFlag) console.log(`Theme:     ${themeFlag}`);
+  console.log('');
+  console.log('Edit the deck JSON to hot-reload. Ctrl+C to stop.');
+  console.log('');
+
+  if (!noOpen && !process.env.CI) {
+    try {
+      const open = (await import('open')).default;
+      await open(stage.url);
+    } catch {
+      // Non-fatal — user can open the URL manually.
+    }
+  }
+
+  // Keep the process alive until SIGINT.
+  let stopping = false;
+  const stopAndExit = async (signal) => {
+    if (stopping) return;
+    stopping = true;
+    console.log(`\n\x1b[33m${signal} received — stopping Stage…\x1b[0m`);
+    try { await stage.stop(); } catch { /* best-effort */ }
+    process.exit(0);
+  };
+  process.on('SIGINT', () => stopAndExit('SIGINT'));
+  process.on('SIGTERM', () => stopAndExit('SIGTERM'));
+
+  // Park.
+  return new Promise(() => { /* never resolves; SIGINT exits */ });
+}
+
+module.exports = {
+  handle,
+  startSliceStage,
+  VALID_THEMES,
+};