@hypersocial/decks-cli 0.1.9 → 0.1.11

package/README.md

@@ -5,25 +5,25 @@ Command-line client for Hypersocial Decks live analytics and share management.
 Most users should install the friendlier package name:
 
 ```bash
-pnpm dlx hyperdecks whoami
+npx hyperdecks whoami
 ```
 
 This package targets production by default:
 
 ```bash
-pnpm dlx @hypersocial/decks-cli login
-pnpm dlx @hypersocial/decks-cli whoami
-pnpm dlx @hypersocial/decks-cli deck list
-pnpm dlx @hypersocial/decks-cli deck stats netflix
-pnpm dlx @hypersocial/decks-cli activity --limit 20
-pnpm dlx @hypersocial/decks-cli import ./claude-design-export.zip --slug acme-pitch
-pnpm dlx @hypersocial/decks-cli skills install
+npx @hypersocial/decks-cli login
+npx @hypersocial/decks-cli whoami
+npx @hypersocial/decks-cli deck list
+npx @hypersocial/decks-cli deck stats netflix
+npx @hypersocial/decks-cli activity --limit 20
+npx @hypersocial/decks-cli import ./claude-design-export.zip --slug acme-pitch
+npx @hypersocial/decks-cli skills install
 ```
 
 Global install:
 
 ```bash
-pnpm add -g @hypersocial/decks-cli
+npm install -g @hypersocial/decks-cli
 decks login
 decks activity
 ```
@@ -55,9 +55,10 @@ deck list [--json]
 deck stats <slug> [--json]
 deck open <slug>
 
-share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]
+share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify]
 share list <slug> [--json]
 share on|off <token>
+share mute|unmute <token>
 share rm <token>
 share url <token>
 
@@ -115,3 +116,47 @@ The same import is exposed to agents via the `hypersocial-decks` MCP server as t
 ```
 
 It authenticates with the stored CLI credential — run `decks login --prod` first.
+
+## QA and narration (0.1.10)
+
+`share new <slug> "QA" --qa` serves the full deck runtime but is completely
+untracked and always muted. `share new <slug> "Telemetry test" --no-notify`
+creates a tracked muted link; use it only on an isolated test deck for telemetry
+QA. `share mute <token>` and `share unmute <token>` are owner-only; QA links
+cannot be unmuted. Statistics distinguish narration started, narration finished,
+narration not started, and unknown legacy playback. Closing a deck does not
+establish completion. See the main repository README for the runtime event contract.
+
+## Animated email previews (0.1.10+)
+
+Published in 0.1.10; the owner-only `previews:get` query is live in production. Local-file export needs no login. Both `hyperdecks` and `decks` accept the same command; the canonical package is `@hypersocial/decks-cli`.
+
+```sh
+hyperdecks preview setup
+hyperdecks preview create --file ./presentation/index.html --out ./preview-local --json
+hyperdecks share list my-deck --json
+hyperdecks preview create my-deck --share EXISTING_TOKEN --out ./preview-email --upload --json
+```
+
+Generate locally, select an existing same-deck recipient share, then explicitly upload into a **new** output directory. The command never creates or visits a share. Upload requires an owned deck slug; `--file` with `--upload` or `--share` is rejected. Disabled, expired, exhausted and mismatched shares fail before upload. QA shares are supported intentionally: their click-through remains untracked and muted, so use a regular recipient share for measured outreach.
+
+Capture defaults to the initial slide, 4 seconds, 600px width and 10 fps, with a play/watch badge on GIF, PNG and silent MP4. `--duration` accepts 1–10 seconds, `--width` 240–1200 pixels (odd widths round up for MP4), `--delay` 0–10000 milliseconds (default 1000), and `--label "Watch · 2:41"` supplies an explicit label; no whole-deck narration duration is inferred. Aspect comes from `--aspect-ratio W:H`, `<meta name="preview-aspect-ratio" content="16:9">`, or the first slide/canvas bounds; otherwise 16:9. Output height rounds to an even pixel. Fonts get up to 5 seconds to settle. Inspect readiness warnings/poster for slow modules or media and increase the bounded delay if needed.
+
+`--json` prints one line on stdout, identical to `<out>/manifest.json`:
+
+```json
+{ "status": "exported | uploaded | failed", "shareUrl": "https://decks.hypersocial.ai/v/<token>",
+  "files": [{ "type": "gif | png | mp4", "path": "...", "url": "https://...convex.cloud/api/storage/...", "bytes": 74662, "width": 600, "height": 338 }],
+  "email": { "sendable": true, "path": "<out>/email.html", "html": "<a href=\"<shareUrl>\"><img src=\"<gif url>\" ...></a>" },
+  "warnings": [] }
+```
+
+`email.html` is the embed: drop it into any HTML email body or API send. `url` and `email` exist only after `--upload`.
+
+Errors/progress use stderr and failures exit nonzero. `manifest.json` records source, status, absolute artifact paths, MIME types, bytes, dimensions, clip durations/fps, share URL, warnings and each completed upload. Files larger than 5 MiB warn: reduce duration/width for email. On upload failure local artifacts survive; inspect the manifest's URLs and `upload` records (an uploaded storage blob can exist even if saving its asset failed). Retry in a fresh directory; never overwrite an image already used in an email.
+
+Only successful explicit uploads produce `email.html` and `email.sendable: true`, with the GIF wrapped in the exact recipient link. Use that HTML/GIF in your draft manually. Some email clients show only the first GIF frame: the PNG poster and the visible watch badge provide a static fallback. MP4 is for other channels; email video support varies. Local exports provide files to insert manually and a separate share URL when selected, with no claim of sendable remote-image HTML. Static image downloads do not open the deck, start narration, record engagement, or notify the owner.
+
+Playwright and the platform FFmpeg executable are declared dependencies loaded only for preview capture; normal login/import/stats do not need capture prerequisites. `preview setup` installs the matching Chromium with no personal profile. On Linux, install Playwright's system libraries using `npx playwright@1.64.1 install-deps chromium` (may need administrator access), then run setup. FFmpeg comes from `@ffmpeg-installer/ffmpeg`, never a global/Homebrew executable. npm installs must include optional dependencies and allow install scripts; pnpm users must approve their `@ffmpeg-installer/<platform>` chmod script. Reinstall with `npm install -g hyperdecks --include=optional` if it is missing. Unsupported platforms fail with recovery guidance.
+
+The local server exposes only supported static files within the explicit HTML file's directory; dotfiles, traversal and outside symlinks are denied. Keep capture inputs in a dedicated asset directory. Relative modules/fonts/video and external `<base>` URLs are retained. A fresh browser context receives no CLI credentials, cookies, profile or environment secrets. Recipient routes, first-party telemetry, non-GET requests, sockets and unrelated local services are blocked by URL and DNS checks that fail closed on lookup errors. Chromium resolves independently, so DNS rebinding is not fully prevented; use OS/network isolation for untrusted content. Video stays muted; the exporter does not click controls or start narration. Capture is bounded and temporary browser/server/frame files are removed on success/failure. Use only trusted deck content; third-party static resources may be fetched while rendering. HTTP redirects are refused before the browser follows them; use direct final asset URLs if a resource warns or fails to load.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",
@@ -30,8 +30,10 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "convex": "^1.41.0",
-    "fflate": "^0.8.2"
+    "fflate": "^0.8.2",
+    "playwright": "^1.64.1"
   },
   "publishConfig": {
     "access": "public"

package/skills/hyperdecks/SKILL.md

@@ -53,3 +53,37 @@ hyperdecks login
   live changes, state the action and target clearly before executing when user
   intent is ambiguous.
 - Avoid printing full share tokens unless the user needs the exact URL/token.
+
+## Animated email previews (0.1.10+)
+
+Published in 0.1.10; the owner-only `previews:get` query is live in production. Local-file export needs no login. Both `hyperdecks` and `decks` accept the same command; the canonical package is `@hypersocial/decks-cli`.
+
+```sh
+hyperdecks preview setup
+hyperdecks preview create --file ./presentation/index.html --out ./preview-local --json
+hyperdecks share list my-deck --json
+hyperdecks preview create my-deck --share EXISTING_TOKEN --out ./preview-email --upload --json
+```
+
+Generate locally, select an existing same-deck recipient share, then explicitly upload into a **new** output directory. The command never creates or visits a share. Upload requires an owned deck slug; `--file` with `--upload` or `--share` is rejected. Disabled, expired, exhausted and mismatched shares fail before upload. QA shares are supported intentionally: their click-through remains untracked and muted, so use a regular recipient share for measured outreach.
+
+Capture defaults to the initial slide, 4 seconds, 600px width and 10 fps, with a play/watch badge on GIF, PNG and silent MP4. `--duration` accepts 1–10 seconds, `--width` 240–1200 pixels (odd widths round up for MP4), `--delay` 0–10000 milliseconds (default 1000), and `--label "Watch · 2:41"` supplies an explicit label; no whole-deck narration duration is inferred. Aspect comes from `--aspect-ratio W:H`, `<meta name="preview-aspect-ratio" content="16:9">`, or the first slide/canvas bounds; otherwise 16:9. Output height rounds to an even pixel. Fonts get up to 5 seconds to settle. Inspect readiness warnings/poster for slow modules or media and increase the bounded delay if needed.
+
+`--json` prints one line on stdout, identical to `<out>/manifest.json`:
+
+```json
+{ "status": "exported | uploaded | failed", "shareUrl": "https://decks.hypersocial.ai/v/<token>",
+  "files": [{ "type": "gif | png | mp4", "path": "...", "url": "https://...convex.cloud/api/storage/...", "bytes": 74662, "width": 600, "height": 338 }],
+  "email": { "sendable": true, "path": "<out>/email.html", "html": "<a href=\"<shareUrl>\"><img src=\"<gif url>\" ...></a>" },
+  "warnings": [] }
+```
+
+`email.html` is the embed: drop it into any HTML email body or API send. `url` and `email` exist only after `--upload`.
+
+Errors/progress use stderr and failures exit nonzero. `manifest.json` records source, status, absolute artifact paths, MIME types, bytes, dimensions, clip durations/fps, share URL, warnings and each completed upload. Files larger than 5 MiB warn: reduce duration/width for email. On upload failure local artifacts survive; inspect the manifest's URLs and `upload` records (an uploaded storage blob can exist even if saving its asset failed). Retry in a fresh directory; never overwrite an image already used in an email.
+
+Only successful explicit uploads produce `email.html` and `email.sendable: true`, with the GIF wrapped in the exact recipient link. Use that HTML/GIF in your draft manually. Some email clients show only the first GIF frame: the PNG poster and the visible watch badge provide a static fallback. MP4 is for other channels; email video support varies. Local exports provide files to insert manually and a separate share URL when selected, with no claim of sendable remote-image HTML. Static image downloads do not open the deck, start narration, record engagement, or notify the owner.
+
+Playwright and the platform FFmpeg executable are declared dependencies loaded only for preview capture; normal login/import/stats do not need capture prerequisites. `preview setup` installs the matching Chromium with no personal profile. On Linux, install Playwright's system libraries using `npx playwright@1.64.1 install-deps chromium` (may need administrator access), then run setup. FFmpeg comes from `@ffmpeg-installer/ffmpeg`, never a global/Homebrew executable. npm installs must include optional dependencies and allow install scripts; pnpm users must approve their `@ffmpeg-installer/<platform>` chmod script. Reinstall with `npm install -g hyperdecks --include=optional` if it is missing. Unsupported platforms fail with recovery guidance.
+
+The local server exposes only supported static files within the explicit HTML file's directory; dotfiles, traversal and outside symlinks are denied. Keep capture inputs in a dedicated asset directory. Relative modules/fonts/video and external `<base>` URLs are retained. A fresh browser context receives no CLI credentials, cookies, profile or environment secrets. Recipient routes, first-party telemetry, non-GET requests, sockets and unrelated local services are blocked by URL and DNS checks that fail closed on lookup errors. Chromium resolves independently, so DNS rebinding is not fully prevented; use OS/network isolation for untrusted content. Video stays muted; the exporter does not click controls or start narration. Capture is bounded and temporary browser/server/frame files are removed on success/failure. Use only trusted deck content; third-party static resources may be fetched while rendering. HTTP redirects are refused before the browser follows them; use direct final asset URLs if a resource warns or fails to load.

package/src/commands.mjs

@@ -10,6 +10,10 @@ import {
 } from "./runtime.mjs";
 import * as ops from "./ops.mjs";
 
+export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
+  : p.narrationStarted ? "narration started"
+    : p.telemetryVersion === 2 ? "narration not started" : "playback unknown (legacy)";
+
 const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
 
 async function whoamiCmd(opts) {
@@ -57,7 +61,7 @@ async function deckStats(pos, opts) {
     console.log("  recent:");
     for (const r of s.recent) {
       const where = [r.city, r.country].filter(Boolean).join(", ");
-      console.log(`    ${new Date(r.lastSeenAt).toISOString()}\t${r.recipient}\t${fmtMs(r.totalMs)}\tslide ${r.maxSlide}${r.completed ? " complete" : ""}\t${where}`);
+      console.log(`    ${new Date(r.lastSeenAt).toISOString()}\t${r.recipient}\t${fmtMs(r.totalMs)}\tslide ${r.maxSlide} · ${playbackLabel(r)}\t${where}`);
     }
   }
 }
@@ -83,13 +87,15 @@ function shareBase(opts) {
 
 async function shareNew(pos, opts) {
   const [slug, recipient] = pos;
-  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]");
+  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify]");
   const { token } = await ops.createShare(opts, {
     slug,
     recipient,
     email: opts.email,
     note: opts.note,
     requireEmail: opts["require-email"],
+    qa: opts.qa || undefined,
+    notify: opts["no-notify"] ? false : undefined,
     expires: opts.expires,
     limit: opts.limit,
   });
@@ -106,7 +112,7 @@ async function shareList(pos, opts) {
     console.log(JSON.stringify(rows, null, 2));
     return;
   }
-  for (const r of rows) console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${r.recipient}\topens:${r.opens}${r.archived ? "\t(archived)" : ""}`);
+  for (const r of rows) console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${r.recipient}\topens:${r.opens}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.archived ? "\t(archived)" : ""}`);
   if (!rows.length) console.log("(no shares)");
 }
 
@@ -156,11 +162,26 @@ async function activity(pos, opts) {
       console.log(`${when}\tsent\t${f.recipient}\t${f.deckTitle}`);
     } else {
       const where = [f.city, f.country].filter(Boolean).join(", ");
-      console.log(`${when}\topened\t${f.recipient}\t${f.deckTitle}\tslide ${f.maxSlide}\t${fmtMs(f.totalMs)}${f.completed ? " complete" : ""}\t${where}`);
+      console.log(`${when}\topened\t${f.recipient}\t${f.deckTitle}\tslide ${f.maxSlide}\t${fmtMs(f.totalMs)} · ${playbackLabel(f)}\t${where}`);
     }
   }
 }
 
+async function credits(pos, opts) {
+  const bal = await ops.creditsBalance(opts);
+  const ledger = await ops.creditsLedger(opts, opts.limit || 10);
+  if (opts.json) {
+    console.log(JSON.stringify({ ...bal, ledger }, null, 2));
+    return;
+  }
+  console.log(`credits: ${bal.balance}`);
+  for (const e of ledger) {
+    const when = new Date(e.at).toISOString().slice(0, 16).replace("T", " ");
+    console.log(`  ${when}  ${e.delta > 0 ? "+" : ""}${e.delta}\t${e.kind}\t${e.reason}`);
+  }
+  if (!ledger.length) console.log("  (no history yet)");
+}
+
 async function importDeck(pos, opts) {
   const [src] = pos;
   if (!src) {
@@ -220,7 +241,8 @@ commands:
   logout [--dev]
   whoami [--json] [--dev]
   deck list|stats|open|rm
-  share new|list|on|off|rm|url
+  share new|list|on|off|mute|unmute|rm|url
+    share new <slug> <recipient> [--qa] [--no-notify]
   recipient archive|unarchive
   import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live]
   import-design <project-id> --serve-token <token> --entry <file.html> --slug <slug>
@@ -229,6 +251,11 @@ commands:
   activity [--deck <slug>] [--limit <n>] [--json]
   gen-image "<prompt>" [--transparent] [--image <url>] [--size <s>] [--quality <q>] [--count <n>] [--slug <deck>] [--download <file>]
   image-job <jobId> [--json]
+  credits [--limit <n>] [--json]   show your credit balance and recent history
+
+  preview create <slug> --out <directory> [--share <token>] [--upload] [--json]
+  preview create --file <index.html> --out <directory> [--duration 4] [--width 600] [--delay 1000] [--label "Watch"] [--aspect-ratio 16:9]
+  preview setup    install isolated Chromium (Linux: see README for system dependencies)
 
 global:
   --json
@@ -282,6 +309,7 @@ async function genImage(pos, opts) {
     for (const im of images) if (im.url) console.log(im.url);
     if (opts.download) console.log(`\nSaved ${images.length} file(s) to ${opts.download}`);
   }
+  if (out.creditsRemaining != null) process.stderr.write(`credits left: ${out.creditsRemaining}\n`);
 }
 
 async function imageJob(pos, opts) {
@@ -312,6 +340,15 @@ export async function runCli(argv = process.argv.slice(2)) {
   const [group, cmd] = pos;
   const rest = pos.slice(2);
   const handlers = {
+    "preview create": async () => {
+      const { createPreview } = await import("./preview.mjs");
+      const result = await createPreview(rest, opts);
+      console.log(opts.json ? JSON.stringify(result) : `Preview saved: ${result.manifestPath}\n${result.email.sendable ? result.email.path : "Insert the GIF or PNG manually; upload with an existing share for linked email HTML."}`);
+    },
+    "preview setup": async () => {
+      const { setupCapture } = await import("./preview-capture.mjs");
+      await setupCapture(rest, opts);
+    },
     login: () => login(opts),
     logout: () => logout(opts),
     whoami: () => whoamiCmd(opts),
@@ -323,6 +360,8 @@ export async function runCli(argv = process.argv.slice(2)) {
     "share list": () => shareList(rest, opts),
     "share on": () => shareToggle(rest, opts, true),
     "share off": () => shareToggle(rest, opts, false),
+    "share mute": async () => { if (!rest[0]) throw new Error("usage: share mute <token>"); await ops.setShareNotify(opts, rest[0], false); console.log(`OK muted ${rest[0]}`); },
+    "share unmute": async () => { if (!rest[0]) throw new Error("usage: share unmute <token>"); await ops.setShareNotify(opts, rest[0], true); console.log(`OK notification preference requested for ${rest[0]} (QA links remain muted)`); },
     "share rm": () => shareRm(rest, opts),
     "share url": () => shareUrl(rest, opts),
     "recipient archive": () => recipientArchive(rest, opts, true),
@@ -334,6 +373,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     activity: () => activity(pos.slice(1), opts),
     "gen-image": () => genImage(pos.slice(1), opts),
     "image-job": () => imageJob(pos.slice(1), opts),
+    credits: () => credits(pos.slice(1), opts),
   };
 
   const handler = handlers[`${group} ${cmd}`] || handlers[group];

package/src/ops.mjs

@@ -64,6 +64,17 @@ export async function checkImageJob(opts, jobId) {
   return (await client(opts)).query(api.imagegen.checkImageJob, { jobId: String(jobId) });
 }
 
+// Read the signed-in user's credit balance.
+export async function creditsBalance(opts = {}) {
+  return (await client(opts)).query(api.credits.getBalance, {});
+}
+
+// Read the user's recent credit ledger (most recent first).
+export async function creditsLedger(opts = {}, limit) {
+  const args = limit ? { limit: Number(limit) } : {};
+  return (await client(opts)).query(api.credits.getLedger, args);
+}
+
 // Poll an async image job until it finishes. Returns { images, slug } on success
 // (results are the same shape as the inline { images }); throws on job error or
 // timeout. `onProgress(job)` is called each tick. Used by the CLI so gen-image stays
@@ -73,7 +84,7 @@ export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs =
   const start = Date.now();
   for (;;) {
     const job = await c.query(api.imagegen.checkImageJob, { jobId: String(jobId) });
-    if (job.status === "done") return { images: job.results || [], slug: job.slug };
+    if (job.status === "done") return { images: job.results || [], slug: job.slug, creditsRemaining: job.creditsRemaining };
     if (job.status === "error") {
       // A batch isn't atomic: earlier images may have been generated + saved before
       // the failure. Surface that so the user knows assets/spend exist despite "error".
@@ -95,6 +106,8 @@ export async function listShares(opts, slug) {
     enabled: r.enabled,
     opens: r.opens,
     archived: !!r.archived,
+    qa: !!r.qa,
+    notify: r.qa ? false : r.notify !== false,
     lastOpenedAt: r.lastOpenedAt ?? null,
     requireEmail: r.requireEmail,
     recipientEmail: r.recipientEmail ?? null,
@@ -107,6 +120,8 @@ export async function createShare(opts, fields) {
   const { slug, recipient } = fields;
   if (!slug || !recipient) throw new Error("slug and recipient are required");
   const args = { deckSlug: slug, recipient };
+  if (fields.qa !== undefined) args.qa = !!fields.qa;
+  if (fields.notify !== undefined) args.notify = !!fields.notify;
   if (fields.email) args.recipientEmail = fields.email;
   if (fields.note) args.note = fields.note;
   if (fields.requireEmail) args.requireEmail = true;
@@ -129,6 +144,11 @@ export async function setShareEnabled(opts, token, enabled) {
   return { token, enabled: !!enabled };
 }
 
+export async function setShareNotify(opts, token, notify) {
+  if (!token) throw new Error("token is required");
+  await (await client(opts)).mutation(api.shares.setNotify, { token, notify });
+}
+
 export async function removeShare(opts, token) {
   if (!token) throw new Error("token is required");
   await (await client(opts)).mutation(api.shares.remove, { token });

package/src/preview-capture.mjs

@@ -0,0 +1,194 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { createServer } from 'node:http';
+import { readFile, realpath, mkdtemp, rm, stat } from 'node:fs/promises';
+import { resolve, dirname, extname, sep, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+const run = promisify(execFile);
+const require = createRequire(import.meta.url);
+const MIME = { '.html':'text/html', '.htm':'text/html', '.js':'text/javascript', '.mjs':'text/javascript', '.css':'text/css', '.json':'application/json', '.png':'image/png', '.jpg':'image/jpeg', '.jpeg':'image/jpeg', '.gif':'image/gif', '.webp':'image/webp', '.svg':'image/svg+xml', '.woff':'font/woff', '.woff2':'font/woff2', '.ttf':'font/ttf', '.otf':'font/otf', '.mp4':'video/mp4', '.webm':'video/webm', '.mp3':'audio/mpeg', '.wav':'audio/wav', '.wasm':'application/wasm', '.glb':'model/gltf-binary', '.gltf':'model/gltf+json', '.bin':'application/octet-stream' };
+const SETUP = 'Run `hyperdecks preview setup` (or `decks preview setup`) to install the matching isolated Chromium. On Linux install system libraries with `npx playwright install-deps chromium` using the Playwright version in your installed CLI.';
+export async function setupCapture(pos, opts) {
+  if (pos.length || Object.keys(opts).some(k => !['json', 'dev', 'convex', 'prod'].includes(k))) throw new Error('usage: preview setup');
+  await run(process.execPath, [join(dirname(require.resolve('playwright/package.json')), 'cli.js'), 'install', 'chromium'], { timeout: 240000, maxBuffer: 4 * 1024 * 1024 });
+  console.log(opts.json ? JSON.stringify({ installed: 'chromium' }) : 'Chromium installed. Preview capture is ready.');
+}
+
+// Capability URL + realpath containment; captured code gets no general file server.
+export async function serveSource({ file, html }) {
+  const root = file ? await realpath(dirname(file)) : null;
+  const prefix = '/' + randomUUID() + '/';
+  const entry = prefix + (file ? encodeURIComponent(resolve(file).split(sep).pop()) : 'index.html');
+  const server = createServer(async (req, res) => {
+    try {
+      const path = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+      if (req.method !== 'GET' || !path.startsWith(prefix)) { res.writeHead(404).end(); return; }
+      if (!file && path === entry) { res.writeHead(200, { 'Content-Type':'text/html; charset=utf-8', 'Cache-Control':'no-store' }).end(html); return; }
+      const rel = path.slice(prefix.length);
+      if (!root || rel.split('/').some(s => s.startsWith('.') || s.includes('\\')) || !MIME[extname(rel).toLowerCase()]) { res.writeHead(404).end(); return; }
+      const full = await realpath(resolve(root, rel));
+      if (!full.startsWith(root + sep) || !(await stat(full)).isFile()) { res.writeHead(404).end(); return; }
+      res.writeHead(200, { 'Content-Type': MIME[extname(full).toLowerCase()] + (MIME[extname(full).toLowerCase()].startsWith('text/') ? '; charset=utf-8' : ''), 'Cache-Control':'no-store' });
+      res.end(await readFile(full));
+    } catch { res.writeHead(404).end(); }
+  });
+  await new Promise((ok, fail) => { server.once('error', fail); server.listen(0, '127.0.0.1', ok); });
+  const url = `http://127.0.0.1:${server.address().port}${entry}`;
+  return { url, close: () => new Promise((ok, fail) => { server.close(e => e ? fail(e) : ok()); server.closeAllConnections(); }) };
+}
+export function allowCaptureRequest(url, method, type, entryUrl, firstPartyOrigins = []) {
+  let u, path;
+  try { u = new URL(url); path = decodeURIComponent(u.pathname); } catch { return false; }
+  if (!['http:', 'https:', 'data:', 'blob:'].includes(u.protocol) || method !== 'GET') return false;
+  if (/(^|\/)(v|track|telemetry|analytics|beacon)(\/|$)/i.test(path)) return false;
+  if (type === 'document') return url === entryUrl;
+  if (['websocket', 'eventsource', 'ping', 'other'].includes(type)) return false;
+  if (firstPartyOrigins.some(v => new URL(v).origin === u.origin) || /\.convex\.(cloud|site)$/.test(u.hostname)) {
+    return /^\/api\/storage\//.test(path);
+  }
+  // Prevent page code from reaching local services or cloud metadata. Only the
+  // capability file server is available on loopback; redirects are checked too.
+  if (u.origin !== new URL(entryUrl).origin && /^(localhost|127\.|0\.|10\.|192\.168\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|\[|.*\.localhost$)/i.test(u.hostname.replace(/\.+$/, ''))) return false;
+  return true;
+}
+
+// DNS is checked per request; HTTP redirects are refused, without trusting host spelling.
+// This is defense in depth for trusted capture inputs, not a network sandbox:
+// Chromium resolves independently, so DNS rebinding requires OS/network isolation.
+export function isPublicAddress(address) {
+  if (isIP(address) === 4) {
+    const [a,b] = address.split('.').map(Number);
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 ||
+      (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) || (a === 192 && [0,168].includes(b)) ||
+      (a === 198 && [18,19].includes(b)));
+  }
+  // Global unicast only; mapped IPv4, unique-local, multicast and link-local fail.
+  return isIP(address) === 6 && /^[23][0-9a-f]{3}:/i.test(address) && !/^2001:(db8|0):/i.test(address);
+}
+export async function allowCaptureDestination(url, entryUrl, resolver = lookup) {
+  try {
+    const u = new URL(url);
+    if (u.origin === new URL(entryUrl).origin) return true;
+    if (['data:', 'blob:'].includes(u.protocol)) return true;
+    const host = u.hostname.replace(/\.+$/, '').replace(/^\[|\]$/g, '');
+    if (isIP(host)) return isPublicAddress(host);
+    // Bound DNS latency; lookup itself is OS-owned and may finish after timeout.
+    let timer;
+    try {
+      const addresses = await Promise.race([
+        resolver(host, { all:true, verbatim:true }),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('DNS timeout')), 3000); }),
+      ]);
+      return addresses.length > 0 && addresses.every(({address}) => isPublicAddress(address));
+    } finally { clearTimeout(timer); }
+  } catch { return false; }
+}
+
+// Playwright's continue() follows redirects without routing each hop. Fetch
+// without following redirects and never fulfill a 3xx response into Chromium.
+export async function routeCaptureRequest(route, entryUrl, origins = []) {
+  const r = route.request();
+  try {
+    if (!allowCaptureRequest(r.url(), r.method(), r.resourceType(), entryUrl, origins) || !await allowCaptureDestination(r.url(), entryUrl)) {
+      await route.abort(); return false;
+    }
+    const response = await route.fetch({ maxRedirects:0, timeout:15000 });
+    if (response.status() >= 300 && response.status() < 400) {
+      await response.dispose(); await route.abort(); return false;
+    }
+    await route.fulfill({ response });
+    await response.dispose();
+    return true;
+  } catch { await route.abort().catch(() => {}); return false; }
+}
+
+async function encode(ffmpeg, args) {
+  try { await run(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-nostdin', ...args], { timeout: 90000, maxBuffer: 1024 * 1024, env: { PATH: dirname(ffmpeg), ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}) } }); }
+  catch (e) { throw new Error(`FFmpeg encoding failed (${e.killed ? '90s timeout' : 'check portable encoder installation'}); no global FFmpeg is used`); }
+}
+export async function capturePreview(config) {
+  const { chromium } = await import('playwright');
+  let ffmpeg;
+  try { ffmpeg = (await import('@ffmpeg-installer/ffmpeg')).default.path; await run(ffmpeg, ['-version'], { timeout:10000 }); }
+  catch { throw new Error('Portable FFmpeg missing. Reinstall the CLI with optional dependencies and install scripts enabled (`npm install -g hyperdecks --include=optional`); pnpm users must approve @ffmpeg-installer platform build scripts.'); }
+  let browser, server, temp, deadline, timedOut = false;
+  const warnings = [];
+  try {
+    temp = await mkdtemp(join(tmpdir(), 'hyperdecks-preview-'));
+    try {
+      browser = await chromium.launch({ headless: true, timeout:30000, chromiumSandbox: process.platform === 'linux', args: ['--mute-audio', '--enable-unsafe-swiftshader'], env: { ...(process.platform === 'win32' ? { SystemRoot: process.env.SystemRoot } : {}), PATH: process.env.PATH, TMPDIR: temp, HOME: temp } });
+    } catch { throw new Error(`Could not launch isolated Chromium. ${SETUP}`); }
+    deadline = setTimeout(() => { timedOut = true; browser.close().catch(() => {}); }, 60000);
+    server = await serveSource(config);
+    const context = await browser.newContext({ viewport: { width:1280, height:720 }, deviceScaleFactor:1, serviceWorkers:'block', acceptDownloads:false });
+    let blocked = 0, failed = 0;
+    await context.route('**/*', async route => {
+      if (!await routeCaptureRequest(route, server.url, config.firstPartyOrigins)) blocked++;
+    });
+    await context.routeWebSocket('**/*', ws => ws.close());
+    // Defense in depth for unload beacons and popup attempts. No credentials,
+    // storage state, permission grants or personal profile enter this context.
+    await context.addInitScript(() => {
+      navigator.sendBeacon = () => false;
+      window.open = () => null;
+      const play = HTMLMediaElement.prototype.play;
+      HTMLMediaElement.prototype.play = function() { this.muted = true; return this instanceof HTMLAudioElement ? Promise.resolve() : play.call(this); };
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(15000);
+    page.on('pageerror', () => failed++);
+    page.on('requestfailed', request => { if (request.failure()?.errorText !== 'net::ERR_FAILED') failed++; });
+    await page.goto(server.url, { waitUntil:'domcontentloaded', timeout:30000 });
+    const fontsReady = await page.evaluate(async () => Promise.race([document.fonts.ready.then(() => true), new Promise(ok => setTimeout(() => ok(false), 5000))]));
+    if (!fontsReady) warnings.push('Fonts did not settle within 5s; inspect the poster or increase --delay.');
+    await page.waitForTimeout(config.delay);
+    const detected = await page.evaluate(() => {
+      const meta = document.querySelector('meta[name="preview-aspect-ratio"]')?.getAttribute('content');
+      if (meta && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(meta)) { const [w,h] = meta.split(':').map(Number); return w/h; }
+      const slide = document.querySelector('.slide, [data-slide], canvas');
+      const rect = slide?.getBoundingClientRect();
+      return rect && rect.width > 100 && rect.height > 100 ? rect.width/rect.height : null;
+    });
+    const aspect = config.aspect ?? (detected >= 0.5 && detected <= 3 ? detected : 16/9);
+    if (!config.aspect && !detected) warnings.push('Using 16:9 aspect ratio; use --aspect-ratio W:H or preview-aspect-ratio metadata for a different deck shape.');
+    const width = config.width % 2 ? config.width + 1 : config.width;
+    const height = Math.round(width / aspect / 2) * 2;
+    await page.setViewportSize({ width:1280, height:Math.round(1280/aspect) });
+    await page.evaluate(label => {
+      const badge = document.createElement('div');
+      badge.textContent = '▶  ' + label;
+      badge.setAttribute('style', 'all:initial;position:fixed;bottom:28px;left:50%;transform:translateX(-50%);background:rgba(0,0,0,.85);color:white;font:600 25px sans-serif;padding:14px 24px;border-radius:40px;z-index:2147483647;white-space:nowrap;max-width:90%;overflow:hidden;text-overflow:ellipsis;pointer-events:none');
+      document.documentElement.appendChild(badge);
+    }, config.label);
+    const fps = 10, frames = Math.round(config.duration * fps), duration = frames/fps;
+    // Screenshots capture the live WebGL compositor and CSS motion without
+    // starting a deck narration tour or waiting forever on looped media.
+    for (let i = 0; i < frames; i++) {
+      const start = Date.now();
+      await page.screenshot({ path: join(temp, `frame-${String(i).padStart(4,'0')}.png`), timeout:10000 });
+      if (i < frames-1) await page.waitForTimeout(Math.max(0, 1000/fps - (Date.now()-start)));
+    }
+    await context.close();
+    clearTimeout(deadline);
+    const input = ['-framerate', String(fps), '-i', join(temp, 'frame-%04d.png')];
+    const paths = Object.fromEntries(['png','gif','mp4'].map(t => [t, resolve(config.out, `preview.${t}`)]));
+    await encode(ffmpeg, ['-i', join(temp,'frame-0000.png'), '-vf', `scale=${width}:${height}`, '-frames:v','1', paths.png]);
+    await encode(ffmpeg, [...input, '-filter_complex', `scale=${width}:${height}:flags=lanczos,split[a][b];[a]palettegen[p];[b][p]paletteuse`, '-loop','0', paths.gif]);
+    await encode(ffmpeg, [...input, '-vf',`scale=${width}:${height}`, '-an','-c:v','libx264','-pix_fmt','yuv420p','-movflags','+faststart',paths.mp4]);
+    if (blocked) warnings.push(`${blocked} navigation/telemetry/unsafe request(s) blocked; no recipient page was visited.`);
+    if (failed) warnings.push(`${failed} page/resource error(s); inspect the poster and increase --delay if necessary.`);
+    const files = await Promise.all(['gif','png','mp4'].map(async type => ({ type, path: paths[type], contentType: type === 'mp4' ? 'video/mp4' : `image/${type}`, bytes: (await stat(paths[type])).size, width, height, ...(type === 'png' ? {} : { duration, fps, silent:true, ...(type === 'gif' ? { loop:0 } : {}) }) })));
+    return { files, warnings };
+  } catch (e) { throw new Error(`Capture failed: ${timedOut ? '60s capture timeout; the renderer did not respond' : /Timeout/i.test(e.name) ? 'bounded capture timeout; inspect the deck or increase --delay' : e.message}`); }
+  finally {
+    clearTimeout(deadline);
+    if (browser) await browser.close().catch(() => {});
+    if (server) await server.close();
+    if (temp) await rm(temp, { recursive:true, force:true });
+  }
+}

package/src/preview.mjs

@@ -0,0 +1,117 @@
+import { mkdir, readFile, writeFile, stat } from "node:fs/promises";
+import { resolve, extname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { api, client, target, uploadBytes } from "./runtime.mjs";
+
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+export function httpUrl(value) {
+  const u = new URL(value);
+  if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password) throw new Error("Expected an HTTP(S) URL without credentials");
+  return value;
+}
+function bounded(value, fallback, min, max, name, integer = false) {
+  const n = value === undefined ? fallback : Number(value);
+  if (value === '' || !Number.isFinite(n) || n < min || n > max || (integer && !Number.isInteger(n))) throw new Error(`${name} must be ${integer ? 'an integer ' : ''}between ${min} and ${max}`);
+  return n;
+}
+export function previewOptions(pos, opts) {
+  const allowed = new Set(['file', 'out', 'duration', 'width', 'delay', 'label', 'aspect-ratio', 'share', 'upload', 'json', 'prod', 'dev', 'admin', 'broker', 'convex', 'token', 'client']);
+  for (const k of Object.keys(opts)) if (!allowed.has(k)) throw new Error(`Unknown preview option --${k}`);
+  for (const [k, v] of Object.entries(opts)) if (v === undefined) throw new Error(`--${k} requires a value`);
+  if (pos.length > 1 || (opts.file ? pos.length !== 0 : pos.length !== 1)) throw new Error("usage: preview create <slug> --out <new-directory> OR preview create --file <index.html> --out <new-directory>");
+  if (!opts.out || typeof opts.out !== 'string') throw new Error('--out <new-directory> is required');
+  if (opts.file && (opts.upload || opts.share)) throw new Error('Local-file capture is export-only; use an owned deck slug for --share/--upload');
+  if (opts.upload && !opts.share) throw new Error('--upload requires --share <existing-token>');
+  if (pos[0] && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,199}$/.test(pos[0])) throw new Error('Invalid deck slug');
+  if (opts.share !== undefined && !/^[a-zA-Z0-9_-]{1,200}$/.test(opts.share)) throw new Error('Invalid share token');
+  if (opts.file && !['.html', '.htm'].includes(extname(opts.file).toLowerCase())) throw new Error('--file must be an HTML file');
+  const label = opts.label ?? 'Watch presentation';
+  if (typeof label !== 'string' || !label.trim() || label.length > 120 || /[\x00-\x1f]/.test(label)) throw new Error('--label must be 1–120 printable characters');
+  let aspect;
+  if (opts['aspect-ratio'] !== undefined) {
+    const m = /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/.exec(opts['aspect-ratio']);
+    aspect = m ? Number(m[1]) / Number(m[2]) : NaN;
+    bounded(aspect, null, 0.5, 3, '--aspect-ratio');
+  }
+  return { slug: pos[0], file: opts.file && resolve(opts.file), out: resolve(opts.out), duration: bounded(opts.duration, 4, 1, 10, '--duration'), width: bounded(opts.width, 600, 240, 1200, '--width', true), delay: bounded(opts.delay, 1000, 0, 10000, '--delay', true), aspect, label };
+}
+export function validateShare(rows, slug, token, now = Date.now()) {
+  const row = rows.find(s => s.token === token && s.deckSlug === slug);
+  if (!row || row.enabled !== true || (row.expiresAt != null && row.expiresAt <= now) || (row.viewLimit != null && row.opens >= row.viewLimit)) throw new Error('Share is missing, mismatched, disabled, expired, or at its open limit; select another existing share');
+  return row;
+}
+export function emailHtml(image, url, label, width, height) {
+  httpUrl(image); httpUrl(url);
+  return `<a href="${escapeHtml(url)}" target="_blank"><img src="${escapeHtml(image)}" alt="${escapeHtml(label)}" width="${width}" height="${height}" style="display:block;max-width:100%;height:auto;border:0"></a>`;
+}
+
+// Capture is injected by tests; production loads the browser/encoder only here.
+export async function createPreview(pos, opts, adapters = {}) {
+  const config = previewOptions(pos, opts);
+  let c, deck, html, shareUrl = null;
+  const warnings = [];
+  if (config.file) {
+    if (!(await stat(config.file)).isFile()) throw new Error('--file must be a regular HTML file');
+  } else {
+    c = await client(opts);
+    deck = await c.query(api.previews.get, { slug: config.slug });
+    if (opts.share) {
+      if (deck.status === 'archived') throw new Error('Archived deck cannot provide a sendable share preview');
+      validateShare(await c.query(api.shares.listForDeck, { deckSlug: config.slug }), config.slug, opts.share);
+      shareUrl = httpUrl(`${target(opts).shareBase}/v/${opts.share}`);
+    }
+    html = deck.html;
+    if (!html && deck.htmlUrl) {
+      const res = await (adapters.fetch || fetch)(httpUrl(deck.htmlUrl), { signal: AbortSignal.timeout(30000), redirect: 'error' });
+      if (!res.ok) throw new Error(`Could not read stored HTML (${res.status})`);
+      html = await res.text();
+    }
+    if (!html) throw new Error('Deck has no HTML to capture');
+  }
+  // A new directory prevents replacing artifacts referenced by an earlier manifest.
+  await mkdir(config.out, { recursive: false });
+  const manifestPath = resolve(config.out, 'manifest.json');
+  const result = { version: 1, status: 'capturing', source: config.file ? { file: config.file } : { slug: config.slug, title: deck.title }, shareUrl, manifestPath, files: [], email: { sendable: false, path: null, html: null }, warnings };
+  const save = () => writeFile(manifestPath, JSON.stringify(result, null, 2) + '\n');
+  await save();
+  try {
+    const capture = adapters.capture || (await import('./preview-capture.mjs')).capturePreview;
+    const captured = await capture({ ...config, html, firstPartyOrigins: [targetForCapture(opts), 'https://decks.hypersocial.ai', 'https://dashing-snail-874.convex.cloud'] });
+    result.files = captured.files;
+    warnings.push(...captured.warnings);
+    for (const f of result.files) if (f.bytes > 5 * 1024 * 1024) warnings.push(`${f.type} exceeds 5 MiB; shorten --duration or reduce --width for email`);
+    result.status = 'exported';
+    await save();
+    if (opts.upload) {
+      // Recheck after potentially slow capture and before any upload side effect.
+      validateShare(await c.query(api.shares.listForDeck, { deckSlug: config.slug }), config.slug, opts.share);
+      const id = randomUUID();
+      for (const f of result.files) {
+        const name = `preview-${id}-${f.type}`;
+        const storageId = await (adapters.uploadBytes || uploadBytes)(c, await readFile(f.path), f.contentType);
+        f.upload = { name, storageId, saved: false };
+        await save();
+        const saved = await c.mutation(api.assets.saveAsset, { name, storageId, contentType: f.contentType, deckSlug: config.slug });
+        f.upload.saved = true;
+        f.url = httpUrl(saved.url);
+        await save();
+      }
+      const gif = result.files.find(f => f.type === 'gif');
+      result.email = { sendable: true, path: resolve(config.out, 'email.html'), html: emailHtml(gif.url, shareUrl, config.label, gif.width, gif.height) };
+      await writeFile(result.email.path, result.email.html + '\n', { flag: 'wx' });
+      result.status = 'uploaded';
+    } else warnings.push('Local export: insert GIF/PNG into an email client manually. No sendable remote-image HTML exists until explicit upload with an existing share.');
+    await save();
+    return result;
+  } catch (e) {
+    result.status = 'failed';
+    // Do not persist raw HTTP/broker errors which may contain signed URLs or tokens.
+    result.error = 'Preview failed; local artifacts and any recorded partial uploads are preserved.';
+    await save();
+    throw new Error(`Preview failed. Artifacts and partial upload records: ${manifestPath}. ${e.message}`);
+  }
+}
+function targetForCapture(opts) {
+  // Offline local-file capture must not require deployment configuration/login.
+  return opts.file ? 'https://decks.hypersocial.ai' : target(opts).brokerBase;
+}

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.1.9";
+export const VERSION = "0.1.11";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -19,6 +19,7 @@ export const PROD = {
 };
 
 export const api = {
+  previews: { get: makeFunctionReference("previews:get") },
   assets: {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
@@ -44,14 +45,19 @@ export const api = {
     listForDeck: makeFunctionReference("shares:listForDeck"),
     remove: makeFunctionReference("shares:remove"),
     setEnabled: makeFunctionReference("shares:setEnabled"),
+    setNotify: makeFunctionReference("shares:setNotify"),
   },
   imagegen: {
     generateImage: makeFunctionReference("imagegen:generateImage"),
     checkImageJob: makeFunctionReference("imagegen:checkImageJob"),
   },
+  credits: {
+    getBalance: makeFunctionReference("credits:getBalance"),
+    getLedger: makeFunctionReference("credits:getLedger"),
+  },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "help", "version", "all-agents", "global", "project", "transparent"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload"]);
 
 export const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
 export const CRED_FILE = join(CRED_DIR, "credentials.json");