@hypersocial/decks-cli 0.1.6 → 0.1.9

package/README.md

@@ -16,6 +16,7 @@ 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
 ```
 
@@ -61,6 +62,7 @@ share rm <token>
 share url <token>
 
 recipient archive|unarchive <name>
+import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live|archived]
 skills install [--agent codex,claude-code] [--all-agents]
 activity [--deck <slug>] [--limit <n>] [--json]
 ```
@@ -79,3 +81,37 @@ HSDECKS_PROD=0 HSDECKS_CONVEX_URL=https://your-dev.convex.cloud HSDECKS_BROKER_B
 
 Legacy unauthenticated dev access is available with `--admin` or
 `HSDECKS_ADMIN=1`. It is rejected for production.
+
+## Claude Design Imports
+
+Export a Claude Design project as standalone HTML or a ZIP, then import it into
+Hyperdecks:
+
+```bash
+# From a local export…
+decks import ./claude-design-export.zip --slug acme-pitch --title "Acme Pitch"
+# …or directly from a downloadable export URL (no local file needed):
+decks import https://example.com/claude-design-export.zip --slug acme-pitch
+decks share new acme-pitch "Jane at Acme" --email jane@acme.com
+```
+
+The import command uploads bundled assets, rewrites local asset references, and
+stores large generated HTML in Convex file storage so it can be sent through
+per-recipient share links with analytics.
+
+The URL form must point at the **downloadable export bytes** (a ZIP or standalone
+HTML). A `claude.ai/design/p/...` project page is not importable on its own — use
+the project's Export/Download to get a direct URL or a local ZIP. Only `http(s)`
+is allowed and loopback/private hosts are refused.
+
+### MCP
+
+The same import is exposed to agents via the `hypersocial-decks` MCP server as the
+`import_deck_from_url` tool:
+
+```jsonc
+// import_deck_from_url
+{ "url": "https://example.com/claude-design-export.zip", "slug": "acme-pitch", "status": "draft" }
+```
+
+It authenticates with the stored CLI credential — run `decks login --prod` first.

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",
   "exports": {
     ".": "./src/commands.mjs",
     "./commands": "./src/commands.mjs",
+    "./importer": "./src/importer.mjs",
     "./ops": "./src/ops.mjs",
     "./runtime": "./src/runtime.mjs",
     "./src/commands.mjs": "./src/commands.mjs",
+    "./src/importer.mjs": "./src/importer.mjs",
     "./src/ops.mjs": "./src/ops.mjs",
     "./src/runtime.mjs": "./src/runtime.mjs",
     "./package.json": "./package.json"
@@ -28,7 +30,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "convex": "^1.41.0"
+    "convex": "^1.41.0",
+    "fflate": "^0.8.2"
   },
   "publishConfig": {
     "access": "public"

package/src/commands.mjs

@@ -1,4 +1,13 @@
-import { installHyperdecksSkill, login, logout, openBrowser, parse, target, VERSION } from "./runtime.mjs";
+import { readFileSync, writeFileSync } from "node:fs";
+import {
+  installHyperdecksSkill,
+  login,
+  logout,
+  openBrowser,
+  parse,
+  target,
+  VERSION,
+} from "./runtime.mjs";
 import * as ops from "./ops.mjs";
 
 const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
@@ -61,6 +70,13 @@ function deckOpen(pos, opts) {
   openBrowser(url);
 }
 
+async function deckRemove(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: deck rm <slug>");
+  await ops.removeDeck(opts, slug);
+  console.log(`OK removed deck ${slug}`);
+}
+
 function shareBase(opts) {
   return target(opts).shareBase;
 }
@@ -145,6 +161,57 @@ async function activity(pos, opts) {
   }
 }
 
+async function importDeck(pos, opts) {
+  const [src] = pos;
+  if (!src) {
+    throw new Error("usage: import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live]");
+  }
+  const fields = {
+    slug: opts.slug,
+    title: opts.title,
+    status: opts.status,
+    htmlFile: opts["html-file"],
+  };
+  // Shared import core lives in ops.mjs (so the MCP server runs the exact same
+  // path). A URL source streams server-side; a path reads bytes off disk.
+  const out = /^https?:\/\//i.test(src)
+    ? await ops.importDeckFromUrl(opts, { ...fields, url: src })
+    : await ops.importDeckFromBytes(opts, { ...fields, bytes: readFileSync(src), filename: src });
+
+  if (opts.json) console.log(JSON.stringify(out, null, 2));
+  else {
+    console.log(`OK imported "${out.title}" as ${out.slug}`);
+    console.log(`  assets: ${out.assets}`);
+    console.log(`  html:   ${(out.bytes / 1024).toFixed(1)} KB`);
+    console.log(`  deck:   ${out.deckUrl}`);
+  }
+}
+
+async function importDesignDeck(pos, opts) {
+  const [project] = pos;
+  if (!project) {
+    throw new Error("usage: import-design <project-id> --serve-token <token> --entry <file.html> --slug <slug>");
+  }
+  const out = await ops.importDeckFromDesign(opts, {
+    project,
+    token: opts["serve-token"],
+    entry: opts.entry,
+    slug: opts.slug,
+    title: opts.title,
+    status: opts.status,
+  });
+  if (opts.json) console.log(JSON.stringify(out, null, 2));
+  else {
+    console.log(`OK imported "${out.title}" as ${out.slug}`);
+    console.log(`  fetched: ${out.fetched} files, ${out.assets} assets`);
+    console.log(`  html:    ${(out.bytes / 1024).toFixed(1)} KB`);
+    if (out.missing?.length) {
+      console.log(`  missing: ${out.missing.length} (${out.missing.slice(0, 5).join(", ")}${out.missing.length > 5 ? ", …" : ""})`);
+    }
+    console.log(`  deck:    ${out.deckUrl}`);
+  }
+}
+
 export function help() {
   console.log(`decks ${VERSION}
 
@@ -152,12 +219,16 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open
+  deck list|stats|open|rm
   share new|list|on|off|rm|url
   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>
   skill install [--agent codex,claude-code] [--all-agents]
   skills install [--agent codex,claude-code] [--all-agents]
   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]
 
 global:
   --json
@@ -168,6 +239,65 @@ global:
 `);
 }
 
+async function genImage(pos, opts) {
+  const prompt = pos.join(" ").trim() || opts.prompt;
+  if (!prompt) {
+    throw new Error(
+      'usage: gen-image "<prompt>" [--image <url>] [--transparent] [--size <s>] [--quality <q>] [--count <n>] [--format png|jpeg|webp] [--slug <deck>] [--name <name>] [--download <file>]',
+    );
+  }
+  let out = await ops.generateImage(opts, {
+    prompt,
+    image: opts.image,
+    transparent: opts.transparent,
+    size: opts.size,
+    quality: opts.quality,
+    count: opts.count,
+    format: opts.format,
+    slug: opts.slug,
+    name: opts.name,
+  });
+  // Slow requests (high/auto quality, transparent, count>1) come back as a job id;
+  // poll it so gen-image stays one blocking command. Progress prints to stderr so
+  // it doesn't pollute the URL output (or --json).
+  if (out.jobId) {
+    process.stderr.write(`queued ${out.count} image(s) — job ${out.jobId}\n`);
+    out = await ops.pollImageJob(opts, out.jobId, {
+      onProgress: (job) => process.stderr.write(`  ${job.progress} (${job.status})…\r`),
+    });
+    process.stderr.write("\n");
+  }
+  const images = out.images || [];
+  if (opts.download && images.length) {
+    for (let i = 0; i < images.length; i++) {
+      if (!images[i].url) continue;
+      const file = images.length > 1 ? opts.download.replace(/(\.[^./]+)?$/, `-${i + 1}$1`) : opts.download;
+      const res = await fetch(images[i].url);
+      writeFileSync(file, Buffer.from(await res.arrayBuffer()));
+    }
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(out, null, 2));
+  } else {
+    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}`);
+  }
+}
+
+async function imageJob(pos, opts) {
+  const [jobId] = pos;
+  if (!jobId) throw new Error("usage: image-job <jobId>");
+  const job = await ops.checkImageJob(opts, jobId);
+  if (opts.json) {
+    console.log(JSON.stringify(job, null, 2));
+    return;
+  }
+  console.log(`status:   ${job.status}`);
+  console.log(`progress: ${job.progress}`);
+  if (job.error) console.log(`error:    ${job.error}`);
+  for (const im of job.results || []) if (im.url) console.log(im.url);
+}
+
 export async function runCli(argv = process.argv.slice(2)) {
   const { pos, opts } = parse(argv);
   if (opts.version) {
@@ -188,6 +318,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     "deck list": () => deckList(opts),
     "deck stats": () => deckStats(rest, opts),
     "deck open": () => deckOpen(rest, opts),
+    "deck rm": () => deckRemove(rest, opts),
     "share new": () => shareNew(rest, opts),
     "share list": () => shareList(rest, opts),
     "share on": () => shareToggle(rest, opts, true),
@@ -196,9 +327,13 @@ export async function runCli(argv = process.argv.slice(2)) {
     "share url": () => shareUrl(rest, opts),
     "recipient archive": () => recipientArchive(rest, opts, true),
     "recipient unarchive": () => recipientArchive(rest, opts, false),
+    import: () => importDeck(pos.slice(1), opts),
+    "import-design": () => importDesignDeck(pos.slice(1), opts),
     "skill install": () => installHyperdecksSkill(opts, rest),
     "skills install": () => installHyperdecksSkill(opts, rest),
     activity: () => activity(pos.slice(1), opts),
+    "gen-image": () => genImage(pos.slice(1), opts),
+    "image-job": () => imageJob(pos.slice(1), opts),
   };
 
   const handler = handlers[`${group} ${cmd}`] || handlers[group];

package/src/importer.mjs

@@ -0,0 +1,330 @@
+import { strFromU8, strToU8, unzipSync } from "fflate";
+
+const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04];
+const TEXT_TYPES = new Set([
+  "text/css",
+  "application/javascript",
+  "text/javascript",
+  "application/json",
+  "image/svg+xml",
+]);
+
+export function slugify(input) {
+  return String(input || "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 72);
+}
+
+export function titleFromFilename(filename) {
+  const base = basename(filename).replace(/\.(html?|zip)$/i, "");
+  return base
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/\b\w/g, (m) => m.toUpperCase());
+}
+
+export function inferContentType(path) {
+  const ext = path.toLowerCase().split(".").pop() || "";
+  switch (ext) {
+    case "html":
+    case "htm":
+      return "text/html; charset=utf-8";
+    case "css":
+      return "text/css";
+    case "js":
+    case "mjs":
+      return "application/javascript";
+    case "json":
+      return "application/json";
+    case "png":
+      return "image/png";
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "gif":
+      return "image/gif";
+    case "webp":
+      return "image/webp";
+    case "svg":
+      return "image/svg+xml";
+    case "ico":
+      return "image/x-icon";
+    case "mp4":
+      return "video/mp4";
+    case "webm":
+      return "video/webm";
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "woff":
+      return "font/woff";
+    case "woff2":
+      return "font/woff2";
+    case "ttf":
+      return "font/ttf";
+    case "otf":
+      return "font/otf";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+export function bytesFromText(text) {
+  return strToU8(text);
+}
+
+export function textFromBytes(bytes) {
+  return strFromU8(bytes);
+}
+
+export function prepareDeckImport({ bytes, filename = "deck.html", htmlFile } = {}) {
+  if (!bytes) throw new Error("missing file bytes");
+  const input = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  const isZip = /\.zip$/i.test(filename) || ZIP_MAGIC.every((b, i) => input[i] === b);
+  if (!isZip) {
+    const html = textFromBytes(input);
+    return {
+      html,
+      htmlEntry: normalizePath(filename),
+      title: titleFromHtml(html) || titleFromFilename(filename),
+      assets: [],
+      warnings: [],
+    };
+  }
+
+  const unzipped = unzipSync(input);
+  const files = Object.entries(unzipped)
+    .map(([path, data]) => ({ path: normalizePath(path), data }))
+    .filter((f) => isUsableArchiveFile(f.path));
+  const htmlEntry = chooseHtmlEntry(files.map((f) => f.path), htmlFile);
+  if (!htmlEntry) throw new Error("zip does not contain an HTML file");
+
+  const htmlFileRow = files.find((f) => f.path === htmlEntry);
+  if (!htmlFileRow) throw new Error(`HTML file not found: ${htmlEntry}`);
+  const html = textFromBytes(htmlFileRow.data);
+  const baseDir = dirname(htmlEntry);
+  const seenNames = new Set();
+  const assets = files
+    .filter((f) => f.path !== htmlEntry && !/\.html?$/i.test(f.path))
+    .map((f) => {
+      const relative = stripBaseDir(f.path, baseDir);
+      const name = uniqueAssetName(relative || basename(f.path), seenNames);
+      return {
+        sourcePath: f.path,
+        relativePath: relative,
+        name,
+        contentType: inferContentType(f.path),
+        data: f.data,
+      };
+    });
+
+  return {
+    html,
+    htmlEntry,
+    title: titleFromHtml(html) || titleFromFilename(filename),
+    assets,
+    warnings: [],
+  };
+}
+
+export function buildAssetUrlMap(assets, uploadedByName, fromSourcePath) {
+  const map = new Map();
+  for (const asset of assets) {
+    const url = uploadedByName.get(asset.name);
+    if (!url) continue;
+    for (const key of candidateKeys(asset, fromSourcePath)) {
+      if (key) map.set(key, url);
+    }
+  }
+  return map;
+}
+
+export function rewriteCssAssetUrls(css, cssSourcePath, assets, uploadedByName) {
+  const assetMap = buildAssetUrlMap(assets, uploadedByName, cssSourcePath);
+  return rewriteTextRefs(rewriteCssUrls(css, assetMap), assetMap);
+}
+
+export function rewriteTextAssetUrls(text, sourcePath, assets, uploadedByName) {
+  const assetMap = buildAssetUrlMap(assets, uploadedByName, sourcePath);
+  return rewriteTextRefs(rewriteCssUrls(text, assetMap), assetMap);
+}
+
+export function rewriteHtmlAssetUrls(html, htmlEntry, assets, uploadedByName) {
+  const assetMap = buildAssetUrlMap(assets, uploadedByName, htmlEntry);
+  let out = html.replace(
+    /\b(src|href|poster)\s*=\s*(["'])([^"']+)\2/gi,
+    (match, attr, quote, raw) => {
+      const url = resolveLocalUrl(raw, assetMap);
+      return url ? `${attr}=${quote}${url}${quote}` : match;
+    },
+  );
+  out = out.replace(/\bsrcset\s*=\s*(["'])([^"']+)\1/gi, (match, quote, raw) => {
+    const rewritten = raw
+      .split(",")
+      .map((part) => {
+        const trimmed = part.trim();
+        if (!trimmed) return trimmed;
+        const [urlPart, ...descriptor] = trimmed.split(/\s+/);
+        const url = resolveLocalUrl(urlPart, assetMap) || urlPart;
+        return [url, ...descriptor].join(" ");
+      })
+      .join(", ");
+    return `srcset=${quote}${rewritten}${quote}`;
+  });
+  return rewriteTextRefs(rewriteCssUrls(out, assetMap), assetMap);
+}
+
+export function isTextAsset(asset) {
+  const type = String(asset.contentType || "").split(";")[0].trim().toLowerCase();
+  return type.startsWith("text/") || TEXT_TYPES.has(type);
+}
+
+function titleFromHtml(html) {
+  return html.match(/<title[^>]*>([^<]+)<\/title>/i)?.[1]?.trim() || "";
+}
+
+function chooseHtmlEntry(paths, requested) {
+  const normalized = requested ? normalizePath(requested) : "";
+  if (normalized && paths.includes(normalized)) return normalized;
+  const htmls = paths.filter((p) => /\.html?$/i.test(p));
+  const index = htmls
+    .filter((p) => /(^|\/)index\.html?$/i.test(p))
+    .sort((a, b) => pathDepth(a) - pathDepth(b) || a.length - b.length)[0];
+  return index || htmls.sort((a, b) => pathDepth(a) - pathDepth(b) || a.localeCompare(b))[0] || "";
+}
+
+function rewriteCssUrls(input, assetMap) {
+  return input.replace(/url\(\s*(["']?)([^"')]+)\1\s*\)/gi, (match, quote, raw) => {
+    const url = resolveLocalUrl(raw, assetMap);
+    return url ? `url(${quote}${url}${quote})` : match;
+  });
+}
+
+function rewriteTextRefs(input, assetMap) {
+  return rewriteEscapedTextRefs(input, assetMap).replace(/(["'`])([^"'`]+)\1/g, (match, quote, raw) => {
+    if (quote === "`" && raw.includes("${")) return match;
+    const url = resolveLocalUrl(raw, assetMap);
+    return url ? `${quote}${url}${quote}` : match;
+  });
+}
+
+function rewriteEscapedTextRefs(input, assetMap) {
+  return input.replace(/\\(["'])([^"'`]*?)\\\1/g, (match, quote, raw) => {
+    const unescapedRaw = raw.replace(/\\\//g, "/");
+    const url = resolveLocalUrl(unescapedRaw, assetMap);
+    return url ? `\\${quote}${url}\\${quote}` : match;
+  });
+}
+
+function resolveLocalUrl(raw, assetMap) {
+  const value = String(raw || "").trim();
+  if (!value || isExternalOrSpecial(value)) return "";
+  const clean = normalizeRefPath(value);
+  return assetMap.get(clean) || assetMap.get(clean.replace(/^\//, "")) || fallbackLocalUrl(clean);
+}
+
+function fallbackLocalUrl(clean) {
+  return clean === ".image-slots.state.json" ? "data:application/json,%7B%7D" : "";
+}
+
+function isExternalOrSpecial(value) {
+  return (
+    value.startsWith("#") ||
+    value.startsWith("//") ||
+    value.startsWith("data:") ||
+    value.startsWith("blob:") ||
+    value.startsWith("mailto:") ||
+    value.startsWith("tel:") ||
+    value.startsWith("javascript:") ||
+    /^[a-z][a-z0-9+.-]*:\/\//i.test(value)
+  );
+}
+
+function candidateKeys(asset, fromSourcePath) {
+  const fromDir = dirname(fromSourcePath || "");
+  return [
+    asset.sourcePath,
+    asset.relativePath,
+    asset.name,
+    `/${asset.relativePath}`,
+    `/${asset.name}`,
+    normalizePath(relativePath(fromDir, asset.sourcePath)),
+    basename(asset.sourcePath),
+  ].map(normalizePath);
+}
+
+function normalizeRefPath(value) {
+  const withoutHash = value.split("#")[0];
+  const withoutQuery = withoutHash.split("?")[0];
+  try {
+    return normalizePath(decodeURIComponent(withoutQuery));
+  } catch {
+    return normalizePath(withoutQuery);
+  }
+}
+
+function normalizePath(path) {
+  return String(path || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.?\//, "")
+    .replace(/\/+/g, "/");
+}
+
+function isUsableArchiveFile(path) {
+  if (!path || path.endsWith("/")) return false;
+  if (path.includes("__MACOSX/")) return false;
+  if (basename(path) === ".DS_Store") return false;
+  return true;
+}
+
+function stripBaseDir(path, baseDir) {
+  if (!baseDir) return path;
+  return path.startsWith(`${baseDir}/`) ? path.slice(baseDir.length + 1) : path;
+}
+
+function uniqueAssetName(name, seen) {
+  const clean = normalizePath(name).replace(/^\/+/, "") || "asset";
+  if (!seen.has(clean)) {
+    seen.add(clean);
+    return clean;
+  }
+  const dot = clean.lastIndexOf(".");
+  const stem = dot === -1 ? clean : clean.slice(0, dot);
+  const ext = dot === -1 ? "" : clean.slice(dot);
+  let i = 2;
+  while (seen.has(`${stem}-${i}${ext}`)) i++;
+  const out = `${stem}-${i}${ext}`;
+  seen.add(out);
+  return out;
+}
+
+function dirname(path) {
+  const clean = normalizePath(path);
+  const i = clean.lastIndexOf("/");
+  return i === -1 ? "" : clean.slice(0, i);
+}
+
+function basename(path) {
+  const clean = normalizePath(path);
+  return clean.slice(clean.lastIndexOf("/") + 1);
+}
+
+function pathDepth(path) {
+  return normalizePath(path).split("/").filter(Boolean).length;
+}
+
+function relativePath(fromDir, toPath) {
+  const from = normalizePath(fromDir).split("/").filter(Boolean);
+  const to = normalizePath(toPath).split("/").filter(Boolean);
+  while (from.length && to.length && from[0] === to[0]) {
+    from.shift();
+    to.shift();
+  }
+  return `${"../".repeat(from.length)}${to.join("/")}`;
+}

package/src/ops.mjs

@@ -1,4 +1,16 @@
-import { api, client } from "./runtime.mjs";
+import { zipSync } from "fflate";
+import { api, client, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
+import {
+  bytesFromText,
+  isTextAsset,
+  prepareDeckImport,
+  rewriteCssAssetUrls,
+  rewriteHtmlAssetUrls,
+  rewriteTextAssetUrls,
+  slugify,
+  textFromBytes,
+  titleFromFilename,
+} from "./importer.mjs";
 
 export async function whoami(opts = {}) {
   return (await client(opts)).query(api.decks.whoami, {});
@@ -11,7 +23,7 @@ export async function listDecks(opts = {}) {
     title: d.title,
     status: d.status,
     ownerEmail: d.ownerEmail ?? null,
-    hasHtml: !!d.html,
+    hasHtml: !!(d.html || d.htmlStorageId || d.hasHtml),
   }));
 }
 
@@ -24,6 +36,56 @@ export async function activityOverview(opts = {}) {
   return (await client(opts)).query(api.activity.overview, {});
 }
 
+// Generate an image via fal (GPT Image 2 t2i/i2i, optional BiRefNet transparency),
+// store it in Convex, and return the hosted URL. Runs the imagegen action as the
+// authenticated user (injected client supported via opts.client).
+export async function generateImage(opts, fields = {}) {
+  if (!fields.prompt) throw new Error("prompt is required");
+  const args = { prompt: String(fields.prompt) };
+  const img = fields.image || fields.imageUrl;
+  if (img) args.imageUrl = String(img);
+  if (fields.transparent) args.transparent = true;
+  if (fields.slug) args.slug = String(fields.slug);
+  if (fields.name) args.name = String(fields.name);
+  if (fields.size) args.size = String(fields.size);
+  if (fields.quality) args.quality = String(fields.quality);
+  if (fields.count != null && fields.count !== "") args.count = Number(fields.count);
+  if (fields.format) args.format = String(fields.format);
+  // Returns { images } for fast requests, or { jobId, status, count } for slow ones
+  // (high/auto quality, transparent, count>1). The MCP tool returns this as-is so it
+  // never blocks; the CLI polls with pollImageJob to stay one-command (see commands).
+  return (await client(opts)).action(api.imagegen.generateImage, args);
+}
+
+// Read one async image job's status/results. Shared by the MCP check_image_job tool
+// and the CLI poller.
+export async function checkImageJob(opts, jobId) {
+  if (!jobId) throw new Error("jobId is required");
+  return (await client(opts)).query(api.imagegen.checkImageJob, { jobId: String(jobId) });
+}
+
+// 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
+// a single blocking command even when it routes to a background job.
+export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs = 900_000, onProgress } = {}) {
+  const c = await client(opts);
+  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 === "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".
+      const ok = (job.results || []).filter((r) => r.url).length;
+      throw new Error(`${job.error || "image job failed"}${ok ? ` (${ok} image(s) completed before the failure)` : ""}`);
+    }
+    if (Date.now() - start > timeoutMs) throw new Error(`image job ${jobId} timed out after ${Math.round(timeoutMs / 1000)}s`);
+    if (onProgress) onProgress(job);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+
 export async function listShares(opts, slug) {
   if (!slug) throw new Error("slug is required");
   const rows = await (await client(opts)).query(api.shares.listForDeck, { deckSlug: slug });
@@ -73,8 +135,387 @@ export async function removeShare(opts, token) {
   return { token, removed: true };
 }
 
+export async function removeDeck(opts, slug) {
+  if (!slug) throw new Error("slug is required");
+  // Cascade delete (deck + its assets/shares/sessions + stored HTML) runs in
+  // decks:remove; this just authorizes as the owner and fires it.
+  await (await client(opts)).mutation(api.decks.remove, { slug });
+  return { slug, removed: true };
+}
+
 export async function setRecipientArchived(opts, recipient, archived) {
   if (!recipient) throw new Error("recipient is required");
   await (await client(opts)).mutation(api.activity.setArchived, { recipient, archived });
   return { recipient, archived: !!archived };
 }
+
+// ── Deck import ─────────────────────────────────────────────────────────────
+// IMPORTANT: `app/api/decks/import/route.js` implements the SAME pipeline for the
+// dashboard's browser/multipart path (Clerk session client + per-asset progress
+// logging). The two are intentionally NOT yet merged: importing this module into
+// the Next route would pull the whole CLI runtime (OAuth login flow, node:http
+// server, child_process) into that serverless bundle. `importDeckFromBytes`
+// accepts an `adapter` so a future pass can extract a runtime-free shared core
+// and have both call it. Until then, keep the two pipelines in sync by hand.
+
+const IMPORT_STATUSES = new Set(["draft", "live", "archived"]);
+const DEFAULT_IMPORT_CONCURRENCY = 3;
+const URL_FETCH_TIMEOUT_MS = 120_000;
+
+const deckHasHtml = (deck) => !!(deck?.hasHtml || deck?.html || deck?.htmlUrl || deck?.htmlStorageId);
+
+// Bounded-concurrency map that fails fast and surfaces the first error. Used so a
+// media-heavy import doesn't upload assets one-at-a-time.
+async function mapWithConcurrency(items, limit, worker) {
+  if (!items.length) return;
+  let next = 0;
+  let failure = null;
+  const size = Math.max(1, Math.min(limit || 1, items.length));
+  const runners = Array.from({ length: size }, async () => {
+    while (!failure) {
+      const index = next;
+      next += 1;
+      if (index >= items.length) return;
+      try {
+        await worker(items[index], index);
+      } catch (e) {
+        failure = e;
+      }
+    }
+  });
+  await Promise.all(runners);
+  if (failure) throw failure;
+}
+
+// Import a Claude Design export (ZIP or single HTML) into Hyperdecks: upload its
+// assets to Convex storage, rewrite refs to the stored URLs, store the HTML, and
+// upsert the deck. Rollback is owned here (single layer): a deck created for this
+// import — or an existing record that had no HTML yet — is removed on failure; an
+// existing deck that already had valid HTML is left untouched.
+//
+// `adapter` lets a caller inject its own Convex client / upload helper / progress
+// sink (the dashboard route would pass its Clerk session); defaults use the CLI
+// runtime so CLI + MCP share this exact path.
+export async function importDeckFromBytes(opts = {}, fields = {}, adapter = {}) {
+  const { bytes, filename = "deck.html", htmlFile } = fields;
+  if (!bytes) throw new Error("import needs file bytes");
+
+  const parsed = prepareDeckImport({ bytes, filename, htmlFile });
+
+  // Derive the slug from an explicit slug, else the caller-provided title, else the
+  // document <title>, and only fall back to the filename last — so a deck imported
+  // as "Strudel" becomes /strudel, not /bundled-page (the bundle's generic filename).
+  const slug = slugify(fields.slug || fields.title || parsed.title || titleFromFilename(filename));
+  if (!slug) throw new Error("import needs --slug <slug>");
+  const title = String(fields.title || parsed.title || titleFromFilename(filename) || slug);
+  const status = String(fields.status || "draft");
+  if (!IMPORT_STATUSES.has(status)) {
+    throw new Error("status must be draft, live, or archived");
+  }
+
+  const c = adapter.client || (await client(opts));
+  const upload = adapter.uploadBytes || runtimeUploadBytes;
+  const concurrency = adapter.concurrency || DEFAULT_IMPORT_CONCURRENCY;
+  const onStage = typeof adapter.onStage === "function" ? adapter.onStage : () => {};
+
+  onStage("checking existing deck");
+  const existingDeck = await c.query(api.decks.get, { slug });
+  const shouldRollbackDeck = !existingDeck;
+  const shouldRollbackPartial = !!existingDeck && !deckHasHtml(existingDeck);
+  let deckCreated = false;
+
+  const uploadedByName = new Map();
+  const saveDeckAsset = async (asset, data = asset.data, contentType = asset.contentType) => {
+    const storageId = await upload(c, data, contentType, asset.name);
+    const saved = await c.mutation(api.assets.saveAsset, {
+      name: asset.name,
+      storageId,
+      contentType,
+      deckSlug: slug,
+    });
+    uploadedByName.set(asset.name, saved.url);
+    return saved.url;
+  };
+
+  try {
+    if (shouldRollbackDeck) {
+      onStage("creating deck");
+      // assets:saveAsset checks deck ownership, so the deck must exist first.
+      await c.mutation(api.decks.upsert, { slug, title, status: "draft" });
+      deckCreated = true;
+    }
+
+    // Phase 1: upload every asset and fully populate uploadedByName.
+    await mapWithConcurrency(parsed.assets, concurrency, async (asset, index) => {
+      onStage(`uploading asset ${index + 1}/${parsed.assets.length}: ${asset.name}`);
+      await saveDeckAsset(asset);
+    });
+
+    // Phase 2 (hard barrier after phase 1): rewrite text assets against the now-
+    // complete URL map and re-upload them under the same name. Must not interleave
+    // with phase 1 or refs could resolve against a half-built map.
+    const textAssets = parsed.assets.filter(isTextAsset);
+    await mapWithConcurrency(textAssets, concurrency, async (asset, index) => {
+      onStage(`rewriting asset ${index + 1}/${textAssets.length}: ${asset.name}`);
+      const text = asset.contentType === "text/css"
+        ? rewriteCssAssetUrls(textFromBytes(asset.data), asset.sourcePath, parsed.assets, uploadedByName)
+        : rewriteTextAssetUrls(textFromBytes(asset.data), asset.sourcePath, parsed.assets, uploadedByName);
+      await saveDeckAsset(asset, bytesFromText(text), asset.contentType);
+    });
+
+    onStage("storing deck HTML");
+    const html = rewriteHtmlAssetUrls(parsed.html, parsed.htmlEntry, parsed.assets, uploadedByName);
+    const htmlBytes = bytesFromText(html);
+    const htmlStorageId = await upload(c, htmlBytes, "text/html; charset=utf-8", "deck HTML");
+    onStage("saving deck");
+    await c.mutation(api.decks.upsert, { slug, title, status });
+    onStage("saving deck HTML");
+    await c.mutation(api.decks.setHtmlStorage, { slug, storageId: htmlStorageId, bytes: htmlBytes.byteLength });
+
+    const t = target(opts);
+    return {
+      slug,
+      title,
+      status,
+      assets: parsed.assets.length,
+      bytes: htmlBytes.byteLength,
+      deployment: t.name,
+      // The owner-facing dashboard view (Preview / Stats / Share / Present), not
+      // the raw /d/<slug> storage redirect.
+      deckUrl: `${t.brokerBase}/dashboard/d/${slug}`,
+    };
+  } catch (e) {
+    if ((shouldRollbackDeck && deckCreated) || shouldRollbackPartial) {
+      await c.mutation(api.decks.remove, { slug }).catch(() => {});
+    }
+    throw e;
+  }
+}
+
+// SSRF guard: only http(s), and refuse obvious loopback / private / link-local
+// targets. This blocks literal hosts/IPs; it does NOT resolve DNS, so a public
+// hostname that resolves to a private address is not caught here (documented
+// limitation — acceptable since the fetch runs on the caller's own machine with
+// their credentials).
+function isBlockedHost(host) {
+  if (!host) return true;
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  if (host === "::1") return true;
+  if (host.startsWith("fe80:") || host.startsWith("fc") || host.startsWith("fd")) return true; // link-local + ULA
+  const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$/);
+  if (m) {
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    if (a === 0 || a === 127 || a === 10) return true; // 0/8, loopback, RFC1918 10/8
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16/12
+    if (a === 192 && b === 168) return true; // 192.168/16
+    if (a === 169 && b === 254) return true; // link-local + metadata 169.254.169.254
+  }
+  return false;
+}
+
+function assertImportableUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`invalid url: ${rawUrl}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`url must be http(s); got "${url.protocol.replace(/:$/, "")}"`);
+  }
+  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (isBlockedHost(host)) {
+    throw new Error(`refusing to fetch private/loopback host: ${url.hostname}`);
+  }
+  return url;
+}
+
+function filenameFromResponse(url, res) {
+  const cd = res.headers.get("content-disposition") || "";
+  const m = cd.match(/filename\*?=(?:UTF-8'')?["']?([^"';]+)/i);
+  if (m && m[1]) {
+    try {
+      return decodeURIComponent(m[1].trim());
+    } catch {
+      return m[1].trim();
+    }
+  }
+  const base = url.pathname.split("/").filter(Boolean).pop();
+  if (base && /\.[a-z0-9]+$/i.test(base)) return base;
+  const ct = (res.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+  if (ct.includes("zip")) return "deck.zip";
+  if (ct.includes("html")) return "deck.html";
+  return "deck.zip";
+}
+
+// Fetch a direct Claude Design HTML/ZIP export URL server-side (no 256 KiB /
+// 10 MB caps apply here) and import it via importDeckFromBytes. `adapter` is
+// forwarded so tests can inject a fake client/upload helper.
+export async function importDeckFromUrl(opts = {}, fields = {}, adapter = {}) {
+  if (!fields.url) throw new Error("import needs a url");
+  const url = assertImportableUrl(fields.url);
+
+  let res;
+  try {
+    // Browser-ish headers: some hosts (e.g. Cloudflare-fronted claudeusercontent.com)
+    // bot-challenge requests with a default Node/undici user-agent. This helps with
+    // simple UA rules but will NOT pass a managed JS challenge from a datacenter IP.
+    res = await fetch(url, {
+      redirect: "follow",
+      headers: {
+        "user-agent":
+          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+        accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+        "accept-language": "en-US,en;q=0.9",
+      },
+      signal: AbortSignal.timeout(URL_FETCH_TIMEOUT_MS),
+    });
+  } catch (e) {
+    if (e?.name === "TimeoutError") {
+      throw new Error(`fetch timed out after ${URL_FETCH_TIMEOUT_MS / 1000}s: ${url}`);
+    }
+    throw new Error(`could not fetch ${url}: ${e?.message || e}`);
+  }
+
+  // A redirect could land on a private host even when the first URL was public.
+  if (res.url && res.url !== String(url)) assertImportableUrl(res.url);
+
+  if (!res.ok) {
+    const body = (await res.text().catch(() => "")).slice(0, 200);
+    throw new Error(`fetch failed (${res.status} ${res.statusText || ""}) for ${url}${body ? `: ${body}` : ""}`);
+  }
+
+  const bytes = new Uint8Array(await res.arrayBuffer());
+  const filename = fields.filename || filenameFromResponse(url, res);
+  return importDeckFromBytes(opts, { ...fields, bytes, filename }, adapter);
+}
+
+// ── Import straight from a Claude Design project ─────────────────────────────
+// Claude Design serves every project file UNCAPPED from a per-project CDN host:
+//   https://<projectId>.claudeusercontent.com/v1/design/projects/<projectId>/serve/<path>?t=<token>
+// The `?t=` token is project-scoped (one token fetches every file) and the only
+// credential needed — no cookie. This is the path the design preview itself uses
+// for images, and unlike the MCP `get_file` (256 KiB cap) it streams full bytes,
+// so it's how we pull a media-heavy deck without an export.
+//
+// Caveat: this is an undocumented internal endpoint and may change. The supported
+// alternative remains an Export ZIP fed to importDeckFromBytes.
+const DESIGN_HOST_SUFFIX = ".claudeusercontent.com";
+const MAX_DESIGN_FILES = 500;
+
+function designServeUrl(projectId, token, path) {
+  const clean = String(path).replace(/^\/+/, "");
+  const encoded = clean.split("/").map(encodeURIComponent).join("/");
+  return `https://${projectId}${DESIGN_HOST_SUFFIX}/v1/design/projects/${projectId}/serve/${encoded}?t=${encodeURIComponent(token)}`;
+}
+
+// Pull every local asset path a deck file references (HTML or CSS): the
+// ext-resource-dependency manifest, src/href/poster, srcset, <script>/<link>,
+// and CSS url(). Mirrors the importer's rewrite surface so we fetch the same set
+// it will later rewrite. External/data/blob refs are skipped.
+function extractDesignRefs(text) {
+  const out = new Set();
+  const add = (raw) => {
+    const v = String(raw || "").trim();
+    if (!v || /^(?:https?:|data:|blob:|mailto:|tel:|javascript:|#|\/\/)/i.test(v)) return;
+    const clean = v.split("#")[0].split("?")[0].replace(/^\.?\//, "");
+    if (clean) out.add(clean);
+  };
+  for (const m of text.matchAll(/ext-resource-dependency"\s+content="([^"]+)"/gi)) add(m[1]);
+  for (const m of text.matchAll(/\b(?:src|href|poster)\s*=\s*["']([^"']+)["']/gi)) add(m[1]);
+  for (const m of text.matchAll(/\bsrcset\s*=\s*["']([^"']+)["']/gi)) {
+    for (const part of m[1].split(",")) add(part.trim().split(/\s+/)[0]);
+  }
+  for (const m of text.matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)/gi)) add(m[1]);
+  return [...out];
+}
+
+function looksTextual(contentType, path) {
+  const ct = String(contentType || "").toLowerCase();
+  if (/text\/|javascript|json|svg|css/.test(ct)) return true;
+  return /\.(html?|css|m?js|json|svg)$/i.test(path);
+}
+
+export async function importDeckFromDesign(opts = {}, fields = {}, adapter = {}) {
+  const project = fields.project;
+  const token = fields.token;
+  if (!project) throw new Error("import-design needs --project <id>");
+  if (!token) throw new Error("import-design needs --token <serve-token>");
+  const entry = String(fields.entry || "index.html").replace(/^\/+/, "");
+  const concurrency = adapter.concurrency || DEFAULT_IMPORT_CONCURRENCY;
+  const log = typeof adapter.onStage === "function" ? adapter.onStage : () => {};
+
+  const fetchServe = async (path) => {
+    const res = await fetch(designServeUrl(project, token, path), {
+      signal: AbortSignal.timeout(URL_FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) return { path, ok: false, status: res.status };
+    const ct = res.headers.get("content-type") || "";
+    return { path, ok: true, bytes: new Uint8Array(await res.arrayBuffer()), contentType: ct };
+  };
+
+  // The entry HTML is required — its refs seed the crawl.
+  log(`fetching ${entry}`);
+  const root = await fetchServe(entry);
+  if (!root.ok) {
+    throw new Error(
+      `could not fetch entry "${entry}" (status ${root.status}). Pass --entry <file.html> and check --token hasn't expired.`,
+    );
+  }
+
+  // Breadth-first over refs: HTML/CSS/JS we fetch get re-scanned for nested refs
+  // (e.g. CSS url(), a deck script that pulls more assets). Binary files are leaves.
+  const files = new Map([[entry, root.bytes]]);
+  const queue = extractDesignRefs(textFromBytes(root.bytes));
+  const seen = new Set([entry, ...queue]);
+  const missing = [];
+
+  while (queue.length && files.size < MAX_DESIGN_FILES) {
+    const batch = queue.splice(0, concurrency);
+    const results = await Promise.all(
+      batch.map(async (path) => {
+        log(`fetching ${path}`);
+        try {
+          return await fetchServe(path);
+        } catch (e) {
+          return { path, ok: false, status: e?.message || "fetch error" };
+        }
+      }),
+    );
+    for (const r of results) {
+      if (!r.ok) {
+        missing.push(`${r.path} (${r.status})`);
+        continue;
+      }
+      files.set(r.path, r.bytes);
+      if (looksTextual(r.contentType, r.path)) {
+        for (const ref of extractDesignRefs(textFromBytes(r.bytes))) {
+          if (!seen.has(ref)) {
+            seen.add(ref);
+            queue.push(ref);
+          }
+        }
+      }
+    }
+  }
+
+  // Zip the crawl and hand it to the shared importer (asset upload + ref rewrite).
+  const zipInput = {};
+  for (const [path, bytes] of files) zipInput[path] = bytes;
+  const zip = zipSync(zipInput);
+
+  const result = await importDeckFromBytes(
+    opts,
+    {
+      bytes: zip,
+      filename: `${slugify(fields.slug || titleFromFilename(entry)) || "deck"}.zip`,
+      htmlFile: entry,
+      slug: fields.slug,
+      title: fields.title,
+      status: fields.status,
+    },
+    adapter,
+  );
+  return { ...result, fetched: files.size, missing };
+}

package/src/runtime.mjs

@@ -8,7 +8,8 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.1.6";
+export const VERSION = "0.1.9";
+const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
   name: "prod",
@@ -18,6 +19,10 @@ export const PROD = {
 };
 
 export const api = {
+  assets: {
+    generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
+    saveAsset: makeFunctionReference("assets:saveAsset"),
+  },
   activity: {
     overview: makeFunctionReference("activity:overview"),
     setArchived: makeFunctionReference("activity:setArchived"),
@@ -26,7 +31,11 @@ export const api = {
     revokeByHash: makeFunctionReference("cliCredentials:revokeByHash"),
   },
   decks: {
+    get: makeFunctionReference("decks:get"),
     listForViewer: makeFunctionReference("decks:listForViewer"),
+    remove: makeFunctionReference("decks:remove"),
+    setHtmlStorage: makeFunctionReference("decks:setHtmlStorage"),
+    upsert: makeFunctionReference("decks:upsert"),
     whoami: makeFunctionReference("decks:whoami"),
   },
   shares: {
@@ -36,9 +45,13 @@ export const api = {
     remove: makeFunctionReference("shares:remove"),
     setEnabled: makeFunctionReference("shares:setEnabled"),
   },
+  imagegen: {
+    generateImage: makeFunctionReference("imagegen:generateImage"),
+    checkImageJob: makeFunctionReference("imagegen:checkImageJob"),
+  },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "help", "version", "all-agents", "global", "project"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "help", "version", "all-agents", "global", "project", "transparent"]);
 
 export const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
 export const CRED_FILE = join(CRED_DIR, "credentials.json");
@@ -158,6 +171,9 @@ async function jwtFor(brokerBase, refreshToken) {
 }
 
 export async function client(opts = {}) {
+  // Allow a pre-authenticated client to be injected (e.g. the remote MCP OAuth
+  // route, which already holds a Convex client authed as the requesting user).
+  if (opts.client) return opts.client;
   const t = target(opts);
   const c = new ConvexHttpClient(t.convexUrl);
   const admin = opts.admin || process.env.HSDECKS_ADMIN === "1";
@@ -182,6 +198,27 @@ export function openBrowser(url) {
   execFile(cmd, args, () => {});
 }
 
+export async function uploadBytes(c, bytes, contentType) {
+  const uploadUrl = await c.mutation(api.assets.generateUploadUrl, {});
+  let res;
+  try {
+    res = await fetch(uploadUrl, {
+      method: "POST",
+      headers: { "Content-Type": contentType },
+      body: bytes,
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+    });
+  } catch (e) {
+    const message = e?.name === "TimeoutError"
+      ? `upload exceeded ${Math.round(UPLOAD_TIMEOUT_MS / 1000)}s`
+      : `upload failed: ${e?.message || String(e)}`;
+    throw new Error(message);
+  }
+  if (!res.ok) throw new Error(`upload failed: ${res.status} ${await res.text()}`);
+  const json = await res.json();
+  return json.storageId;
+}
+
 function splitAgents(value) {
   return String(value || "").split(/[,\s]+/).filter(Boolean);
 }