@hypersocial/decks-cli 0.6.0 → 0.7.0

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -124,6 +124,7 @@ 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` |
 | 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` |
@@ -226,6 +227,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 +311,13 @@ 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.
 
 **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 +378,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 +451,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 +466,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
@@ -515,7 +552,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,10 +23,13 @@ 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.
+   (`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
    starts in the saved brand's colours, fonts and logo (`brand` in the result
@@ -40,6 +43,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,7 +64,10 @@ 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

package/src/brandCli.mjs

@@ -7,20 +7,23 @@
 //             [--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 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 +67,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 +129,38 @@ 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 [
+    `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;
+}