@hypersocial/decks-cli 0.8.0 → 0.8.1

package/package.json

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

package/skills/hyperdecks/SKILL.md

@@ -215,6 +215,13 @@ The deck contract (`check` enforces each line):
   `narrate` fills `data-manifest`; do not edit it by hand.
 - 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 +454,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 +496,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 |
@@ -527,6 +553,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/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,7 +142,17 @@ 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"),
   };
 }
 
@@ -144,7 +162,7 @@ export async function checkDeck(dirArg, opts = {}, { fetch: fetchImpl = globalTh
   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

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 } };
 
@@ -295,6 +299,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);
@@ -547,6 +718,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 +776,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/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

@@ -6,10 +6,10 @@ import {
   bytesFromText,
   isTextAsset,
   prepareDeckImport,
-  rewriteCssAssetUrls,
   rewriteHtmlAssetUrls,
-  rewriteTextAssetUrls,
+  rewriteTextAsset,
   slugify,
+  textAssetRounds,
   textFromBytes,
   titleFromFilename,
 } from "./importer.mjs";
@@ -585,23 +585,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);

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
@@ -86,6 +91,7 @@ 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 [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.1";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {

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;