wand-kit 0.3.2 → 0.5.0

package/lib/audit.js

@@ -0,0 +1,142 @@
+/**
+ * lib/audit.js — how a page's link preview looks today, before anyone redraws it.
+ *
+ * The 2026-10-23 fix (runs/2026-10-23-wand-og-fix) began by reading the live
+ * pages: one image for every page, its words outside the centre square Slack
+ * keeps, small print that vanished in LinkedIn's compact card, an og:title that
+ * repeated the image, an em dash, no twitter tags. This reads the same things
+ * from any page and shows its image the way those feeds do.
+ *
+ *   node wand.js social --audit https://wand.ai/ https://wand.ai/insights/… [--out audit]
+ *   node wand.js social --audit saved-page.html --image its-og-image.png
+ *
+ * A chat with no web access gets a clear row saying so: save the page (and its
+ * image) and pass the files.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { browser } from "./engine.js";
+import { fetchTo, feedRows, wholeWithSquare, previewPage } from "./social.js";
+
+const LIMIT = 300 * 1024;
+const ENT = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">", nbsp: " ", mdash: "—", ndash: "–", rsquo: "’", lsquo: "‘", rdquo: "”", ldquo: "“", hellip: "…" };
+const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => e[0] === "#" ? String.fromCodePoint(e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : +e.slice(1)) : ENT[e.toLowerCase()] ?? m);
+
+/** The page's og: and twitter: tags (the first of each, as Slack reads them), how many twitter:card tags, and its <title>. */
+export function readTags(html) {
+  const tags = {}, count = {};
+  for (const [m] of html.matchAll(/<meta\b[^>]*>/gi)) {
+    const attr = {};
+    for (const [, k, , a, b] of m.matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) attr[k.toLowerCase()] = decode(a ?? b ?? "");
+    const key = (attr.property || attr.name || "").toLowerCase();
+    if (!/^(og|twitter):/.test(key) || attr.content == null) continue;
+    count[key] = (count[key] || 0) + 1;
+    if (!(key in tags)) tags[key] = attr.content;
+  }
+  const title = decode((/<title[^>]*>([\s\S]*?)<\/title>/i.exec(html) || [])[1] || "").trim();
+  return { tags, count, title };
+}
+
+/** Width, height and type from a PNG, JPEG, GIF or WebP's own header. */
+export function imageFacts(file) {
+  const b = fs.readFileSync(file), bytes = b.length;
+  if (b[0] === 0x89 && b.toString("ascii", 1, 4) === "PNG") return { type: "png", w: b.readUInt32BE(16), h: b.readUInt32BE(20), bytes };
+  if (b.toString("ascii", 0, 3) === "GIF") return { type: "gif", w: b.readUInt16LE(6), h: b.readUInt16LE(8), bytes };
+  if (b.toString("ascii", 8, 12) === "WEBP") {
+    const k = b.toString("ascii", 12, 16);
+    if (k === "VP8X") return { type: "webp", w: 1 + b.readUIntLE(24, 3), h: 1 + b.readUIntLE(27, 3), bytes };
+    if (k === "VP8L") { const v = b.readUInt32LE(21); return { type: "webp", w: (v & 0x3fff) + 1, h: ((v >> 14) & 0x3fff) + 1, bytes }; }
+    return { type: "webp", w: b.readUInt16LE(26) & 0x3fff, h: b.readUInt16LE(28) & 0x3fff, bytes };
+  }
+  if (b[0] === 0xff && b[1] === 0xd8) {
+    for (let i = 2; i < b.length - 9;) {
+      if (b[i] !== 0xff) { i++; continue; }
+      const m = b[i + 1], len = b.readUInt16BE(i + 2);
+      if (m >= 0xc0 && m <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(m)) return { type: "jpeg", w: b.readUInt16BE(i + 7), h: b.readUInt16BE(i + 5), bytes };
+      i += 2 + len;
+    }
+    return { type: "jpeg", w: 0, h: 0, bytes };
+  }
+  return { type: "unknown", w: 0, h: 0, bytes };
+}
+
+const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+/** A short name for a page: the last part of its path, or its host for a home page. */
+const slug = (t) => {
+  const u = /^https?:\/\//.test(t) ? new URL(t) : null, last = (u ? u.pathname : t).split("/").filter(Boolean).pop();
+  return norm((last || u?.hostname || "page").replace(/\.[a-z0-9]+$/i, "")).replace(/ /g, "-").slice(0, 40) || "page";
+};
+/** The image's words (its alt, less the brand's name) found again in the og:title: a preview that says them twice. */
+const repeats = (title, alt) => {
+  const words = (s) => norm(s).split(" ").filter((w) => w && !["wand", "ai", "a", "an", "the"].includes(w));
+  const t = new Set(words(title)), a = words(alt);
+  return a.length >= 3 && a.filter((w) => t.has(w)).length / a.length >= 0.8;
+};
+
+export async function audit(targets, { image = null, out = "audit" } = {}) {
+  if (!targets.length) throw new Error("usage: node wand.js social --audit <url | page.html> [more] [--image og-image.png] [--out audit]");
+  out = path.resolve(out); fs.mkdirSync(out, { recursive: true });
+  const rows = [], pages = [];
+  const row = (ok, gate, msg, warn = false) => rows.push({ ok, warn, gate, msg });
+  for (const t of targets) {
+    const id = slug(t), isUrl = /^https?:\/\//.test(t);
+    let html;
+    try {
+      if (isUrl) {
+        const r = await fetch(t, { signal: AbortSignal.timeout(15000), headers: { "user-agent": "Mozilla/5.0 (wand-kit link-preview audit)" } });
+        if (!r.ok) throw new Error(`answered ${r.status}`);
+        html = await r.text();
+      } else html = fs.readFileSync(path.resolve(t), "utf8");
+    } catch (e) {
+      row(false, id, `could not read ${t} from here (${e.cause?.code || e.message}). Save the page (File, Save As) and its og:image, then: --audit page.html --image image.png`);
+      continue;
+    }
+    const { tags, count, title } = readTags(html), p = { id, target: t, tags, title };
+    pages.push(p);
+    const want = ["og:title", "og:description", "og:url", "og:image", "og:image:width", "og:image:height", "og:image:type", "og:image:alt", "twitter:card", "twitter:title", "twitter:image"];
+    const missing = want.filter((k) => !tags[k]);
+    row(!!tags["og:image"] && !missing.length, `${id} tags`, tags["og:image"] ? (missing.length ? `missing ${missing.join(", ")}` : "every og: and twitter: tag a feed reads") : "no og:image: every feed shows a bare link", !!tags["og:image"] && missing.length > 0);
+    if ((count["twitter:card"] || 0) > 1) row(false, `${id} twitter:card`, `${count["twitter:card"]} twitter:card tags; Slack reads the first`, true);
+    const dash = Object.entries(tags).filter(([, v]) => /—/.test(v)).map(([k]) => k);
+    if (dash.length) row(false, `${id} dashes`, `em dash in ${dash.join(", ")}`, true);
+    if (repeats(tags["og:title"], tags["og:image:alt"])) row(false, `${id} title`, "og:title repeats the image's words, so the preview shows them twice", true);
+    // the image itself
+    const src = image && targets.length === 1 ? image : tags["og:image"] ? new URL(tags["og:image"], isUrl ? t : "https://example.com/").href : null;
+    if (tags["og:image"] && !/^https:\/\//.test(tags["og:image"])) row(false, `${id} image url`, `og:image is not an absolute https URL (${tags["og:image"]}); some feeds drop it`, true);
+    if (src) {
+      try {
+        p.png = await fetchTo(src, path.join(out, `live-${id}`), process.cwd());
+        const f = imageFacts(p.png); p.facts = f;
+        const ratio = f.h ? f.w / f.h : 0, notes = [];
+        if (f.bytes > LIMIT) notes.push("over 300 KB: WhatsApp shows no preview");
+        if (ratio && Math.abs(ratio / 1.905 - 1) > 0.05) notes.push(`${ratio.toFixed(2)}:1, not 1.91:1: feeds crop it`);
+        if (f.w && f.w < 1200) notes.push("under 1200 wide: soft on large cards");
+        row(!notes.length, `${id} image`, `${f.w} x ${f.h}, ${Math.round(f.bytes / 1024)} KB, ${f.type}${notes.length ? "; " + notes.join("; ") : ""}`, notes.length > 0);
+      } catch (e) { row(false, `${id} image`, `${e.message}`); }
+    }
+  }
+  // one picture for every page: nothing in it says what the link is
+  const imgs = pages.map((p) => p.tags["og:image"]).filter(Boolean);
+  if (pages.length > 1 && new Set(imgs).size < imgs.length) row(false, "pages", `${imgs.length - new Set(imgs).size + 1} pages share one og:image: each needs its own (an article its headline)`, true);
+
+  const shot = pages.filter((p) => p.png);
+  if (shot.length) {
+    const u = (f) => pathToFileURL(f).href;
+    const body = shot.map((p) => `<h2>${p.target}</h2>${feedRows(u(p.png), { title: p.tags["og:title"] || p.title, url: p.tags["og:url"] || p.target, description: p.tags["og:description"] })}${p.facts?.w ? wholeWithSquare(u(p.png), p.facts.w, p.facts.h) : ""}`).join("\n");
+    const pg = previewPage(body), htmlPath = path.join(out, "audit.html"), png = path.join(out, "audit.png");
+    fs.writeFileSync(htmlPath, pg.html);
+    const b = await browser(), v = await b.newPage({ viewport: { width: pg.w, height: 400 } });
+    await v.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+    await v.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
+    await v.screenshot({ path: png, fullPage: true });
+    await v.close();
+    row(true, "preview", path.relative(process.cwd(), png));
+  }
+  const ok = rows.every((r) => r.ok || r.warn);
+  console.log("");
+  for (const r of rows) console.log(`  ${r.ok ? " ok " : r.warn ? " -- " : "FAIL"}  ${r.gate.padEnd(34)} ${r.msg}`);
+  if (shot.length) console.log(`\n  review  ${path.relative(process.cwd(), path.join(out, "audit.png"))}, as the people scrolling past will see it:\n          does the dashed centre square (Slack's and WhatsApp's cut) hold the whole wordmark and the words?\n          in LinkedIn's compact card (128pt), can you read the line? is there small print that vanishes?\n          is the type the brand's, and does the image say what this page is?`);
+  console.log("");
+  return { ok, rows, pages };
+}

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

@@ -18,9 +18,10 @@
  * 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 fs from "node:fs";
 import path from "node:path";
 import { esc } from "./content.js";
-import { url } from "./brand.js";
+import { url, brandDir, BRANDS } 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>`;
 
@@ -50,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>`;
   };
 
@@ -130,13 +134,29 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
   /** 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>`;
 
+  /**
+   * A photograph, filling its box and given the brand's one grade: blacks lift toward the dark ground,
+   * highlights settle toward the light one, so photographs from different shoots read as one set.
+   * `src` is a photograph of the brands' set by name ("walk", "corridor"; `brand-next/assets/photos`, which
+   * the current brand shares, graded on its own grounds) or a path.
+   */
+  const photo = (src, { cls: k = "", alt = "", pos = "" } = {}) => {
+    let href = /^(file|https?|data):/.test(src) ? src : url(src);
+    if (!/[\/.]/.test(src)) {
+      const dirs = [brand.assets, ...BRANDS.filter((b) => b !== brand.name).map((b) => { try { return path.join(brandDir(b), "assets"); } catch { return null; } }).filter(Boolean)];
+      const hit = dirs.map((d) => path.join(d, "photos", `${src}.jpg`)).find((f) => fs.existsSync(f));
+      if (!hit) throw new Error(`photo("${src}"): no photograph of that name in ${dirs.map((d) => path.join(d, "photos")).join(" or ")}`);
+      href = url(hit);
+    }
+    return `<figure class="photo${cls(k)}"><img src="${href}" alt="${esc(alt)}"${pos ? ` style="object-position:${esc(pos)}"` : ""}><span class="grade"></span></figure>`;
+  };
   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>`;
 
   /* ---------------------------------------------------------- motion */
 
-  /** An entrance, as attributes for raw markup: `<div${c.enter("pop", 2)}>`. Kinds: rise (default), fade, pop, grow (bars, up), widen (bars, across), draw (an SVG path with pathLength="1"), count. */
+  /** An entrance, as attributes for raw markup: `<div${c.enter("pop", 2)}>`. Kinds: rise (default), fade, pop, grow (bars, up), widen (bars, across), draw (an SVG path with pathLength="1"), count, words (a title rising word by word), lit (a statement lighting word by word), window (a photograph opening). */
   const enter = (kind = "", i = null) => ` data-a="${esc(kind)}"${i != null ? ` style="--i:${+i}"` : ""}`;
   /** Held back until the presenter moves on; steps of one number come in together. */
   const step = (nth, html, { a = "", tag: t = "div", cls: k = "" } = {}) => `<${t} data-step="${+nth}"${a ? ` data-a="${esc(a)}"` : ""}${k ? ` class="${k}"` : ""}>${html}</${t}>`;
@@ -235,7 +255,7 @@ ${DIR.some(([k]) => s[k]) ? `<dl class="direction">${DIR.filter(([k]) => s[k]).m
     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,
+    cover, closing, chapter, img, photo, icon, tile, mark, wordmark,
     asset: brand.assetUrl, art: brand.artUrl,
     enter, step, countup, video, demo, sketch, storyboard,
     brand: brand.name, surface: surface.name, count: () => n,
@@ -249,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)}
@@ -265,7 +285,13 @@ 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)}
+/* 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. 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)}
@@ -382,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}
@@ -401,6 +427,12 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .has-chapter .left{width:62%;display:flex;flex-direction:column;gap:var(--m-gap)}
 /* images, icons */
 .img{display:block;max-width:100%}
+.photo{position:relative;margin:0;overflow:hidden;border-radius:calc(var(--m-radius) * var(--radius-k));background:var(--grade-high)}
+.photo>img{display:block;width:100%;height:100%;object-fit:cover}
+.photo>.grade{position:absolute;inset:0;pointer-events:none}
+.photo>.grade::before,.photo>.grade::after{content:"";position:absolute;inset:0}
+.photo>.grade::before{background:var(--grade-low);mix-blend-mode:lighten;opacity:.42}
+.photo>.grade::after{background:var(--grade-high);mix-blend-mode:darken;opacity:.55}
 .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}

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,15 +123,32 @@ 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(".") : ""); };
+  res.sig = pages.map((pg) => {
+    const c = pg.querySelector(".content");
+    if (!c || pg.matches(".cover, .back, .shot, .run")) return null;
+    return [...c.children].filter((k) => !k.classList.contains("deco")).map((k) => kindOf(k) + (/\b(cols|strip|stats|steps|grid)\b/.test(k.className) ? `[${k.children.length}]` : "")).join(" ");
+  });
   pages.forEach((pg, pi) => {
     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("*")) {
@@ -135,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;
@@ -163,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);
@@ -178,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);
@@ -187,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 };
@@ -238,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;
@@ -263,9 +307,26 @@ 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);
-  row(!g.broken.length, "images", g.broken.length ? `${g.broken.length} did not load: ${g.broken.slice(0, 3).join(", ")}` : "every image loaded");
+  // the same composition page after page is what makes a set of pages read as a template
+  const runs = [], composed = !job.__board && surface.kind !== "card";
+  if (composed) for (let i = 1, start = 0; i <= g.sig.length; i++) {
+    if (i < g.sig.length && g.sig[i] && g.sig[i] === g.sig[i - 1]) continue;
+    if (i - start >= 3 && g.sig[start]) runs.push([start + 1, i]);
+    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);
+  // 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)`);
@@ -320,6 +381,8 @@ export function printReport(r) {
   if (r.outputs.pdf) console.log(`\n  ${path.relative(process.cwd(), r.outputs.pdf)}  (${(fs.statSync(r.outputs.pdf).size / 1e6).toFixed(1)} MB, ${r.pages} page${r.pages === 1 ? "" : "s"}, ${r.brand} brand, ${r.surface}, ${(r.ms / 1000).toFixed(1)}s)`);
   if (r.outputs.pptx) console.log(`  ${path.relative(process.cwd(), r.outputs.pptx)}  (${(fs.statSync(r.outputs.pptx).size / 1e6).toFixed(1)} MB)`);
   if (r.outputs.single) console.log(`  ${path.relative(process.cwd(), r.outputs.single)}  (${(fs.statSync(r.outputs.single).size / 1e6).toFixed(1)} MB, one file, opens offline)`);
+  // what no gate sees: read the sheet the way a creative director would, before anyone else does
+  if (r.outputs.sheet) console.log(`\n  review  ${path.relative(process.cwd(), r.outputs.sheet)}, as a creative director:\n          does every page carry its one claim? is one page memorable, and which?\n          is the accent rare (cover, statement, close, figures)? photographs large or absent?\n          hairlines and type doing the separating, not boxes?`);
   console.log(r.ok ? "" : "\n  FAILED — fix the rows marked FAIL\n");
 }