@hypersocial/decks-cli 0.6.0 → 0.8.0

package/README.md

@@ -79,6 +79,7 @@ voice list|clone|upload|rm
 
 deck new <slug> "<title>" --narrated [--dir <path>]
 check <slug|deck-dir> [--forbid "<phrase>,<phrase>"] [--max-duration <s>] [--json]
+play <slug|deck-dir> [--voice <v>] [--slug <slug>] [--port <n>] [--no-open] [--json]
 release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
 ```
 
@@ -93,7 +94,12 @@ clip's audio and timeline resolve with the right type; captions are in time,
 cover the clip text and run 4 to 85 characters; local `src`/`href` resolve inside
 the folder; the player is the pinned `player/v1`; `--forbid` phrases appear
 nowhere; every slide has a `data-note` and long titles a `data-title-mobile`.
-`release` refuses uncommitted changes in the deck folder, runs check and narrate
+`play` plays the folder as it is, committed or not, with the real face and voice:
+the face goes on the served copy in memory, on 127.0.0.1 behind a random path, until
+Ctrl-C. It writes no file, uploads nothing, creates no share and renders no audio, so
+changed lines need `narrate` first. The hosted draft link `/p/<token>` shows the same face.
+`release` refuses uncommitted changes in the deck folder (`--qa` too: a release
+replaces what every link to the deck plays), runs check and narrate
 (stopping for a commit if narration changed the folder), imports `index.html` with
 the local files it references, and creates one share per `--to`. The agent
 procedure is the "Author a narrated deck" section of the bundled skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -66,7 +66,8 @@ returns a link; hand it to them, word for word, and wait.
 The faces narrators wear; these commands still work as before.
 
 A deck narrated in the user's own voice is presented by their default avatar
-(a cartoon Minimoji, never a photo) from its next release; with none it plays
+(a cartoon Minimoji, never a photo): in `play` and the draft link at once, on
+share links from its next release. With none it plays
 captions only. D.A.S.H. presents only in its own voice. **Never pick or approve
 a face for the person.** Every command that needs a choice returns a link (and,
 for an import, a code): hand it to them, word for word, and wait.
@@ -124,6 +125,9 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Step | CLI | MCP tool |
 |---|---|---|
 | Brand (once; every new deck starts from it) | `hyperdecks brand show` / `brand set` / `brand edit` | `get_brand` / `set_brand` |
+| Import a brand (website, .pptx/.potx, .pdf, a deck; preview first) | `hyperdecks brand import <url\|file\|slug>` | `import_brand` |
+| Revise the brand with a prompt (preview first) | `hyperdecks brand revise "<change>"` | `revise_brand` |
+| Brand history / undo a brand change | `hyperdecks brand history` / `brand undo [<version>]` | `brand_history` / `undo_brand` |
 | Scaffold | `hyperdecks deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer]` | `new_deck` (`layouts`) |
 | Images | `hyperdecks gen-image "<prompt>" --slug <slug>` | `generate_image` |
 | Video clips | `hyperdecks gen-video "<prompt>" --slug <slug>` | `generate_video` |
@@ -136,6 +140,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Who narrates (ask the person first; see *Narrators*) | `hyperdecks deck narrator <slug> <name\|none\|default>` | `list_narrators`, then `set_deck_narrator` |
 | Narrate | `hyperdecks narrate decks/<slug>` | `narrate_deck` |
 | Check | `hyperdecks check decks/<slug>` | `check_deck` |
+| Watch a draft with its real face | `hyperdecks play decks/<slug>` | the `previewUrl` from `get_deck_source` |
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
@@ -226,6 +231,9 @@ its `##` heading.
 | `glass` | dark or busy slides: head and captions on one frosted panel |
 | `corner` | the slide is the point (a product shot, a chart, a demo): small head bottom-right, subtitles along the bottom |
 
+The live head's face follows script cues too (`[nod]`, `[look #card]`,
+`[smile]`, `[gesture: lightbulb]`; see the script topic); a still face ignores them.
+
 Below 650 px stage and glass become corner on their own. Run
 `hyperdecks check <deck> --layout` to be warned about any slide whose presenter
 would cover its title.
@@ -307,10 +315,17 @@ a presenter style and a design.md (voice, do and don't). `deck new` and
 `new_deck` put its tokens in `:root` and its logo on the first slide, so read
 it first (`hyperdecks brand show --json`, `get_brand`) and write in its voice.
 An explicit request for this deck wins over the brand; `--no-brand`
-(`brand: false`) starts from the template's look. No brand yet? Offer to set
-one up: read the person's website (`capture_url`, its colours, fonts and logo),
-show them what you would save, and `brand set` / `set_brand` only after they
-agree.
+(`brand: false`) starts from the template's look. No brand yet? Offer to
+import it from what they already have: `hyperdecks brand import
+<url|file.pptx|file.pdf|deck-slug>` (`import_brand`) reads the real colours,
+fonts and logo (a PowerPoint's theme exactly) and returns a preview link, a
+sample slide in that brand, and a token. Always show them the preview and
+ask; save with `brand set --draft <token>` (`set_brand { draft }`) only after
+they say yes.
+To change it in words ("darker accent, serif titles"), `hyperdecks brand
+revise "<change>"` (`revise_brand`) gives a draft and preview the same way.
+Every brand save is kept in its history: `brand history` (`brand_history`)
+lists the last changes and `brand undo [<version>]` (`undo_brand`) goes back.
 
 **Fonts: pick a pairing.** Fonts load from Google Fonts. Use one of the
 curated pairings below (display for titles, body for text, mono for kickers
@@ -371,7 +386,26 @@ where there is room so slide changes move the presenter.
   palette hexes, "no text"). `--model nano-banana-2.1` when the image must
   carry legible type.
 - Video: `gen-video` for a short loop behind a hero or a product moment, with
-  `[play: video]` at its word; never needed for a deck to work.
+  `[play: video]` at its word; never needed for a deck to work. A clip that
+  plays on repeat should be made with `--loop` (`loop: true`): it starts and
+  ends on the same frame, so there is no jump at the seam. Give it `--image`
+  to loop a still you already have; without one a keyframe is rendered first.
+- Moving cut-outs: `--transparent` (`transparent: true`) mattes the
+  background out, the moving version of a `gen-image --transparent` PNG: a
+  spinning part, a product turning, over the slide's own background. Use it
+  with `--loop` and a subject on a plain background. It returns a VP9 WebM
+  with alpha (Chrome, Firefox, Edge) and a stacked-alpha MP4 that the hosted
+  player draws on a canvas in Safari and on iOS, which ignore WebM alpha. The
+  job's `markup` is the tag to paste, as is:
+
+  ```html
+  <video muted loop playsinline autoplay crossorigin="anonymous"
+    src="(video.url)" data-alpha-stacked="(video.stacked.url)"></video>
+  ```
+
+  Keep `crossorigin` and `data-alpha-stacked`: the player needs both. A deck
+  without the hosted player shows the clip in a box in Safari. A transparent
+  clip costs 2 credits a second more than an opaque one.
 - People: real photos only with permission; initials otherwise.
 
 **Motion.** The presenter's moves are the deck's motion; keep everything else
@@ -425,6 +459,12 @@ phone screenshots, the same `fix` bar.
   showcase is a slide of stacked cards, one point each, with a `go` to each
   card at the word that starts it: `Write [go: #step-1] the slides, write
   [go: #step-2] what you'd say`. Give each card an id.
+- Face: the live head already moves with the speech (eyes, brows, a nod on a
+  falling end); add a few face cues only where they carry the point, each on
+  the word before it: `This is the big one [nod] and here [look #m3] is the
+  proof.` / `Not a slide tool [shake], a presenter.` / `Then it clicked
+  [gesture: lightbulb].` / `Really? [brow up] Yes [smile].` A still or
+  captions-only presenter ignores them.
 
 | Cue | Effect |
 |---|---|
@@ -434,7 +474,12 @@ phone screenshots, the same `fix` bar.
 | `[pause: 0.5]` | a beat of silence (≤ 5 s) |
 | `[play: video]` / `[pause: video]` | play or pause the slide's video |
 | `[go: .list]` / `[go: slot]` | fly beside `.list` / back to the slot |
-| `[look: h2]` | look at the title |
+| `[look: h2]` / `[look #card]` | look at the title / the card, then back |
+| `[look viewer]` / `[look away]` | look back at the viewer / glance aside |
+| `[nod]` / `[shake]` | a nod or head shake that suits the mood |
+| `[brow up]` / `[brow down]` | raise or lower the brows |
+| `[smile]` / `[think]` | `[mood: happy]` / `[mood: thinking]` |
+| `[gesture: <id>]` | one of the head's tracks: `knowing-nod`, `ponder-tilt`, `lightbulb`, `side-eye-hmm`, `chuckle-bob`, `sunny-nod`, `double-take`… (check lists them all) |
 | `[custom: name]` | only the slide's controller sees it |
 - `voice: dash` narrates with D.A.S.H.'s own robot voice, a synthetic
   character voice (not a clone of anyone) any account may use, for decks that
@@ -502,7 +547,16 @@ an internal codename). Messages and what to do:
 
 ### 6. Look at it, at both widths
 
-Serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
+To watch it as it will really play, run `hyperdecks play decks/<slug>`. It plays
+the folder as it is, committed or not, with the real face and voice, on
+127.0.0.1 until Ctrl-C. It writes nothing, uploads nothing, creates no share and
+spends nothing, so it plays the last narration: changed lines need `narrate`
+first. It prints who presents, or why it is captions only. `--no-open` skips the
+browser (an agent reads the URL; `--json` prints it as one line).
+`release --qa` is not a preview: it needs a commit, and it changes what every
+link to this deck plays.
+
+For the layout pass, serve the folder (`npx serve decks/<slug>` or `python3 -m http.server -d decks/<slug>`)
 and screenshot it with Playwright at 1440×900 and 390×844, every slide
 (`#scene=<id>`). Look at both: nothing clipped, the presenter and its captions
 clear of the text, the mobile titles in use. Fix and repeat until both read well.
@@ -515,7 +569,8 @@ the deck's QA link on desktop and phone and list each problem as `fix` or
 
 Pick image models by job: `gen-image` defaults to GPT Image 2.5; `--model
 nano-banana-2.1` is stronger on typography and photoreal scenes. `gen-video`
-defaults to MiniMax H3 Max (`--model kling-v3` is the fallback). Use `chart` for
+defaults to MiniMax H3 Max (`--model kling-v3` is the fallback); `--loop` and
+`--transparent` work with both. Use `chart` for
 real numbers instead of a generated picture of a chart, `icons search` for
 real line icons, and `icons --style` with the deck's palette for an
 illustrated set that matches.

package/skills/hyperdecks/chat.md

@@ -23,12 +23,20 @@ makes the hello deck; continue from step 5 below.
 
 1. `deck_guide` (this page), then `deck_guide { topic: "layouts" }` to pick slides.
    `get_brand` for the person's saved brand: write in its designMd's voice.
-   None yet and they have a website? Offer to set one up: `capture_url` the
-   site, read its colours, fonts and logo, show what you would save and
-   `set_brand` once they agree (`deck_guide { topic: "design" }` lists the
-   font pairings).
+   None yet? Offer to import it from what they have: `import_brand` with
+   their website (`url`), a PowerPoint or PDF they attach (`file`) or one of
+   their decks (`slug`). It reads the real colours, fonts and logo and returns
+   a `previewUrl` (a sample slide in that brand) and a `token`. Always give
+   them the preview link, say what it found (and its notes), and ask; only
+   after a yes call `set_brand { draft: token }`. Never save without the yes.
+   To change the brand in words ("less yellow", "serif titles"),
+   `revise_brand { instruction }` gives a draft and preview the same way.
+   Any brand change can be undone: `brand_history`, then `undo_brand`.
+   (`deck_guide { topic: "design" }` lists the font pairings.)
 2. `new_deck { slug, title, layouts }`: registers your draft and returns the
-   full text of every file plus a `previewUrl` (the draft, untracked). It
+   full text of every file plus a `previewUrl` (the draft, untracked; once
+   narrated it plays with the face its release would have, so the person can
+   watch it before anything ships). It
    starts in the saved brand's colours, fonts and logo (`brand` in the result
    says what it took); `brand: false` gives the template's look.
 3. Images: `generate_image`, `render_chart`, `capture_url`, or
@@ -40,6 +48,12 @@ makes the hello deck; continue from step 5 below.
    you swap each for an `<img>` of its real file, or delete the hero's art.
    Icons: `search_icons { query }` returns real line icons as inline `<svg>`
    in `currentColor`; paste one where a features card has its icon.
+   For motion, `generate_video` (poll `check_video_job`): `loop: true` for a
+   clip that repeats with no jump, `transparent: true` for a moving cut-out
+   over the slide. Paste the finished job's `markup` as is (a transparent
+   clip's `<video>` names a second file in `data-alpha-stacked`, which the
+   player shows in Safari and on iOS).
+   `deck_guide { topic: "design" }` says when each fits.
 4. `write_deck_source` to change a file: `edits: [{ find, replace }]` with
    exact text that occurs once (copy it from `get_deck_source`), or `content`
    to replace the file. Pass `baseRev` (the `rev` you last read) so a
@@ -55,11 +69,14 @@ makes the hello deck; continue from step 5 below.
    poll `check_narration_job` until `done`. The draft's player tag then has its
    `data-manifest`. Its `presenter` says who will present (`face: null` is
    captions only, `reason` says why): tell the person. No voice of their own
-   yet? Pass `voice: "dash"`.
+   yet? Pass `voice: "dash"`. To direct the face, put a few cues in
+   script.md on the words that carry the point (`[nod]`, `[look #card]`,
+   `[smile]`, `[gesture: lightbulb]`; `deck_guide script` lists them) and
+   narrate again.
 8. `check_deck { slug }` again, then `review_deck { slug, draft: true }` and
-   `check_review_job`: it shoots desktop and 390×844 phone frames, which is how
-   you catch a slide that overflows a phone (the hosted check cannot measure
-   layout).
+   `check_review_job`: it shoots desktop and 390×844 phone frames, face included,
+   which is how you catch a slide that overflows a phone (the hosted check cannot
+   measure layout).
 9. `release_deck { slug, qa: true }` gives the user a QA link to watch first.
    `release_deck { slug, recipients: [{ recipient, email }] }` makes one
    tracked link each. Release creates live links: confirm the recipients with

package/src/avatar.mjs

@@ -86,6 +86,6 @@ export async function avatarConnect(opts, { log = console.log, interactive = int
   log("Waiting for you to pick a face…");
   const done = await ops.waitForConnect(opts, out.connectId);
   if (done.status !== "added") throw new Error(done.status === "denied" ? "not shared on minimoji.com" : done.status === "expired" ? "the code expired; run avatar connect again" : done.error || `the import ended (${done.status})`);
-  log("✓ Presenter: your Minimoji. Your decks use it from the next release.");
+  log("✓ Presenter: your Minimoji. Your drafts show it now; share links get it from the next release.");
   return { status: "added", avatarId: done.avatarId };
 }

package/src/brandCli.mjs

@@ -7,20 +7,26 @@
 //             [--fonts <pairing>] [--display "<family>"] [--body …] [--mono …]
 //             [--logo <url|file>] [--no-logo] [--presenter-style s]
 //             [--design <file.md|->] [--name "<company>"]
+//             [--draft <token>]      (a brand import, saved after you saw its preview)
+//   brand import <url|file|slug>     read a brand from a website, a .pptx / .potx /
+//                                    .pdf or one of your decks into a draft + preview
+//   brand revise "<change>"          a draft + preview of the brand with that change
+//   brand history                    the last changes (from any surface)
+//   brand undo [<version>]           undo the last change, or go back to a version
 //   brand edit                       design.md in $VISUAL / $EDITOR, saved on exit
 //   brand fonts                      the curated font pairings
 //   brand clear                      forget the brand (new decks get the template look)
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { extname, join } from "node:path";
+import { basename, extname, join } from "node:path";
 import * as ops from "./ops.mjs";
 import { FONT_PAIRINGS } from "./brand.mjs";
 
 const LOGO_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml", ".avif": "image/avif" };
 const COLOR_FLAGS = { ink: "ink", paper: "paper", accent: "accent", "accent-2": "accent2", card: "card" };
 const FONT_FLAGS = ["display", "body", "mono"];
-const SET_USAGE = 'usage: brand set [--accent "#hex"] [--ink …] [--paper …] [--accent-2 …] [--card …] [--fonts <pairing>] [--display "<family>"] [--body …] [--mono …] [--logo <url|file>] [--no-logo] [--presenter-style stage|bubble|glass|corner] [--design <file.md|->] [--name "<company>"]';
+const SET_USAGE = 'usage: brand set [--draft <token>] [--accent "#hex"] [--ink …] [--paper …] [--accent-2 …] [--card …] [--fonts <pairing>] [--display "<family>"] [--body …] [--mono …] [--logo <url|file>] [--no-logo] [--presenter-style stage|bubble|glass|corner] [--design <file.md|->] [--name "<company>"]';
 
 export function brandLines(b) {
   if (!b) return ["no brand saved: new decks get the template look", "  set one: hyperdecks brand set --accent \"#ff5a1f\" --fonts editorial --logo ./logo.svg"];
@@ -64,6 +70,7 @@ export function brandArgs(opts, { readFile = readFileSync, stdin = () => readFil
     }
   }
   if (opts["no-logo"]) args.clearLogo = true;
+  if (flag(opts, "draft") !== undefined) args.draft = flag(opts, "draft");
   return args;
 }
 
@@ -125,3 +132,80 @@ export async function brandClear(opts = {}, { log = (line) => console.log(line)
   log(opts.json ? JSON.stringify(out) : "✓ brand cleared; new decks get the template look");
   return out;
 }
+
+// What `brand import` read, for the terminal.
+export function importLines(d) {
+  const colors = Object.entries(d.colors ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  const fonts = Object.entries(d.fonts ?? {}).map(([k, v]) => `${k} ${v}`).join(", ");
+  return [
+    d.source?.kind === "revise" ? `revised: ${d.source.ref}` : `read from ${d.source?.kind} ${d.source?.ref}`,
+    ...(d.name ? [`name:      ${d.name}`] : []),
+    `colours:   ${colors || "(none found)"}`,
+    `fonts:     ${fonts || "(none found)"}`,
+    `logo:      ${d.logoUrl ?? "(none found)"}`,
+    ...(d.notes ?? []).map((n) => `  · ${n}`),
+    "",
+    `preview:   ${d.previewUrl}`,
+    `Nothing is saved yet. To make it your brand: hyperdecks brand set --draft ${d.token}`,
+  ];
+}
+
+// brand import <url|file|slug>: an http(s) URL or a domain is a website, an
+// existing path a file, anything else one of your deck slugs.
+export async function brandImport(from, opts = {}, { log = (line) => console.log(line), readFile = readFileSync, exists = existsSync } = {}) {
+  const src = String(from ?? "").trim();
+  if (!src) throw new Error("usage: brand import <https://your.site | deck.pptx | brand.pdf | deck-slug> [--json]");
+  let args;
+  if (/^https?:\/\//i.test(src)) args = { url: src };
+  else if (exists(src)) args = { bytes: new Uint8Array(readFile(src)), fileName: basename(src) };
+  else if (/\.(pptx|potx|pdf)$/i.test(src)) throw new Error(`${src}: no such file`);
+  else if (/^[a-z0-9][a-z0-9-]*$/.test(src)) args = { slug: src };
+  else if (/^[\w-]+(\.[\w-]+)+(\/.*)?$/.test(src)) args = { url: `https://${src}` };
+  else throw new Error(`${src}: not a URL, a file or a deck slug`);
+  const d = await ops.importBrand(opts, args);
+  if (opts.json) log(JSON.stringify(d, null, 2));
+  else for (const line of importLines(d)) log(line);
+  return d;
+}
+
+// brand revise "<change>": the model's take on the brand, as a draft + preview.
+export async function brandRevise(words, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const instruction = (Array.isArray(words) ? words.join(" ") : String(words ?? "")).trim();
+  if (!instruction) throw new Error('usage: brand revise "<change>", e.g. brand revise "make the accent darker and use a serif for titles"');
+  const d = await ops.reviseBrand(opts, { instruction });
+  if (opts.json) log(JSON.stringify(d, null, 2));
+  else for (const line of importLines(d)) log(line);
+  return d;
+}
+
+const ago = (at, now = Date.now()) => {
+  const m = Math.round((now - at) / 60000);
+  if (m < 1) return "just now";
+  if (m < 60) return `${m} min ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`;
+};
+
+export function historyLines(versions, now = Date.now()) {
+  if (!versions.length) return ["no brand changes yet"];
+  return [
+    ...versions.map((v) => `${v.current ? "* " : "  "}${v.label.padEnd(48)} ${ago(v.at, now).padEnd(12)} ${v.id}`),
+    "",
+    "hyperdecks brand undo            undo the last change",
+    "hyperdecks brand undo <version>  go back to one of these",
+  ];
+}
+
+export async function brandHistory(opts = {}, { log = (line) => console.log(line) } = {}) {
+  const out = await ops.brandHistory(opts);
+  if (opts.json) log(JSON.stringify(out, null, 2));
+  else for (const line of historyLines(out.versions)) log(line);
+  return out;
+}
+
+export async function brandUndo(version, opts = {}, { log = (line) => console.log(line) } = {}) {
+  const b = await ops.undoBrand(opts, { version });
+  if (opts.json) log(JSON.stringify(b, null, 2));
+  else for (const line of [version ? "✓ brand restored" : "✓ last change undone", ...brandLines(b)]) log(line);
+  return b;
+}