belt-trailer 0.1.0

data/engine/lib/showcase.mjs

@@ -0,0 +1,83 @@
+// Where the pages come from, and what answers their requests.
+//
+// A showcase is the app's screens built from hand-written states (fixtures)
+// with no backend: `showcase.build` is a module in the app that builds it and
+// says where (`buildShowcase()` returning { distDir }, or a `distDir`
+// export). The engine serves the build to Playwright by route interception,
+// so there is no dev server, and the app's API calls get the config's canned
+// answers. `showcase.url` films a running site instead, which works but can't
+// promise the same shot twice.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { contentType } from './sound.mjs';
+
+export const ORIGIN = 'http://showcase.local';
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const TITLES_PATH = '/__trailer/titles';
+const TITLES_CSS_PATH = '/__trailer/titles.css';
+
+export async function prepareShowcase(config) {
+  const { showcase, appDir } = config;
+  if (showcase.url) {
+    console.warn(`Filming ${showcase.url}, a running site: its data can change between takes, so a shot may not come out the same twice.`);
+    const url = new URL(showcase.url);
+    return { origin: url.origin, entry: url.pathname, dist: null };
+  }
+  const mod = await import(pathToFileURL(path.resolve(appDir, showcase.build)).href);
+  const build = mod.buildShowcase || mod.default;
+  if (typeof build !== 'function') throw new Error(`${showcase.build} must export buildShowcase() (or a default function)`);
+  const built = await build();
+  const distDir = showcase.dist || built?.distDir || mod.distDir;
+  if (!distDir) throw new Error(`${showcase.build}: buildShowcase() must return { distDir } (or the module export distDir)`);
+  return { origin: ORIGIN, entry: `/${showcase.index || 'showcase.html'}`, dist: path.resolve(appDir, distDir) };
+}
+
+// The URL a beat opens: the showcase's page with ?view=<fixture> and the
+// config's and the beat's query parameters.
+export function beatUrl(site, config, beat) {
+  const url = new URL(beat.path || site.entry, site.origin);
+  if (beat.view) url.searchParams.set('view', beat.view);
+  for (const query of [config.showcase.query, beat.query]) {
+    const params = typeof query === 'string' ? new URLSearchParams(query) : Object.entries(query || {});
+    for (const [k, v] of params) url.searchParams.set(k, String(v));
+  }
+  return url.toString();
+}
+
+// The canned answer for an API path, or undefined. Keys are exact paths, or
+// a prefix ending in `*`; the first that matches wins, so put specific ones
+// first. A value is the JSON to answer with, or a function of the URL that
+// returns it.
+export function cannedAnswer(api, url) {
+  for (const [pattern, answer] of Object.entries(api || {})) {
+    const hit = pattern.endsWith('*') ? url.pathname.startsWith(pattern.slice(0, -1)) : url.pathname === pattern;
+    if (hit) return typeof answer === 'function' ? answer(url) : answer;
+  }
+  return undefined;
+}
+
+// The route handler for every page the engine opens: the titles page, live
+// sounds, canned API answers, then the showcase build (or, filming a running
+// site, the site itself).
+export function router(site, config, live) {
+  return async route => {
+    const url = new URL(route.request().url());
+    if (url.pathname === TITLES_PATH) {
+      return route.fulfill({ body: fs.readFileSync(path.join(here, '../titles.html')), contentType: 'text/html' });
+    }
+    if (url.pathname === TITLES_CSS_PATH) {
+      const css = config.titles.css ? fs.readFileSync(path.resolve(config.appDir, config.titles.css)) : '';
+      return route.fulfill({ body: css, contentType: 'text/css' });
+    }
+    if (live && await live.answer(route, url)) return undefined;
+    const canned = await cannedAnswer(config.api, url);
+    if (canned !== undefined) return route.fulfill({ json: canned });
+    if (!site.dist) return route.continue();
+    const file = path.join(site.dist, url.pathname === '/' ? site.entry : decodeURIComponent(url.pathname));
+    if (!file.startsWith(site.dist) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+      return route.fulfill({ status: 404, body: '' });
+    }
+    return route.fulfill({ body: fs.readFileSync(file), contentType: contentType(file) });
+  };
+}

data/engine/lib/sound.mjs

@@ -0,0 +1,145 @@
+// Sound is captured, not placed: the app decides what plays and when, and the
+// recorder only writes it down.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ffmpeg } from './ffmpeg.mjs';
+
+// An init script that notes every sound effect the page starts, with how far
+// ahead it was scheduled, in window.__heard. The app fetches each file,
+// decodes it and plays it through Web Audio; the URL is carried from the
+// download (Response.arrayBuffer) through decodeAudioData to the buffer, and
+// noted when an AudioBufferSourceNode starts it. URLs matching `ignore`
+// (music) are left out: music is laid under the whole cut instead.
+export function listen(ignore) {
+  const skip = ignore.map(source => new RegExp(source));
+  const urlOf = new WeakMap();
+  const arrayBuffer = Response.prototype.arrayBuffer;
+  Response.prototype.arrayBuffer = async function () {
+    const data = await arrayBuffer.call(this);
+    urlOf.set(data, this.url);
+    return data;
+  };
+  const decode = BaseAudioContext.prototype.decodeAudioData;
+  BaseAudioContext.prototype.decodeAudioData = function (data, ok, fail) {
+    const url = urlOf.get(data);
+    const tag = buffer => { if (url) urlOf.set(buffer, url); return buffer; };
+    const pending = decode.call(this, data, buffer => ok?.(tag(buffer)), fail);
+    return pending?.then ? pending.then(tag) : pending;
+  };
+  const start = AudioBufferSourceNode.prototype.start;
+  AudioBufferSourceNode.prototype.start = function (when = 0, ...rest) {
+    const url = urlOf.get(this.buffer);
+    if (url && !skip.some(re => re.test(url))) {
+      (window.__heard ||= []).push({ url, delay: Math.max(0, when - this.context.currentTime) });
+    }
+    return start.call(this, when, ...rest);
+  };
+}
+
+// The patterns listen() skips: the config's own, plus every music track that
+// is a plain file, by name.
+export function ignored(config) {
+  const own = [config.sounds.ignore].flat().filter(Boolean).map(re => (re instanceof RegExp ? re.source : String(re)));
+  const tracks = Object.values(config.music.tracks)
+    .filter(t => typeof t === 'string')
+    .map(t => `${path.basename(t).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+  return [...own, ...tracks];
+}
+
+// The live site's sounds, when the app lets someone replace them there
+// (sounds.live: { origin, paths }). Requests under those paths are answered
+// from the live site: files (with an extension) are fetched once and kept in
+// sounds.cache, anything else (a list of replacements) is fetched fresh each
+// run. Offline, or with --sounds=bundled, `live` is null and the app gets the
+// config's canned API answers and its bundled files instead.
+export function liveSounds(config, { bundled = false } = {}) {
+  const live = config.sounds.live;
+  if (bundled || !live?.origin) return null;
+  const cache = path.resolve(config.appDir, config.sounds.cache);
+  const paths = [live.paths || []].flat();
+  const fresh = new Map();
+
+  const fetchFrom = async pathname => {
+    try {
+      const response = await fetch(new URL(pathname, live.origin));
+      return response.ok ? Buffer.from(await response.arrayBuffer()) : null;
+    } catch {
+      return null;
+    }
+  };
+
+  const source = {
+    cache,
+    covers: pathname => paths.some(p => pathname.startsWith(p)),
+    fileFor: pathname => path.join(cache, decodeURIComponent(pathname)),
+    // The file behind a live path, fetched the first time; null if the live
+    // site doesn't have it.
+    async file(pathname) {
+      const file = source.fileFor(pathname);
+      if (fs.existsSync(file)) return file;
+      const body = await fetchFrom(pathname);
+      if (!body) return null;
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, body);
+      return file;
+    },
+    // The body behind a live path that isn't a file, fetched once a run.
+    async body(pathname) {
+      if (!fresh.has(pathname)) fresh.set(pathname, fetchFrom(pathname));
+      return fresh.get(pathname);
+    },
+    async json(pathname) {
+      const body = await source.body(pathname);
+      try { return body ? JSON.parse(body) : null; } catch { return null; }
+    },
+    // Answers a page's request for a live path, or returns false to let the
+    // canned API answer it.
+    async answer(route, url) {
+      if (!source.covers(url.pathname)) return false;
+      if (path.extname(url.pathname)) {
+        const file = await source.file(url.pathname);
+        if (!file) return false;
+        await route.fulfill({ body: fs.readFileSync(file), contentType: contentType(file) });
+        return true;
+      }
+      const body = await source.body(url.pathname + url.search);
+      if (!body) return false;
+      await route.fulfill({ body, contentType: 'application/json' });
+      return true;
+    },
+  };
+  return source;
+}
+
+// The file on disk behind a URL the page played: the live site's (cached)
+// or the app's bundled one.
+export function fileFor(config, live, url) {
+  const { pathname } = new URL(url, 'http://showcase.local');
+  if (live?.covers(pathname)) return live.fileFor(pathname);
+  return path.join(config.appDir, config.sounds.bundled, decodeURIComponent(pathname));
+}
+
+// Mixes effects into one track `seconds` long: each { at, file } starts `at`
+// seconds in and plays out, level as the app plays it.
+export function mixEffects(sounds, seconds, out) {
+  const heard = sounds.filter(s => fs.existsSync(s.file));
+  if (!heard.length) {
+    ffmpeg(['-f', 'lavfi', '-i', 'anullsrc=r=48000:cl=stereo', '-t', seconds.toFixed(6), out]);
+    return;
+  }
+  const inputs = heard.flatMap(s => ['-i', s.file]);
+  const delayed = heard.map((s, i) => {
+    const ms = Math.max(0, Math.round(s.at * 1000));
+    return `[${i}:a]aformat=sample_rates=48000:channel_layouts=stereo,adelay=${ms}|${ms}[e${i}]`;
+  });
+  const mix = `${heard.map((_, i) => `[e${i}]`).join('')}amix=inputs=${heard.length}:normalize=0,apad,atrim=0:${seconds.toFixed(6)}[out]`;
+  ffmpeg([...inputs, '-filter_complex', [...delayed, mix].join(';'), '-map', '[out]', out]);
+}
+
+const TYPES = {
+  '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
+};
+export const contentType = file => TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream';

data/engine/lib/titles.mjs

@@ -0,0 +1,43 @@
+// Films the titles for a beat: the same number of frames as the beat, each
+// cue played on the frame it was given, on a transparent page the size of the
+// output. Its animations are stepped the way the app's are.
+import path from 'node:path';
+import { freeze, step } from './clock.mjs';
+import { TITLES_PATH } from './showcase.mjs';
+
+// The cues with a closing hide added: a title still up near the end leaves
+// `leaveBefore` seconds before the cut, so a shot never ends on words and the
+// next one's can't read as the same title changing, or its dark panel
+// flicker out and back in.
+export function closeTitles(cues, frames, fps, leaveBefore) {
+  const last = cues[cues.length - 1];
+  if (!last?.show) return cues;
+  return [...cues, { frame: Math.max(last.frame + 1, frames - Math.round(leaveBefore * fps)), hide: true }];
+}
+
+export async function filmTitles(browser, { site, route, config, format, cues, frames, dir }) {
+  const [width, height] = format.out;
+  const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
+  await page.route(`${site.origin}/**`, route);
+  await page.clock.install();
+  await page.goto(`${site.origin}${TITLES_PATH}`);
+  await page.evaluate(async logo => {
+    await document.fonts.ready;
+    if (logo) await Object.assign(new Image(), { src: logo }).decode().catch(() => {});
+  }, config.titles.endCard?.logo);
+  await freeze(page);
+  const frameMs = 1000 / config.fps;
+  const all = closeTitles(cues, frames, config.fps, config.titles.leaveBefore);
+  let now = 0;
+  for (let i = 0; i < frames; i += 1) {
+    for (const cue of all.filter(c => c.frame === i)) {
+      if (cue.show) await page.evaluate(t => window.show(t), cue.show);
+      if (cue.hide) await page.evaluate(() => window.hide());
+      if (cue.end) await page.evaluate(card => window.endCard(card), config.titles.endCard || {});
+    }
+    now += frameMs;
+    await step(page, now, frameMs);
+    await page.screenshot({ path: path.join(dir, `${String(i).padStart(5, '0')}.png`), omitBackground: true });
+  }
+  await page.close();
+}

data/engine/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "belt-trailer",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Films a launch trailer of a web app from its own screens and sounds",
+  "type": "module",
+  "bin": { "belt-trailer": "bin/trailer.mjs" },
+  "exports": {
+    ".": "./lib/index.mjs"
+  },
+  "engines": { "node": ">=20" },
+  "peerDependencies": { "playwright": ">=1.45" },
+  "scripts": { "test": "node --test test/*.test.mjs" }
+}

data/engine/titles.html

@@ -0,0 +1,144 @@
+<!DOCTYPE html>
+<!-- The titles layer: a transparent page the size of the finished video,
+     filmed for the same frames as a beat and laid over its clean clip, so the
+     camera can move the app without moving the words.
+
+     window.show({ kicker, line, place }) brings a title in, word by word;
+     window.hide() sends it out; window.endCard(card) is the last shot.
+     place is side (a panel on the right of a wide frame), band (the strip
+     across the middle of a tall one), top or bottom, or { wide, tall }.
+
+     The look is the app's: its titles css (titles.css in the config) is
+     loaded after these defaults. Set the custom properties below, add
+     @font-face rules for the app's fonts (served from the showcase build),
+     or restyle any class. -->
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<style>
+  :root {
+    --title-font: system-ui, sans-serif;
+    --line-font: var(--title-font);
+    --line-weight: 800;
+    --kicker-color: #f5d27a;
+    --word-fill: linear-gradient(180deg, #ffffff 0%, #f1f1f1 55%, #cfcfcf 100%);
+    --word-glow: rgba(255, 255, 255, 0.25);
+    --rule: linear-gradient(90deg, transparent, #f5d27a 30%, #fff3c9 50%, #f5d27a 70%, transparent);
+    --shade: 9, 6, 16;
+    --end-text: #f4f0e6;
+    --end-muted: #cfc7b4;
+    --url-text: #1d1405;
+    --url-fill: linear-gradient(180deg, #fff1c4 0%, #f5d27a 55%, #d1a23f 100%);
+  }
+  html, body { margin: 0; height: 100%; background: transparent; overflow: hidden; }
+  /* Sizes follow the frame: --u is 1% of its short side. */
+  body { --u: 1vmin; font-family: var(--title-font); }
+
+  /* A dark wash behind the words, at the edge they sit on, fading into the
+     picture, so they read over anything without boxing the app in. */
+  .scrim { position: fixed; left: 0; right: 0; height: 46%; pointer-events: none; animation: fade-in 0.35s ease-out both; }
+  .scrim.top { top: 0; background: linear-gradient(180deg, rgba(var(--shade), 0.94) 0%, rgba(var(--shade), 0.72) 42%, rgba(var(--shade), 0) 100%); }
+  .scrim.bottom { bottom: 0; background: linear-gradient(0deg, rgba(var(--shade), 0.94) 0%, rgba(var(--shade), 0.72) 42%, rgba(var(--shade), 0) 100%); }
+  .scrim.side { top: 0; bottom: 0; right: 0; left: auto; width: 58%; height: auto;
+    background: linear-gradient(90deg, rgba(var(--shade), 0) 0%, rgba(var(--shade), 0.84) 34%, rgba(var(--shade), 0.95) 100%); }
+  .scrim.band { top: 56%; height: 30%; background: linear-gradient(180deg, rgba(var(--shade), 0) 0%, rgba(var(--shade), 0.86) 28%, rgba(var(--shade), 0.86) 72%, rgba(var(--shade), 0) 100%); }
+
+  .title { position: fixed; left: 5%; right: 5%; text-align: center; }
+  .title.top { top: calc(var(--u) * 6); }
+  .title.bottom { bottom: calc(var(--u) * 7); }
+  .title.band { top: 71%; transform: translateY(-50%); }
+  .title.side { left: auto; right: 3%; width: 38%; top: 50%; transform: translateY(-50%); }
+  .title.side .line { font-size: calc(var(--u) * 8.4); }
+  .title.side .kicker { font-size: calc(var(--u) * 2.8); }
+  .title.side .rule { width: 60%; }
+
+  .kicker {
+    font-weight: 700; text-transform: uppercase; color: var(--kicker-color);
+    font-size: calc(var(--u) * 3.1); letter-spacing: 0.42em; margin-right: -0.42em;
+    text-shadow: 0 2px 0 rgba(0, 0, 0, 0.8);
+    animation: kicker-in 0.7s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+  }
+  .line {
+    font-family: var(--line-font); font-weight: var(--line-weight);
+    font-size: calc(var(--u) * 9); line-height: 1.08; margin-top: calc(var(--u) * 1.2);
+  }
+  .tall .line { font-size: calc(var(--u) * 9.5); }
+  /* Each word lands one after another. */
+  .word {
+    display: inline-block; margin: 0 0.12em; padding: 0 0.04em;
+    background: var(--word-fill); -webkit-background-clip: text; background-clip: text; color: transparent;
+    filter: drop-shadow(0 calc(var(--u) * 0.5) 0 rgba(0, 0, 0, 0.75)) drop-shadow(0 0 calc(var(--u) * 2.4) var(--word-glow));
+    animation: word-in 0.6s cubic-bezier(0.2, 1.5, 0.35, 1) both;
+    animation-delay: calc(0.15s + var(--i) * 0.09s);
+  }
+  .rule {
+    height: calc(var(--u) * 0.35); width: 42%; margin: calc(var(--u) * 1.6) auto 0;
+    background: var(--rule); animation: rule-in 0.7s 0.3s cubic-bezier(0.2, 0.8, 0.2, 1) both;
+  }
+  .leaving { animation: leave 0.3s ease-in both !important; }
+  .leaving * { animation-play-state: paused; }
+
+  /* The last shot: the logo, the offer and the address. */
+  .end { position: fixed; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; text-align: center;
+    background: radial-gradient(ellipse at 50% 42%, rgba(var(--shade), 0.55) 0%, rgba(var(--shade), 0.9) 70%); animation: fade-in 0.4s ease-out both; }
+  .end img { width: calc(var(--u) * 52); animation: logo-in 0.8s cubic-bezier(0.2, 1.4, 0.35, 1) 0.1s both; }
+  .tall .end img { width: calc(var(--u) * 78); }
+  .end .pitch { margin-top: calc(var(--u) * 3); font-weight: 700; color: var(--end-text); font-size: calc(var(--u) * 4.4); animation: rise 0.5s ease-out 0.55s both; }
+  .end .terms { margin-top: calc(var(--u) * 1.2); color: var(--end-muted); font-size: calc(var(--u) * 3); letter-spacing: 0.08em; animation: rise 0.5s ease-out 0.75s both; }
+  .end .url {
+    margin-top: calc(var(--u) * 4); padding: calc(var(--u) * 1.4) calc(var(--u) * 4); border-radius: 999px;
+    font-weight: 800; font-size: calc(var(--u) * 4.6); color: var(--url-text); letter-spacing: 0.04em; background: var(--url-fill);
+    box-shadow: 0 calc(var(--u) * 1) calc(var(--u) * 3) rgba(0, 0, 0, 0.6);
+    animation: pop 0.55s cubic-bezier(0.2, 1.5, 0.35, 1) 1s both;
+  }
+
+  @keyframes fade-in { from { opacity: 0; } }
+  @keyframes kicker-in { from { opacity: 0; letter-spacing: 1.1em; } }
+  @keyframes word-in { from { opacity: 0; transform: translateY(0.35em) scale(1.35); filter: blur(calc(var(--u) * 1)); } }
+  @keyframes rule-in { from { transform: scaleX(0); opacity: 0; } }
+  @keyframes leave { to { opacity: 0; transform: translateY(calc(var(--u) * -2)); } }
+  @keyframes logo-in { from { opacity: 0; transform: scale(0.6) rotate(-4deg); } }
+  @keyframes rise { from { opacity: 0; transform: translateY(calc(var(--u) * 2)); } }
+  @keyframes pop { from { opacity: 0; transform: scale(0.6); } }
+</style>
+<link rel="stylesheet" href="/__trailer/titles.css" />
+</head>
+<body>
+<script>
+  const tall = innerHeight > innerWidth;
+  document.body.classList.toggle('tall', tall);
+  const el = (className, text) => Object.assign(document.createElement('div'), { className, textContent: text ?? '' });
+  let shown = [];
+  window.show = ({ kicker, line, place }) => {
+    window.hide(true);
+    // By default beside the picture in a wide frame, in the band of a tall one.
+    place = (typeof place === 'object' ? place?.[tall ? 'tall' : 'wide'] : place) || (tall ? 'band' : 'side');
+    const scrim = el(`scrim ${place}`);
+    const title = el(`title ${place}`);
+    if (kicker) title.append(el('kicker', kicker));
+    const words = el('line');
+    line.split(' ').forEach((text, i) => {
+      const word = Object.assign(document.createElement('span'), { className: 'word', textContent: text });
+      word.style.setProperty('--i', i);
+      words.append(word);
+    });
+    title.append(words, el('rule'));
+    document.body.append(scrim, title);
+    shown = [scrim, title];
+  };
+  window.hide = (now = false) => {
+    shown.forEach(e => (now ? e.remove() : e.classList.add('leaving')));
+    if (now) shown = [];
+  };
+  window.endCard = ({ logo, alt, lines = [], url } = {}) => {
+    window.hide(true);
+    const end = el('end');
+    if (logo) end.append(Object.assign(document.createElement('img'), { src: logo, alt: alt || '' }));
+    lines.forEach((text, i) => end.append(el(i === 0 ? 'pitch' : 'terms', text)));
+    if (url) end.append(el('url', url));
+    document.body.append(end);
+    shown = [end];
+  };
+</script>
+</body>
+</html>

data/examples/posh-nosh/trailer-titles.css

@@ -0,0 +1,26 @@
+/* Posh Nosh's titles: Cinzel, in gilt, over a near-black wash. The fonts and
+   the logo come from the showcase build (public/). */
+@font-face { font-family: 'Cinzel'; font-weight: 500 900; src: url(/fonts/cinzel-latin.woff2) format('woff2'); }
+@font-face { font-family: 'Cinzel Decorative'; font-weight: 900; src: url(/fonts/cinzel-decorative-900-latin.woff2) format('woff2'); }
+@font-face { font-family: 'Cinzel Decorative'; font-weight: 700; src: url(/fonts/cinzel-decorative-700-latin.woff2) format('woff2'); }
+
+:root {
+  --title-font: 'Cinzel', Georgia, serif;
+  --line-font: 'Cinzel Decorative', 'Cinzel', serif;
+  --line-weight: 900;
+  --kicker-color: #e6bf5c;
+  --word-fill: linear-gradient(180deg, #fff7dc 0%, #f6dd94 38%, #e6bf5c 60%, #b0802c 100%);
+  --word-glow: rgba(230, 191, 92, 0.35);
+  --rule: linear-gradient(90deg, transparent, #e6bf5c 30%, #fff1c4 50%, #e6bf5c 70%, transparent);
+  --shade: 9, 6, 16;
+  --end-text: #fbe9b5;
+  --end-muted: #d9c9a4;
+  --url-text: #2a1a06;
+  --url-fill: linear-gradient(180deg, #fbe9b5 0%, #e6bf5c 55%, #c99a3a 100%);
+}
+
+.end { background: radial-gradient(ellipse at 50% 42%, rgba(30, 18, 44, 0.55) 0%, rgba(9, 6, 16, 0.9) 70%); }
+.end img { filter: drop-shadow(0 0 calc(var(--u) * 4) rgba(230, 191, 92, 0.45)); }
+.end .url {
+  box-shadow: 0 0 0 calc(var(--u) * 0.3) #7a5a1e, 0 calc(var(--u) * 1) calc(var(--u) * 3) rgba(0, 0, 0, 0.6), 0 0 calc(var(--u) * 5) rgba(230, 191, 92, 0.4);
+}

data/examples/posh-nosh/trailer.config.mjs

@@ -0,0 +1,168 @@
+// Posh Nosh's launch trailer (Fizzy #1818) as a belt-trailer config: the
+// storyboard in posh_nosh docs/launch-video.md, filmed from the screenshot
+// showcase (frontend/scripts/screenshots/). Lives in frontend/.
+
+// The table without the chronicle and chat beside it: the units and the hand.
+const TABLE = ['.unit', '.hand .pcard'];
+// Both ranks with room on the right for the words: where the Skeleton's shot
+// ends and the Dragon's begins.
+const BOTH_RANKS = ['.unit.ally', '.unit.foe'];
+const bothRanksRoom = cam => ({ pad: 0.06, right: cam.tall ? 0 : 0.6 });
+const card = idx => `.hand .pcard[data-hand-idx="${idx}"]`;
+
+// The file a music slot plays, as the game chooses it (sound.js): the live
+// upload, else what it stands in for, else the bundled theme.
+const STAND_INS = { 'music-battle-75': 'music-battle-50', 'music-battle-50': 'music-battle' };
+const THEME = 'public/sounds/the-great-march.mp3';
+const slot = name => async ({ live }) => {
+  const board = live && await live.json('/api/sounds');
+  for (let s = name; s; s = STAND_INS[s]) {
+    const own = board?.sounds?.find(x => x.slot === s)?.url;
+    if (own) return (await live.file(own)) || THEME;
+  }
+  return THEME;
+};
+
+export default {
+  showcase: { build: './scripts/screenshots/build.mjs', query: { sound: 1 } },
+  api: {
+    '/api/matches': { matches: [] },
+    // The live soundboard answers this when it can (sounds.live); offline, or
+    // with --sounds bundled, no replacements, so the bundled files play.
+    '/api/sounds': { sounds: [] },
+    '/api/*': {},
+  },
+  // An admin can replace any sound at /admin/sounds; the live site lists the
+  // replacements at /api/sounds and serves them under /soundboard/.
+  sounds: {
+    bundled: 'public',
+    live: { origin: 'https://playposhnosh.com', paths: ['/api/sounds', '/soundboard/'] },
+    ignore: ['/music-', 'the-great-march'],
+  },
+  page: {
+    // The chronicle and chat beside the table are never the subject.
+    css: '.combat-log { visibility: hidden; }',
+    init: () => {
+      sessionStorage.clear();
+      localStorage.setItem('posh-nosh-sound-on', '1');
+      localStorage.setItem('posh-nosh-welcome', 'seen');
+    },
+  },
+  titles: {
+    css: './trailer-titles.css',
+    endCard: {
+      logo: '/images/brand/posh-nosh-logo.png',
+      alt: 'Posh Nosh',
+      lines: ['A card battle for two', 'Free in your browser · No account needed'],
+      url: 'playposhnosh.com',
+    },
+  },
+  // The game's rule: the table's track while the battle is young, its "50"
+  // track once the fight has turned, silence from the win (the victory beat's
+  // hush mark), the lobby's music under the end card. --music theme plays the
+  // lobby theme throughout.
+  music: {
+    fade: 1.5,
+    tracks: { battle: slot('music-battle'), 'battle-50': slot('music-battle-50'), lobby: slot('music-lobby'), theme: THEME },
+    plan: { hook: 'battle', recruit: 'battle', strike: 'battle', dragon: 'battle-50', banter: 'battle-50', victory: 'battle-50', end: 'lobby' },
+    plans: { theme: { hook: 'theme', recruit: 'theme', strike: 'theme', dragon: 'theme', banter: 'theme', victory: 'theme', end: 'theme' } },
+  },
+  beats: [
+    // The hook: no words, a card thrown, a rival falls, the camera slams in.
+    { name: 'hook', view: 'battle-my-turn-fresh', play: async ({ cam, setView, drag }) => {
+      // Wide, the hand is below the frame and the card flies up into it.
+      await cam.focus(cam.tall ? TABLE : '.unit', { pad: 0.03 });
+      await cam.focus(cam.tall ? ['.unit.foe', '.hand .pcard'] : '.unit', { ms: 900, pad: cam.tall ? 0.04 : -0.02 });
+      await cam.hold(200);
+      await drag(card(0), '.unit.foe >> nth=1', { ms: 600 });
+      await setView('trailer-knockout');
+      await cam.punch('.unit.foe >> nth=1', { pad: 0.3 });
+      cam.shake(400, 10);
+      await cam.hold(1600);
+    } },
+    // Pick a warband: the camera glides along the roster close enough to see
+    // the art. The pointer stays off the portraits, so no tooltip covers them.
+    { name: 'recruit', view: 'selection-partial',
+      // The title stands in for the screen's own heading.
+      css: '.recruit-screen .phase-header { visibility: hidden; }',
+      play: async ({ page, cam, ease }) => {
+        cam.title({ kicker: 'Step one', line: 'Choose your champions', place: 'top' });
+        const row = (from, to) => Array.from({ length: to - from + 1 }, (_, i) => `.recruit-portrait >> nth=${from + i}`);
+        await page.mouse.move(2, page.viewportSize().height - 2);
+        await cam.focus(row(0, 3), { pad: 0.08, top: 0.55 });
+        await cam.focus(row(3, 6), { ms: 3200, pad: 0.08, top: 0.55, ease: ease.linear });
+        await cam.hold(3300);
+      } },
+    // Out-play: the Necromancer's ritual, slow enough to follow, and a
+    // Skeleton rises. The words wait for the Skeleton.
+    { name: 'strike', view: 'trailer-ritual', play: async ({ page, cam, setView, ease }) => {
+      await cam.focus('.ability-dialog', { pad: 0.12 });
+      await cam.focus('.ability-dialog', { ms: 2600, pad: 0.04, ease: ease.linear });
+      await cam.hold(700);
+      // No pointer on the cards: a hovered card lifts, then lifts again when picked.
+      await page.mouse.move(2, 2);
+      await cam.hold(450);
+      await setView('trailer-ritual-ready');
+      await cam.hold(1300);
+      await setView('trailer-risen');
+      await cam.focus(BOTH_RANKS, { pad: 0.05, right: 0.6 });
+      await cam.hold(250);
+      cam.title({ kicker: 'Every unit has an ability', line: 'Out-play your rival' });
+      await cam.punch('.unit.ally >> nth=4', { pad: 0.9, right: 0.8, top: 0.2, ms: 500 });
+      cam.shake(300, 6);
+      await cam.hold(1500);
+      // Back out to the frame the Dragon's shot opens on.
+      await cam.focus(BOTH_RANKS, { ms: 1000, ...bothRanksRoom(cam) });
+      await cam.hold(1100);
+    } },
+    // A Dragon is summoned, and the camera meets it.
+    { name: 'dragon', view: 'trailer-dragon-offer', play: async ({ cam, setView, ease }) => {
+      await cam.focus(BOTH_RANKS, bothRanksRoom(cam));
+      await cam.focus('.unit.ally', { ms: 900, pad: 0.12, top: cam.tall ? 0.9 : 0.4, right: cam.tall ? 0 : 0.7, ease: ease.linear });
+      await cam.hold(700);
+      await setView('trailer-dragon');
+      await cam.hold(150);
+      // A push of more than 1.5× takes 0.9 s; at 0.5 s it snapped.
+      await cam.focus('.summoned-dragon', { pad: 0.5, top: cam.tall ? 0.9 : 0.1, right: cam.tall ? 0 : 0.7, ms: 900 });
+      cam.shake(400, 5);
+      await cam.hold(350);
+      cam.title({ kicker: 'When manners fail', line: 'Summon a dragon', place: { tall: 'top' } });
+      await cam.hold(2900);
+    } },
+    // Table talk: each bubble is framed once it has popped.
+    { name: 'banter', view: 'trailer-banter', query: 'chat=phrases', play: async ({ cam, fire, ease }) => {
+      await cam.focus(TABLE, { pad: 0.03 });
+      await cam.hold(200);
+      await fire('__say', 'Is that all you’ve got?', '1');
+      await cam.hold(450);
+      await cam.focus(['.speech-bubble.theirs', '.unit.foe >> nth=3'], { ms: 450, pad: 0.35, ease: ease.out });
+      await cam.hold(1300);
+      await fire('__say', 'You’ll pay for that!', '0');
+      await cam.hold(400);
+      await cam.focus(['.speech-bubble.mine', '.unit.ally >> nth=0'], { ms: 500, pad: 0.3, ease: ease.out });
+      await cam.hold(1500);
+    } },
+    // Victory: the final blow, and only then the win.
+    { name: 'victory', view: 'trailer-last-stand', play: async ({ cam, setView, drag, ease }) => {
+      await cam.focus(['.unit.foe', '.hand .pcard'], { pad: 0.04 });
+      await cam.hold(300);
+      await drag(card(0), '.unit.foe >> nth=3', { ms: 600 });
+      await setView('trailer-final-blow');
+      await cam.punch('.unit.foe >> nth=3', { pad: 0.5 });
+      cam.shake(450, 10);
+      await cam.hold(1400);
+      await setView('trailer-won');
+      cam.mark('hush');
+      await cam.hold(100);
+      cam.title({ line: 'Leave no one standing', place: 'bottom' });
+      await cam.focus(['.gameover-icon', '.gameover-title'], { ms: 2600, pad: 0.5, bottom: 1.2, ease: ease.out });
+      await cam.hold(3000);
+    } },
+    // The end card over the Great Hall, softened behind it.
+    { name: 'end', view: 'lobby', css: '#root { filter: blur(5px) brightness(0.6) saturate(0.8); }', play: async ({ cam, ease }) => {
+      await cam.focus('#root', { pad: -0.08, ms: 3800, ease: ease.linear });
+      cam.endCard();
+      await cam.hold(3800);
+    } },
+  ],
+};