@hypersocial/decks-cli 0.8.0 → 0.8.2

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -147,6 +147,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
 | Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |
 | Forwarding, whole deck | `hyperdecks deck forward on\|off <slug>` | `set_deck_forwarding` |
+| Slides or scroll, viewer toggle | `hyperdecks deck view <slug> [slides\|scroll\|default] [--toggle on\|off]` | `set_deck_view` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
 | All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
 | What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
@@ -159,6 +160,15 @@ Disabling the parent link (`share off`) turns off its forwards too, and
 `share forward default` (or `allowForward: null`) drops a link's own setting
 so it follows the deck's.
 
+How a deck opens (slides or scroll) is a deck setting too: `deck view <slug>
+scroll` (`set_deck_view { slug, view: "scroll" }`) takes effect on every link's
+next load, with no re-release; `default` (`view: null`) goes back to what the
+HTML says. Viewers get a slides/scroll toggle in the player, remembered per
+link, unless you turn it off (`--toggle off`, `viewToggle: false`). A viewer
+who already switched keeps their own choice while the toggle is on; turn the
+toggle off to make every viewer see the deck's view.
+`deck list --json` / `list_decks` and `deck stats` / `deck_stats` show both.
+
 ### 1. Ground it in the user's own material
 
 Build the deck from what you can already read in this session: files in the
@@ -213,8 +223,24 @@ The deck contract (`check` enforces each line):
 - The player script stays
   `<script type="module" src="https://decks.hypersocial.ai/player/v1/player.js" data-manifest="…">`.
   `narrate` fills `data-manifest`; do not edit it by hand.
+- To read the deck as one long page instead of slide by slide, add
+  `data-view="scroll"` to that player script (on the hosted MCP, through
+  write_deck_source). The slides stay as they are: they stack and snap, the
+  page fades to each landed slide's background (`data-bg="#ffd166"` on a
+  `<section>` overrides it), the presenter travels to each slide's
+  `narration-slot` as you scroll, and the narration scrolls the page on by
+  itself. Remove the attribute to go back. For a released deck, prefer the
+  deck setting (`deck view <slug> scroll`, `set_deck_view`): it overrides the
+  attribute and needs no re-release.
 - Local images and files sit inside the deck folder and are referenced
   relatively (`img/chart.png`). Hosted images (`gen-image` URLs) are fine too.
+- A file the deck's own JavaScript loads (`fetch('media/data.json')`, a clip
+  for `new Audio(…)`) is written out as a quoted path, in an inline `<script>`
+  or in a `.js` or `.json` file the deck loads. Release follows those paths and ships the files
+  (`play` serves the whole folder, the `/v/` link only what release shipped).
+  A path built at runtime (`` `media/lines/${id}.mp3` ``) can't be followed:
+  list each file literally (`{ otter: "media/lines/otter.mp3" }`) and pick from
+  that.
 
 <!-- topic: presenter -->
 #### Which presenter style
@@ -447,13 +473,32 @@ phone screenshots, the same `fix` bar.
 - Narration: short phrases, each sentence one caption of 4 to 85 characters
   (two lines in the bubble). Aim for 2.5 to 3 minutes in all; `maxTotalSeconds`
   in the front matter is the cap check uses (180 in the scaffold).
-- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal, and `hold: 2` on interactive slides.
-- Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it; also
+- Holds: 0.4 s by default. Give a slide `hold: 1.5` when the viewer needs time to read a number, a chart or a reveal.
+- Interactive slides (something the viewer taps or plays with): add
+  `data-interactive` to the slide's `<section>`. The presenter finishes the
+  line, then the deck waits with a Continue button instead of advancing, and
+  taps inside the slide don't pause the narration. The slide hears the
+  presenter through `deck:presenter { slide, state }` on `window` (or a
+  controller's `onNarration(state, ctx)`), ducks its own audio while `state`
+  is `playing`, and can quiet the presenter with `ctx.player.pause()` /
+  `resume()` (or `window.hyperdecks.pauseNarration()` / `resumeNarration()`).
+- Anything the viewer clicks on a slide (interactive or not) gets
+  `data-hd-tap` (or `cursor: pointer`), so the click doesn't also pause the
+  presenter. Buttons, links, canvases and focusable elements are exempt already.
+- Cues: `[reveal: #id]` reveals `.reveal#id` at the word before it (going
+  back or replaying the slide replays its reveals from the first, and the
+  live head glances at each, unless a `[look]`/`[go]` is beside it or a
+  `go` has it docked; `data-reveal-glance="off"` on the slide or `<body>`
+  stops the glance); also
   `[wave]`, `[mood: excited]`, `[pause: 0.5]`, `[custom: name]`.
 - Moves, to point at part of a slide: `[go: <selector>]` flies the presenter
   beside that element (the side with room) until the next `go`, the slide's
-  end, or `[go: slot]`; `[look: <selector>]` turns the head toward it without
-  moving. One selector each, matched inside that slide; check fails one that
+  end, or `[go: slot]`. The element grows a little and, when it is one item
+  of a list or grid, the other items fade back (`.hd-dimmed`); the presenter
+  never covers them, so with no room beside it it stays put and looks at it.
+  Put `data-focus="ring"` on the element or slide for an accent ring instead,
+  or restyle `.hd-focus` / `.hd-dimmed` in the deck's CSS.
+  `[look: <selector>]` turns the head toward an element without moving. One selector each, matched inside that slide; check fails one that
   matches nothing. Use `go` when the narration walks through a list or chart,
   `look` for a glance at a title or number. Not in `corner` style. The best
   showcase is a slide of stacked cards, one point each, with a `go` to each
@@ -470,10 +515,10 @@ phone screenshots, the same `fix` bar.
 |---|---|
 | `[wave]` | the presenter greets (the live head's joy emote) |
 | `[mood: excited]` / `[emote: name]` | the head's mood or emote |
-| `[reveal: #id]` | adds `is-revealed` to `#id` |
+| `[reveal: #id]` | adds `is-revealed` to `#id` (reset when the slide is left or replays); the live head glances at it unless a `[look]`/`[go]` is beside it |
 | `[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 |
+| `[go: #step-2]` / `[go: slot]` | fly beside that item, grow it, fade the other items / back to the slot |
 | `[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 |
@@ -487,6 +532,10 @@ phone screenshots, the same `fix` bar.
 - No `voice:` in the front matter means the user's first ready voice. If
   `hyperdecks voice list` shows none, ask the user to record one and run
   `voice clone` (it asks them for consent; never clone anyone else's voice).
+- Names speech-to-text spells another way fail narrate's transcript check
+  (step 4). Map what it heard to what you wrote with a `normalize:` entry in
+  the front matter, `heard=written`, comma-separated: a clip that says
+  "Minimoji" but is transcribed as "Moji" needs `normalize: moji=minimoji`.
 
 ### 4. Narrate and read the guard
 
@@ -510,9 +559,13 @@ hyperdecks check decks/<slug> [--forbid "Other Co,codename"] [--layout]
 At the stage size it warns, without failing, when a slide's presenter would
 overlap its title. On a 390×844 phone (the share player's 374×736 slide card)
 it fails any slide whose content overflows: the player never scrolls a slide.
+`release` (local or `--hosted`) always runs this layout check and refuses an
+overflowing slide; `check <slug> --hosted --layout` measures a hosted draft.
 
 `--forbid` lists phrases that must not reach this audience (another customer,
-an internal codename). Messages and what to do:
+an internal codename). It matches the page's text, alt text, titles and
+script.md, not URLs in attributes, so forbidding your own brand still passes
+with the player's `decks.hypersocial.ai` script tag. Messages and what to do:
 
 | Message starts with | Fix |
 |---|---|
@@ -527,6 +580,9 @@ an internal codename). Messages and what to do:
 | `clip <id>: captions do not cover the clip text` | narrate that slide again |
 | `clip <id>: caption N is … characters` | split or join sentences in that block |
 | `local reference does not resolve` / `leaves the deck folder` | move the file into the deck folder or fix the path |
+| `<file> names <path>, which is not in the deck folder` | add the file, or fix the path in that script |
+| ⚠ `<file> builds file paths at runtime` | list each file as a quoted path (an object or array, in a script or a `.json` it fetches) and pick from it |
+| ⚠ `<file> loads files from computed values` | fine when every file it can load is also written out as a quoted path; otherwise list them so release ships them |
 | `player script must be` / `no player script` | restore the player/v1 script tag |
 | `the player script has no data-manifest` | run `narrate` |
 | `no loading state` | copy the template's `<style data-hd-loading>` block (and the preload lines above it) into `<head>`; set `--hd-ground` / `--hd-ground-ink` to the first slide's colours |

package/skills/hyperdecks/chat.md

@@ -90,7 +90,9 @@ makes the hello deck; continue from step 5 below.
 10. Later: `list_shares` and `deck_stats` (both show the card),
    `activity_overview`; `email_embed { token }` for the HTML that pastes into an
    email as the deck's moving preview (it needs a recipient's link, not a QA
-   one); `set_share_notify` to mute a link's "opened" alerts;
+   one); `set_deck_view { slug, view: "scroll" | "slides" | null, viewToggle }`
+   for how the deck opens and whether viewers may switch (every link, next
+   load, no re-release); `set_share_notify` to mute a link's "opened" alerts;
    `set_recipient_archived` to tidy the activity feed; `credits` for the
    balance. `remove_deck` deletes a deck and breaks every link to it: confirm
    with the user first.

package/src/check.mjs

@@ -119,7 +119,7 @@ export function resolveDeckDir(arg, cwd = process.cwd()) {
 // following symlinks). Anything that climbs out is refused, so release never
 // uploads a file from elsewhere on the machine.
 export function deckFileResolver(deckDir) {
-  const root = realpathSync(deckDir);
+  const pathExists = deckPathResolver(deckDir);
   return (ref) => {
     let clean;
     try {
@@ -127,6 +127,14 @@ export function deckFileResolver(deckDir) {
     } catch {
       return false;
     }
+    return pathExists(clean);
+  };
+}
+
+// The same answer for an already-decoded path; `kind: "dir"` asks about a folder instead.
+export function deckPathResolver(deckDir, { kind = "file" } = {}) {
+  const root = realpathSync(deckDir);
+  return (clean) => {
     const path = isAbsolute(clean) ? join(root, clean) : resolve(root, clean);
     const inside = (p) => p === root || p.startsWith(root + sep);
     if (!inside(path)) return "outside";
@@ -134,34 +142,54 @@ export function deckFileResolver(deckDir) {
     const real = realpathSync(path);
     if (!inside(real)) return "outside";
     if (relative(root, real).split(sep).some((part) => part.startsWith("."))) return "outside";
-    return lstatSync(real).isFile();
+    return kind === "dir" ? lstatSync(real).isDirectory() : lstatSync(real).isFile();
   };
 }
 
+// What deckFiles needs to walk a deck folder: whether a path is a file or a
+// folder inside it, and a file's text.
+export function deckFolder(deckDir) {
+  return {
+    pathExists: deckPathResolver(deckDir),
+    isDir: deckPathResolver(deckDir, { kind: "dir" }),
+    read: (path) => readFileSync(join(deckDir, path), "utf8"),
+  };
+}
+
+// The browser half of check --layout, on a folder holding the deck's index.html
+// (the hosted release measures a draft the same way, from a temp folder). A
+// presenter over the title is a warning, not a failure: only a person can judge
+// it. A slide that overflows the phone card is an error: the player never
+// scrolls a slide. No Chromium is a warning, as each measurement is optional.
+export async function layoutCheck(deckDir, html, manifest = null, { measure = measureLayout, measureFit = measurePhoneFit } = {}) {
+  const errors = [], warnings = [];
+  const { width: w, height: h } = stageSize(html);
+  try {
+    warnings.push(...overlapWarnings(await measure(deckDir, slideStyles(html, manifest), { width: w, height: h }), `${w}×${h}`));
+  } catch (e) {
+    warnings.push(MESSAGES.layoutUnchecked(e.message));
+  }
+  try {
+    errors.push(...phoneOverflowErrors(await measureFit(deckDir)));
+  } catch (e) {
+    warnings.push(MESSAGES.layoutUnchecked(e.message));
+  }
+  return { errors, warnings: [...new Set(warnings)] };
+}
+
 // Run every rule on a deck folder. Returns { deckDir, slug, slides, totalDuration, errors }.
 export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalThis.fetch, cwd, measure = measureLayout, measureFit = measurePhoneFit } = {}) {
   const deckDir = resolveDeckDir(dirArg, cwd);
   const html = readFileSync(join(deckDir, "index.html"), "utf8");
   const scriptPath = join(deckDir, "script.md");
   const script = existsSync(scriptPath) ? readFileSync(scriptPath, "utf8") : "";
-  const { manifest, ...result } = await checkSources({ html, script }, { ...opts, hosted: false, exists: deckFileResolver(deckDir) }, { fetch: fetchImpl });
+  const { manifest, ...result } = await checkSources({ html, script }, { ...opts, hosted: false, exists: deckFileResolver(deckDir), ...deckFolder(deckDir) }, { fetch: fetchImpl });
   const { errors, warnings } = result;
-  // A presenter over the title is a warning, not a failure: only a person can
-  // judge it. A slide that overflows the phone card is an error. Both need a
-  // browser, so they run only with --layout.
+  // Both need a browser, so they run only with --layout (release always asks).
   if (opts.layout) {
-    const { width: w, height: h } = stageSize(html);
-    try {
-      warnings.push(...overlapWarnings(await measure(deckDir, slideStyles(html, manifest), { width: w, height: h }), `${w}×${h}`));
-    } catch (e) {
-      warnings.push(MESSAGES.layoutUnchecked(e.message));
-    }
-    // A slide that scrolls on a phone fails: the player never scrolls a slide.
-    try {
-      errors.push(...phoneOverflowErrors(await measureFit(deckDir)));
-    } catch (e) {
-      warnings.push(MESSAGES.layoutUnchecked(e.message));
-    }
+    const layout = await layoutCheck(deckDir, html, manifest, { measure, measureFit });
+    errors.push(...layout.errors);
+    warnings.push(...layout.warnings);
   }
   return {
     deckDir,

package/src/checkRules.mjs

@@ -36,6 +36,10 @@ export const MESSAGES = {
   localRef: (ref) => `local reference does not resolve: ${ref}`,
   outsideRef: (ref) => `local reference leaves the deck folder: ${ref}`,
   hostedRef: (ref) => `local reference ${ref}: a hosted deck has no folder, so every file must be a URL; upload it with upload_deck_asset and use the URL it returns`,
+  scriptRef: (ref, from) => `${from} names ${ref}, which is not in the deck folder; add the file or fix the path`,
+  // Warnings: deliberate sometimes (a path built from a CDN base), so the deck still passes.
+  scriptTemplate: (from, samples) => `${from} builds file paths at runtime (${samples.slice(0, 3).join(", ")}${samples.length > 3 ? ", …" : ""}); release can't see them, so they 404 on the shared link. Write each file out as a quoted path (an object or array of "media/…" strings, in a script or a .json file it fetches) and pick from that`,
+  scriptComputed: (from, calls) => `${from} loads files from computed values (${calls.join(", ")}); release only ships files the deck names literally, so make sure each file it can load is written out as a quoted path in index.html, a script or a .json file the deck loads`,
   forbidden: (phrase, where) => `forbidden phrase "${phrase}" appears in ${where}`,
   note: (id) => `slide ${id}: needs a data-note naming the source of its facts`,
   mobileTitle: (id, title) => `slide ${id}: title "${title}" is over ${MOBILE_TITLE_CHARS} characters and needs a data-title-mobile`,
@@ -61,7 +65,7 @@ export const MESSAGES = {
 };
 
 // The framed player's slide card on a phone (player.css): the screen less the
-// 52px masthead, the 56px dock and 8px gutters.
+// 60px masthead, the 48px dock and 8px gutters.
 export const HOSTED_LAYOUT_WHY = "presenter overlap and phone fit need a browser: run review_deck with draft=true";
 export const PHONE = { width: 390, height: 844, card: { width: 374, height: 736 } };
 
@@ -72,6 +76,9 @@ const attr = (tag, name) => {
 };
 const round = (n) => Math.round(n * 100) / 100;
 const decode = (s) => s.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'");
+// Blank every attribute value that is an absolute or protocol-relative URL
+// (src, href, data-manifest, …); the audience never reads those.
+const withoutUrlAttrs = (html) => html.replace(/(\s[\w:.-]+\s*=\s*)(?:"(?:https?:)?\/\/[^"]*"|'(?:https?:)?\/\/[^']*')/gi, '$1""');
 const textOf = (html) => decode(html.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
 
 // Comments blanked but newlines kept, so line numbers still match the file.
@@ -295,6 +302,173 @@ export function localRefs(html) {
   return [...new Set(refs.filter((r) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(r) && !r.endsWith("/")))];
 }
 
+// Files a deck's own scripts load. `play` serves the folder, so any path a
+// script asks for resolves; a released deck is uploaded file by file and its
+// text rewritten to storage URLs, so a file only a script names has to be found
+// here to ship, and a path built at runtime can't be rewritten at all.
+
+// Extensions a quoted string must end in to count as a deck file.
+const ASSET_EXT = /\.(?:json|csv|txt|vtt|mp3|m4a|aac|wav|ogg|opus|flac|mp4|m4v|webm|mov|png|jpe?g|webp|avif|gif|svg|ico|pdf|glb|gltf|bin|wasm|m?js|css|woff2?|ttf|otf|eot)$/i;
+const SCHEME = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const stripQuery = (s) => s.split("#")[0].split("?")[0];
+const isScriptPath = (s) => !/[\s<>"'`(){}|\\^*]/.test(s) && !SCHEME.test(s) && ASSET_EXT.test(stripQuery(s));
+const dirOf = (path) => path.slice(0, path.lastIndexOf("/") + 1);
+
+// `ref` against the folder `dir` ("" for the deck root), as a decoded path
+// inside the deck; null when it climbs out or does not decode. A leading "/"
+// means the deck root, which is where `play` serves it from.
+export function deckPath(dir, ref) {
+  let clean;
+  try {
+    clean = decodeURIComponent(stripQuery(ref.trim()));
+  } catch {
+    return null;
+  }
+  const parts = clean.startsWith("/") ? [] : dir.split("/").filter(Boolean);
+  for (const p of clean.split("/")) {
+    if (!p || p === ".") continue;
+    if (p !== "..") parts.push(p);
+    else if (!parts.pop()) return null;
+  }
+  return parts.join("/") || null;
+}
+
+// A JavaScript source's string literals, comments skipped: { value, interpolated }
+// for each, plus `code`, the source with every string emptied, so a call can be
+// read without its arguments' text getting in the way.
+export function jsStrings(src) {
+  const strings = [];
+  let code = "";
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "/" && src[i + 1] === "/") {
+      const end = src.indexOf("\n", i);
+      i = end < 0 ? src.length : end;
+    } else if (c === "/" && src[i + 1] === "*") {
+      const end = src.indexOf("*/", i + 2);
+      i = end < 0 ? src.length : end + 2;
+    } else if (c === '"' || c === "'" || c === "`") {
+      let j = i + 1;
+      let depth = 0;
+      let interpolated = false;
+      while (j < src.length) {
+        const d = src[j];
+        if (d === "\\") j += 2;
+        else if (c === "`" && depth === 0 && d === "$" && src[j + 1] === "{") { interpolated = true; depth = 1; j += 2; }
+        else if (depth > 0) { depth += d === "{" ? 1 : d === "}" ? -1 : 0; j++; }
+        else if (d === c || (c !== "`" && d === "\n")) break;
+        else j++;
+      }
+      strings.push({ value: src.slice(i + 1, j), interpolated });
+      code += c + c;
+      i = j + 1;
+    } else {
+      code += c;
+      i++;
+    }
+  }
+  return { strings, code };
+}
+
+// A template string that builds a local file path: every static piece is
+// path-like, and there is a folder in front of the interpolation or a file
+// extension after it (`media/lines/${id}.mp3`, `${dir}/clip.mp4`).
+function templatePath(raw) {
+  const pieces = raw.split(/\$\{(?:[^{}]|\{[^{}]*\})*\}/);
+  if (pieces.length < 2 || pieces.some((p) => !/^[\w./-]*$/.test(p))) return false;
+  const [head, tail] = [pieces[0], pieces.at(-1)];
+  if (SCHEME.test(head)) return false;
+  return head.includes("/") || ASSET_EXT.test(tail);
+}
+
+// Calls that load a file from a value check can't read.
+// `code` has every string emptied, so a value starts with a name or call, or
+// with an emptied string joined by + ('media/' + id + '.mp3').
+const COMPUTED = "(?:(?![\\s)\"'`])|([\"'`])\\1\\s*\\+)";
+const COMPUTED_LOADS = [
+  { name: "fetch(…)", re: new RegExp(String.raw`(?<![\w$.])fetch\s*\(\s*` + COMPUTED) },
+  { name: "new Audio(…)", re: new RegExp(String.raw`\bnew\s+Audio\s*\(\s*` + COMPUTED) },
+  { name: ".src = …", re: new RegExp(String.raw`\.src\s*=\s*(?!=)(?!URL\.createObjectURL)` + COMPUTED) },
+];
+
+// Every file the released page needs, following references through the files
+// it bundles: index.html's own refs (localRefs), the paths quoted in its inline
+// scripts, and in each bundled .js or .json the quoted paths, in each .css its
+// url()s and @imports, until nothing new turns up. A script path resolves against
+// the page first (that is how fetch() and Audio resolve; an ES import resolves
+// against its module, so a same-named file at the root wins, as it does in the
+// importer's rewrite) and then the script's own folder; a stylesheet's against
+// its own folder first. A quoted path counts only when it names a real file, so
+// ordinary strings never get bundled.
+//
+// `pathExists(path)` answers for a decoded deck-relative path: true, false, "outside"
+// or "hosted"; `read(path)` returns a file's text (omitted for a hosted deck,
+// which has no folder); `isDir(path)` lets a quoted path in a real subfolder
+// that names no file be reported as missing (one at the deck root could be
+// anything, a vendored library's own "./worker.js" say, so it is left alone).
+// Returns { files: [{ path, from }], missing: [{ ref, from }], templates: [{ from, samples }], computed: [{ from, calls }] }:
+// `from` is "html" for index.html's own attribute refs, "index.html" for a path
+// quoted in its inline scripts, or the bundled file that named it.
+export function deckFiles(html, { pathExists: exists = () => false, read, isDir = () => false } = {}) {
+  const files = new Map();
+  const queue = [];
+  const missing = [];
+  const templates = [];
+  const computed = [];
+  const add = (path, from) => {
+    if (files.has(path)) return;
+    files.set(path, from);
+    queue.push(path);
+  };
+  for (const ref of localRefs(html)) {
+    const path = deckPath("", ref);
+    if (path) add(path, "html");
+  }
+  // `url` is true for a CSS url()/@import, which is a file reference whatever its extension.
+  const quoted = (value, from, dirs, { url = false } = {}) => {
+    if (url ? !value || SCHEME.test(value) || value.startsWith("#") : !isScriptPath(value)) return;
+    const candidates = [...new Set(dirs.map((d) => deckPath(d, value)).filter(Boolean))];
+    const found = candidates.find((p) => exists(p) === true);
+    // Missing only where the browser would look (the page for a script, the
+    // stylesheet's folder for CSS), and only in a real subfolder there.
+    if (found) add(found, from);
+    else if (candidates.length && candidates.every((p) => exists(p) === false) && dirOf(candidates[0]) && isDir(dirOf(candidates[0])) && !missing.some((m) => m.ref === value && m.from === from)) missing.push({ ref: value, from });
+  };
+  const scanJs = (src, from, dir, { json = false } = {}) => {
+    const { strings, code } = jsStrings(src);
+    if (json) {
+      for (const s of strings) quoted(s.value, from, ["", dir]);
+      return;
+    }
+    const built = [];
+    for (const s of strings) {
+      if (!s.interpolated) quoted(s.value, from, ["", dir]);
+      else if (templatePath(s.value)) built.push(`\`${s.value}\``);
+    }
+    if (built.length) templates.push({ from, samples: [...new Set(built)] });
+    const calls = COMPUTED_LOADS.filter((l) => l.re.test(code)).map((l) => l.name);
+    if (calls.length) computed.push({ from, calls });
+  };
+  for (const [, attrs, body] of uncommented(html).matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+    if (!/\ssrc\s*=/i.test(attrs) && !/\stype\s*=\s*["']?(?:application\/(?:ld\+)?json|importmap)/i.test(attrs)) scanJs(body, "index.html", "");
+  }
+  while (read && queue.length) {
+    const path = queue.shift();
+    if (!/\.(?:m?js|css|json)$/i.test(path) || exists(path) !== true) continue;
+    const text = read(path);
+    const dir = dirOf(path);
+    if (/\.css$/i.test(path)) {
+      const css = text.replace(/\/\*[\s\S]*?\*\//g, "");
+      for (const m of css.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"\s]+))\s*\)|@import\s+(?:"([^"]*)"|'([^']*)')/gi)) {
+        const ref = m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5];
+        quoted(ref.trim(), path, [dir, ""], { url: true });
+      }
+    } else scanJs(text, path, dir, { json: /\.json$/i.test(path) });
+  }
+  return { files: [...files].map(([path, from]) => ({ path, from })), missing, templates, computed };
+}
+
 export function phraseList(value) {
   if (!value) return [];
   if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
@@ -359,9 +533,13 @@ export function htmlErrors(html, { exists = () => true, forbid = [], script = ""
     else if (!found) errs.push(MESSAGES.localRef(ref));
   }
   const page = textOf(uncommented(html).replace(/<(script|style)\b[\s\S]*?<\/\1>/g, " ")).toLowerCase();
+  // The raw HTML too (alt text, <title>, meta content, inline script), less
+  // attribute values that are URLs: the player's own src (PLAYER_V1) names
+  // decks.hypersocial.ai, so forbidding the brand would otherwise always fail.
+  const raw = withoutUrlAttrs(uncommented(html)).toLowerCase();
   for (const phrase of phraseList(forbid)) {
     const p = phrase.toLowerCase();
-    if (page.includes(p) || uncommented(html).toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "index.html"));
+    if (page.includes(p) || raw.includes(p)) errs.push(MESSAGES.forbidden(phrase, "index.html"));
     if (script.toLowerCase().includes(p)) errs.push(MESSAGES.forbidden(phrase, "script.md"));
   }
   return errs;
@@ -547,6 +725,9 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
   }
   const exists = opts.hosted ? () => "hosted" : (opts.exists ?? (() => true));
   const errors = htmlErrors(html, { exists, forbid, script, hosted: !!opts.hosted });
+  // Without a folder (hosted, or a caller that passes no reader) only the inline scripts are read.
+  const walked = deckFiles(html, opts.hosted ? {} : { pathExists: opts.pathExists, read: opts.read, isDir: opts.isDir });
+  for (const m of walked.missing) errors.push(MESSAGES.scriptRef(m.ref, m.from));
   const ids = slides(html).map((s) => s.id);
   const player = playerScript(html);
   let manifest = null;
@@ -602,6 +783,8 @@ export async function checkSources({ html, script = "" }, opts = {}, { fetch: fe
     }
   }
   const warnings = transitionWarnings(html, script, manifest);
+  for (const t of walked.templates) warnings.push(MESSAGES.scriptTemplate(t.from, t.samples));
+  for (const c of walked.computed) warnings.push(MESSAGES.scriptComputed(c.from, c.calls));
   if (opts.hosted) {
     for (const url of absoluteRefs(html)) if (!isHostedAsset(url) && /\.(png|jpe?g|gif|webp|avif|svg|mp4|webm|mov)(\?|#|$)/i.test(url)) warnings.push(MESSAGES.hotlink(url));
     warnings.push(MESSAGES.layoutUnchecked(HOSTED_LAYOUT_WHY));

package/src/commands.mjs

@@ -58,6 +58,7 @@ async function deckStats(pos, opts) {
   console.log(`  unique viewers: ${s.viewers}`);
   console.log(`  avg engaged:    ${fmtMs(s.avgMs)}`);
   console.log(`  total engaged:  ${fmtMs(s.totalMs)}`);
+  if (s.view !== undefined) console.log(`  plays as:       ${s.view ?? "as its HTML says"}${s.viewToggle === false ? " (viewer toggle off)" : ""}${s.usesPlayer === false ? " (won't apply: the deck doesn't load player/v1)" : ""}`);
   if (s.recent?.length) {
     console.log("  recent:");
     for (const r of s.recent) {
@@ -153,6 +154,31 @@ async function deckForward(pos, opts) {
   console.log(`OK forwarding ${mode} for deck ${slug} (links with their own setting keep it)`);
 }
 
+const VIEW_USAGE = "usage: deck view <slug> [slides|scroll|default] [--toggle on|off]";
+const VIEWS = { slides: "slides", scroll: "scroll", default: null };
+async function deckView(pos, opts) {
+  const [slug, mode] = pos;
+  const toggle = opts.toggle;
+  if (!slug || (mode === undefined && !Object.hasOwn(opts, "toggle"))) throw new Error(VIEW_USAGE);
+  if (mode !== undefined && !Object.hasOwn(VIEWS, mode)) throw new Error(VIEW_USAGE);
+  // A trailing --toggle with no value is a mistake, not "leave it".
+  if (Object.hasOwn(opts, "toggle") && toggle !== "on" && toggle !== "off") throw new Error(VIEW_USAGE);
+  const out = await ops.setDeckView(opts, slug, {
+    view: mode === undefined ? undefined : VIEWS[mode],
+    viewToggle: toggle === undefined ? undefined : toggle === "on",
+  });
+  if (opts.json) return void console.log(JSON.stringify(out, null, 2));
+  const said = [];
+  if (mode !== undefined) said.push(mode === "default" ? "opens as its HTML says" : `opens as ${mode}`);
+  if (toggle !== undefined) said.push(`viewer toggle ${toggle}`);
+  if (out.applies === false) {
+    console.log(`OK deck ${slug} ${said.join(", ")} (saved)`);
+    console.warn(`warning: ${out.warning}`);
+    return;
+  }
+  console.log(`OK deck ${slug} ${said.join(", ")} (every link, on its next load)`);
+}
+
 function shareUrl(pos, opts) {
   const [token] = pos;
   if (!token) throw new Error("usage: share url <token>");
@@ -264,6 +290,7 @@ async function importDeck(pos, opts) {
     console.log(`  html:   ${(out.bytes / 1024).toFixed(1)} KB`);
     console.log(`  deck:   ${out.deckUrl}`);
   }
+  for (const w of out.warnings ?? []) console.warn(`warning: ${w}`);
 }
 
 async function importDesignDeck(pos, opts) {
@@ -304,9 +331,12 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open|rm|forward
+  deck list|stats|open|rm|forward|view
   deck forward on|off <slug>
                    whether viewers can forward the deck's links (on by default; a link's own setting wins)
+  deck view <slug> [slides|scroll|default] [--toggle on|off]
+                   how the deck opens in the player (default: as its HTML says, data-view or slides) and
+                   whether viewers get the slides/scroll toggle (on by default). Every link, next load; no re-release.
   deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--no-brand] [--dir <path>]
                    scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md,
                    in your saved brand's colours, fonts and logo (--no-brand: the template's look)
@@ -676,8 +706,8 @@ function commandTable(pos, rest, opts) {
     },
     check: async () => {
       const { check } = await import("./check.mjs");
-      const { hostedCheck } = await import("./source.mjs");
-      const result = opts.hosted ? await hostedCheck(opts, { slug: pos[1], forbid: opts.forbid, maxDuration: opts["max-duration"] }) : await check(pos.slice(1), opts);
+      const { hostedCheckCli } = await import("./source.mjs");
+      const result = opts.hosted ? await hostedCheckCli(opts, { slug: pos[1], forbid: opts.forbid, maxDuration: opts["max-duration"] }) : await check(pos.slice(1), opts);
       if (opts.hosted && !opts.json) {
         console.log(`deck "${pos[1]}" rev ${result.rev}: ${result.slides} slides${result.totalDuration != null ? `, ${result.totalDuration}s narrated` : ""}`);
         for (const e of result.errors) console.log(`  - ${e}`);
@@ -689,8 +719,8 @@ function commandTable(pos, rest, opts) {
     },
     release: async () => {
       if (opts.hosted) {
-        const { hostedRelease } = await import("./source.mjs");
-        const out = await hostedRelease(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid, captionsOnly: opts["captions-only"] });
+        const { hostedReleaseCli } = await import("./source.mjs");
+        const out = await hostedReleaseCli(opts, { slug: pos[1], recipients: opts.recipients, qa: opts.qa, title: opts.title, forbid: opts.forbid, captionsOnly: opts["captions-only"] }, opts.json ? { log: (line) => console.error(line) } : {});
         if (opts.json) return void console.log(JSON.stringify(out, null, 2));
         console.log(`✓ released ${out.slug} rev ${out.rev}\n  deck: ${out.deckUrl}`);
         const who = presenterLine(out.presenter);
@@ -849,6 +879,7 @@ function commandTable(pos, rest, opts) {
     "deck open": () => deckOpen(rest, opts),
     "deck rm": () => deckRemove(rest, opts),
     "deck forward": () => deckForward(rest, opts),
+    "deck view": () => deckView(rest, opts),
     "share new": () => shareNew(rest, opts),
     "share list": () => shareList(rest, opts),
     "share on": () => shareToggle(rest, opts, true),

package/src/deckPlayer.mjs

@@ -0,0 +1,45 @@
+// Whether a deck runs on the Hyperdecks player (player/v1). One rule, shared by
+// Convex (decks.usesPlayer), the share route (owner chip vs fallback pill), the
+// importers and the CLI, so they never disagree. Scroll mode, the viewer
+// slides/scroll toggle and the owner chip all live in player/v1; a deck that
+// runs its own runtime (a legacy copy-and-swap deck.js, a plain HTML export)
+// gets none of them.
+
+export const loadsPlayer = (html) => /\/player\/v1\/player\.js\b/.test(String(html ?? ""));
+
+const SCRIPT_SRC = /<script\b[^>]*\ssrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>/gi;
+const MAX_SCRIPT_NAME = 120;
+
+// The deck's own entry script, for the warning ("it runs deck.js"): its first
+// module script, else its first script with a src. Only the file name, so
+// https://cdn.example/js/deck.js reads as deck.js. Null when
+// the deck loads player/v1, has no script with a src, or its script is an
+// uploaded asset (a storage URL names no file).
+export function ownScript(html) {
+  const doc = String(html ?? "").replace(/<!--[\s\S]*?-->/g, "");
+  if (loadsPlayer(doc)) return null;
+  const tags = [...doc.matchAll(SCRIPT_SRC)].map((m) => ({ tag: m[0], src: (m[1] ?? m[2] ?? m[3] ?? "").trim() })).filter((s) => s.src);
+  const pick = tags.find((s) => /\stype\s*=\s*["']?module\b/i.test(s.tag)) ?? tags[0];
+  // An imported asset's src is a storage URL (…/api/storage/<uuid>): no name to show.
+  if (!pick || /\/api\/storage\//.test(pick.src)) return null;
+  const name = pick.src.split(/[?#]/)[0].split("/").filter(Boolean).pop() || pick.src;
+  return name.slice(0, MAX_SCRIPT_NAME);
+}
+
+// What Convex stores on the deck row.
+export function deckPlayer(html) {
+  if (loadsPlayer(html)) return { usesPlayer: true, ownScript: undefined };
+  return { usesPlayer: false, ownScript: ownScript(html) ?? undefined };
+}
+
+const runs = (script) => (script ? ` (it runs its own ${script})` : "");
+
+// Import: a warning, never a refusal (plain HTML exports are legitimate decks).
+export const importPlayerWarning = (script) =>
+  `deck doesn't load player/v1${runs(script)}: scroll mode, the owner chip and the viewer toggle won't apply`;
+
+// set_deck_view / `deck view` on such a deck: the value is saved for a later
+// rebuild on player/v1, but does nothing today.
+export const viewPlayerWarning = (slug, script) =>
+  `${slug} doesn't load player/v1${runs(script)}, so slides/scroll and the viewer toggle won't apply. ` +
+  "The setting is saved and takes effect once the deck is rebuilt on player/v1 (deck_guide explains the format).";

package/src/importer.mjs

@@ -180,6 +180,33 @@ export function rewriteHtmlAssetUrls(html, htmlEntry, assets, uploadedByName) {
   return rewriteTextRefs(rewriteCssUrls(out, assetMap), assetMap);
 }
 
+// One text asset rewritten against the uploaded URLs.
+export function rewriteTextAsset(asset, assets, uploadedByName) {
+  const text = textFromBytes(asset.data);
+  return asset.contentType === "text/css"
+    ? rewriteCssAssetUrls(text, asset.sourcePath, assets, uploadedByName)
+    : rewriteTextAssetUrls(text, asset.sourcePath, assets, uploadedByName);
+}
+
+// The text assets in the order they can be saved: each round holds the ones
+// that name no text asset still unsaved. Saving a name again deletes its old
+// copy, so a script rewritten before the file it fetches is saved would embed a
+// dead URL. A cycle (two scripts naming each other) goes last as one round, its
+// refs to each other left relative.
+export function textAssetRounds(assets) {
+  const PENDING = "hd-pending:";
+  const rounds = [];
+  let pending = assets.filter(isTextAsset);
+  while (pending.length) {
+    const marks = new Map(pending.map((a) => [a.name, PENDING + a.name]));
+    const ready = pending.filter((a) => !rewriteTextAsset(a, assets, marks).split(PENDING + a.name).join("").includes(PENDING));
+    const round = ready.length ? ready : pending;
+    rounds.push(round);
+    pending = pending.filter((a) => !round.includes(a));
+  }
+  return rounds;
+}
+
 export function isTextAsset(asset) {
   const type = String(asset.contentType || "").split(";")[0].trim().toLowerCase();
   return type.startsWith("text/") || TEXT_TYPES.has(type);
@@ -206,12 +233,23 @@ function rewriteCssUrls(input, assetMap) {
   });
 }
 
+// Quoted strings that name an uploaded file. A pair that names nothing gives
+// up only its opening quote, so one apostrophe ("Don't stop", a data-note's
+// "company's") can't throw the pairing off for every path after it.
 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;
-  });
+  const text = rewriteEscapedTextRefs(input, assetMap);
+  const pair = /(["'`])([^"'`]+)\1/g;
+  let out = "";
+  let from = 0;
+  for (let m = pair.exec(text); m; m = pair.exec(text)) {
+    const [match, quote, raw] = m;
+    const url = !(quote === "`" && raw.includes("${")) && resolveLocalUrl(raw, assetMap);
+    if (url) {
+      out += `${text.slice(from, m.index)}${quote}${url}${quote}`;
+      from = m.index + match.length;
+    } else pair.lastIndex = m.index + 1;
+  }
+  return out + text.slice(from);
 }
 
 function rewriteEscapedTextRefs(input, assetMap) {

package/src/ops.mjs

@@ -1,3 +1,4 @@
+import { deckPlayer, importPlayerWarning, viewPlayerWarning } from "./deckPlayer.mjs";
 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";
@@ -6,10 +7,10 @@ import {
   bytesFromText,
   isTextAsset,
   prepareDeckImport,
-  rewriteCssAssetUrls,
   rewriteHtmlAssetUrls,
-  rewriteTextAssetUrls,
+  rewriteTextAsset,
   slugify,
+  textAssetRounds,
   textFromBytes,
   titleFromFilename,
 } from "./importer.mjs";
@@ -26,6 +27,12 @@ export async function listDecks(opts = {}) {
     status: d.status,
     ownerEmail: d.ownerEmail ?? null,
     hasHtml: !!(d.html || d.htmlStorageId || d.hasHtml),
+    // How it opens (null: as its HTML says) and whether viewers may switch.
+    view: d.view ?? null,
+    viewToggle: d.viewToggle !== false,
+    // false: the deck runs its own player, so view/viewToggle do not apply
+    // (null: not known yet, treated as on).
+    usesPlayer: d.usesPlayer ?? null,
   }));
 }
 
@@ -466,6 +473,32 @@ export async function setDeckForwarding(opts, slug, allowForward) {
   return { slug, allowForward: !!allowForward };
 }
 
+// How a deck opens in the player and whether viewers may switch: view is
+// "slides", "scroll", or null to follow the deck's own HTML again; viewToggle
+// true/false. Either may be left out; both go in one owner-only mutation, so a
+// failure changes neither.
+// Applies on every link's next load (the route injects it), with no re-release.
+export const DECK_VIEWS = ["slides", "scroll"];
+export async function setDeckView(opts, slug, { view, viewToggle } = {}) {
+  if (!slug) throw new Error("slug is required");
+  if (view === undefined && viewToggle === undefined) throw new Error("give a view (slides, scroll or default) and/or a viewToggle");
+  if (view !== undefined && view !== null && !DECK_VIEWS.includes(view)) throw new Error(`view must be slides, scroll or null (got ${JSON.stringify(view)})`);
+  const res = await (await client(opts)).mutation(api.decks.setViewSettings, {
+    slug,
+    ...(view !== undefined ? { view } : {}),
+    ...(viewToggle !== undefined ? { viewToggle: !!viewToggle } : {}),
+  });
+  // Saved either way; a deck on its own player says the setting won't apply.
+  const applies = res?.applies !== false;
+  return {
+    slug,
+    ...(view !== undefined ? { view } : {}),
+    ...(viewToggle !== undefined ? { viewToggle: !!viewToggle } : {}),
+    applies,
+    ...(applies ? {} : { warning: viewPlayerWarning(slug, res?.ownScript ?? null) }),
+  };
+}
+
 // Register a new deck (draft) you own. Refuses any slug that already exists:
 // upsert would otherwise reset your own live deck to a draft and rename it.
 export async function createDeck(opts, { slug, title }) {
@@ -585,23 +618,24 @@ export async function importDeckFromBytes(opts = {}, fields = {}, adapter = {})
       deckCreated = true;
     }
 
-    // Phase 1: upload every asset and fully populate uploadedByName.
-    await mapWithConcurrency(parsed.assets, concurrency, async (asset, index) => {
+    // Phase 1: upload every binary asset.
+    const binary = parsed.assets.filter((a) => !isTextAsset(a));
+    await mapWithConcurrency(binary, 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);
-    });
+    // Phase 2 (after phase 1): text assets, rewritten against the URLs saved so
+    // far, each after the text assets it names (textAssetRounds). Saving a name
+    // twice deletes the first copy, so a script must never embed a URL from a
+    // save that a later save replaces.
+    let done = binary.length;
+    for (const round of textAssetRounds(parsed.assets)) {
+      await mapWithConcurrency(round, concurrency, async (asset) => {
+        onStage(`uploading asset ${++done}/${parsed.assets.length}: ${asset.name}`);
+        await saveDeckAsset(asset, bytesFromText(rewriteTextAsset(asset, parsed.assets, uploadedByName)), asset.contentType);
+      });
+    }
 
     onStage("storing deck HTML");
     const html = rewriteHtmlAssetUrls(parsed.html, parsed.htmlEntry, parsed.assets, uploadedByName);
@@ -613,12 +647,17 @@ export async function importDeckFromBytes(opts = {}, fields = {}, adapter = {})
     await c.mutation(api.decks.setHtmlStorage, { slug, storageId: htmlStorageId, bytes: htmlBytes.byteLength });
 
     const t = target(opts);
+    // A warning, never a refusal: plain HTML exports are legitimate decks.
+    // Read before the asset rewrite, while the script still has its own name.
+    const player = deckPlayer(parsed.html);
     return {
       slug,
       title,
       status,
       assets: parsed.assets.length,
       bytes: htmlBytes.byteLength,
+      usesPlayer: player.usesPlayer,
+      warnings: player.usesPlayer ? [] : [importPlayerWarning(player.ownScript)],
       deployment: t.name,
       // The owner-facing dashboard view (Preview / Stats / Share / Present), not
       // the raw /d/<slug> storage redirect.

package/src/release.mjs

@@ -12,12 +12,12 @@
 //   5. creates one share per --to (paired in order with --email) and prints the URLs.
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { join, posix } from "node:path";
+import { join } from "node:path";
 import { zipSync } from "fflate";
 import * as ops from "./ops.mjs";
 import { withAvatar } from "./presenter.mjs";
 import { target } from "./runtime.mjs";
-import { checkDeck, localRefs, resolveDeckDir } from "./check.mjs";
+import { checkDeck, deckFiles, deckFolder, resolveDeckDir } from "./check.mjs";
 import { narrate as runNarrate } from "./narrate.mjs";
 
 const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -47,18 +47,23 @@ export function deckCommit(deckDir) {
   return execFileSync("git", ["-C", deckDir, "rev-parse", "--short", "HEAD"], { encoding: "utf8" }).trim();
 }
 
-// What import uploads: the page alone, or a zip of the page and its local files.
+// What import uploads: the page alone, or a zip of the page and its local files:
+// what index.html names, and what the scripts and stylesheets it bundles name in
+// turn (deckFiles). `added` maps each bundled script or stylesheet to the files
+// it brought in, so release can say what came from where.
 // `presenter` (from avatars.presenterFor) puts the owner's avatar on the
 // uploaded page's player tag; the committed index.html is never changed.
 export function releaseBundle(deckDir, presenter = null) {
   const raw = readFileSync(join(deckDir, "index.html"));
   const html = presenter ? Buffer.from(withAvatar(raw.toString("utf8"), presenter)) : raw;
-  // check has already refused refs that leave the folder or do not decode.
-  const refs = [...new Set(localRefs(html.toString("utf8")).map((r) => posix.normalize(decodeURIComponent(r)).replace(/^(\.?\/)+/, "")))];
-  if (!refs.length) return { bytes: html, filename: "index.html", files: ["index.html"] };
+  // check has already refused refs that leave the folder or do not resolve.
+  const found = deckFiles(html.toString("utf8"), deckFolder(deckDir)).files.filter((f) => f.path !== "index.html");
+  const added = {};
+  for (const f of found) if (f.from !== "html") (added[f.from] ??= []).push(f.path);
+  if (!found.length) return { bytes: html, filename: "index.html", files: ["index.html"], added };
   const files = { "index.html": html };
-  for (const ref of refs) files[ref] = readFileSync(join(deckDir, ref));
-  return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files) };
+  for (const f of found) files[f.path] = readFileSync(join(deckDir, f.path));
+  return { bytes: Buffer.from(zipSync(files)), filename: "deck.zip", htmlFile: "index.html", files: Object.keys(files), added };
 }
 
 // From the CLI, parse() collects opts.recipients in order (each --email follows
@@ -71,14 +76,16 @@ export function recipients(opts) {
 }
 
 export async function release(pos, opts = {}, io = {}) {
-  const { log = (line) => console.log(line), changes = deckChanges, untracked = untrackedFiles, commit = deckCommit, narrate = runNarrate, fetch, cwd } = io;
+  const { log = (line) => console.log(line), changes = deckChanges, untracked = untrackedFiles, commit = deckCommit, narrate = runNarrate, fetch, cwd, measure, measureFit } = io;
   const deckDir = resolveDeckDir(pos[0], cwd);
   const to = recipients(opts);
 
   const dirty = changes(deckDir);
   if (dirty) throw new Error(`refusing to release: ${deckDir} has uncommitted changes\n${dirty}\ncommit them first so the release corresponds to a commit`);
 
-  const checked = await checkDeck(deckDir, opts, { fetch, cwd });
+  // Always with the layout check: a slide that overflows a phone must not ship
+  // (the hosted release runs the same measurement, hostedLayoutCheck in source.mjs).
+  const checked = await checkDeck(deckDir, { ...opts, layout: true }, { fetch, cwd, ...(measure ? { measure } : {}), ...(measureFit ? { measureFit } : {}) });
   const slug = opts.slug || checked.slug;
   if (!SLUG.test(slug)) throw new Error(`"${slug}" is not a deck slug (lowercase letters, digits, dashes): rename the folder or pass --slug`);
   if (checked.errors.length) throw new Error(`check failed for ${slug}:\n${checked.errors.map((e) => `  - ${e}`).join("\n")}`);
@@ -86,6 +93,8 @@ export async function release(pos, opts = {}, io = {}) {
   const loose = untracked(deckDir, bundle.files);
   if (loose.length) throw new Error(`refusing to release: git does not track ${loose.join(", ")} (ignored or never added); commit them so the release corresponds to a commit`);
   log(`✓ check passed: ${checked.slides} slides, ${checked.totalDuration}s`);
+  for (const w of checked.warnings) log(`  ⚠ ${w}`);
+  for (const [from, paths] of Object.entries(bundle.added)) log(`  +${paths.length} file(s) referenced from ${from}: ${paths.join(", ")}`);
 
   // Cached slides cost nothing, so this only renders what changed since the commit.
   // Only the options narrate understands: an undefined --slide/--voice key would fail its flag check.

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.8.0";
+export const VERSION = "0.8.2";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -98,6 +98,9 @@ export const api = {
     listForViewer: makeFunctionReference("decks:listForViewer"),
     remove: makeFunctionReference("decks:remove"),
     setAllowForward: makeFunctionReference("decks:setAllowForward"),
+    setView: makeFunctionReference("decks:setView"),
+    setViewToggle: makeFunctionReference("decks:setViewToggle"),
+    setViewSettings: makeFunctionReference("decks:setViewSettings"),
     setHtmlStorage: makeFunctionReference("decks:setHtmlStorage"),
     upsert: makeFunctionReference("decks:upsert"),
     whoami: makeFunctionReference("decks:whoami"),

package/src/source.mjs

@@ -6,15 +6,58 @@
 //   hyperdecks check <slug> --hosted
 //   hyperdecks release <slug> --hosted [--to "<name>" [--email e]]... [--qa]
 //   hyperdecks asset add <slug> <file|url> [--name n]
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { basename, extname, join, resolve } from "node:path";
 import { api, client, uploadBytes } from "./runtime.mjs";
-import { SOURCE_FILES, getDeckSource, uploadDeckAsset, writeDeckSource } from "./hosted.mjs";
+import { HOSTED_LAYOUT_WHY, MESSAGES } from "./checkRules.mjs";
+import { SOURCE_FILES, getDeckSource, hostedCheck, hostedRelease, uploadDeckAsset, writeDeckSource } from "./hosted.mjs";
 
 export * from "./hosted.mjs";
 
 // ---- CLI ------------------------------------------------------------------
 
+// The browser half of check --layout for a hosted draft. The hosted check runs
+// in Convex and can't open a browser (HOSTED_LAYOUT_WHY), so the CLI measures
+// the draft's index.html here, from a temp folder, with check.mjs's Chromium
+// code. Returns the rev it measured, and { errors, warnings } as check --layout.
+export async function hostedLayoutCheck(opts, { slug } = {}, { measure, measureFit } = {}) {
+  if (!slug) throw new Error("slug is required");
+  const got = await getDeckSource(opts, { slug, file: "index.html" });
+  const html = got.files?.["index.html"];
+  if (typeof html !== "string") throw new Error(`hosted deck "${slug}" has no index.html`);
+  const { layoutCheck } = await import("./check.mjs");
+  const dir = mkdtempSync(join(tmpdir(), "hyperdecks-hosted-layout-"));
+  try {
+    writeFileSync(join(dir, "index.html"), html);
+    return { rev: got.rev, ...(await layoutCheck(dir, html, null, { ...(measure ? { measure } : {}), ...(measureFit ? { measureFit } : {}) })) };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// check <slug> --hosted [--layout]: the hosted rules, plus the layout measured
+// here when --layout asks for it (in place of the hosted check's "layout not
+// checked" warning).
+export async function hostedCheckCli(opts, args, io = {}) {
+  const result = await hostedCheck(opts, args);
+  if (!opts.layout) return result;
+  const layout = await hostedLayoutCheck(opts, args, io);
+  const errors = [...result.errors, ...layout.errors];
+  const unchecked = MESSAGES.layoutUnchecked(HOSTED_LAYOUT_WHY);
+  return { ...result, errors, passed: errors.length === 0, warnings: [...new Set([...result.warnings.filter((w) => w !== unchecked), ...layout.warnings])] };
+}
+
+// release <slug> --hosted: the same layout check the local release runs, then
+// the release pinned to the rev that was measured, so a later write can't slip
+// an unmeasured draft through. A slide that overflows a phone refuses it.
+export async function hostedReleaseCli(opts, args, { log = (line) => console.log(line), ...io } = {}) {
+  const layout = await hostedLayoutCheck(opts, args, io);
+  if (layout.errors.length) throw new Error(`check failed for ${args.slug}:\n${layout.errors.map((e) => `  - ${e}`).join("\n")}`);
+  for (const w of layout.warnings) log(`  ⚠ ${w}`);
+  return hostedRelease(opts, { ...args, rev: layout.rev });
+}
+
 export async function sourcePull(pos, opts = {}, { log = (line) => console.log(line), cwd = process.cwd() } = {}) {
   const [slug, dirArg] = pos;
   if (!slug) throw new Error("usage: source pull <slug> [dir]");

package/templates/script.md

@@ -10,8 +10,11 @@ One `## <slide-id>` block per slide, in slide order; the id is the slide's
 phrase (4 to 85 characters, two lines in the bubble). Aim for 150 to 180 s in
 all. Holds: 0.4 s by default, `hold: 1.5` for a number, chart or reveal,
 `hold: 2` on interactive slides. Stage tags become
-cues at the word before them: [wave], [mood: excited], [reveal: #detail],
-[go: #detail] (the presenter flies beside it; [go: slot] brings it home),
+cues at the word before them: [wave], [mood: excited], [reveal: #detail]
+(replays from the start when the slide does; the head glances at it unless
+a [look] or [go] is right beside it),
+[go: #detail] (it grows, its siblings fade and the presenter flies beside it,
+or looks at it when there is no room; [go: slot] brings it home),
 [look: h2] (the head looks at it), [custom: confetti]. `presenterStyle: stage`
 above sets the deck's presenter; `presenter-style: corner` under a heading sets
 one slide's. `transition: drift` above is how every slide enters;