wand-kit 0.2.0 → 0.3.0

package/lib/components.js

@@ -18,12 +18,13 @@
  * content lines. A job's `pages(c)` composes with them and may add its own
  * CSS on top; nothing stops it writing raw markup where no component fits.
  */
+import path from "node:path";
 import { esc } from "./content.js";
 import { url } from "./brand.js";
 
 export const ARROW = `<svg class="arrow deco" viewBox="0 0 10 10" aria-hidden="true"><path d="M2 1 L9 5 L2 9 Z"/></svg>`;
 
-export function bind({ brand, surface, job, content }) {
+export function bind({ brand, surface, job, content, dir: jobDir = process.cwd() }) {
   let n = 0;
   const L = content.L;
   const cls = (c) => (c ? ` ${c}` : "");
@@ -47,13 +48,15 @@ export function bind({ brand, surface, job, content }) {
    * A page (a slide, a sheet, a card) with the chrome: the tag and eyebrow top
    * left, the mark top right, the footer with the running line and the page
    * number. `art` is a brand art role ("cover", "overlay", "closing") or a
-   * file path; `notes` become speaker notes in the .pptx.
+   * file path; `notes` become speaker notes in the .pptx and the presenter
+   * view; `seconds` is the slide's share of the talk, for the presenter's
+   * pace; `motion: "none"` keeps a slide still when the deck animates.
    */
-  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true } = {}) => {
+  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true, seconds = 0, motion = "" } = {}) => {
     n += 1;
     const artSrc = art ? (/[\/.]/.test(art) && !brand.tokens.art[art] ? url(art) : brand.artUrl(art)) : null;
     const eb = job.tag && eyebrow ? `${esc(job.tag)}<span class="bar">|</span>${esc(eyebrow)}` : esc(job.tag || eyebrow || "");
-    return `<section class="page ${dark ? "dark" : "light"}${cls(k)}" data-n="${n}"${notes ? ` data-notes="${esc(notes)}"` : ""}>
+    return `<section class="page ${dark ? "dark" : "light"}${cls(k)}" data-n="${n}"${notes ? ` data-notes="${esc(notes)}"` : ""}${seconds ? ` data-seconds="${seconds}"` : ""}${motion ? ` data-motion="${esc(motion)}"` : ""}>
 ${artSrc ? `<img class="art deco" src="${artSrc}" alt="">${shade ? `<div class="shade deco"></div>` : ""}` : ""}
 ${chrome ? `<div class="eyebrow">${eb}</div>${mark(dark)}` : ""}
 <div class="content">${body}</div>
@@ -104,7 +107,8 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
     return `<div class="card q${emph ? " emph" : ""}${cls(k)}"><p>${esc(text)}</p>${who(name, role)}</div>`;
   };
 
-  const stat = ({ v, k, hero = false }) => `<div class="stat${hero ? " hero" : ""}"><div class="v">${esc(v)}</div><div class="k">${esc(k)}</div></div>`;
+  /** A figure and its key; `count` makes the figure count up as its slide arrives in a talk. */
+  const stat = ({ v, k, hero = false, count = false }) => `<div class="stat${hero ? " hero" : ""}"><div class="v"${count ? ' data-a="count"' : ""}>${esc(v)}</div><div class="k">${esc(k)}</div></div>`;
   const stats = (items) => `<div class="stats">${items.map(stat).join("")}</div>`;
   const delta = (from, to) => `<div class="delta"><span class="from">${esc(from)}</span>${ARROW}<span class="to">${esc(to)}</span></div>`;
 
@@ -130,6 +134,99 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
   const icon = (name, k = "") => brand.glyph(name).replace("<svg", `<svg class="icon deco${cls(k)}" aria-hidden="true"`);
   const tile = (name) => `<div class="tile deco">${icon(name)}</div>`;
 
+  /* ---------------------------------------------------------- motion */
+
+  /** An entrance, as attributes for raw markup: `<div${c.enter("pop", 2)}>`. Kinds: rise (default), fade, pop, grow (bars, up), widen (bars, across), draw (an SVG path with pathLength="1"), count. */
+  const enter = (kind = "", i = null) => ` data-a="${esc(kind)}"${i != null ? ` style="--i:${+i}"` : ""}`;
+  /** Held back until the presenter moves on; steps of one number come in together. */
+  const step = (nth, html, { a = "", tag: t = "div", cls: k = "" } = {}) => `<${t} data-step="${+nth}"${a ? ` data-a="${esc(a)}"` : ""}${k ? ` class="${k}"` : ""}>${html}</${t}>`;
+  /** A figure that counts up from zero as its slide arrives. */
+  const countup = (text, k = "") => `<span data-a="count"${k ? ` class="${k}"` : ""}>${esc(text)}</span>`;
+
+  const fileUrl = (f) => (/^(file|https?|data):/.test(f) ? f : url(path.resolve(jobDir, f)));
+  /** A clip that plays while its slide is on (muted, looping by default); the poster is what the PDF, the PNGs and the .pptx show. */
+  const video = ({ src, poster, autoplay = true, loop = true, label = "", cls: k = "" }) => {
+    if (!poster) throw new Error(`video ${src}: a poster is required, it is the frame every static export shows`);
+    return `<figure class="media video${cls(k)}"${autoplay ? ' data-autoplay="1"' : ""}${label ? ` aria-label="${esc(label)}"` : ""}><img class="poster" src="${fileUrl(poster)}" alt=""><video src="${fileUrl(src)}" muted playsinline preload="none"${loop ? " loop" : ""}></video></figure>`;
+  };
+  /**
+   * A live page (a simulation, a product walk-through) in a frame on the slide.
+   * `src` is one self-contained HTML file; it travels inside the deck. It may
+   * expose window.wandDemo = { play, pause, reset } for the D and R keys.
+   * `min` is the size it is laid out at before being scaled into the frame.
+   */
+  const demo = ({ src, poster, min = [1280, 720], label = "Live demo", cls: k = "" }) => {
+    if (!poster) throw new Error(`demo ${src}: a poster is required (node wand.js poster ${src}), it is the frame every static export shows`);
+    return `<figure class="media demo${cls(k)}" data-demo-src="${fileUrl(src)}" data-min="${min[0]}x${min[1]}" aria-label="${esc(label)}"><img class="poster" src="${fileUrl(poster)}" alt=""><div class="screen"></div></figure>`;
+  };
+
+  /* ------------------------------------------------------- storyboard */
+
+  const tc = (t) => `${Math.floor(t / 60)}:${(t % 60).toFixed(1).padStart(4, "0")}`;
+  /**
+   * A quick frame in the brand's colours, for a shot with no artwork yet:
+   * people as dots, software as labelled boxes, agents as sparks, left to
+   * right with arrows between, and a line under them.
+   */
+  const sketch = ({ people = 0, apps = [], agents = 0, label = "", arrows = true } = {}) => {
+    const groups = [];
+    if (people) groups.push((x) => { const n = Math.min(people, 12), cols = Math.ceil(Math.sqrt(n)), r = 34, g = 96, rows = Math.ceil(n / cols);
+      return Array.from({ length: n }, (_, i) => `<circle class="sk-p" cx="${x + (i % cols - (cols - 1) / 2) * g}" cy="${470 + (Math.floor(i / cols) - (rows - 1) / 2) * g}" r="${r}"/>`).join(""); });
+    if (apps.length) groups.push((x) => apps.slice(0, 4).map((a, i, all) => { const h = 104, y = 470 + (i - (all.length - 1) / 2) * (h + 26);
+      return `<g class="sk-app"><rect x="${x - 190}" y="${y - h / 2}" width="380" height="${h}" rx="18"/><text x="${x}" y="${y + 20}" text-anchor="middle">${esc(a)}</text></g>`; }).join(""));
+    if (agents) groups.push((x) => { const n = Math.min(agents, 6); return Array.from({ length: n }, (_, i) => { const cx = x + ((i % 3) - (Math.min(n, 3) - 1) / 2) * 150, cy = 470 + (Math.floor(i / 3) - (n > 3 ? .5 : 0)) * 150, R = 58, r = 16;
+      return `<path class="sk-s" d="M${cx} ${cy - R}Q${cx + r} ${cy - r} ${cx + R} ${cy}Q${cx + r} ${cy + r} ${cx} ${cy + R}Q${cx - r} ${cy + r} ${cx - R} ${cy}Q${cx - r} ${cy - r} ${cx} ${cy - R}Z"/>`; }).join(""); });
+    const xs = groups.length === 1 ? [960] : groups.length === 2 ? [600, 1320] : [400, 960, 1520];
+    const arrow = (x) => `<path class="sk-arrow" d="M${x - 40} 452h56v-22l40 40-40 40v-22h-56z"/>`;
+    const art = groups.map((g, i) => g(xs[i])).join("") + (arrows ? xs.slice(1).map((x, i) => arrow((xs[i] + x) / 2)).join("") : "");
+    return `<svg class="sk" viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid meet" aria-hidden="true">${art}${label ? `<text class="sk-label" x="960" y="900" text-anchor="middle">${esc(label)}</text>` : ""}</svg>`;
+  };
+
+  /**
+   * A storyboard from a script: the cover, the run of show, one page per shot.
+   * Timing is scratch timing: each voiceover line lasts its words at `wpm`,
+   * with `lead` before and `tail` after; a shot without voiceover holds for
+   * `hold` seconds; `seconds` on a shot overrides the estimate. A frame lands
+   * on its `cue` word. The timeline is kept for the CSV, the captions and the
+   * player in the HTML.
+   * A shot: { act, name, vo, line, camera, motion, onscreen, sound, next,
+   *           lead, tail, hold, seconds, frames: [{ cue, caption, art | img | sketch }] }
+   */
+  const storyboard = ({ title, lede = "", wpm = 150, target = 0, shots = [], dark = true, cover: withCover = true, index = true, audio = "" }) => {
+    let t = 0;
+    const timeline = shots.map((s, i) => {
+      const vo = String(s.vo ?? "").trim(), words = vo ? vo.split(/\s+/).length : 0;
+      const voDur = vo ? +(s.seconds ?? words / (wpm / 60)).toFixed(1) : 0;
+      const lead = vo ? s.lead ?? 0.5 : 0, tail = vo ? s.tail ?? 0.5 : 0;
+      const inT = t, voIn = inT + lead, voOut = voIn + voDur, out = vo ? voOut + tail : inT + (s.hold ?? s.seconds ?? 3);
+      t = +out.toFixed(1);
+      const fr = (s.frames && s.frames.length ? s.frames : [{}]).slice(0, 4).map((f, j, all) => {
+        const at = f.cue && vo ? vo.toLowerCase().indexOf(String(f.cue).toLowerCase()) : -1;
+        // the first frame is on screen from the cut; the others land on their cue words
+        const ft = j === 0 ? inT : at >= 0 ? voIn + voDur * (at / vo.length) : voIn + (voDur * j) / all.length;
+        return { ...f, id: `${String(i + 1).padStart(2, "0")}${"ABCD"[j]}`, t: +ft.toFixed(1), placeholder: !(f.art || f.img || f.sketch) };
+      });
+      return { ...s, n: i + 1, vo, in: +inT.toFixed(1), voIn: +voIn.toFixed(1), voOut: +voOut.toFixed(1), out: t, dur: +(t - inT).toFixed(1), frames: fr };
+    });
+    const total = t;
+    job.__board = { wpm, target, total, audio: audio ? path.resolve(jobDir, audio) : "", shots: timeline.map(({ n, act, name, vo, in: i, voIn, voOut, out, dur, frames }) => ({ n, act: act || "", name: name || "", vo, in: i, voIn, voOut, out, dur, frames: frames.map(({ id, t: ft, cue, placeholder }) => ({ id, t: ft, cue: cue || "", placeholder })) })) };
+
+    const art = (f) => f.art ? f.art : f.img ? `<img src="${fileUrl(f.img)}" alt="">` : f.sketch ? sketch(f.sketch) : `<div class="todo"><span>${esc(f.cue ? `on ‘${f.cue}’` : "frame")}</span></div>`;
+    const DIR = [["line", "The line"], ["camera", "Camera"], ["motion", "Motion"], ["onscreen", "On screen"], ["sound", "Sound"], ["next", "Into next"]];
+    const shotPage = (s) => page({ eyebrow: s.act || "", dark, cls: "shot", notes: s.vo, body: `
+<div class="shot-head"><div class="shot-id"><span class="tag">Shot</span><span class="no">${String(s.n).padStart(2, "0")}</span></div>
+<div class="shot-title"><h2>${esc(s.name || "")}</h2><p class="tc">${tc(s.in)} → ${tc(s.out)} · ${s.dur.toFixed(1)} s${s.vo ? ` · voice ${(s.voOut - s.voIn).toFixed(1)} s` : ""}</p></div></div>
+${s.vo ? `<blockquote class="vo">${esc(s.vo)}</blockquote>` : `<p class="vo none">No voiceover; holds ${s.dur.toFixed(1)} s</p>`}
+<div class="shot-body n${s.frames.length} ${s.frames.length <= 2 ? "side" : "stack"}"><div class="frames n${s.frames.length}">${s.frames.map((f) => `<figure class="frame${f.placeholder ? " placeholder" : ""}" data-frame="${f.id}"><div class="frame-art">${art(f)}</div><figcaption><b>${f.id}</b> · ${tc(f.t)}${f.cue ? ` · on ‘${esc(f.cue)}’` : ""}${f.caption ? `<span>${esc(f.caption)}</span>` : ""}</figcaption></figure>`).join("")}</div>
+${DIR.some(([k]) => s[k]) ? `<dl class="direction">${DIR.filter(([k]) => s[k]).map(([k, l]) => `<div><dt>${l}</dt><dd>${esc(s[k])}</dd></div>`).join("")}</dl>` : ""}</div>` });
+
+    const out = [];
+    if (withCover) out.push(cover({ label: "Storyboard", title: esc(title), lede, meta: `${timeline.length} shots · ${tc(total)}${target ? ` of ${tc(target)}` : ""} · scratch timing at ${wpm} words a minute` }));
+    if (index) for (let i = 0; i < timeline.length; i += 9) out.push(page({ eyebrow: "Run of show", dark, cls: "run", body: `${h("h2")(i ? "Run of show, continued" : "Run of show")}${table({ head: ["Shot", "Act", "Name", "In", "Length"], rows: timeline.slice(i, i + 9).map((s) => [String(s.n).padStart(2, "0"), s.act || "", s.name || "", tc(s.in), `${s.dur.toFixed(1)} s`]) })}` }));
+    timeline.forEach((s) => out.push(shotPage(s)));
+    return out;
+  };
+
   return {
     L, lines: content.lines, esc, accent, split, cap, raw: (s) => s, ARROW, arrow: ARROW,
     page, sec, h1: h("h1"), h2: h("h2"), h3: h("h3"), h4: h("h4"), h5: h("h5"),
@@ -137,6 +234,7 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
     cols, card, chip, strip, phase, flow, table, who, quote, stat, stats, delta, steps, callout, list: listOf,
     cover, closing, chapter, img, icon, tile, mark, wordmark,
     asset: brand.assetUrl, art: brand.artUrl,
+    enter, step, countup, video, demo, sketch, storyboard,
     brand: brand.name, surface: surface.name, count: () => n,
   };
 }
@@ -310,4 +408,52 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .centre{text-align:center;align-items:center}
 .grow{flex:1}
 .spread{justify-content:space-between}
+
+/* media: the poster is what a static export shows; the runtime plays the rest */
+.media{position:relative;margin:0;overflow:hidden;border-radius:calc(var(--m-radius) * var(--radius-k));aspect-ratio:16/9;background:var(--track);border:var(--card-stroke) solid var(--stroke)}
+.media>.poster{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;display:block}
+.media>video{display:none;position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+.media>.screen{position:absolute;inset:0;overflow:hidden}
+
+/* the storyboard: a shot a page, frames left to right, the direction under them */
+.shot .content{display:flex;flex-direction:column;gap:calc(var(--m-gap) * .8)}
+.shot-head{display:flex;align-items:flex-end;gap:calc(var(--m-gap) * 1.2)}
+.shot-id{display:flex;flex-direction:column;line-height:1}
+.shot-id .tag{margin:0 0 .3em}
+.shot-id .no{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-stat);line-height:.9;color:var(--accent);font-variant-numeric:tabular-nums}
+.shot-title h2{margin:0}
+.shot-title .tc{margin:.35em 0 0;font-size:var(--t-sm);color:var(--soft);font-variant-numeric:tabular-nums}
+.vo{margin:0;font-size:var(--t-lead);line-height:1.45;color:var(--ink);max-width:92%;quotes:"\\201C" "\\201D"}
+.vo::before{content:open-quote;color:var(--accent)}
+.vo::after{content:close-quote;color:var(--accent)}
+.vo.none{color:var(--soft);font-size:var(--t-sm)}
+.vo.none::before,.vo.none::after{content:none}
+/* one or two frames: the direction beside them; three or four: under them */
+.shot-body{display:grid;gap:calc(var(--m-gap) * .8) var(--m-col-gap);align-items:start}
+.shot-body.side.n1{grid-template-columns:minmax(0,1.1fr) minmax(0,1fr)}
+.shot-body.side.n2{grid-template-columns:minmax(0,1.7fr) minmax(0,1fr)}
+.shot-body.side .direction{grid-template-columns:minmax(0,1fr);border-top:0;padding-top:0;border-left:var(--card-stroke) solid var(--rule);padding-left:var(--m-col-gap)}
+.frames{display:grid;gap:var(--m-col-gap);align-items:start}
+.frames.n1{grid-template-columns:minmax(0,1fr)}
+.frames.n2{grid-template-columns:repeat(2,minmax(0,1fr))}
+.frames.n3{grid-template-columns:repeat(3,minmax(0,1fr))}
+.frames.n4{grid-template-columns:repeat(4,minmax(0,1fr))}
+.frame{margin:0;display:flex;flex-direction:column;gap:.5em}
+.frame-art{position:relative;aspect-ratio:16/9;overflow:hidden;border-radius:calc(var(--m-radius) * .7 * var(--radius-k));background:var(--track);border:var(--card-stroke) solid var(--stroke)}
+.frame-art>svg,.frame-art>img{position:absolute;inset:0;width:100%;height:100%;display:block}
+.frame-art>img{object-fit:cover}
+.frame figcaption{font-size:var(--t-note);line-height:1.4;color:var(--soft);font-variant-numeric:tabular-nums}
+.frame figcaption b{color:var(--label);font-weight:600}
+.frame figcaption span{display:block;color:var(--text);margin-top:.2em}
+.frame .todo{position:absolute;inset:0;display:grid;place-items:center;border:2px dashed var(--rule);border-radius:inherit}
+.frame .todo span{font-size:var(--t-sm);color:var(--soft)}
+.direction{margin:0;display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:calc(var(--m-gap) * .5) var(--m-col-gap);border-top:var(--card-stroke) solid var(--rule);padding-top:calc(var(--m-gap) * .6)}
+.direction dt{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.14em;text-transform:var(--caps-label);color:var(--label);margin-bottom:.3em}
+.direction dd{margin:0;font-size:var(--t-sm);line-height:1.45;color:var(--text)}
+.sk .sk-p{fill:var(--ink)}
+.sk .sk-app rect{fill:var(--paper);stroke:var(--stroke);stroke-width:5}
+.sk .sk-app text{fill:var(--ink);font-family:var(--face-body);font-size:52px}
+.sk .sk-s{fill:var(--accent)}
+.sk .sk-arrow{fill:var(--soft)}
+.sk .sk-label{fill:var(--text);font-family:var(--face-body);font-size:62px}
 `;

package/lib/engine.js

@@ -109,7 +109,9 @@ function GATES({ min, chars, tokens, families, base }) {
   const lum = (h) => { const c = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255).map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4)); return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]; };
   const contrast = (a, b) => { const x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); };
   const bgOf = (el) => { for (let e = el; e; e = e.parentElement) { const h = toHex(getComputedStyle(e).backgroundColor); if (h) return h; if (e.classList.contains("page")) break; } return null; };
-  const res = { fit: [], overlap: [], brand: [], fonts: [], contrast: [], type: [], measure: [], dash: [], texts: [], notes: [] };
+  const res = { fit: [], overlap: [], brand: [], fonts: [], contrast: [], type: [], measure: [], dash: [], texts: [], notes: [], broken: [],
+    motion: { a: document.querySelectorAll("[data-a]").length, steps: document.querySelectorAll("[data-step]").length, video: document.querySelectorAll(".media.video").length, demo: document.querySelectorAll(".media.demo").length, placeholders: document.querySelectorAll(".frame.placeholder").length } };
+  document.querySelectorAll("img").forEach((im) => { if (im.getAttribute("src") && !(im.complete && im.naturalWidth)) res.broken.push(decodeURIComponent(im.getAttribute("src").replace(/^file:\/\//, "")).split("/").slice(-2).join("/")); });
   const seen = new Set();
   pages.forEach((pg, pi) => {
     const n = pi + 1;
@@ -176,16 +178,21 @@ function GATES({ min, chars, tokens, families, base }) {
  * Build a job: gates, and unless `outputs` is false, the PDF, the PNGs and the
  * sheet in `<job dir>/out/`. Returns { ok, rows, outputs, html, texts }.
  */
-export async function build(jobPath, { outputs: wantOutputs = true, outDir = null, quiet = false } = {}) {
+export async function build(jobPath, { outputs: wantOutputs = true, outDir = null, quiet = false, brand: brandOverride = null } = {}) {
   const t0 = Date.now();
   const { job, file, dir } = await loadJob(jobPath);
-  const brand = loadBrand(job.brand || DEFAULT_BRAND, job.theme || null);
+  // --brand builds the same job on the other brand, beside the first, in out-<brand>/
+  const brandName = brandOverride || job.brand || DEFAULT_BRAND;
+  const brand = loadBrand(brandName, job.theme || null);
   const surface = surfaceOf(job.surface || "letter");
   const content = loadContent(dir, job);
-  const c = bind({ brand, surface, job, content });
+  delete job.__board;
+  const c = bind({ brand, surface, job, content, dir });
   const pages = job.pages(c);
   const html = assemble({ brand, surface, job, pages });
-  const out = outDir || path.join(dir, "out");
+  const out = outDir || path.join(dir, brandOverride && brandOverride !== (job.brand || DEFAULT_BRAND) ? `out-${brandOverride}` : "out");
+  // every file a demo or a clip names must exist before anything is drawn from it
+  const absent = [...html.matchAll(/(?:data-demo-src|<video src)="(file:\/\/[^"]+)"/g)].map((m) => fileURLToPath(m[1])).filter((p) => !fs.existsSync(p));
   const work = path.join(out, "work");
   fs.mkdirSync(work, { recursive: true });
   const name = stem(job, file);
@@ -224,6 +231,16 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
   row(!deny.length, "names", job.denylist?.length ? (deny.length ? `found ${deny.join(", ")}` : `none of ${job.denylist.length} denied names`) : "no denylist", !job.denylist?.length);
   row(!g.contrast.length, "contrast", g.contrast.length ? `${g.contrast.length} low: ` + g.contrast.slice(0, 3).map((o) => `p${o.page} ${o.el} ${o.ratio}:1 (needs ${o.need})`).join("; ") : "every text passes WCAG AA", true);
   row(!g.measure.length, "measure", g.measure.length ? `${g.measure.length} long: ` + g.measure.slice(0, 3).map((o) => `p${o.page} ${o.el} ~${o.chars} chars`).join("; ") : `no line over ${surface.chars} characters`, true);
+  row(!g.broken.length, "images", g.broken.length ? `${g.broken.length} did not load: ${g.broken.slice(0, 3).join(", ")}` : "every image loaded");
+  if (absent.length || g.motion.demo || g.motion.video) row(!absent.length, "media", absent.length ? `missing: ${absent.map((p) => path.basename(p)).join(", ")}` : `${g.motion.demo} demo${g.motion.demo === 1 ? "" : "s"}, ${g.motion.video} clip${g.motion.video === 1 ? "" : "s"}, each with its poster`);
+  const board = job.__board || null;
+  if (surface.kind === "slide" && !board) row(true, "motion", `${job.talk?.motion === "none" ? "still" : "entrances on every slide"}${g.motion.a ? `, ${g.motion.a} marked` : ""}${g.motion.steps ? `, ${g.motion.steps} held for steps` : ""} (the HTML; static exports show the end state)`);
+  if (board) {
+    const off = board.target ? Math.abs(board.total - board.target) / board.target : 0;
+    const mmss = (t) => `${Math.floor(t / 60)}:${String(Math.round(t % 60)).padStart(2, "0")}`;
+    row(off <= 0.1, "timing", `${board.shots.length} shots, ${mmss(board.total)}${board.target ? ` against ${mmss(board.target)} (${board.total > board.target ? "+" : "-"}${Math.round(off * 100)}%)` : ""}, scratch timing at ${board.wpm} wpm`, true);
+    row(!g.motion.placeholders, "frames", g.motion.placeholders ? `${g.motion.placeholders} frame${g.motion.placeholders === 1 ? "" : "s"} still to draw` : `${board.shots.reduce((a, s) => a + s.frames.length, 0)} frames, every one drawn`, true);
+  }
   row(!errors.length, "console", errors.length ? errors.slice(0, 2).join(" | ") : "no errors");
 
   const outputs = { html: htmlPath };
@@ -244,11 +261,20 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
       row(!(pc && pc.miss.length) && !dash, "pdf text", dash ? "em dash in the PDF text" : pc ? (pc.miss.length ? `missing lines ${pc.miss.join(", ")}` : `${pc.found}/${pc.total} lines read back from the PDF`) : "readable");
     }
     row(true, "renders", `${path.relative(process.cwd(), shots)}/p01…${String(els.length).padStart(2, "0")}.png, ${path.relative(process.cwd(), outputs.sheet)}`);
+    if (board) {
+      // the timeline for an editor and a captioner: one row a shot, one caption a line
+      const q = (v) => `"${String(v).replace(/"/g, '""')}"`;
+      const csv = ["shot,act,name,in,out,seconds,vo_in,vo_out,voiceover", ...board.shots.map((s) => [s.n, q(s.act), q(s.name), s.in, s.out, s.dur, s.voIn, s.voOut, q(s.vo)].join(","))].join("\n") + "\n";
+      fs.writeFileSync(outputs.csv = path.join(out, "timing.csv"), csv);
+      const srt = (t) => { const ms = Math.round(t * 1000), h = Math.floor(ms / 3600000), m = Math.floor(ms / 60000) % 60, s = Math.floor(ms / 1000) % 60; return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")},${String(ms % 1000).padStart(3, "0")}`; };
+      const cues = board.shots.filter((s) => s.vo);
+      fs.writeFileSync(outputs.srt = path.join(out, "captions.srt"), cues.map((s, i) => `${i + 1}\n${srt(s.voIn)} --> ${srt(s.voOut)}\n${s.vo}\n`).join("\n"));
+    }
   }
   await page.close();
 
   const ok = rows.every((r) => r.ok || r.warn);
-  const report = { ok, rows, outputs, pages: pageCount, brand: brand.name, surface: surface.name, ms: Date.now() - t0, texts: g.texts, notes: g.notes, name };
+  const report = { ok, rows, outputs, pages: pageCount, brand: brand.name, surface: surface.name, ms: Date.now() - t0, texts: g.texts, notes: g.notes, name, title: job.name || name, talk: job.talk || null, board };
   fs.writeFileSync(path.join(work, "report.json"), JSON.stringify({ ...report, texts: undefined }, null, 1));
   if (!quiet) printReport(report);
   return report;

package/lib/html_export.js

@@ -6,17 +6,35 @@
  * runtime: on a slide or card surface, one page at a time scaled to the
  * window, arrow keys and clicks to move, G for the grid, print gives one
  * sheet per page; on a page surface, the pages stacked and scaled to fit.
+ *
+ * A slide deck gets the talk runtime instead (lib/talk.js): crossfades,
+ * entrances and steps, media, the presenter view. A storyboard gets the
+ * board runtime (lib/board.js): the shot pages to read, and a player that
+ * runs the frames against the clock. A demo named by `data-demo-src` travels
+ * gzipped inside the file and mounts in a frame when its slide comes up.
  */
 import fs from "node:fs";
 import path from "node:path";
+import zlib from "node:zlib";
 import { fileURLToPath } from "node:url";
+import { talkShell, TALK_CSS, TALK_JS } from "./talk.js";
+import { BOARD_CSS, BOARD_JS, boardShell } from "./board.js";
 
 const MIME = { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
-  ttf: "font/ttf", otf: "font/otf", woff: "font/woff", woff2: "font/woff2" };
+  ttf: "font/ttf", otf: "font/otf", woff: "font/woff", woff2: "font/woff2",
+  mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime", m4v: "video/mp4", mp3: "audio/mpeg", m4a: "audio/mp4", wav: "audio/wav", ogg: "audio/ogg" };
 
-export function singleFile(htmlPath, outPath, { kind = "page", w, h }) {
+export function singleFile(htmlPath, outPath, { kind = "page", w, h, talk = null, board = null, title = "" }) {
   let html = fs.readFileSync(htmlPath, "utf8");
   const cache = new Map(), missing = [];
+  // demos first: each page travels gzipped, once, however many slides use it
+  const demos = new Map();
+  html = html.replace(/data-demo-src="(file:\/\/[^"]+)"/g, (m, u) => {
+    let p; try { p = fileURLToPath(u); } catch { return m; }
+    if (!fs.existsSync(p)) { missing.push(p); return m; }
+    if (!demos.has(p)) demos.set(p, { id: demos.size + 1, b64: zlib.gzipSync(fs.readFileSync(p)).toString("base64") });
+    return `data-demo="${demos.get(p).id}"`;
+  });
   html = html.replace(/file:\/\/[^"')\s]+/g, (u) => {
     if (cache.has(u)) return cache.get(u);
     let p; try { p = fileURLToPath(u); } catch { return u; }
@@ -25,8 +43,21 @@ export function singleFile(htmlPath, outPath, { kind = "page", w, h }) {
     const d = `data:${MIME[ext] || "application/octet-stream"};base64,${fs.readFileSync(p).toString("base64")}`;
     cache.set(u, d); return d;
   });
-  html = html.replace("</body>", `${RUNTIME_CSS}<script>${RUNTIME_JS}</script></body>`)
-    .replace("<body", `<body data-kind="${kind}" data-w="${w}" data-h="${h}"`);
+  const demoTags = [...demos.values()].map((d) => `<script type="application/octet-stream" id="wand-demo-${d.id}">${d.b64}</script>`).join("");
+  const data = (o) => `<script id="deck-data" type="application/json">${JSON.stringify(o).replace(/</g, "\\u003c")}</script>`;
+  if (board) {
+    const a = board.audio && fs.existsSync(board.audio) ? board.audio : "";
+    if (board.audio && !a) missing.push(board.audio);
+    const sh = boardShell({ ...board, audio: a ? `data:${MIME[path.extname(a).slice(1).toLowerCase()] || "audio/mpeg"};base64,${fs.readFileSync(a).toString("base64")}` : "" });
+    html = html.replace(/(<body[^>]*>)([\s\S]*)<\/body>/, (m, open, inner) => `${open}${sh.before}${inner}${sh.after}${BOARD_CSS}${data({ title, ...board, audio: !!a })}<script>${BOARD_JS}</script></body>`);
+  } else if (kind === "slide") {
+    const total = (html.match(/<section class="page /g) || []).length;
+    const sh = talkShell(total);
+    html = html.replace(/(<body[^>]*>)([\s\S]*)<\/body>/, (m, open, inner) => `${open}${sh.before}${inner}${sh.after}${TALK_CSS}${data({ title, motion: "auto", minutes: 0, ...(talk || {}) })}${demoTags}<script>${TALK_JS}</script></body>`);
+  } else {
+    html = html.replace("</body>", `${RUNTIME_CSS}<script>${RUNTIME_JS}</script></body>`);
+  }
+  html = html.replace("<body", `<body data-kind="${kind}" data-w="${w}" data-h="${h}"`);
   fs.writeFileSync(outPath, html);
   return { out: outPath, missing, bytes: fs.statSync(outPath).size };
 }

package/lib/runtime_check.js

@@ -0,0 +1,108 @@
+/**
+ * lib/runtime_check.js — the one-file HTML, driven the way a presenter drives it.
+ *
+ * The gates in engine.js read the static render, which is all the PDF, the
+ * PNGs and the .pptx ever see. A talk or a board also has a runtime, and a
+ * runtime can break where no still frame shows it. This opens the exported
+ * file in Chromium and uses it: every slide and step by keyboard, the
+ * overview, the notes, the presenter view kept in step both ways, every demo
+ * mounted; or, for a board, play, scrub and the frames on their cues.
+ * Ported from the BofA talk's qa.mjs feature checks.
+ */
+import { pathToFileURL } from "node:url";
+import { browser } from "./engine.js";
+
+const watch = (page, errors) => {
+  page.on("pageerror", (e) => errors.push(String(e).split("\n")[0]));
+  page.on("console", (m) => { if (m.type() === "error") errors.push(m.text()); });
+};
+
+export async function checkTalk(file, { total }) {
+  const b = await browser();
+  const ctx = await b.newContext({ viewport: { width: 1440, height: 810 } });
+  const page = await ctx.newPage();
+  const errors = [], fail = [];
+  watch(page, errors);
+  try {
+    await page.goto(pathToFileURL(file).href, { waitUntil: "load" });
+    await page.waitForFunction(() => window.wandTalk, null, { timeout: 8000 });
+    const st = (p = page) => p.evaluate(() => ({ cur: wandTalk.cur, shown: wandTalk.shown, total: wandTalk.total, on: document.querySelectorAll(".stage > .page.is-current").length }));
+    const s0 = await st();
+    if (s0.total !== total) fail.push(`the runtime sees ${s0.total} slides, the build ${total}`);
+    if (s0.on !== 1) fail.push(`${s0.on} slides on screen at once`);
+
+    // every slide and every step, forward, by keyboard
+    let presses = 0, steps = 0;
+    for (;;) {
+      const a = await st(); await page.keyboard.press("ArrowRight"); const z = await st();
+      if (z.cur === a.cur && z.shown === a.shown) break;
+      presses++; if (z.cur === a.cur) steps++;
+      if (presses > 600) { fail.push("ArrowRight never reaches the end"); break; }
+    }
+    if ((await st()).cur !== total - 1) fail.push("the keyboard does not reach the last slide");
+    await page.keyboard.press("Home");
+
+    await page.keyboard.press("g");
+    const thumbs = await page.$$eval(".overview:not([hidden]) .thumb", (t) => t.length);
+    if (thumbs !== total) fail.push(`the overview shows ${thumbs} of ${total}`);
+    await page.keyboard.press("Escape");
+    await page.keyboard.press("n");
+    if (!(await page.$eval(".notes-panel", (e) => !e.hidden))) fail.push("N does not open the notes");
+    await page.keyboard.press("Escape");
+
+    // the presenter's window, kept in step from either side
+    const [pop] = await Promise.all([ctx.waitForEvent("page", { timeout: 8000 }), page.keyboard.press("p")]);
+    watch(pop, errors);
+    await pop.waitForLoadState("load");
+    await pop.waitForFunction(() => window.wandTalk, null, { timeout: 8000 });
+    await page.keyboard.press("ArrowRight"); await page.waitForTimeout(250);
+    let r = await st(), q = await st(pop);
+    if (r.cur !== q.cur || r.shown !== q.shown) fail.push(`room ${r.cur + 1}/${r.shown} and presenter ${q.cur + 1}/${q.shown} disagree`);
+    await pop.keyboard.press("ArrowRight"); await page.waitForTimeout(250);
+    r = await st(); q = await st(pop);
+    if (r.cur !== q.cur || r.shown !== q.shown) fail.push("the presenter's keys do not move the room");
+    await pop.close();
+
+    // every demo mounts and loads
+    const demoSlides = await page.$$eval(".stage > .page", (ps) => ps.map((p, i) => (p.querySelector(".media.demo") ? i : -1)).filter((i) => i >= 0));
+    for (const i of demoSlides) {
+      await page.evaluate((n) => wandTalk.go(n), i);
+      try { await page.waitForSelector(".stage > .page.is-current .media.demo.is-ready", { timeout: 10000 }); }
+      catch { fail.push(`the demo on slide ${i + 1} never loaded`); }
+    }
+    const facts = `${total} slides${steps ? ` and ${steps} steps` : ""} by keyboard, overview, notes, presenter in step both ways${demoSlides.length ? `, ${demoSlides.length} demo${demoSlides.length === 1 ? "" : "s"} mounted` : ""}`;
+    const all = [...fail, ...errors.map((e) => `console: ${e}`)];
+    return { ok: !all.length, msg: all.length ? all.slice(0, 3).join("; ") : facts };
+  } catch (e) {
+    return { ok: false, msg: `${String(e.message || e).split("\n")[0]}` };
+  } finally { await ctx.close(); }
+}
+
+export async function checkBoard(file, { shots, total }) {
+  const b = await browser();
+  const ctx = await b.newContext({ viewport: { width: 1440, height: 900 } });
+  const page = await ctx.newPage();
+  const errors = [], fail = [];
+  watch(page, errors);
+  try {
+    await page.goto(pathToFileURL(file).href, { waitUntil: "load" });
+    await page.waitForFunction(() => window.wandBoard, null, { timeout: 8000 });
+    await page.click('[data-ui="play-board"]');
+    await page.waitForTimeout(1200);
+    const a = await page.evaluate(() => ({ t: wandBoard.t, playing: wandBoard.playing, on: document.querySelectorAll(".pl-frames .pf.on").length, art: !!document.querySelector(".pl-frames .pf.on .frame-art") }));
+    if (!a.playing || a.t < 0.6) fail.push(`the player did not run (t=${a.t.toFixed(1)})`);
+    if (a.on !== 1 || !a.art) fail.push("no frame on the player's screen");
+    // scrub to the last shot: its frame and its words come up
+    const last = shots[shots.length - 1];
+    await page.evaluate((t) => { wandBoard.pause(); wandBoard.seek(t); }, last.in + 0.05);
+    const z = await page.evaluate(() => ({ id: document.querySelector(".pl-frames .pf.on")?.dataset.id, vo: document.querySelector(".pl-vo").dataset.n }));
+    if (z.vo !== String(last.n)) fail.push(`seeking to shot ${last.n} shows shot ${z.vo}`);
+    if (!z.id || !z.id.startsWith(String(last.n).padStart(2, "0"))) fail.push(`seeking to shot ${last.n} shows frame ${z.id}`);
+    await page.keyboard.press("Escape");
+    const all = [...fail, ...errors.map((e) => `console: ${e}`)];
+    const frames = shots.reduce((s, x) => s + x.frames.length, 0);
+    return { ok: !all.length, msg: all.length ? all.slice(0, 3).join("; ") : `the player runs ${frames} frames over ${Math.floor(total / 60)}:${String(Math.round(total % 60)).padStart(2, "0")}, scrubs to the last shot, captions follow` };
+  } catch (e) {
+    return { ok: false, msg: `${String(e.message || e).split("\n")[0]}` };
+  } finally { await ctx.close(); }
+}