@hypersocial/decks-cli 0.5.0 → 0.7.0

package/src/ops.mjs

@@ -1,4 +1,6 @@
 import { zipSync } from "fflate";
+import { COLOR_KEYS, FONT_PAIRINGS, FONT_ROLES, findPairing, googleFontsUrl } from "./brand.mjs";
+import { MAX_IMPORT_FILE_BYTES, draftArgs, extractFile } from "./brandImport.mjs";
 import { api, client, target, uploadBytes as runtimeUploadBytes } from "./runtime.mjs";
 import {
   bytesFromText,
@@ -119,8 +121,9 @@ export async function pollImageJob(opts, jobId, { intervalMs = 3000, timeoutMs =
 
 // Generate a short clip via fal (MiniMax H3 Max by default, Kling v3 with
 // model "kling-v3": text→video, or image→video when an image URL is given as the
-// first frame). Always a background job: returns
-// { jobId, status, seconds, aspect?, creditsRemaining? } without waiting, so the MCP
+// first frame; loop starts and ends on one frame, transparent mattes the background
+// out). Always a background job: returns
+// { jobId, status, seconds, aspect?, loop, transparent, creditsRemaining? } without waiting, so the MCP
 // tool never blocks; the CLI polls with pollVideoJob.
 export async function generateVideo(opts, fields = {}) {
   if (!fields.prompt) throw new Error("prompt is required");
@@ -130,6 +133,8 @@ export async function generateVideo(opts, fields = {}) {
   if (fields.seconds != null && fields.seconds !== "") args.seconds = Number(fields.seconds);
   if (fields.aspect) args.aspect = String(fields.aspect);
   if (fields.model) args.model = String(fields.model);
+  if (fields.loop === true || fields.loop === "true") args.loop = true;
+  if (fields.transparent === true || fields.transparent === "true") args.transparent = true;
   if (fields.slug) args.slug = String(fields.slug);
   if (fields.name) args.name = String(fields.name);
   return (await client(opts)).action(api.videogen.generateVideo, args);
@@ -231,11 +236,11 @@ export async function checkVideoJob(opts, jobId) {
 }
 
 // Poll a video job until it finishes. Returns the job (its `video` holds the hosted
-// URL); throws on job error or timeout. The server settles every job within 15
-// minutes, so the 16-minute default only trips if the job row itself stalls. A few
-// failed checks in a row (network, Convex hiccup) are tolerated: the job keeps
+// URL); throws on job error or timeout. A few failed checks in a row (network, Convex hiccup) are tolerated: the job keeps
 // running server-side either way, so giving up early would only lose the result.
-export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs = 960_000, maxErrors = 5, onProgress } = {}) {
+// 30 minutes: a transparent clip can take the render's 12 minutes, then up to 14
+// more to matte and store it (convex/videogen.ts gives the matte its own clock).
+export async function pollVideoJob(opts, jobId, { intervalMs = 5000, timeoutMs = 1_800_000, maxErrors = 5, onProgress } = {}) {
   const c = await client(opts);
   const start = Date.now();
   const resume = `check it later with: video-job ${jobId}`;
@@ -746,7 +751,7 @@ function designServeUrl(projectId, token, path) {
 }
 
 // Pull every local asset path a deck file references (HTML or CSS): the
-// ext-resource-dependency manifest, src/href/poster/data-presenter-image, srcset, <script>/<link>,
+// ext-resource-dependency manifest, src/href/poster/data-presenter-image/data-alpha-stacked, 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) {
@@ -758,7 +763,7 @@ function extractDesignRefs(text) {
     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|data-presenter-image)\s*=\s*["']([^"']+)["']/gi)) add(m[1]);
+  for (const m of text.matchAll(/\b(?:src|href|poster|data-presenter-image|data-alpha-stacked)\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]);
   }
@@ -1088,6 +1093,75 @@ export async function setDeckNarrator(opts, slug, ref) {
   return (await client(opts)).mutation(api.narrators.setDeckNarrator, { slug, narrator: value });
 }
 
+// The account's brand (convex/brand.ts): what new_deck / deck new start from.
+export async function getBrand(opts = {}) {
+  return (await client(opts)).query(api.brand.get, {});
+}
+
+// Merge into the saved brand: a field left out keeps its value, "" clears it.
+// fontPairing names one of FONT_PAIRINGS and fills the three fonts (an explicit
+// font still wins). logoUrl is fetched into our storage; logoBytes (with
+// logoType) is a file the CLI read. clearLogo removes the logo. draft is a
+// brand import's token (importBrand): its colours, fonts, name and logo,
+// saved after the person has seen the preview; other fields still win.
+export async function setBrand(opts, { name, designMd, colors, fonts, fontPairing, presenterStyle, logoUrl, logoBytes, logoType, clearLogo, draft } = {}) {
+  const c = await client(opts);
+  let fontSet = fonts;
+  if (fontPairing) {
+    const p = findPairing(fontPairing);
+    if (!p) throw new Error(`no font pairing "${fontPairing}": pick one of ${FONT_PAIRINGS.map((x) => x.id).join(", ")}`);
+    fontSet = { display: p.display, body: p.body, mono: p.mono, ...(fonts ?? {}) };
+  }
+  if (logoUrl && logoBytes) throw new Error("pass logoUrl or a logo file, not both");
+  if (clearLogo && (logoUrl || logoBytes)) throw new Error("clearLogo removes the logo; do not also pass one");
+  const known = (map, keys, what) => {
+    const extra = Object.keys(map ?? {}).filter((k) => !keys.includes(k));
+    if (extra.length) throw new Error(`unknown ${what} ${extra.join(", ")}: use ${keys.join(", ")}`);
+    return map;
+  };
+  known(colors, COLOR_KEYS, "colour");
+  known(fontSet, FONT_ROLES, "font role");
+  const fields = { name, designMd, colors, fonts: fontSet, presenterStyle, draft: draft ? String(draft).trim() : undefined };
+  const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined && v !== null));
+  if (!Object.keys(defined).length && !logoUrl && !logoBytes && !clearLogo) throw new Error("nothing to set: pass draft, colors, fonts, fontPairing, logoUrl, designMd, name or presenterStyle");
+  let out = Object.keys(defined).length ? await c.mutation(api.brand.set, defined) : null;
+  try {
+    if (clearLogo) out = await c.mutation(api.brand.clear, { logoOnly: true });
+    if (logoUrl) out = await c.action(api.brandNode.importLogo, { url: String(logoUrl) });
+    if (logoBytes) {
+      const bytes = logoBytes instanceof ArrayBuffer ? logoBytes : new Uint8Array(logoBytes).slice().buffer;
+      out = await c.action(api.brandNode.uploadLogo, { bytes, contentType: String(logoType ?? "") });
+    }
+  } catch (e) {
+    // The fields above are already saved: say so, so nobody redoes or reports them as lost.
+    const kept = Object.keys(defined);
+    throw new Error(`${kept.length ? `brand saved (${kept.join(", ")}) but the logo was not` : "the logo was not saved"}: ${errorText(e)}`);
+  }
+  return out ?? getBrand(opts);
+}
+
+// Read a brand from a website (url), one of your decks (slug) or a .pptx /
+// .potx / .pdf (bytes + fileName, read here with brandImport.mjs) into a
+// draft. Returns { token, colors, fonts, logoUrl, notes, previewUrl, … };
+// nothing is saved until setBrand({ draft: token }).
+export async function importBrand(opts, { url, slug, bytes, fileName } = {}) {
+  const given = [url, slug, bytes].filter((x) => x !== undefined && x !== null && x !== "");
+  if (given.length !== 1) throw new Error("import a brand from one of: a website url, a deck slug or a .pptx / .potx / .pdf file");
+  const c = await client(opts);
+  if (url) return c.action(api.brandNode.importFromUrl, { url: String(url) });
+  if (slug) return c.action(api.brandNode.importFromDeck, { slug: String(slug) });
+  const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  if (data.byteLength > MAX_IMPORT_FILE_BYTES) throw new Error(`${fileName ?? "the file"} is over ${MAX_IMPORT_FILE_BYTES / 1024 / 1024} MB`);
+  return c.action(api.brandNode.createDraft, draftArgs(extractFile(data, fileName)));
+}
+
+export async function clearBrand(opts = {}) {
+  await (await client(opts)).mutation(api.brand.clear, {});
+  return { cleared: true };
+}
+
+export const listFontPairings = () => ({ pairings: FONT_PAIRINGS.map((p) => ({ ...p, urls: [googleFontsUrl(p.display, "display"), googleFontsUrl(p.body, "body"), googleFontsUrl(p.mono, "mono")] })) });
+
 // Polls `read` until `done`; a few failed reads in a row (a network blip) are
 // retried, since the person may still be finishing in the browser.
 async function pollUntil(read, done, { intervalMs = 2000, timeoutMs }) {

package/src/presenter.mjs

@@ -26,3 +26,12 @@ export function withAvatar(html, { avatarUrl, imageUrl }) {
   const next = none ? tag.replace(/\sdata-presenter="none"/, face) : tag.replace(/>$/, `${face}>`);
   return html.replace(tag, () => next);
 }
+
+// One line for who presents a deck, from narrate's or release's `presenter`
+// ({ narrator, voice, face, reason }); a warning when it plays captions only.
+// Empty for an older backend that sends none.
+export function presenterLine(p) {
+  if (!p) return "";
+  if (!p.face) return `⚠ captions only: ${p.reason ?? `no face for voice "${p.voice}"`}`;
+  return `presented by ${p.face}${p.narrator && p.narrator !== p.face ? ` (narrator ${p.narrator})` : ""}, voice "${p.voice}"`;
+}

package/src/release.mjs

@@ -108,6 +108,8 @@ export async function release(pos, opts = {}, io = {}) {
   }
   const released = presenter ? releaseBundle(deckDir, presenter) : bundle;
   if (presenter) log("✓ presented by your avatar");
+  // A terminal user sees this before it ships, so the CLI warns rather than refuses.
+  else if (job.presenter && !job.presenter.face) log(`⚠ releasing captions only: ${job.presenter.reason ?? "no face"}`);
   const imported = await ops.importDeckFromBytes(opts, {
     slug,
     title: opts.title,
@@ -142,5 +144,5 @@ export async function release(pos, opts = {}, io = {}) {
     log(`✓ share for "${r.recipient}"${share.qa ? " (QA, untracked)" : ""} → ${share.url}`);
   }
   if (!shares.length) log(`  no --to given: \`hyperdecks share new ${imported.slug} "Me" --qa\` makes a link for your own viewing`);
-  return { slug: imported.slug, deckDir, commit: sha, deckUrl: imported.deckUrl, totalDuration: checked.totalDuration, files: bundle.files, shares };
+  return { slug: imported.slug, deckDir, commit: sha, deckUrl: imported.deckUrl, totalDuration: checked.totalDuration, presenter: job.presenter ?? null, files: bundle.files, shares };
 }

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.5.0";
+export const VERSION = "0.7.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -43,6 +43,18 @@ export const api = {
     rename: makeFunctionReference("narrators:rename"),
     setFace: makeFunctionReference("narrators:setFace"),
   },
+  brand: {
+    get: makeFunctionReference("brand:get"),
+    set: makeFunctionReference("brand:set"),
+    clear: makeFunctionReference("brand:clear"),
+  },
+  brandNode: {
+    importLogo: makeFunctionReference("brandNode:importLogo"),
+    uploadLogo: makeFunctionReference("brandNode:uploadLogo"),
+    importFromUrl: makeFunctionReference("brandNode:importFromUrl"),
+    importFromDeck: makeFunctionReference("brandNode:importFromDeck"),
+    createDraft: makeFunctionReference("brandNode:createDraft"),
+  },
   narratorsNode: {
     hear: makeFunctionReference("narratorsNode:hear"),
   },
@@ -136,7 +148,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "loop", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji", "captions-only", "no-brand", "no-logo"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).

package/src/scaffold.mjs

@@ -9,12 +9,13 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import * as ops from "./ops.mjs";
 import { PRESENTER_STYLES } from "./checkRules.mjs";
-import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate } from "./layouts.mjs";
+import { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts } from "./layouts.mjs";
+import { applyBrand, brandForNewDeck, brandSummary } from "./brand.mjs";
 
 export { LAYOUTS, NARRATED_FILES, assembleLayoutDeck, fillTemplate, parseLayouts, readLayout } from "./layouts.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
-const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--dir <path>]';
+const USAGE = 'usage: deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style <stage|bubble|glass|corner>] [--no-brand] [--dir <path>]';
 
 export async function deckNew(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, title] = pos;
@@ -28,9 +29,15 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
   const dir = resolve(/*turbopackIgnore: true*/ cwd, typeof opts.dir === "string" ? opts.dir : join("decks", slug));
   if (existsSync(dir)) throw new Error(`${dir} already exists; pick another slug or --dir`);
   if (opts.layouts === true) throw new Error(`--layouts needs a list, e.g. --layouts ${LAYOUTS.slice(0, 3).join(",")},closer`);
-  const files = opts.layouts !== undefined
-    ? Object.entries(assembleLayoutDeck({ slug, title, presenterStyle, layouts: opts.layouts }))
-    : Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle })]);
+  if (opts.layouts !== undefined) parseLayouts(opts.layouts);
+  // The account's brand goes on the template (--no-brand: the template's look);
+  // an explicit --presenter-style wins over the brand's.
+  const { brand, readError } = await brandForNewDeck(() => ops.getBrand(opts), !(opts["no-brand"] || opts.brand === false));
+  const style = presenterStyle ?? (PRESENTER_STYLES.includes(brand?.presenterStyle) ? brand.presenterStyle : undefined);
+  const files = (opts.layouts !== undefined
+    ? Object.entries(assembleLayoutDeck({ slug, title, presenterStyle: style, layouts: opts.layouts }))
+    : Object.entries(NARRATED_FILES).map(([out, file]) => [out, fillTemplate(file, { slug, title, presenterStyle: style })]))
+    .map(([out, text]) => [out, out === "index.html" ? applyBrand(text, brand) : text]);
   await ops.createDeck(opts, { slug, title });
   try {
     mkdirSync(dir, { recursive: true });
@@ -39,6 +46,7 @@ export async function deckNew(pos, opts = {}, { log = (line) => console.log(line
     rmSync(dir, { recursive: true, force: true });
     throw new Error(`deck ${slug} is registered but its files could not be written (${e.message}); remove the draft with \`hyperdecks deck rm ${slug}\` and run deck new again`);
   }
-  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  next:  hyperdecks narrate ${dir} --dry-run`);
-  return { slug, title, dir, files: Object.keys(NARRATED_FILES) };
+  const summary = brandSummary(brand, readError);
+  log(`✓ created deck "${slug}" → ${dir}\n  files: ${Object.keys(NARRATED_FILES).join(", ")}\n  brand: ${summary.error ? `could not read it (${summary.error}); template look` : summary.applied.length ? summary.applied.join(", ") : "none applied (hyperdecks brand set)"}\n  next:  hyperdecks narrate ${dir} --dry-run`);
+  return { slug, title, dir, files: Object.keys(NARRATED_FILES), brand: summary };
 }

package/templates/icons/LICENSE

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.