voxflow 1.15.2 → 1.15.3

package/lib/commands/slice-stage.js

@@ -19,8 +19,11 @@ 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 { startLocalRender, getJobStatus } = require('../stage-core/local-render');
+const { validatePaperSlideDeck, isV2LayoutTreeDeck } = require('../internal/deck-validator');
 const { renderSliceStageHtml } = require('../stage-ui/slice/template');
 const { emit: emitTelemetry } = require('../core/telemetry');
+const { readCachedToken } = require('../core/auth');
 
 // 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
@@ -137,12 +140,72 @@ async function startSliceStage(opts) {
   // user logged into; the page never sees the JWT.
   const cloudRender = opts.cloudRender || createCloudRenderClient();
 
+  // ─── Local render bridge ───────────────────────────────────────────────
+  // Wires @remotion/renderer into stage so the page can produce mp4 without
+  // touching the cloud. The bridge captures the deck snapshot at submit
+  // time and proxies progress events through the existing SSE bus.
+  const localRenderBridge = opts.localRender || {
+    start({ output, onProgress, onDone, onError }) {
+      if (!snapshot.deck) {
+        const err = new Error('No deck loaded — fix the JSON parse error first.');
+        err.code = 'invalid_deck';
+        throw err;
+      }
+      return startLocalRender({
+        deck: snapshot.deck,
+        deckPath,
+        output,
+        onProgress,
+        onDone,
+        onError,
+      });
+    },
+    status: (jobId) => getJobStatus(jobId),
+  };
+
+  // ─── Inline deck save bridge (Task B) ──────────────────────────────────
+  // Validates the incoming deck against the same schema the cloud route
+  // uses, then writes atomically (tmp → rename). The watcher already
+  // broadcasts the resulting change to SSE — no extra fan-out needed.
+  const deckSaverBridge = opts.deckSaver || {
+    save(deck) {
+      if (isV2LayoutTreeDeck(deck)) {
+        return {
+          ok: false,
+          message: 'V2 LayoutTree decks are not supported for inline edit yet — edit deck.json directly.',
+        };
+      }
+      try {
+        validatePaperSlideDeck(deck);
+      } catch (err) {
+        return { ok: false, message: err.message, errors: [err.message] };
+      }
+      const tmp = `${deckPath}.tmp-${process.pid}-${Date.now()}`;
+      const out = JSON.stringify(deck, null, 2) + '\n';
+      fs.writeFileSync(tmp, out, 'utf8');
+      fs.renameSync(tmp, deckPath);
+      return { ok: true };
+    },
+  };
+
+  // Boot-time auth probe so the UI can emphasise local vs cloud render.
+  // We treat any cached, non-expired token as "logged in"; the actual
+  // request flow still revalidates on /api/quota-balance.
+  const tokenAvailable = (() => {
+    if (typeof opts.tokenAvailable === 'boolean') return opts.tokenAvailable;
+    try { return !!readCachedToken(); } catch { return false; }
+  })();
+
   const handle = await startStageServer({
     uiHtml: initialHtml,
     getDeckSnapshot: () => snapshot,
     subscribe: bus.subscribe,
     snapshots: snapshotsBridge,
     cloudRender,
+    localRender: localRenderBridge,
+    deckSaver: deckSaverBridge,
+    publishEvent: bus.publish,
+    tokenAvailable,
     preferredPort,
     maxPortTries,
   });

package/lib/stage-core/local-render.js

@@ -0,0 +1,268 @@
+'use strict';
+
+/**
+ * Stage → @remotion/renderer bridge for the *offline* Slice renderer.
+ *
+ * Why this exists: stage's existing "Render mp4" button proxies to the cloud
+ * backend (Fly render-worker), which requires `voxflow login` and burns 500
+ * quota per call. The Phase 0 promise was offline-first authoring — if a
+ * skill-driven user never logged in, the only render path on the stage page
+ * was broken. This module wires the same `@remotion/renderer` flow that
+ * `voxflow slice render` already uses (see `slice-render.js`) into stage,
+ * so the page can produce an mp4 against the pre-bundled Remotion serveUrl
+ * at `cli/dist/remotion-bundle/` with no network round-trip.
+ *
+ * Public surface:
+ *   startLocalRender({ deck, output, onProgress, onDone, onError })
+ *     → { jobId }                       — non-blocking, returns immediately
+ *   getJobStatus(jobId)                 → { state, progress, framesRendered,
+ *                                            framesTotal, outputPath, error }
+ *
+ * State machine per job:
+ *   pending  → preparing  → rendering  → completed
+ *                                     └→ failed
+ *
+ * Concurrency: jobs run sequentially on the stage server's event loop —
+ * `@remotion/renderer` spawns headless Chromium in subprocess workers and is
+ * CPU-bound, so parallel renders would thrash. The stage server is for
+ * single-author iteration; queueing is acceptable.
+ *
+ * Reuses helpers from slice-render.js (single source of truth):
+ *   - buildInputProps     — validator deck → PaperSlideDeckProps
+ *   - resolveServeUrl     — find dist/remotion-bundle in dev + ncc layouts
+ *   - chromeBinaryExists  — detect first-run cold start (so we can warn)
+ *   - THEME_TO_DECK_ID    — slice theme id → Remotion composition id
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const {
+  buildInputProps,
+  resolveServeUrl,
+  chromeBinaryExists,
+  THEME_TO_DECK_ID,
+  DEFAULT_THEME,
+} = require('../commands/slice-render');
+
+// In-memory job table. We never persist jobs — a stage restart wipes history,
+// which is fine because the produced mp4 lives on disk under the user's deck
+// directory. The page only knows about jobs while it's open.
+const jobs = new Map();
+
+function makeJobId() {
+  // crypto.randomUUID is Node 19+; the cli's engines field requires 20+, so
+  // it's always available. Tests can stub the module to inject deterministic
+  // ids if needed (see local-render.test.js).
+  return crypto.randomUUID();
+}
+
+/**
+ * Default output path: sibling of the deck file, same basename, `.mp4` ext.
+ *   /tmp/.../my-deck.json  →  /tmp/.../my-deck.mp4
+ *
+ * Falls back to `out.mp4` if the deck wasn't loaded from disk (deck-in-memory
+ * is hypothetical at the moment; current stage always has a deckPath, but we
+ * future-proof for an MCP-piped variant).
+ */
+function defaultOutputPath(deckPath) {
+  if (deckPath && typeof deckPath === 'string') {
+    const dir = path.dirname(deckPath);
+    const base = path.basename(deckPath, path.extname(deckPath));
+    return path.join(dir, `${base}.mp4`);
+  }
+  return path.resolve(process.cwd(), 'out.mp4');
+}
+
+/**
+ * Lazy-load @remotion/renderer. Doing this at module load would force every
+ * stage boot to pay the ~30 MB resolver cost; we defer until the first job.
+ * The renderer is a peer of slice-render.js (same version) so the bundle
+ * deduplicates in node_modules.
+ */
+function loadRenderer() {
+  return require('@remotion/renderer');
+}
+
+/**
+ * Start an offline Remotion render against the pre-bundled serveUrl.
+ *
+ * @param {object} opts
+ * @param {object} opts.deck                 Validator-shaped deck (cards + theme).
+ * @param {string} [opts.deckPath]           For default output path inference.
+ * @param {string} [opts.output]             Optional explicit output path.
+ * @param {(p:object) => void} [opts.onProgress]
+ *   Called on every Remotion progress tick. Payload:
+ *     { jobId, progress (0..1), framesRendered, framesTotal }
+ * @param {(d:object) => void} [opts.onDone]
+ *   Called with { jobId, outputPath, totalMs, sizeBytes } when the mp4 is written.
+ * @param {(e:object) => void} [opts.onError]
+ *   Called with { jobId, message } on any failure (synchronous or async).
+ * @returns {{ jobId:string, outputPath:string }}
+ *   Returned synchronously so the HTTP route can respond immediately while
+ *   the render proceeds in the background.
+ */
+function startLocalRender(opts) {
+  const deck = opts && opts.deck;
+  if (!deck || !Array.isArray(deck.cards)) {
+    const err = new Error('startLocalRender: deck.cards required');
+    err.code = 'invalid_deck';
+    throw err;
+  }
+  const theme = deck.theme || DEFAULT_THEME;
+  const deckId = THEME_TO_DECK_ID[theme];
+  if (!deckId) {
+    const err = new Error(`Unknown theme "${theme}". Valid: ${Object.keys(THEME_TO_DECK_ID).join(', ')}`);
+    err.code = 'invalid_theme';
+    throw err;
+  }
+
+  const outputPath = path.resolve(
+    opts.output || defaultOutputPath(opts.deckPath)
+  );
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+
+  const jobId = makeJobId();
+  const job = {
+    jobId,
+    state: 'pending',
+    progress: 0,
+    framesRendered: 0,
+    framesTotal: 0,
+    outputPath,
+    theme,
+    deckId,
+    error: null,
+    startedAt: Date.now(),
+    finishedAt: null,
+    sizeBytes: null,
+  };
+  jobs.set(jobId, job);
+
+  // Kick off the actual work on the next tick so the caller's POST handler
+  // can flush the response with the jobId before any renderer init starts.
+  setImmediate(() => {
+    runRender({
+      job,
+      deck,
+      onProgress: opts.onProgress,
+      onDone: opts.onDone,
+      onError: opts.onError,
+    });
+  });
+
+  return { jobId, outputPath };
+}
+
+async function runRender({ job, deck, onProgress, onDone, onError }) {
+  const { jobId, outputPath, deckId } = job;
+  try {
+    job.state = 'preparing';
+    const serveUrl = resolveServeUrl();
+    const inputProps = buildInputProps(deck);
+
+    const renderer = loadRenderer();
+    job.coldStart = !chromeBinaryExists();
+
+    const composition = await renderer.selectComposition({
+      serveUrl,
+      id: deckId,
+      inputProps,
+    });
+    job.framesTotal = composition.durationInFrames;
+    job.state = 'rendering';
+    if (typeof onProgress === 'function') {
+      try {
+        onProgress({
+          jobId,
+          progress: 0,
+          framesRendered: 0,
+          framesTotal: job.framesTotal,
+        });
+      } catch { /* swallow consumer errors */ }
+    }
+
+    await renderer.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 }) => {
+        job.progress = progress;
+        job.framesRendered = renderedFrames;
+        if (typeof onProgress === 'function') {
+          try {
+            onProgress({
+              jobId,
+              progress,
+              framesRendered: renderedFrames,
+              framesTotal: job.framesTotal,
+            });
+          } catch { /* swallow */ }
+        }
+      },
+    });
+
+    const stat = fs.statSync(outputPath);
+    job.state = 'completed';
+    job.progress = 1;
+    job.sizeBytes = stat.size;
+    job.finishedAt = Date.now();
+    if (typeof onDone === 'function') {
+      try {
+        onDone({
+          jobId,
+          outputPath,
+          totalMs: job.finishedAt - job.startedAt,
+          sizeBytes: job.sizeBytes,
+        });
+      } catch { /* swallow */ }
+    }
+  } catch (err) {
+    job.state = 'failed';
+    job.error = err && err.message ? err.message : String(err);
+    job.finishedAt = Date.now();
+    if (typeof onError === 'function') {
+      try { onError({ jobId, message: job.error }); } catch { /* swallow */ }
+    }
+  }
+}
+
+function getJobStatus(jobId) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  return {
+    jobId: job.jobId,
+    state: job.state,
+    progress: job.progress,
+    framesRendered: job.framesRendered,
+    framesTotal: job.framesTotal,
+    outputPath: job.outputPath,
+    error: job.error,
+    sizeBytes: job.sizeBytes,
+    startedAt: job.startedAt,
+    finishedAt: job.finishedAt,
+  };
+}
+
+/** Test-only: nuke the job table between cases. Not exposed in module exports
+ *  publicly to discourage callers from clearing state in production paths. */
+function _resetJobsForTests() {
+  jobs.clear();
+}
+
+module.exports = {
+  startLocalRender,
+  getJobStatus,
+  defaultOutputPath,
+  _resetJobsForTests,
+};

package/lib/stage-core/server.js

@@ -32,8 +32,28 @@ const { findAvailablePort } = require('./port');
  *   and GET /api/quota-balance — all proxies to the upstream API. Shape:
  *   { submit(deck), status(jobId), quota() }. Lets users go from "deck I
  *   like" → mp4 without leaving stage; the proxy keeps the JWT off the page.
+ * @param {object} [opts.localRender] Optional local-render handle.
+ *   If provided, exposes POST /api/render-local and GET /api/render-local/:id/status.
+ *   Shape: { start({onProgress, onDone, onError, output}), status(jobId) }.
+ *   Used to render mp4 with `@remotion/renderer` *without* any cloud
+ *   round-trip — required for offline-first authoring (skill-driven users
+ *   may never have run `voxflow login`). Reuses the same SSE channel
+ *   `subscribe` feeds for progress fan-out.
+ * @param {object} [opts.deckSaver] Optional inline-edit handle.
+ *   If provided, exposes POST /api/deck → write new deck JSON to disk.
+ *   Shape: { save(deck) → { ok:true } | { ok:false, errors:[...] } }.
+ *   The file watcher picks up the resulting change and broadcasts deck SSE,
+ *   so no extra fan-out is needed here.
+ * @param {(event:object) => void} [opts.publishEvent]
+ *   Optional event-bus publisher — when provided, local-render progress
+ *   events are fanned out through the same `subscribe` channel as deck
+ *   events, so the page can listen on one EventSource for everything.
  * @param {number} [opts.preferredPort=5180]
  * @param {number} [opts.maxPortTries=10]
+ * @param {boolean} [opts.tokenAvailable]
+ *   Optional flag baked into the boot snapshot returned by GET /api/auth-state.
+ *   The page reads this once on load to decide whether to emphasise the
+ *   "local" or "cloud" render button. Cheap; no JWT ever leaves the server.
  * @returns {Promise<{server:http.Server, port:number, url:string, close:() => Promise<void>}>}
  */
 async function startStageServer(opts) {
@@ -43,6 +63,10 @@ async function startStageServer(opts) {
     subscribe,
     snapshots = null,
     cloudRender = null,
+    localRender = null,
+    deckSaver = null,
+    publishEvent = null,
+    tokenAvailable = false,
     preferredPort = 5180,
     maxPortTries = 10,
   } = opts;
@@ -273,6 +297,153 @@ async function startStageServer(opts) {
       return;
     }
 
+    // ─── Auth-state probe ───────────────────────────────────────────────────
+    // Single GET so the page can decide local-vs-cloud render emphasis on
+    // load. No JWT or refresh-token bytes ever leave the server.
+    if (req.method === 'GET' && req.url === '/api/auth-state') {
+      sendJson(200, { code: 'success', tokenAvailable: !!tokenAvailable });
+      return;
+    }
+
+    // ─── Local render (offline, @remotion/renderer) ─────────────────────────
+    // POST /api/render-local              → start a job, return { jobId }
+    // GET  /api/render-local/:id/status   → poll status
+    //
+    // Progress + done events are pushed onto the deck SSE channel via
+    // publishEvent so the page listens on a single EventSource.
+    if (localRender && req.method === 'POST' && req.url === '/api/render-local') {
+      const chunks = [];
+      let total = 0;
+      const MAX = 64 * 1024;
+      req.on('data', (c) => {
+        total += c.length;
+        if (total > MAX) { req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        let body = {};
+        const raw = Buffer.concat(chunks).toString('utf8');
+        if (raw) {
+          try { body = JSON.parse(raw); }
+          catch { return sendJson(400, { code: 'bad_json', message: 'render-local body must be JSON' }); }
+        }
+        const output = typeof body.output === 'string' && body.output.trim()
+          ? body.output.trim() : null;
+
+        let started;
+        try {
+          started = localRender.start({
+            output,
+            onProgress(p) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-progress',
+                  jobId: p.jobId,
+                  progress: p.progress,
+                  framesRendered: p.framesRendered,
+                  framesTotal: p.framesTotal,
+                  ts: Date.now(),
+                });
+              }
+            },
+            onDone(d) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-done',
+                  jobId: d.jobId,
+                  outputPath: d.outputPath,
+                  totalMs: d.totalMs,
+                  sizeBytes: d.sizeBytes,
+                  ts: Date.now(),
+                });
+              }
+            },
+            onError(e) {
+              if (typeof publishEvent === 'function') {
+                publishEvent({
+                  type: 'render-local-error',
+                  jobId: e.jobId,
+                  message: e.message,
+                  ts: Date.now(),
+                });
+              }
+            },
+          });
+        } catch (err) {
+          return sendJson(400, {
+            code: err.code || 'render_local_failed',
+            message: err.message || 'could not start local render',
+          });
+        }
+        return sendJson(200, {
+          code: 'success',
+          jobId: started.jobId,
+          outputPath: started.outputPath,
+        });
+      });
+      return;
+    }
+
+    if (localRender && req.method === 'GET' && req.url.startsWith('/api/render-local/')) {
+      // expected: /api/render-local/:id/status
+      const rest = req.url.slice('/api/render-local/'.length);
+      const slashIdx = rest.indexOf('/');
+      const id = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+      const tail = slashIdx === -1 ? '' : rest.slice(slashIdx + 1);
+      if (!id || tail !== 'status') {
+        sendJson(404, { code: 'not_found', message: `No route: ${req.method} ${req.url}` });
+        return;
+      }
+      const status = localRender.status(decodeURIComponent(id));
+      if (!status) {
+        sendJson(404, { code: 'job_not_found', message: `No local-render job: ${id}` });
+        return;
+      }
+      sendJson(200, { code: 'success', ...status });
+      return;
+    }
+
+    // ─── Inline deck save (Task B) ──────────────────────────────────────────
+    // POST /api/deck  body: full deck JSON  → validates + writes to disk.
+    // The file watcher picks up the write and broadcasts the deck event, so
+    // the page hot-reloads via the same path as an external editor save.
+    if (deckSaver && req.method === 'POST' && req.url === '/api/deck') {
+      const chunks = [];
+      let total = 0;
+      // Decks are small (5-8 cards, ~5 KB). 256 KB cap is plenty headroom
+      // even with V2 layout-tree decks while still defending against pasted
+      // monsters.
+      const MAX = 256 * 1024;
+      req.on('data', (c) => {
+        total += c.length;
+        if (total > MAX) { req.destroy(); return; }
+        chunks.push(c);
+      });
+      req.on('end', () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); }
+        catch { return sendJson(400, { code: 'bad_json', message: 'deck body must be JSON' }); }
+        const deck = body && body.deck;
+        if (!deck || typeof deck !== 'object') {
+          return sendJson(400, { code: 'invalid_deck', message: 'body.deck (object) required' });
+        }
+        let result;
+        try { result = deckSaver.save(deck); }
+        catch (err) {
+          return sendJson(500, { code: 'deck_save_failed', message: err.message || 'save error' });
+        }
+        if (!result || result.ok !== true) {
+          return sendJson(400, {
+            code: 'invalid_deck',
+            message: (result && result.message) || 'deck failed validation',
+            errors: (result && result.errors) || undefined,
+          });
+        }
+        return sendJson(200, { code: 'success' });
+      });
+      return;
+    }
+
     if (req.method === 'GET' && req.url === '/events') {
       res.writeHead(200, {
         'Content-Type': 'text/event-stream; charset=utf-8',