wand-kit 0.0.0-stage → 0.2.0

package/lib/brand.js

@@ -0,0 +1,135 @@
+/**
+ * lib/brand.js — the two brands, resolved and turned into CSS.
+ *
+ * A brand is a directory with `tokens.json` (swatch, roles, faces, shape, art),
+ * `fonts/`, `assets/` and `lib/` (the Python helpers the exporters borrow).
+ * The kit runs in two shapes and finds the directory in both:
+ *
+ *   repo      power-prompts/studio/kit/ -> ../../../brand and brand-next
+ *   packaged  tools/package.mjs copies each into brands/<name>/ beside the kit
+ *
+ * `WAND_BRANDS_DIR` overrides both: it holds <name>/ per brand.
+ *
+ * Nothing downstream sees a hex. `css()` writes the roles as custom properties
+ * on `.page` (light) and `.page.dark`, the faces as @font-face rules, and the
+ * art as paths; a job may declare a `theme` — a client's own colours — which
+ * is merged into the roles and reported, by the brand gate, as declared.
+ * `theme.extra` lists colours the page carries outside the roles: as an array
+ * they are only declared; as an object (`{ navy: "240F4F" }`) each is also
+ * written as a custom property (`--navy`) so the job's CSS can use it.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const KIT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO_DIRS = { current: "brand", next: "brand-next" };
+export const BRANDS = Object.keys(REPO_DIRS);
+
+// The brand a job gets when the user names none. While the two brands overlap
+// this is the only switch: set it to "next" and publish, and every chat builds
+// on the website's brand unless the user asks for the current one. The skill
+// never states the default; `doctor` prints it from here.
+export const DEFAULT_BRAND = "current";
+
+// What a user says when they want each brand, so the rule reads the same
+// whichever way the default points.
+export const ASKED_AS = {
+  current: ["current brand", "old brand", "existing guidelines", "Geist"],
+  next: ["new brand", "new branding", "new brand guidelines", "the website's look"],
+};
+
+/** The default and the words that switch away from it, as one line. */
+export function brandRule() {
+  const other = BRANDS.find((b) => b !== DEFAULT_BRAND);
+  const words = ASKED_AS[other].map((w) => `"${w}"`);
+  return `${DEFAULT_BRAND} by default; ${other} only when the user asks for ${words.slice(0, -1).join(", ")} or ${words.at(-1)}`;
+}
+
+/** Absolute path of a brand directory, or an error naming every place looked. */
+export function brandDir(name) {
+  if (!REPO_DIRS[name]) throw new Error(`unknown brand "${name}" — one of ${BRANDS.join(", ")}`);
+  const tried = [];
+  for (const dir of candidates(name)) {
+    tried.push(dir);
+    const t = path.join(dir, "tokens.json");
+    if (fs.existsSync(t) && JSON.parse(fs.readFileSync(t, "utf8")).roles) return dir;
+  }
+  throw new Error(`brand "${name}" not found. Looked in:\n  ${tried.join("\n  ")}`);
+}
+
+function candidates(name) {
+  const out = [];
+  if (process.env.WAND_BRANDS_DIR) out.push(path.resolve(process.env.WAND_BRANDS_DIR, name));
+  out.push(path.join(KIT, "brands", name));
+  out.push(path.join(KIT, "..", "..", "..", REPO_DIRS[name]));
+  return out;
+}
+
+const hex6 = (h) => String(h).replace(/^#/, "").toUpperCase();
+export const url = (p) => "file://" + p;
+
+/**
+ * Load a brand, with an optional job theme merged over its roles.
+ *   theme: { light: { accent: "5F30C5" }, dark: {...}, extra: ["1C0943"] | { navy: "240F4F" } }
+ */
+export function loadBrand(name, theme = null) {
+  const dir = brandDir(name);
+  const tokens = JSON.parse(fs.readFileSync(path.join(dir, "tokens.json"), "utf8"));
+  const roles = { light: { ...tokens.roles.light }, dark: { ...tokens.roles.dark } };
+  const declared = new Set(), extras = {};
+  if (theme) {
+    for (const g of ["light", "dark"]) for (const [k, v] of Object.entries(theme[g] || {})) {
+      if (!(k in roles[g])) throw new Error(`theme.${g}.${k}: not a role (roles: ${Object.keys(roles[g]).join(", ")})`);
+      roles[g][k] = hex6(v); declared.add(hex6(v));
+    }
+    const extra = theme.extra || [];
+    for (const [k, v] of Object.entries(extra)) { declared.add(hex6(v)); if (!Array.isArray(extra)) extras[k] = hex6(v); }
+  }
+  const fonts = path.join(dir, "fonts"), assets = path.join(dir, "assets"), lib = path.join(dir, "lib");
+  for (const f of tokens.faces.files) if (!fs.existsSync(path.join(fonts, f.file))) throw new Error(`${name}: font ${f.file} missing from ${fonts}`);
+
+  // every colour a page may carry: both grounds' roles, the swatch, the theme
+  const tokenSet = new Set([...Object.values(roles.light), ...Object.values(roles.dark),
+    ...Object.values(tokens.swatch || {}).map(hex6), "FFFFFF", "000000", ...declared]);
+
+  const families = [...new Set(tokens.faces.files.map((f) => f.family))];
+  const art = (role) => {
+    const f = tokens.art[role];
+    if (!f) throw new Error(`${name}: no art for role "${role}" (${Object.keys(tokens.art).join(", ")})`);
+    return path.join(assets, f);
+  };
+
+  return {
+    name, title: tokens.title, dir, tokens, roles, declared, tokenSet, families, fonts, assets, lib,
+    art, artUrl: (role) => url(art(role)),
+    asset: (file) => path.join(assets, file),
+    assetUrl: (file) => url(path.join(assets, file)),
+    glyph: (g) => readGlyph(assets, g),
+    faceFiles: tokens.faces.files.map((f) => ({ ...f, path: path.join(fonts, f.file) })),
+    css: () => brandCss(tokens, roles, fonts, extras),
+  };
+}
+
+function readGlyph(assets, g) {
+  const loose = path.join(assets, "glyphs", `${g}.svg`);
+  if (fs.existsSync(loose)) return fs.readFileSync(loose, "utf8");
+  const packed = path.join(assets, "glyphs", "glyphs.json");
+  if (fs.existsSync(packed)) { const all = JSON.parse(fs.readFileSync(packed, "utf8")); if (all[g]) return all[g]; }
+  throw new Error(`glyph "${g}" not in ${path.join(assets, "glyphs")}`);
+}
+
+function vars(r) {
+  return Object.entries(r).map(([k, v]) => `--${k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase())}:#${v}`).join(";");
+}
+
+function brandCss(tokens, roles, fonts, extras = {}) {
+  const faces = tokens.faces.files.map((f) =>
+    `@font-face{font-family:"${f.family}";font-weight:${f.weight};font-style:${f.italic ? "italic" : "normal"};src:url("${url(path.join(fonts, f.file))}")}`).join("\n");
+  const F = tokens.faces, S = tokens.shape;
+  const face = (k) => `--face-${k}:"${F[k].family}";--w-${k}:${F[k].weight};--tr-${k}:${F[k].tracking}em;--lh-${k}:${F[k].leading}`;
+  return `${faces}
+.page{${vars(roles.light)};${Object.keys(extras).length ? vars(extras) + ";" : ""}${face("display")};${face("body")};${face("label")};--caps-label:${F.label.caps ? "uppercase" : "none"};
+  --radius-k:${S.radius};--card-stroke:${S.cardStroke}px;--emph-stroke:${S.emphStroke}px}
+.page.dark{${vars(roles.dark)}}`;
+}

package/lib/components.js

@@ -0,0 +1,313 @@
+/**
+ * lib/components.js — the vocabulary a page is composed from.
+ *
+ * Every piece that reviewed well in the Franklin Templeton case study, the
+ * aviation overview and the BofA talk, written once: the chrome (eyebrow,
+ * mark, footer), numbered sections, cards and the emphasis card, the chip
+ * strip with its arrows, the five-node flow, metered tables, quotes with
+ * attribution, figure rows, cover and closing pages, next-step cards.
+ *
+ * A component holds no value of its own. Colours come from the brand's roles
+ * (`--ink`, `--accent`), faces from `--face-display` / `--face-body` /
+ * `--face-label`, sizes from the surface's scale (`--t-h2`, `--m-gap`). The
+ * same markup therefore draws on either brand, light or dark, on a slide or
+ * a page — which is what lets a job be composed freely without leaving the
+ * system.
+ *
+ * `bind()` returns the helpers tied to one job: its brand, surface and
+ * 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 { 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 }) {
+  let n = 0;
+  const L = content.L;
+  const cls = (c) => (c ? ` ${c}` : "");
+  const list = (x) => (Array.isArray(x) ? x.join("") : String(x ?? ""));
+
+  /** `accent("Two Models", "Models")` → the phrase in the accent colour. */
+  const accent = (text, phrase) => (phrase ? esc(text).replace(esc(phrase), `<em>${esc(phrase)}</em>`) : esc(text));
+  const split = (ln, sep = " — ") => { const s = typeof ln === "number" ? L(ln) : ln; const i = s.indexOf(sep); return i < 0 ? [s, ""] : [s.slice(0, i), s.slice(i + sep.length)]; };
+  const cap = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+
+  const mark = (dark) => {
+    const invert = dark && brand.tokens.art.markInvertOnDark;
+    const src = brand.artUrl(dark && !invert ? "markOnDark" : "markOnLight");
+    return invert
+      ? `<div class="mark deco"><img class="w" src="${src}" alt=""><img class="star" src="${src}" alt=""></div>`
+      : `<div class="mark deco"><img src="${src}" alt=""></div>`;
+  };
+  const wordmark = (dark) => `<img class="wordmark deco" src="${brand.artUrl(dark ? "wordmarkOnDark" : "wordmarkOnLight")}" alt="Wand">`;
+
+  /**
+   * 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.
+   */
+  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true } = {}) => {
+    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)}"` : ""}>
+${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>
+${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${String(n).padStart(2, "0")}</span></footer>` : ""}
+</section>`;
+  };
+
+  const sec = (num, title, { stack = false } = {}) => `<div class="sec${stack ? " stack" : ""}"><span class="num">${esc(num)}</span><h2>${title}</h2></div>`;
+  const h = (tag) => (html, k = "") => `<${tag}${cls(k) ? ` class="${k}"` : ""}>${html}</${tag}>`;
+  const p = (k) => (html, extra = "") => `<p class="${k}${cls(extra)}">${html}</p>`;
+  const tag = (text, k = "") => `<div class="tag${cls(k)}">${esc(text)}</div>`;
+
+  const cols = (count, items, { stretch = true, cls: k = "" } = {}) =>
+    `<div class="cols cols-${count}${stretch ? " stretch" : ""}${cls(k)}">${list(items)}</div>`;
+
+  /** A card: optional tag, title (h4 by default), body html or paragraphs, an outcome line; `emph` flips it to the emphasis surface. */
+  const card = ({ tag: t, title, level = "h4", body = "", out = "", emph = false, cls: k = "", sm = false } = {}) =>
+    `<div class="card${emph ? " emph" : ""}${sm ? " sm" : ""}${cls(k)}">${t ? tag(t) : ""}${title ? `<${level}>${title}</${level}>` : ""}${Array.isArray(body) ? body.map((b) => `<p>${b}</p>`).join("") : body}${out ? `<p class="out">${out}</p>` : ""}</div>`;
+
+  const chip = (i, label, state = "") => `<span class="chip${cls(state)}"><span class="dot">${i + 1}</span><span>${esc(label)}</span></span>`;
+  /** The chips in a row, a solid arrow between each; `on` lights one and marks the earlier ones done. */
+  const strip = (labels, { on = -1 } = {}) => `<div class="strip">${labels.map((l, i) => chip(i, l, i === on ? "on" : on >= 0 && i < on ? "done" : "")).join(ARROW)}</div>`;
+  /** A phase heading: its chip, then its line. */
+  const phase = (i, label, line = "") => `<div class="phase">${chip(i, label)}${line ? `<h3>${esc(line)}</h3>` : ""}</div>`;
+
+  /** Five nodes with arrows: [who, verb, "a" | "p"] — agent or person. */
+  const flow = ({ label, nodes, note = "" }) => `<div class="flow"><div class="flabel">${esc(label)}</div><div class="nodes">${nodes.map(([who, verb, kind]) =>
+    `<div class="node ${kind || "p"}"><span class="who">${esc(who)}</span><span class="verb">${esc(verb)}</span></div>`).join(ARROW)}</div>${note ? `<p class="fnote">${note}</p>` : ""}</div>`;
+
+  /**
+   * A ruled table. `head`: cell strings. `rows`: arrays of cells; a cell is a
+   * string, or { v, meter: true, cls }. `emph`: the index of the row set in the accent.
+   */
+  const table = ({ head = [], rows = [], emph = -1, cls: k = "" }) => {
+    const cell = (c) => {
+      const o = typeof c === "object" && c ? c : { v: c };
+      const meter = o.meter ? `<div class="meter"><i style="width:${Math.max(0, Math.min(100, parseFloat(o.v) || 0))}%"></i></div>` : "";
+      return `<td${o.cls ? ` class="${o.cls}"` : ""}>${o.meter ? `<div class="val">${esc(o.v)}</div>` : esc(o.v)}${meter}</td>`;
+    };
+    return `<table class="grid${cls(k)}"><thead><tr>${head.map((x) => `<th>${esc(x)}</th>`).join("")}</tr></thead><tbody>${rows.map((r, i) =>
+      `<tr${i === emph ? ' class="emph"' : ""}>${r.map((c, j) => (j === 0 ? `<td class="rowhead">${esc(typeof c === "object" ? c.v : c)}</td>` : cell(c))).join("")}</tr>`).join("")}</tbody></table>`;
+  };
+
+  const who = (name, role) => `<div class="who"><div><div class="name">${esc(name)}</div><div class="role">${esc(role)}</div></div></div>`;
+  /** A quote card. `by` is "Name  ·  Role" or [name, role]. */
+  const quote = ({ text, by, emph = false, cls: k = "" }) => {
+    const [name, role] = Array.isArray(by) ? by : split(by, "  ·  ");
+    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>`;
+  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>`;
+
+  /** Next-step cards with arrows between; `when` is the timing line. */
+  const steps = (items) => `<div class="steps">${items.map(({ title, when, body, emph }, i) =>
+    `<div class="card step${emph ? " emph" : ""}"><div class="head"><span class="dot">${i + 1}</span><h5>${esc(title)}</h5></div>${when ? `<div class="when">${esc(when)}</div>` : ""}<p>${body}</p></div>`).join(ARROW)}</div>`;
+
+  const callout = ({ tag: t, text, emph = true }) => `<div class="card callout${emph ? " emph" : ""}">${t ? `<div class="tag">${esc(t)}</div>` : ""}<p>${text}</p></div>`;
+  const listOf = (items, k = "") => `<ul class="list${cls(k)}">${items.map((i) => `<li>${i}</li>`).join("")}</ul>`;
+
+  /** A cover page: label, display title (html), lede, body, meta line, anything else, on brand art. */
+  const cover = ({ label, title, lede = "", body = "", meta = "", extra = "", art = "cover", dark = true, eyebrow = "", cls: k = "" }) =>
+    page({ dark, art, eyebrow, cls: `cover${extra ? " split" : ""}${cls(k)}`, body: `<div class="top">${label ? `<div class="label">${esc(label)}</div>` : ""}<h1>${title}</h1>${lede ? `<p class="lede">${lede}</p>` : ""}${body ? `<p class="cover-body">${body}</p>` : ""}${meta ? `<p class="meta">${esc(meta)}</p>` : ""}</div>${extra ? `<div class="bottom">${extra}</div>` : ""}` });
+
+  /** A closing page: the lockup (pair line, title, url) over brand art, with an optional heading and line above it. */
+  const closing = ({ pair, title, url: u = "www.wand.ai", heading = "", lede = "", eyebrow = "", art = "closing", dark = true, cls: k = "" }) =>
+    page({ dark, art, eyebrow, cls: `back${cls(k)}`, body: `${heading ? `<h1>${heading}</h1>` : ""}${lede ? `<p class="lede">${lede}</p>` : ""}<div class="lockup"><div class="pair">${esc(pair)}</div><div class="title">${esc(title)}</div><div class="url">${esc(u)}</div></div>` });
+
+  /** A big outlined numeral in a dark panel on the right (the deck's chapter pages). */
+  const chapter = (num) => `<div class="chapter deco"><span>${esc(num)}</span></div>`;
+
+  const img = (src, k = "", alt = "") => `<img class="img${cls(k)}" src="${/^(file|https?|data):/.test(src) ? src : url(src)}" alt="${esc(alt)}">`;
+  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>`;
+
+  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"),
+    lead: p("lead"), body: p("body"), note: p("note"), small: p("body sm"), tag, p: (html, k = "") => `<p${cls(k) ? ` class="${k}"` : ""}>${html}</p>`,
+    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,
+    brand: brand.name, surface: surface.name, count: () => n,
+  };
+}
+
+/** The components' CSS. Every value is a custom property from the brand or the surface. */
+export const COMPONENTS_CSS = `
+*{box-sizing:border-box;margin:0;padding:0}
+html,body{background:#E9E7EE}
+.page{position:relative;overflow:hidden;break-after:page;background:var(--bg);color:var(--ink);font-family:var(--face-body);font-weight:var(--w-body);
+  letter-spacing:var(--tr-body);line-height:var(--lh-body);-webkit-font-smoothing:antialiased;font-variant-numeric:tabular-nums}
+.art{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;object-position:38% 50%}
+.shade{position:absolute;inset:0;background:var(--bg);opacity:.3}
+.eyebrow{position:absolute;left:var(--x);top:var(--c-eyebrow-top);font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--c-eyebrow-size);
+  letter-spacing:.22em;text-transform:var(--caps-label);color:var(--muted);line-height:1.2}
+.dark .eyebrow{color:var(--ink)}
+.eyebrow .bar{margin:0 .9em;opacity:.6}
+.mark{position:absolute;right:var(--x);top:var(--c-mark-top);width:var(--c-mark-w);height:var(--c-mark-h)}
+.mark img{position:absolute;left:0;top:0;width:100%;height:100%;object-fit:contain}
+.mark .w{filter:brightness(0) invert(1)}.mark .star{clip-path:inset(0 0 60% 58%)}
+.wordmark{position:absolute;right:var(--x);top:var(--c-mark-top);height:calc(var(--c-mark-h) * .62);width:auto}
+.content{position:absolute;left:var(--x);right:var(--x);top:var(--top);bottom:var(--bottom);display:flex;flex-direction:column;gap:var(--m-gap)}
+footer{position:absolute;left:var(--x);right:var(--x);bottom:var(--c-foot-bottom);display:flex;justify-content:space-between;align-items:center;
+  font-size:var(--c-foot-size);color:var(--muted);border-top:var(--c-foot-rule) solid var(--rule);padding-top:calc(var(--c-foot-rule) * 10);line-height:1.2}
+footer .pn{font-weight:500}
+/* type */
+h1,h2,h3,h4,h5,.display{font-family:var(--face-display);font-weight:var(--w-display);letter-spacing:var(--tr-display);line-height:var(--lh-display);color:var(--ink)}
+h1{font-size:var(--t-h1)}h1.md{font-size:var(--t-h1md)}h2{font-size:var(--t-h2)}h3{font-size:var(--t-h3);line-height:1.22}h4{font-size:var(--t-h4);line-height:1.2}h5{font-size:var(--t-h5);line-height:1.25}
+h1 em,h2 em,h3 em,h4 em,.display em,.lede em{font-style:normal;color:var(--accent-text)}
+.label{font-family:var(--face-display);font-weight:500;font-size:var(--t-label);letter-spacing:var(--tr-display);color:var(--label);line-height:1.2}
+.label.sm{font-size:calc(var(--t-label) * .8)}
+.lead{font-size:var(--t-lead);line-height:1.5;color:var(--ink)}
+.body{font-size:var(--t-body);line-height:var(--lh-body);color:var(--text)}
+.body.sm,.small{font-size:var(--t-sm);line-height:1.55;color:var(--text)}
+.note{font-size:var(--t-note);line-height:1.5;color:var(--soft)}
+.note b,.fnote b,.lede b{font-weight:600;color:var(--accent-text)}
+.tag{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.18em;text-transform:var(--caps-label);color:var(--label);margin-bottom:.55em;line-height:1.2}
+.wide{max-width:86%}
+b,strong{font-weight:600}
+/* sections */
+.sec{display:flex;align-items:baseline;gap:1em;padding-top:var(--m-sec-top);border-top:var(--m-stroke) solid var(--rule)}
+.sec:first-child{border-top:0;padding-top:0}
+.sec.stack{flex-direction:column;align-items:flex-start;gap:.35em}
+.sec .num{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-num);letter-spacing:.2em;color:var(--label)}
+.sec + .lead,.sec + .body{margin-top:calc(var(--m-gap) * -.3)}
+/* grids */
+.cols{display:grid;gap:var(--m-col-gap)}
+.cols-2{grid-template-columns:1fr 1fr}.cols-3{grid-template-columns:repeat(3,1fr)}.cols-4{grid-template-columns:repeat(4,1fr)}.cols-5{grid-template-columns:repeat(5,1fr)}
+.cols-12{grid-template-columns:1.35fr 1fr}.cols-21{grid-template-columns:1fr 1.35fr}
+.stretch{align-items:stretch}.span-2{grid-column:span 2}.span-3{grid-column:span 3}
+.rail{display:grid;grid-template-columns:3fr 9fr;gap:var(--m-col-gap)}
+/* cards */
+.card{background:var(--paper);border:var(--card-stroke) solid var(--stroke);border-radius:calc(var(--m-radius) * var(--radius-k));padding:var(--m-card-pad)}
+.card.sm{padding:var(--m-card-pad-sm)}
+.card.emph{background:var(--emph);border:var(--emph-stroke) solid var(--emph-accent);color:var(--emph-ink)}
+.card.emph p,.card.emph .body,.card.emph .role,.card.emph .lead{color:var(--emph-text)}
+.card.emph h3,.card.emph h4,.card.emph h5,.card.emph .name,.card.emph .lead-in,.card.emph .q p{color:var(--emph-ink)}
+.card.emph .tag,.card.emph .out,.card.emph .when,.card.emph em{color:var(--emph-accent)}
+.card.centred{display:flex;flex-direction:column;justify-content:center}
+.card p{font-size:var(--t-sm);line-height:1.5;color:var(--text)}
+.card .body{font-size:var(--t-body);line-height:var(--lh-body)}.card .body.sm{font-size:var(--t-sm);line-height:1.55}
+.card .lead{font-size:var(--t-lead)}
+.card h3{margin-bottom:.3em}.card h4{margin-bottom:.35em}.card h5{margin-bottom:.4em}
+.card .sub{font-size:var(--t-sm);font-weight:500;color:var(--accent-text);margin-bottom:.5em}
+.card.emph .sub{color:var(--emph-accent)}
+.card .out{margin-top:auto;padding-top:.6em;font-weight:500;color:var(--accent-text)}
+.card.fn,.card.flex{display:flex;flex-direction:column}
+.card.fn h5{font-family:var(--face-label);font-weight:var(--w-label);font-size:calc(var(--t-tag) * 1.1);letter-spacing:.12em;text-transform:var(--caps-label);color:var(--ink);margin-bottom:.6em}
+.card.emph.fn h5{color:var(--emph-ink)}
+.callout{padding:var(--m-card-pad)}
+.callout p{font-size:calc(var(--t-lead) * .9);font-weight:500;line-height:1.45}
+.lead-in,.card .lead-in{font-size:calc(var(--t-lead) * .92);font-weight:500;line-height:1.45}
+.role-tag{margin:.4em 0 .7em;font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.18em;text-transform:var(--caps-label);color:var(--soft)}
+.card.emph .role-tag{color:var(--emph-text)}
+/* chips, arrows, phases */
+.arrow{width:var(--m-arrow);height:var(--m-arrow);flex:none;fill:var(--emph)}
+.dark .arrow{fill:var(--accent)}
+.strip{display:flex;align-items:center;gap:calc(var(--m-arrow) * .9)}
+.strip .chip{flex:1}
+.chip{display:flex;align-items:center;gap:.6em;padding:.5em 1em .5em .45em;border:var(--m-stroke) solid var(--stroke);border-radius:999px;background:var(--paper);
+  font-size:calc(var(--t-sm) * .95);font-weight:500;color:var(--ink);line-height:1.2}
+.chip .dot{width:var(--m-chip);height:var(--m-chip);border-radius:50%;background:var(--emph);color:var(--emph-ink);font-size:calc(var(--t-sm) * .8);font-weight:600;display:flex;align-items:center;justify-content:center;flex:none}
+.chip.done{color:var(--accent-text)}
+.chip.on{background:var(--emph);border-color:var(--emph);color:var(--emph-ink)}
+.chip.on .dot{background:var(--emph-ink);color:var(--emph)}
+.phase{display:flex;align-items:center;gap:1em}
+.phase .chip{padding:.4em .9em .4em .4em}
+.phase h3{margin:0}
+/* the five-node flow */
+.flow{display:flex;flex-direction:column;gap:.55em}
+.flabel{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.18em;text-transform:var(--caps-label);color:var(--soft)}
+.flow .nodes{display:flex;align-items:center;gap:calc(var(--m-arrow) * .8)}
+.node{flex:1;display:flex;flex-direction:column;gap:.15em;padding:.7em 1em;border-radius:calc(var(--m-radius) * .7 * var(--radius-k));border:var(--m-stroke) solid var(--stroke);background:var(--paper)}
+.node .who{font-family:var(--face-label);font-weight:var(--w-label);font-size:calc(var(--t-tag) * .92);letter-spacing:.16em;text-transform:var(--caps-label);color:var(--soft);display:block;border:0;padding:0}
+.node .verb{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-sm);color:var(--ink);letter-spacing:var(--tr-display)}
+.node.a{background:var(--emph);border-color:var(--emph)}.node.a .who{color:var(--emph-accent)}.node.a .verb{color:var(--emph-ink)}
+.fnote{font-size:var(--t-sm);line-height:1.4;color:var(--text)}
+/* tables */
+table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums}
+.grid th{text-align:left;font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.16em;text-transform:var(--caps-label);color:var(--ink);padding:0 .7em .8em 0;border-bottom:var(--m-stroke) solid var(--rule)}
+.grid td{font-size:var(--t-body);padding:.8em .7em .8em 0;border-bottom:1px solid var(--rule);vertical-align:middle;color:var(--ink)}
+.grid .rowhead{font-size:calc(var(--t-body) * .95);color:var(--text)}
+.grid .val{font-weight:500}
+.grid tr.emph .val,.grid tr.emph .rowhead{color:var(--accent-text);font-weight:600}
+.grid td.strong{font-weight:600}.grid td.accent{font-weight:600;color:var(--accent-text)}
+.meter{margin-top:.4em;height:3px;border-radius:2px;background:var(--track);width:82%}
+.meter i{display:block;height:100%;border-radius:2px;background:var(--accent)}
+.grid tr.emph .meter i{background:var(--accent-text)}
+/* quotes */
+.q{display:flex;flex-direction:column;justify-content:space-between;gap:1.2em}
+.q p{font-size:var(--t-quote);line-height:1.6;color:var(--ink)}
+.who{display:flex;align-items:center;gap:.9em;border-top:1px solid var(--rule);padding-top:1em}
+.card.emph .who{border-top-color:var(--emph-accent)}
+.who .name{font-size:var(--t-name);font-weight:600;color:var(--ink)}
+.who .role{font-size:var(--t-role);color:var(--soft);margin-top:.15em}
+/* figures */
+.stats{display:grid;grid-auto-flow:column;grid-auto-columns:1fr;gap:var(--m-col-gap)}
+.stat{border:var(--card-stroke) solid var(--stroke);border-radius:calc(var(--m-radius) * var(--radius-k));background:var(--paper);padding:1.2em 1.3em 1.1em;display:flex;flex-direction:column;justify-content:flex-end;gap:.45em}
+.stat .v{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-stat);line-height:1;letter-spacing:-.03em;color:var(--ink)}
+.stat.hero .v{font-size:var(--t-hero)}
+.stat .k{font-size:var(--t-sm);font-weight:500;color:var(--text)}
+.delta{display:flex;align-items:center;gap:.5em;margin:.2em 0 .45em}
+.delta .from{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-h3);color:var(--soft)}
+.delta .to{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-h3);color:var(--accent-text)}
+.delta .arrow{fill:var(--accent)}
+/* next steps */
+.steps{display:flex;align-items:stretch;gap:.7em}
+.steps .arrow{align-self:center}
+.step{flex:1}
+.step .head{display:flex;align-items:center;gap:.6em}
+.step h5{margin:0}
+.step .dot{width:var(--m-chip);height:var(--m-chip);border-radius:50%;background:var(--emph);color:var(--emph-ink);font-size:calc(var(--t-sm) * .8);font-weight:600;display:flex;align-items:center;justify-content:center;flex:none}
+.step.emph .dot{background:var(--emph-ink);color:var(--emph)}
+.step .when{font-size:var(--t-note);font-weight:500;color:var(--accent-text);margin:.5em 0 .3em}
+/* lists */
+.list{list-style:none;display:flex;flex-direction:column;gap:.45em;font-size:var(--t-body);color:var(--text);line-height:1.5}
+.list li{display:flex;gap:.6em}
+.list li::before{content:"";flex:none;width:.4em;height:.4em;border-radius:50%;background:var(--accent);margin-top:.55em}
+.card .list{font-size:var(--t-sm)}
+/* cover and closing */
+.cover .content{justify-content:center;gap:0}
+.cover.split .content{justify-content:space-between}
+.cover .top{display:flex;flex-direction:column;gap:1.3em}
+.cover h1{font-size:var(--t-display);line-height:1.02;letter-spacing:-.03em}
+.lede{font-size:var(--t-lede);font-weight:500;line-height:1.45;color:var(--ink);max-width:88%}
+.cover-body{font-size:var(--t-body);line-height:1.6;color:var(--text);max-width:80%}
+.meta{font-size:var(--t-meta);color:var(--text);padding-top:1em;border-top:1px solid var(--rule);line-height:1.4}
+.cover .bottom{display:flex;flex-direction:column;gap:1em}
+.back .content{justify-content:center;gap:1.4em}
+.lockup{padding-top:1.4em;border-top:1px solid var(--rule);display:flex;flex-direction:column;gap:.5em}
+.lockup .pair{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.22em;text-transform:var(--caps-label);color:var(--accent-text)}
+.lockup .title{font-family:var(--face-display);font-weight:var(--w-display);font-size:var(--t-h1md);letter-spacing:var(--tr-display);line-height:1.1}
+.lockup .url{font-size:var(--t-sm);color:var(--text)}
+.dark .rule,.dark .meta,.dark .lockup,.dark .who,.dark footer{border-color:var(--rule)}
+/* chapter panel */
+.chapter{position:absolute;right:0;top:0;bottom:0;width:31%;border-radius:calc(var(--m-radius) * 1.15 * var(--radius-k));overflow:hidden;
+  background:radial-gradient(120% 90% at 85% 10%, var(--emph-accent) -40%, var(--emph) 55%, color-mix(in srgb, var(--emph), #000 35%) 100%)}
+.chapter span{position:absolute;right:9%;bottom:-.12em;font-family:var(--face-display);font-weight:var(--w-display);font-size:calc(var(--t-display) * 6);line-height:1;letter-spacing:-.05em;
+  color:transparent;-webkit-text-stroke:2px var(--emph-accent);opacity:.6}
+.has-chapter .left{width:62%;display:flex;flex-direction:column;gap:var(--m-gap)}
+/* images, icons */
+.img{display:block;max-width:100%}
+.figure{border-radius:calc(var(--m-radius) * var(--radius-k));overflow:hidden}
+.icon{width:1.25em;height:1.25em;stroke:currentColor;fill:none}
+.tile{width:2.3em;height:2.3em;border-radius:calc(var(--m-radius) * .6 * var(--radius-k));background:var(--surface);display:flex;align-items:center;justify-content:center;color:var(--accent-text);flex:none;margin-bottom:.8em}
+.card.emph .tile{background:var(--emph-accent);color:var(--emph)}
+/* room */
+.roomy .content{gap:calc(var(--m-gap) * 1.3)}
+.roomy .cols{margin:auto 0}
+.roomy .lead{font-size:calc(var(--t-lead) * 1.15)}
+.roomy .card{padding:calc(var(--m-gap) * 1.5) calc(var(--m-gap) * 1.7)}
+.centre{text-align:center;align-items:center}
+.grow{flex:1}
+.spread{justify-content:space-between}
+`;

package/lib/content.js

@@ -0,0 +1,66 @@
+/**
+ * lib/content.js — the words, kept apart from the design.
+ *
+ * A job's copy lives in a lines file (`content.txt`): one source string per
+ * line, verbatim, in the source's order. The page is composed by line number,
+ * so no string can drift from the source without a trace, and the coverage
+ * gate can read every line back off the page.
+ *
+ * Departures are declared, not hidden:
+ *   edits  { 44: [["needle", "replacement"]] }   applied before the page sees the line, must match
+ *   cut    [6, 7]                                 left out on purpose; coverage skips them
+ *   split  " — "                                  a line the layout sets in parts (label — body)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const esc = (s) => String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+export function loadContent(jobDir, job) {
+  if (!job.content) return { lines: [], L: () => { throw new Error("this job has no content file"); }, cut: new Set(), edited: 0, has: false };
+  const file = path.resolve(jobDir, job.content);
+  if (!fs.existsSync(file)) throw new Error(`content file not found: ${file}`);
+  const lines = fs.readFileSync(file, "utf8").replace(/\r/g, "").split("\n");
+  let edited = 0;
+  for (const [k, subs] of Object.entries(job.edits || {})) {
+    const i = +k - 1;
+    if (!(i in lines)) throw new Error(`edits: no line ${k}`);
+    for (const [a, b] of subs) {
+      if (!lines[i].includes(a)) throw new Error(`edit ${k}: "${a}" not found in: ${lines[i].slice(0, 80)}`);
+      lines[i] = lines[i].replace(a, b); edited++;
+    }
+  }
+  const L = (n) => {
+    if (!(n - 1 in lines)) throw new Error(`L(${n}): the content file has ${lines.length} lines`);
+    return lines[n - 1];
+  };
+  return { lines, L, cut: new Set(job.cut || []), edited, has: true, file };
+}
+
+/** Whitespace-free, case-folded, with the characters that get swapped in transit normalised. */
+export function norm(s) {
+  return String(s).normalize("NFKC")
+    .replace(/[‘’]/g, "'").replace(/[“”]/g, '"')
+    .replace(/[–—−]/g, "-").replace(/ /g, " ").replace(/…/g, "...")
+    .replace(/[\s­]+/g, "").toLowerCase();
+}
+
+/**
+ * Which lines are not on the page. A line passes whole, or in every part when
+ * split on one of the job's splitters (the layout sets "Finance — the line" as
+ * a card title over its body).
+ */
+export function coverage(content, pageText, splitters = [" — ", "  ·  ", " · "]) {
+  const hay = norm(pageText);
+  const miss = [];
+  content.lines.forEach((s, i) => {
+    const n = i + 1;
+    if (!s.trim() || content.cut.has(n)) return;
+    if (hay.includes(norm(s))) return;
+    const sp = splitters.find((x) => s.includes(x));
+    if (sp && s.split(sp).every((p) => !p.trim() || hay.includes(norm(p)))) return;
+    miss.push(n);
+  });
+  const total = content.lines.filter((s, i) => s.trim() && !content.cut.has(i + 1)).length;
+  return { miss, total, found: total - miss.length };
+}