wand-kit 0.3.3 → 0.5.0

package/lib/brand.js

@@ -1,11 +1,11 @@
 /**
- * lib/brand.js — the two brands, resolved and turned into CSS.
+ * lib/brand.js — the three 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
+ *   repo      power-prompts/studio/kit/ -> ../../../brand, brand-next and brand-interim
  *   packaged  tools/package.mjs copies each into brands/<name>/ beside the kit
  *
  * `WAND_BRANDS_DIR` overrides both: it holds <name>/ per brand.
@@ -23,7 +23,7 @@ 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" };
+const REPO_DIRS = { current: "brand", next: "brand-next", interim: "brand-interim" };
 export const BRANDS = Object.keys(REPO_DIRS);
 
 // The brand a job gets when the user names none. While the two brands overlap
@@ -37,13 +37,13 @@ export const DEFAULT_BRAND = "current";
 export const ASKED_AS = {
   current: ["current brand", "old brand", "existing guidelines", "Geist"],
   next: ["new brand", "new branding", "new brand guidelines", "the website's look"],
+  interim: ["interim brand", "interim branding", "the live site's look", "the transitional website", "wand.ai as it is today"],
 };
 
 /** 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)}`;
+  const words = (b) => { const w = ASKED_AS[b].map((x) => `"${x}"`); return `${w.slice(0, -1).join(", ")} or ${w.at(-1)}`; };
+  return `${DEFAULT_BRAND} by default; ${BRANDS.filter((b) => b !== DEFAULT_BRAND).map((b) => `${b} only when the user asks for ${words(b)}`).join("; ")}`;
 }
 
 /** Absolute path of a brand directory, or an error naming every place looked. */
@@ -128,11 +128,16 @@ function brandCss(tokens, roles, fonts, extras = {}) {
     `@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}`;
+  // a brand whose title phrase changes face (interim: Newsreader for <em>) declares `faces.phrase`; without it the
+  // phrase inherits the title's face, so the other brands draw exactly as before
+  // a brand may draw its art unshaded (`shape.artShade`, 0.3 otherwise) and set its cover title at its own tracking
+  // (`faces.display.coverTracking`, -0.03em otherwise): interim does both, as its approved social design does
+  const P = F.phrase, phrase = P ? `;--face-phrase:"${P.family}";--w-phrase:${P.weight};--tr-phrase:${P.tracking}em;--style-phrase:${P.italic ? "italic" : "normal"};--style-phrase-art:${P.artItalic || P.italic ? "italic" : "normal"}` : "";
   // the talk and board runtimes' own controls, dressed in the brand's dark roles
   const d = roles.dark, ui = { bg: d.track, card: d.paper, stroke: d.stroke, ink: d.ink, text: d.text, label: d.muted, accent: d.accent };
   return `${faces}
 :root{${Object.entries(ui).map(([k, v]) => `--ui-${k}:#${v}`).join(";")};--ui-face:"${F.body.family}"}
 .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}
+  --radius-k:${S.radius};--card-stroke:${S.cardStroke}px;--emph-stroke:${S.emphStroke}px;--art-shade:${S.artShade ?? 0.3};--tr-cover:${F.display.coverTracking ?? -0.03}em${phrase}}
 .page.dark{${vars(roles.dark)}}`;
 }

package/lib/components.js

@@ -51,17 +51,20 @@ export function bind({ brand, surface, job, content, dir: jobDir = process.cwd()
    * number. `art` is a brand art role ("cover", "overlay", "closing") or a
    * 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.
+   * pace; `motion: "none"` keeps a slide still when the deck animates; `footer` replaces the job's footer line
+   * on this page (a source note).
    */
-  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true, seconds = 0, motion = "", autosize = true } = {}) => {
+  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true, seconds = 0, motion = "", autosize = true, footer = null } = {}) => {
     n += 1;
-    const artSrc = art ? (/[\/.]/.test(art) && !brand.tokens.art[art] ? url(art) : brand.artUrl(art)) : null;
+    // a brand may draw a role again for a portrait page (`coverPortrait`), where its landscape art would crop away
+    const role = art && surface.h > surface.w && brand.tokens.art[`${art}Portrait`] ? `${art}Portrait` : art;
+    const artSrc = art ? (/[\/.]/.test(art) && !brand.tokens.art[art] ? url(art) : brand.artUrl(role)) : 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)}"` : ""}${seconds ? ` data-seconds="${seconds}"` : ""}${motion ? ` data-motion="${esc(motion)}"` : ""}${autosize ? "" : ' data-size="fixed"'}>
 ${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>` : ""}
+${chrome ? `<footer><span>${esc(footer ?? job.footer ?? "")}</span><span class="pn">${String(n).padStart(2, "0")}</span></footer>` : ""}
 </section>`;
   };
 
@@ -266,7 +269,7 @@ 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}
+.shade{position:absolute;inset:0;background:var(--bg);opacity:var(--art-shade,.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)}
@@ -283,10 +286,12 @@ footer .pn{font-weight:500}
 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}
 /* a title's phrase is its second tone (on the current brand, the accent itself); on the cover, a statement
-   and the close, the pages that carry the brand's art, it keeps the accent */
-h1 em,h2 em,.display em{font-style:normal;color:var(--second)}
+   and the close, the pages that carry the brand's art, it keeps the accent. A brand may give the phrase its
+   own face (interim: Newsreader, the italic on the art pages); the others leave the variables unset */
+h1 em,h2 em,.display em{font-family:var(--face-phrase,inherit);font-weight:var(--w-phrase,inherit);font-style:var(--style-phrase,normal);letter-spacing:var(--tr-phrase,inherit);color:var(--second)}
 h3 em,h4 em,h5 em,.lede em{font-style:normal;color:var(--second-sm)}
 .page:has(>.art) :is(h1,h2,h3,h4,h5,.display,.lede) em{color:var(--accent-text)}
+.page:has(>.art) :is(h1,h2,.display) em{font-style:var(--style-phrase-art,normal)}
 .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)}
@@ -403,7 +408,7 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .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}
+.cover h1{font-size:var(--t-display);line-height:1.02;letter-spacing:var(--tr-cover,-.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:min(80%,44em)}
 .meta{font-size:var(--t-meta);color:var(--text);padding-top:1em;border-top:1px solid var(--rule);line-height:1.4}

package/lib/engine.js

@@ -97,7 +97,21 @@ const stem = (job, file) => (job.file || job.name || path.basename(path.dirname(
 /* ------------------------------------------------------------------ gates */
 
 /** Runs inside the page. Everything is read from the rendered DOM. */
-function GATES({ min, chars, tokens, families, base }) {
+/* The lines a block of text sets in, read from the browser's own line boxes: a box's height misleads (a table cell
+   is as tall as its row, a card's paragraph as tall as the card), the fragments of its text do not. Runs inside the page. */
+const LINES_OF = `(el) => {
+  const rg = document.createRange(); rg.selectNodeContents(el);
+  const rs = [...rg.getClientRects()].filter((q) => q.width > 0.5 && q.height > 0.5).sort((a, b) => a.top - b.top);
+  let n = 0, cur = null;
+  for (const q of rs) {
+    if (cur && q.top < cur.bottom - Math.min(q.height, cur.bottom - cur.top) * 0.5) { cur.bottom = Math.max(cur.bottom, q.bottom); continue; }
+    n++; cur = { top: q.top, bottom: q.bottom };
+  }
+  return n;
+}`;
+
+function GATES({ min, chars, tokens, families, base, maxLines = 0, linesOf }) {
+  const countLines = eval(linesOf);
   const T = new Set(tokens);
   const pages = [...document.querySelectorAll(".page")];
   const toHex = (c) => {
@@ -109,9 +123,18 @@ 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: [], broken: [],
+  const res = { fit: [], overlap: [], brand: [], fonts: [], contrast: [], type: [], measure: [], lines: [], dash: [], stretched: [], texts: [], notes: [], broken: [], extent: [],
     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("/")); });
+  // an image drawn at another shape than its own (a flex column stretches an <img> with width:auto across it, the
+  // sales deck's screenshots on 2026-10-27): only object-fit cover, contain or none may change the box's shape
+  document.querySelectorAll("img").forEach((im) => {
+    if (!im.naturalWidth || !im.naturalHeight || /\.svg($|[?#])/i.test(im.getAttribute("src") || "")) return;
+    const r = im.getBoundingClientRect(); if (r.width < 4 || r.height < 4) return;
+    if (["cover", "contain", "none", "scale-down"].includes(getComputedStyle(im).objectFit)) return;
+    const k = (r.width / r.height) / (im.naturalWidth / im.naturalHeight);
+    if (Math.abs(k - 1) > 0.02) res.stretched.push({ page: pages.indexOf(im.closest(".page")) + 1, src: decodeURIComponent(im.getAttribute("src").replace(/^file:\/\//, "")).split("/").pop(), k: +k.toFixed(2) });
+  });
   const seen = new Set();
   // a page's composition, coarsely: the blocks of its content in order, and how many a grid holds
   const kindOf = (el) => { const c = [...el.classList].filter((x) => !/^(deco|big|wide|stretch|centre|sm|md)$/.test(x)).slice(0, 2); return el.tagName.toLowerCase() + (c.length ? "." + c.join(".") : ""); };
@@ -124,7 +147,8 @@ function GATES({ min, chars, tokens, families, base }) {
     const n = pi + 1;
     const content = pg.querySelector(".content");
     const box = (content || pg).getBoundingClientRect();
-    const foot = pg.querySelector("footer")?.getBoundingClientRect();
+    // a page that hides its footer (a cover, a close) is measured against its content box alone
+    const fr = pg.querySelector("footer")?.getBoundingClientRect(), foot = fr && fr.height ? fr : null;
     const floor = foot ? Math.min(box.bottom, foot.top - 6) : box.bottom;
     let over = 0, why = "", low = -Infinity;
     for (const el of (content || pg).querySelectorAll("*")) {
@@ -142,6 +166,9 @@ function GATES({ min, chars, tokens, families, base }) {
     const all = [...pg.querySelectorAll("*")];
     const leaves = all.filter((e) => !e.closest(".deco, svg, script, style") && [...e.childNodes].some((c) => c.nodeType === 3 && c.data.trim()));
     const boxes = leaves.map((e) => ({ e, r: e.getBoundingClientRect() })).filter((x) => x.r.width && x.r.height);
+    // how far the words run across the page, for a share image that a square crop from the centre must keep
+    const words = boxes.filter((x) => content && content.contains(x.e)), pgBox = pg.getBoundingClientRect();
+    if (words.length) res.extent.push({ page: n, l: Math.round(Math.min(...words.map((x) => x.r.left)) - pgBox.left), r: Math.round(Math.max(...words.map((x) => x.r.right)) - pgBox.left) });
     for (let i = 0; i < boxes.length; i++) for (let j = i + 1; j < boxes.length; j++) {
       const A = boxes[i], B = boxes[j];
       if (A.e.contains(B.e) || B.e.contains(A.e)) continue;
@@ -170,6 +197,8 @@ function GATES({ min, chars, tokens, families, base }) {
       const r = el.getBoundingClientRect(), lh = parseFloat(cs.lineHeight) || size * 1.4;
       const inner = r.height - parseFloat(cs.paddingTop) - parseFloat(cs.paddingBottom);
       if (Math.round(inner / lh) >= 2 && r.width / (size * 0.48) > chars) res.measure.push({ page: n, el: sel(el), chars: Math.round(r.width / (size * 0.48)) });
+      // a paragraph that wraps past maxLines on a slide: the edits in PowerPoint and Google Slides reflow it, and it breaks
+      if (maxLines && cs.display !== "inline") { const k = countLines(el); if (k > maxLines) res.lines.push({ page: n, el: sel(el), lines: k, text: (el.innerText || "").trim().slice(0, 32) }); }
     }
     const text = pg.innerText || "";
     if (text.includes("\u2014")) res.dash.push(n);
@@ -185,7 +214,8 @@ function GATES({ min, chars, tokens, families, base }) {
  * sizes itself to its slides, the same way on every run. Returns the pages
  * it changed, and every slide's fill after.
  */
-function AUTOSIZE() {
+function AUTOSIZE({ maxLines = 0, linesOf } = {}) {
+  const countLines = eval(linesOf);
   const fill = (pg) => {
     const c = pg.querySelector(".content"); if (!c) return 1;
     const kids = [...c.children].filter((k) => !k.classList.contains("deco") && k.getBoundingClientRect().height);
@@ -194,15 +224,20 @@ function AUTOSIZE() {
     return (kids.reduce((a, k) => a + k.getBoundingClientRect().height, 0) + gap * (kids.length - 1)) / c.getBoundingClientRect().height;
   };
   const overflows = (pg) => {
-    const c = pg.querySelector(".content"), box = c.getBoundingClientRect(), foot = pg.querySelector("footer")?.getBoundingClientRect();
+    const c = pg.querySelector(".content"), box = c.getBoundingClientRect(), fr = pg.querySelector("footer")?.getBoundingClientRect(), foot = fr && fr.height ? fr : null;
     const floor = foot ? Math.min(box.bottom, foot.top - 6) : box.bottom;
     // as the fit gate reads it: an inline run's line box may rise above the content's top, a block may not
     return [...c.querySelectorAll("*")].some((el) => { if (el.closest(".deco")) return false; const r = el.getBoundingClientRect(); return r.width && r.height && (r.bottom > floor + 0.5 || r.right > box.right + 1 || (getComputedStyle(el).display !== "inline" && r.top < box.top - 0.5)); }) || fill(pg) > 1;
   };
+  // the step up is also undone when it would wrap a paragraph past the job's line limit
+  const tooLong = (pg) => maxLines > 0 && [...pg.querySelectorAll(".content *")].some((el) => {
+    if (el.closest(".deco, svg") || ![...el.childNodes].some((n) => n.nodeType === 3 && n.data.trim())) return false;
+    return getComputedStyle(el).display !== "inline" && countLines(el) > maxLines;
+  });
   const sized = [], fills = [];
   document.querySelectorAll(".page").forEach((pg, i) => {
     if (pg.matches(".cover, .back, .shot, .run, [data-size]")) return;
-    if (fill(pg) < 0.55 && !pg.classList.contains("big")) { pg.classList.add("big"); if (overflows(pg)) pg.classList.remove("big"); else sized.push(i + 1); }
+    if (fill(pg) < 0.55 && !pg.classList.contains("big")) { pg.classList.add("big"); if (overflows(pg) || tooLong(pg)) pg.classList.remove("big"); else sized.push(i + 1); }
     fills.push({ page: i + 1, fill: fill(pg) });
   });
   return { sized, fills };
@@ -245,10 +280,12 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
   await page.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
   await page.waitForTimeout(120);
 
+  // a slide's paragraphs stay at two lines unless the job says otherwise (Carlos, 2026-10-27: past two "it breaks a lot")
+  const maxLines = surface.kind === "slide" ? job.maxLines ?? 2 : job.maxLines ?? 0;
   // a slide deck sizes itself before anything is measured or drawn; the file keeps the sizes it chose
-  const auto = surface.kind === "slide" ? await page.evaluate(AUTOSIZE) : { sized: [], fills: [] };
+  const auto = surface.kind === "slide" ? await page.evaluate(AUTOSIZE, { maxLines, linesOf: LINES_OF }) : { sized: [], fills: [] };
   if (auto.sized.length) fs.writeFileSync(htmlPath, "<!doctype html>\n" + await page.evaluate(() => document.documentElement.outerHTML));
-  const g = await page.evaluate(GATES, { min: surface.min, chars: surface.chars, tokens: [...brand.tokenSet], families: brand.families, base: surface.base });
+  const g = await page.evaluate(GATES, { min: surface.min, chars: surface.chars, tokens: [...brand.tokenSet], families: brand.families, base: surface.base, maxLines, linesOf: LINES_OF });
   const pageCount = g.fit.length;
   const text = g.texts.join("\n");
   const cov = content.has ? coverage(content, text, job.splitters) : null;
@@ -270,6 +307,8 @@ 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);
+  // hard when the job sets maxLines, a warning on every other deck
+  if (maxLines) row(!g.lines.length, "lines", g.lines.length ? `${g.lines.length} over ${maxLines}: ` + g.lines.slice(0, 4).map((o) => `p${o.page} ${o.el} ${o.lines} lines (${o.text}…)`).join("; ") + (g.lines.length > 4 ? " …" : "") : `no paragraph over ${maxLines} line${maxLines === 1 ? "" : "s"}`, job.maxLines == null);
   const sparse = auto.fills.filter((f) => f.fill < 0.4);
   if (surface.kind === "slide") row(!sparse.length, "space", sparse.length ? `${sparse.map((f) => `p${f.page} ${Math.round(f.fill * 100)}%`).join(", ")} of the slide used: add the proof, a figure or a visual, or join it to the next` : `every slide uses its space${auto.sized.length ? ` (type a step up on p${auto.sized.join(", p")})` : ""}`, true);
   // the same composition page after page is what makes a set of pages read as a template
@@ -280,7 +319,14 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
     start = i;
   }
   if (composed) row(!runs.length, "variety", runs.length ? runs.map(([a, z]) => `p${a}–p${z}`).join(", ") + " share one composition: vary it (a statement, a split, a figure, a photograph) or join them" : "no composition repeats three pages running", true);
-  row(!g.broken.length, "images", g.broken.length ? `${g.broken.length} did not load: ${g.broken.slice(0, 3).join(", ")}` : "every image loaded");
+  // Slack's and WhatsApp's thumbnails of a link are a square cut from the image's centre: words outside it are cut
+  if (surface.name === "og") {
+    const sq = [(surface.w - surface.h) / 2, (surface.w + surface.h) / 2], cut = g.extent.filter((e) => e.l < sq[0] || e.r > sq[1]);
+    row(!cut.length, "crop", cut.length ? `${cut.map((e) => `p${e.page} words from x ${e.l} to ${e.r}`).join(", ")}; Slack and WhatsApp keep x ${sq[0]} to ${sq[1]}: keep the words of a share image there` : `every page's words inside the centre square (x ${sq[0]} to ${sq[1]}), whole in Slack's and WhatsApp's square cut`, true);
+  }
+  row(!g.broken.length && !g.stretched.length, "images", g.broken.length ? `${g.broken.length} did not load: ${g.broken.slice(0, 3).join(", ")}`
+    : g.stretched.length ? `${g.stretched.length} drawn out of shape: ` + g.stretched.slice(0, 4).map((o) => `p${o.page} ${o.src} ${o.k > 1 ? "stretched" : "squeezed"} ${Math.round(Math.abs(o.k - 1) * 100)}%`).join("; ") + (g.stretched.length > 4 ? " …" : "")
+    : "every image loaded, each at its own shape");
   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)`);

package/lib/library.js

@@ -0,0 +1,180 @@
+/**
+ * lib/library.js — approved Wand files, handed out as they are.
+ *
+ * `library/index.json` lists every file a person approved: the social set on
+ * the interim brand (banners, avatar, the share images that went live, the
+ * site's icons), and the brands' own logos and art, which it names inside the
+ * brand folders rather than copying. Asked for "the LinkedIn banner", a chat
+ * hands over that file, byte for byte; it never redraws or re-exports one.
+ *
+ *   node wand.js library [words] [--brand interim]     what there is
+ *   node wand.js library get <id> [<id>…] [--to dir]   copy it, with where it goes
+ *   node wand.js library --check                       every file is the one approved, and the kit still draws it
+ *
+ * index.json:
+ *   recipes  { <brand>: a social.json spec }   how the kit draws the files it can draw
+ *   assets   [{ id, brand, kind, title, size, use, approved, recipe?, tags, files: [file] }]
+ *   file     { path, as?, from?, delivered?, tolerance?, px, bytes, sha256 }
+ *            path       inside library/, or "brand:<name>/<path in the brand folder>"
+ *            as         the name it is handed out under (a brand file: wand-<brand>-<name>)
+ *            from       the recipe's output it is checked against ("#tags": the card's tag block)
+ *            delivered  where the stored bytes came from, when they are a file people already received
+ *            tolerance  what the redraw may differ by: { mean (levels in 255, default 1), off (% of pixels
+ *                       over 24 levels, default 0.25) }; past 4 levels or 2% it fails
+ * `tools/library.mjs` (developer-only, in the repo) adds a file and rewrites bytes, sha256 and px.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { brandDir, DEFAULT_BRAND } from "./brand.js";
+
+const KIT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const LIB = path.join(KIT, "library");
+
+export const load = () => JSON.parse(fs.readFileSync(path.join(LIB, "index.json"), "utf8"));
+
+/** The file on disk for an index path. */
+export function resolve(p) {
+  const m = /^brand:([a-z]+)\/(.+)$/.exec(p);
+  return m ? path.join(brandDir(m[1]), m[2]) : path.join(LIB, p);
+}
+
+/** The name a file is handed out under. */
+export function handOutName(file) {
+  if (file.as) return file.as;
+  const m = /^brand:([a-z]+)\/(.+)$/.exec(file.path);
+  return m ? `wand-${m[1]}-${path.basename(m[2])}` : path.basename(file.path);
+}
+
+export const sha256 = (f) => crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+
+/** Pixel size of a PNG, an ICO's largest frame or an SVG's viewBox; null for anything else. */
+export function px(f) {
+  const b = fs.readFileSync(f);
+  if (b[0] === 0x89 && b.toString("ascii", 1, 4) === "PNG") return `${b.readUInt32BE(16)} x ${b.readUInt32BE(20)}`;
+  if (b.readUInt16LE(0) === 0 && b.readUInt16LE(2) === 1) { let m = 0; for (let i = 0; i < b.readUInt16LE(4); i++) m = Math.max(m, b[6 + 16 * i] || 256); return `${m} x ${m}`; }
+  const vb = /viewBox="[-\d.]+ [-\d.]+ ([\d.]+) ([\d.]+)"/.exec(b.toString("utf8", 0, 600));
+  return vb ? `${+vb[1]} x ${+vb[2]} (vector)` : null;
+}
+
+/** Assets whose id, title, kind, brand or tags hold every word. */
+export function list(words = [], { brand = null } = {}) {
+  const ws = words.map((w) => w.toLowerCase());
+  return load().assets.filter((a) => (!brand || a.brand === brand) &&
+    ws.every((w) => [a.id, a.title, a.kind, a.brand, ...(a.tags || [])].join(" ").toLowerCase().includes(w)));
+}
+
+/** One asset by id; a bare name ("wordmark") resolves to the brand asked for, or the default brand's. */
+export function find(id, { brand = null } = {}) {
+  const all = load().assets, exact = all.find((a) => a.id === id);
+  if (exact) return { asset: exact };
+  const cands = all.filter((a) => a.id.startsWith(id + "-") || a.id === `${id}-${brand || DEFAULT_BRAND}`);
+  const pick = cands.filter((a) => a.brand === (brand || DEFAULT_BRAND));
+  if (pick.length === 1) return { asset: pick[0] };
+  if (cands.length === 1) return { asset: cands[0] };
+  // not an id: the assets the word finds, for the chat to choose from
+  return { asset: null, cands: cands.length ? cands : list(id.split(/[\s-]+/), { brand }) };
+}
+
+/** Copy the assets' files into `to`; returns what was copied, for the note the chat gives with them. */
+export function get(ids, { to = "wand-assets", brand = null } = {}) {
+  const done = [], missing = [];
+  for (const id of ids) {
+    const { asset, cands } = find(id, { brand });
+    if (!asset) { missing.push({ id, cands: (cands || []).map((a) => a.id) }); continue; }
+    const files = asset.files.map((f) => {
+      const src = resolve(f.path), dest = path.join(to, f.path.startsWith("brand:") ? "" : path.dirname(f.path).split(path.sep).slice(1).join(path.sep), handOutName(f));
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+      if (f.sha256 && sha256(dest) !== f.sha256) throw new Error(`${dest}: does not match the approved file (run node wand.js library --check)`);
+      return { dest, px: f.px, bytes: f.bytes };
+    });
+    done.push({ asset, files });
+  }
+  return { done, missing };
+}
+
+/** The PNG inside each of an .ico's frames. */
+function icoFrames(f) {
+  const b = fs.readFileSync(f), n = b.readUInt16LE(4);
+  return Array.from({ length: n }, (_, i) => { const o = 6 + 16 * i, len = b.readUInt32LE(o + 8), at = b.readUInt32LE(o + 12); return b.subarray(at, at + len); });
+}
+
+/** A browser page that diffs two images (paths or PNG buffers): mean and largest difference, levels in 255, and the share of pixels visibly off. */
+async function differ(b) {
+  const page = await b.newPage();
+  const url = (f) => `data:image/png;base64,${(Buffer.isBuffer(f) ? f : fs.readFileSync(f)).toString("base64")}`;
+  const diff = (a, c) => page.evaluate(async ([da, dc]) => {
+    const load = (s) => new Promise((ok, no) => { const i = new Image(); i.onload = () => ok(i); i.onerror = () => no(new Error("could not decode")); i.src = s; });
+    const [A, C] = await Promise.all([load(da), load(dc)]);
+    if (A.naturalWidth !== C.naturalWidth || A.naturalHeight !== C.naturalHeight) return { size: `${A.naturalWidth} x ${A.naturalHeight} against ${C.naturalWidth} x ${C.naturalHeight}` };
+    const data = (im) => { const cv = document.createElement("canvas"); cv.width = im.naturalWidth; cv.height = im.naturalHeight; const x = cv.getContext("2d"); x.drawImage(im, 0, 0); return x.getImageData(0, 0, cv.width, cv.height).data; };
+    const p = data(A), q = data(C); let sum = 0, max = 0, off = 0;
+    for (let i = 0; i < p.length; i += 4) {
+      let px = 0;
+      for (let c = 0; c < 4; c++) { const d = Math.abs(p[i + c] - q[i + c]); sum += d; if (d > px) px = d; }
+      if (px > max) max = px; if (px > 24) off++;
+    }
+    return { mean: sum / p.length, max, off: (100 * off * 4) / p.length };
+  }, [url(a), url(c)]);
+  return { diff, close: () => page.close() };
+}
+
+/**
+ * Every file present and the one approved (its sha256), then every file the kit can draw drawn again from the
+ * recipes and compared: within its tolerance it is ok; up to 4 levels a warning to look at; past that a failure,
+ * because the kit no longer draws what was approved (a regression, or a design change that needs approving).
+ */
+export async function check({ quiet = false } = {}) {
+  const idx = load(), rows = [];
+  const row = (ok, gate, msg, warn = false) => rows.push({ ok, warn, gate, msg });
+  for (const a of idx.assets) {
+    const bad = a.files.filter((f) => { const p = resolve(f.path); return !fs.existsSync(p) || sha256(p) !== f.sha256; });
+    row(!bad.length, a.id, bad.length ? `not the approved file: ${bad.map((f) => f.path).join(", ")}` : `${a.files.length} file${a.files.length === 1 ? "" : "s"}, as approved`);
+  }
+  // the redraw: one social job per brand that has recipes, into a temp folder, compared file by file
+  const { social } = await import("./social.js");
+  const { browser } = await import("./engine.js");
+  for (const [brand, spec] of Object.entries(idx.recipes || {})) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), `wand-library-${brand}-`));
+    const r = await social({ ...spec, brand, name: `library-${brand}` }, { dir, zip: false, quiet: true });
+    if (!r.ok) { row(false, `redraw ${brand}`, r.rows.filter((x) => !x.ok && !x.warn).map((x) => `${x.gate}: ${x.msg}`).join("; ")); continue; }
+    const out = r.out, byId = Object.fromEntries(r.images.map((i) => [i.id, i]));
+    const d = await differ(await browser());
+    for (const a of idx.assets.filter((x) => x.brand === brand && x.recipe)) {
+      const img = byId[a.recipe];
+      if (!img) { row(false, `redraw ${a.id}`, `no card "${a.recipe}" in the ${brand} recipes`); continue; }
+      const notes = [];
+      let worst = 0, worstOff = 0, failed = false, warned = false;
+      for (const f of a.files.filter((x) => x.from)) {
+        const mine = resolve(f.path);
+        if (f.from === "#tags") { if (fs.readFileSync(mine, "utf8") !== img.tags) { failed = true; notes.push(`${path.basename(f.path)} differs from the tags the kit writes`); } continue; }
+        const theirs = path.join(out, f.from);
+        if (!fs.existsSync(theirs)) { failed = true; notes.push(`the kit drew no ${f.from}`); continue; }
+        // an .ico holds PNGs, whose bytes differ between browser builds even where their pixels do not: compare each frame
+        const pairs = /\.ico$/i.test(f.from) ? icoFrames(mine).map((a, i) => [a, icoFrames(theirs)[i]]) : /\.png$/i.test(f.from) ? [[mine, theirs]] : null;
+        if (!pairs) { if (fs.readFileSync(mine, "utf8") !== fs.readFileSync(theirs, "utf8")) { failed = true; notes.push(`${f.from} differs`); } continue; }
+        if (pairs.some(([, b]) => !b)) { failed = true; notes.push(`${f.from}: not the same frames`); continue; }
+        const each = await Promise.all(pairs.map(([a, b]) => d.diff(a, b)));
+        const r2 = each.find((x) => x.size) || { mean: Math.max(...each.map((x) => x.mean)), off: Math.max(...each.map((x) => x.off)) };
+        if (r2.size) { failed = true; notes.push(`${f.from}: ${r2.size}`); continue; }
+        // a mean alone hides a moved line of type in a large image; the share of pixels visibly off (over 24 levels) does not
+        const tol = { mean: 1, off: 0.25, ...(f.tolerance || {}) }, said = `${f.from}: ${r2.mean.toFixed(2)} levels, ${r2.off.toFixed(2)}% of pixels visibly off`;
+        worst = Math.max(worst, r2.mean); worstOff = Math.max(worstOff, r2.off);
+        if (r2.mean > 4 || r2.off > 2) { failed = true; notes.push(said); }
+        else if (r2.mean > tol.mean || r2.off > tol.off) { warned = true; notes.push(`${said} (allowed ${tol.mean}, ${tol.off}%)`); }
+      }
+      row(!failed && !warned, `redraw ${a.id}`, failed || warned ? `${notes.join("; ")}; the kit's redraw is in ${out}` : `the kit draws it within ${worst.toFixed(2)} levels in 255, ${worstOff.toFixed(2)}% of pixels visibly off`, warned && !failed);
+    }
+    await d.close();
+  }
+  const ok = rows.every((r) => r.ok || r.warn);
+  if (!quiet) {
+    console.log("");
+    for (const r of rows) console.log(`  ${r.ok ? " ok " : r.warn ? " -- " : "FAIL"}  ${r.gate.padEnd(34)} ${r.msg}`);
+    console.log(`\n  ${idx.assets.length} assets, ${idx.assets.reduce((n, a) => n + a.files.length, 0)} files${ok ? "" : "\n\n  FAILED — a file is not the one approved, or the kit no longer draws it"}\n`);
+  }
+  return { ok, rows };
+}

package/lib/pptx.js

@@ -238,7 +238,7 @@ export async function exportPptx({ htmlPath, outPath, brand: brandName, surface,
 
   const msg = `${pages.length} slide${pages.length === 1 ? "" : "s"}, ${lines} text lines${links ? `, ${links} links` : ""}, ${fonts}`;
   if (missing.length) return { ok: false, warn: false, msg: `${missing.length} of ${lines} lines not verbatim in the XML: ${missing.slice(0, 3).join("; ")}` };
-  return { ok: true, warn, msg };
+  return { ok: !warn, warn, msg };
 }
 
 /** A block of several lines (a title, a paragraph) moves as one: a group. */