wand-kit 0.0.0-stage → 0.2.0

package/lib/pptx.js

@@ -0,0 +1,446 @@
+/**
+ * lib/pptx.js: the rendered pages as a .pptx, one slide per page.
+ *
+ * Reads Chromium's own rendering of the engine's HTML, the render the PDF
+ * came from, and writes each page as two layers:
+ *   - the plate: everything that is not text (ground, art, cards, rules,
+ *     glyphs, the mark) as the slide background, shot at 2x with the text
+ *     made transparent so the layout is untouched;
+ *   - the text: every line as a live text box in the brand's face, at the
+ *     size, weight, colour, tracking and position Chrome set it, read
+ *     character by character; the lines of one block grouped, so a title or
+ *     a paragraph moves as one.
+ * Links to http(s) addresses carry over, a page's `notes` become speaker
+ * notes, and the faces used are embedded, one clean family per face, by
+ * tools/embed_fonts.py when a python is on PATH (without one the .pptx still
+ * ships, with a warning).
+ *
+ * Ported from runs/2026-10-07-bofa-agentic-age-html/pptx (capture.mjs,
+ * build.mjs, fonts.py), generalised over brands and surfaces. A run's CSS
+ * (family, weight, italic) resolves to the nearest file in the brand's
+ * `faces.files` the way Chrome resolves it; that file's `pptx` name carries
+ * the weight, so every run is written b="0", and its own OS/2 usWin metrics
+ * give the line box, so no face is measured with another's numbers.
+ *
+ * Vertical placement: each line is a single-spaced text box centred on
+ * Chrome's baseline. A renderer centres a single line by its own metrics,
+ * which puts the baseline (ascent minus descent) / 2 below the box's middle
+ * with Office's usWin values, and 0.40 em below it with LibreOffice's
+ * font-independent 1.2-em lines. The box is centred on the baseline less the
+ * mean of the two, so either lands within a hundredth of an em.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { loadBrand } from "./brand.js";
+
+const require = createRequire(import.meta.url);
+const KIT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// the pages with their text made transparent, layout intact: the plate
+const PLATE_CSS = `
+  .page, .page * { -webkit-text-fill-color: transparent !important; text-shadow: none !important; }
+  .page *::before, .page *::after { -webkit-text-fill-color: currentColor !important; }
+  .page svg text, .page svg tspan { fill: transparent !important; stroke: none !important; }
+`;
+
+const xml = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const unxml = (s) => s.replace(/&quot;/g, '"').replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
+const label = (line) => line.runs.map((r) => r.text).join("");
+const short = (t, n = 48) => (t.length > n ? t.slice(0, n - 1) + "…" : t);
+const nn = (n) => String(n).padStart(2, "0");
+
+/**
+ * Write `outPath` from the engine's HTML at `htmlPath`. Returns { ok, msg,
+ * warn }: one line for the gate table, and warn when the file shipped
+ * without embedded fonts or with a face the brand does not carry.
+ */
+export async function exportPptx({ htmlPath, outPath, brand: brandName, surface, notes = [], name = "Wand" }) {
+  const PptxGenJS = require("pptxgenjs");
+  const JSZip = require("jszip");
+  const fontkit = require("fontkit");
+  const brand = loadBrand(brandName);
+  const work = path.join(path.dirname(outPath), "work", "pptx");
+  fs.rmSync(work, { recursive: true, force: true });
+  fs.mkdirSync(work, { recursive: true });
+
+  /* ------------------------------------------------------------- units */
+  // a page keeps its paper size; a slide or a card is 10 in wide
+  const W = surface.kind === "page" ? surface.w / 96 : 10;
+  const H = surface.kind === "page" ? surface.h / 96 : (10 * surface.h) / surface.w;
+  const PPI = surface.w / W;                              // canvas px per inch
+  const IN = (px) => px / PPI;                            // pptxgenjs takes inches
+  const PT100 = (px) => Math.round((px * 7200) / PPI);   // hundredths of a point
+
+  /* ------------------------------------------------------------- faces */
+  // the brand's files with what the capture and the boxes need from each:
+  // hhea ascender (Chrome's glyph box top is the baseline less round(asc * size)),
+  // and the usWin line box Office centres by
+  const faces = brand.faceFiles.map((f, i) => {
+    const font = fontkit.openSync(f.path);
+    const upm = font.unitsPerEm, os2 = font["OS/2"];
+    const wa = os2.winAscent, wd = os2.winDescent;
+    return { i, family: f.family, weight: f.weight, italic: !!f.italic, file: f.file, pptx: f.pptx,
+      asc: font.ascent / upm, mid: ((wa - wd) / upm + 0.8) / 4, line: (wa + wd) / upm };
+  });
+  const fallback = brand.tokens.faces.body.family;
+
+  /* ----------------------------------------------------------- capture */
+  const { browser } = await import("./engine.js");
+  const b = await browser();
+  const page = await b.newPage({ viewport: { width: surface.w, height: surface.h }, deviceScaleFactor: 2 });
+  await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+  await page.evaluate(() => document.fonts.ready);
+  await page.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
+  const count = await page.evaluate(() => document.querySelectorAll(".page").length);
+  const pages = [];
+  const subs = new Set();
+  for (let i = 0; i < count; i++) {
+    const d = await page.evaluate(extract, { index: i, faces: faces.map(({ i, family, weight, italic, asc }) => ({ i, family, weight, italic, asc })), fallback });
+    d.subs.forEach((s) => subs.add(s));
+    pages.push(d);
+  }
+  await page.addStyleTag({ content: PLATE_CSS });
+  await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+  const els = await page.$$(".page");
+  for (const pg of pages) {
+    pg.plate = path.join(work, `plate-${nn(pg.n)}.jpg`);
+    await els[pg.n - 1].screenshot({ path: pg.plate, type: "jpeg", quality: 92 });
+  }
+  await page.close();
+  fs.writeFileSync(path.join(work, "capture.json"), JSON.stringify({ name, surface: surface.name, brand: brand.name, pages }, null, 1));
+
+  /* ---------------------------------------------------------- text XML */
+  const used = new Map(); // typeface -> { regular, italic } files
+  const face = (run) => {
+    const f = faces[run.face];
+    if (!used.has(f.pptx)) used.set(f.pptx, {});
+    used.get(f.pptx)[f.italic ? "italic" : "regular"] = f.file;
+    return f;
+  };
+  // weight rides on the typeface name, so b is never set; i picks the italic slot
+  const rPr = (run, tag = "a:rPr") => {
+    const f = face(run);
+    const fill = `<a:solidFill><a:srgbClr val="${run.color}">${run.alpha < 0.999 ? `<a:alpha val="${Math.round(run.alpha * 100000)}"/>` : ""}</a:srgbClr></a:solidFill>`;
+    const spc = PT100(run.ls);
+    return `<${tag} lang="en-US" sz="${PT100(run.size)}" b="0" i="${run.italic ? 1 : 0}"${spc ? ` spc="${spc}"` : ""} kern="100" dirty="0">` +
+      `${fill}<a:latin typeface="${xml(f.pptx)}"/><a:ea typeface="${xml(f.pptx)}"/><a:cs typeface="${xml(f.pptx)}"/></${tag}>`;
+  };
+  const txBody = (line) => {
+    const runs = line.runs.map((r) => `<a:r>${rPr(r)}<a:t>${xml(r.text)}</a:t></a:r>`).join("");
+    return `<p:txBody><a:bodyPr wrap="none" lIns="0" tIns="0" rIns="0" bIns="0" rtlCol="0" anchor="ctr" anchorCtr="0"><a:noAutofit/></a:bodyPr><a:lstStyle/>` +
+      `<a:p><a:pPr marL="0" indent="0" algn="${line.align}"><a:lnSpc><a:spcPct val="100000"/></a:lnSpc><a:spcBef><a:spcPts val="0"/></a:spcBef><a:spcAft><a:spcPts val="0"/></a:spcAft><a:buNone/></a:pPr>` +
+      `${runs}${rPr(line.runs[line.runs.length - 1], "a:endParaRPr")}</a:p></p:txBody>`;
+  };
+  /** A line's box in canvas px: anchored the way the HTML aligns it, with room to spare, sized by its largest run's face. */
+  const boxOf = (line) => {
+    const big = line.runs.reduce((a, r) => (r.size > a.size ? r : a));
+    const { mid, line: lh } = faces[big.face];
+    // Chrome counts the last character's tracking into the line; a slide
+    // renderer aligns the glyphs, so a centred or right-set line loses it
+    const x1 = line.align === "l" ? line.x1 : line.x1 - (line.runs[line.runs.length - 1].ls || 0);
+    const w = x1 - line.x0, slack = Math.max(0.3 * line.size, 0.04 * w);
+    const L = lh * line.size, top = line.base - mid * line.size - L / 2;
+    if (line.align === "ctr") return { x: line.x0 - slack, y: top, w: w + 2 * slack, h: L };
+    if (line.align === "r") return { x: x1 - w - slack, y: top, w: w + slack, h: L };
+    return { x: line.x0, y: top, w: w + slack, h: L };
+  };
+
+  /* ------------------------------------------------------------ slides */
+  const pptx = new PptxGenJS();
+  pptx.defineLayout({ name: "WAND", width: W, height: H });
+  pptx.layout = "WAND";
+  pptx.title = name;
+  pptx.author = "Wand";
+  pptx.company = "Wand";
+  const texts = new Map(); // "page|name" -> line
+  for (const pg of pages) {
+    const sl = pptx.addSlide();
+    sl.background = { path: pg.plate };
+    // links first, so the text sits over them; the text boxes inside carry the same link
+    pg.links.forEach((l, k) => {
+      const color = pg.lines.find((ln) => ln.link)?.runs[0].color || "FFFFFF";
+      sl.addShape(pptx.ShapeType.rect, { x: IN(l.x), y: IN(l.y), w: IN(l.w), h: IN(l.h), objectName: `pp-link-${k}`,
+        fill: { color, transparency: 100 }, line: { type: "none" }, hyperlink: { url: l.url, tooltip: l.text } });
+    });
+    pg.lines.forEach((line, k) => {
+      const bx = boxOf(line), id = `pp-t-${k}`;
+      sl.addText("x", { x: IN(bx.x), y: IN(bx.y), w: IN(bx.w), h: IN(bx.h), margin: 0, isTextBox: true, objectName: id });
+      texts.set(`${pg.n}|${id}`, line);
+    });
+    const nt = String(notes[pg.n - 1] || "").trim();
+    if (nt) sl.addNotes(nt);
+  }
+
+  /* ------------------------------------------------- write, then finish */
+  const zip = await JSZip.loadAsync(await pptx.write({ outputType: "nodebuffer" }));
+  for (const f of Object.keys(zip.files).filter((f) => /^ppt\/slides\/slide\d+\.xml$/.test(f))) {
+    const n = +f.match(/slide(\d+)\.xml/)[1];
+    const pg = pages[n - 1];
+    let x = await zip.file(f).async("string");
+    // the rIds the link shapes were given, by address
+    const linkRid = new Map();
+    for (const m of x.matchAll(/<p:cNvPr id="\d+" name="pp-link-(\d+)"><a:hlinkClick r:id="(rId\d+)"/g)) linkRid.set(pg.links[+m[1]].url, m[2]);
+    // text: the measured body in place of the placeholder; the link, if any; a readable name
+    x = x.replace(/<p:sp>(?:(?!<\/p:sp>)[\s\S])*?name="(pp-t-\d+)"[\s\S]*?<\/p:sp>/g, (sp, id) => {
+      const line = texts.get(`${n}|${id}`);
+      const rid = line.link && linkRid.get(line.link.url);
+      return sp
+        .replace(/name="pp-t-\d+">/, () => `name="${xml(`Text: ${short(label(line).trim())}`)}">${rid ? `<a:hlinkClick r:id="${rid}"/>` : ""}`)
+        .replace(/<p:txBody>[\s\S]*<\/p:txBody>/, () => txBody(line))
+        .replace(/<p:sp>/, () => `<p:sp><!--block:${line.block}-->`);
+    });
+    x = x.replace(/name="pp-link-(\d+)"/g, (_, k) => `name="${xml(`Link: ${short(pg.links[+k].text)}`)}"`);
+    x = groupBlocks(x).replace(/<!--block:\d+-->/g, "");
+    x = x.replace(/<a:ln><\/a:ln>/g, "<a:ln><a:noFill/></a:ln>");
+    zip.file(f, x);
+  }
+  // speaker notes: one paragraph per line of the page's notes
+  for (const f of Object.keys(zip.files).filter((f) => /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(f))) {
+    const x = await zip.file(f).async("string");
+    zip.file(f, x.replace(/<a:p><a:r><a:rPr lang="en-US" dirty="0"\/><a:t>([\s\S]*?)<\/a:t><\/a:r>(?:<a:endParaRPr[^>]*\/>)?<\/a:p>/, (_, t) =>
+      t.split(/\r?\n/).map((p) => `<a:p><a:r><a:rPr lang="en-US" dirty="0"/><a:t>${p}</a:t></a:r></a:p>`).join("")));
+  }
+  const raw = path.join(work, "raw.pptx");
+  fs.writeFileSync(raw, await zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE", compressionOptions: { level: 6 } }));
+
+  // every line read back from the XML, verbatim
+  const paras = new Set();
+  for (const f of Object.keys(zip.files).filter((f) => /^ppt\/slides\/slide\d+\.xml$/.test(f))) {
+    const x = await zip.file(f).async("string");
+    for (const m of x.matchAll(/<a:p>([\s\S]*?)<\/a:p>/g)) paras.add(unxml([...m[1].matchAll(/<a:t>([\s\S]*?)<\/a:t>/g)].map((t) => t[1]).join("")));
+  }
+  const lines = pages.reduce((a, p) => a + p.lines.length, 0);
+  const links = pages.reduce((a, p) => a + p.links.length, 0);
+  const missing = pages.flatMap((p) => p.lines.filter((ln) => !paras.has(label(ln))).map((ln) => `p${p.n} "${short(label(ln), 32)}"`));
+
+  /* ------------------------------------------------------------- fonts */
+  // one family per typeface: its regular file, and the italic file when one was used
+  const table = {};
+  for (const [tf, slots] of used) {
+    table[tf] = { regular: slots.regular || faces.find((f) => f.pptx === tf && !f.italic)?.file || slots.italic };
+    if (slots.italic) table[tf].italic = slots.italic;
+  }
+  const facesPath = path.join(work, "faces.json");
+  fs.writeFileSync(facesPath, JSON.stringify(table, null, 1));
+  const py = ["python3", "python"].find((c) => spawnSync(c, ["-c", "import sys;print(sys.version_info[0])"], { encoding: "utf8" }).stdout?.trim() === "3");
+  let fonts, warn = false;
+  if (!py) { fonts = "fonts not embedded (no python3 on PATH)"; warn = true; }
+  else {
+    const r = spawnSync(py, [path.join(KIT, "tools", "embed_fonts.py"), "--faces", facesPath, "--fonts", brand.fonts, "--lib", brand.lib, raw, outPath], { encoding: "utf8" });
+    if (r.status === 0 && fs.existsSync(outPath)) fonts = `fonts embedded (${Object.keys(table).length} faces: ${Object.keys(table).join(", ")})`;
+    else { fonts = `fonts not embedded (${(r.stderr || r.stdout || String(r.error || "embed_fonts.py failed")).trim().split("\n").pop()})`; warn = true; }
+  }
+  if (warn) fs.copyFileSync(raw, outPath);
+  if (subs.size) { warn = true; fonts += `; not a brand face, set in ${fallback}: ${[...subs].join(", ")}`; }
+
+  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 };
+}
+
+/** A block of several lines (a title, a paragraph) moves as one: a group. */
+function groupBlocks(x) {
+  let id = Math.max(...[...x.matchAll(/<p:cNvPr id="(\d+)"/g)].map((m) => +m[1])) + 1;
+  const sps = [...x.matchAll(/<p:sp><!--block:(\d+)-->[\s\S]*?<\/p:sp>/g)];
+  const runs = [];
+  for (const m of sps) {
+    const last = runs[runs.length - 1];
+    if (last && last.block === m[1] && last.end === m.index) { last.items.push(m); last.end = m.index + m[0].length; }
+    else runs.push({ block: m[1], items: [m], start: m.index, end: m.index + m[0].length });
+  }
+  let out = "", at = 0;
+  for (const r of runs) {
+    if (r.items.length < 2) continue;
+    const xs = r.items.map((m) => {
+      const o = m[0].match(/<a:off x="(-?\d+)" y="(-?\d+)"\/><a:ext cx="(\d+)" cy="(\d+)"\/>/);
+      return { x: +o[1], y: +o[2], w: +o[3], h: +o[4] };
+    });
+    const gx = Math.min(...xs.map((b) => b.x)), gy = Math.min(...xs.map((b) => b.y));
+    const gw = Math.max(...xs.map((b) => b.x + b.w)) - gx, gh = Math.max(...xs.map((b) => b.y + b.h)) - gy;
+    const name = xml(`Group: ${short(r.items.map((m) => (m[0].match(/name="Text: ([^"]*)"/) || [])[1] || "").join(" "))}`);
+    out += x.slice(at, r.start) +
+      `<p:grpSp><p:nvGrpSpPr><p:cNvPr id="${id++}" name="${name}"/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>` +
+      `<p:grpSpPr><a:xfrm><a:off x="${gx}" y="${gy}"/><a:ext cx="${gw}" cy="${gh}"/><a:chOff x="${gx}" y="${gy}"/><a:chExt cx="${gw}" cy="${gh}"/></a:xfrm></p:grpSpPr>` +
+      x.slice(r.start, r.end) + "</p:grpSp>";
+    at = r.end;
+  }
+  return out + x.slice(at);
+}
+
+/* ------------------------------------------------------------------ in page */
+/**
+ * Runs inside the page: one section's text, character by character, so each
+ * line is exactly where Chrome set it, hand breaks and soft wraps alike;
+ * SVG text; the links. Coordinates are canvas px relative to the section.
+ */
+function extract({ index, faces, fallback }) {
+  const pg = document.querySelectorAll(".page")[index];
+  const sr = pg.getBoundingClientRect();
+  const X = (x) => x - sr.left, Y = (y) => y - sr.top;
+  const subs = new Set();
+
+  // CSS font matching over the brand's files: the family, its style, then the
+  // nearest weight the way Chrome picks it; a family the brand lacks is set
+  // in the body face and reported
+  const picked = new Map();
+  const pick = (family, weight, italic) => {
+    const k = `${family}|${weight}|${italic}`;
+    if (picked.has(k)) return picked.get(k);
+    let pool = faces.filter((f) => f.family === family);
+    if (!pool.length) { subs.add(family); pool = faces.filter((f) => f.family === fallback); }
+    const styled = pool.filter((f) => f.italic === italic);
+    if (styled.length) pool = styled;
+    const ws = [...new Set(pool.map((f) => f.weight))].sort((a, b) => a - b);
+    let w = weight;
+    if (!ws.includes(w)) {
+      const up = ws.filter((v) => v > w), down = ws.filter((v) => v < w).reverse();
+      if (w >= 400 && w <= 500) { const mid = up.filter((v) => v <= 500); w = mid[0] ?? down[0] ?? up[0]; }
+      else w = w < 400 ? (down[0] ?? up[0]) : (up[0] ?? down[0]);
+    }
+    const i = pool.find((f) => f.weight === w).i;
+    picked.set(k, i);
+    return i;
+  };
+  const familyOf = (s) => s.split(",")[0].replace(/["']/g, "").trim();
+
+  const rgba = (c) => {
+    const m = String(c).match(/rgba?\(([^)]+)\)/);
+    if (!m) return null;
+    const p = m[1].split(/[ ,/]+/).filter(Boolean).map(Number);
+    return { r: p[0], g: p[1], b: p[2], a: p.length > 3 ? p[3] : 1 };
+  };
+  const hex = (c) => [c.r, c.g, c.b].map((v) => Math.round(v).toString(16).padStart(2, "0")).join("").toUpperCase();
+  const opacityOf = (el) => { let o = 1; for (let e = el; e && e !== pg.parentElement; e = e.parentElement) o *= +getComputedStyle(e).opacity; return o; };
+  const blockOf = (el) => { for (let e = el; e; e = e.parentElement) { const d = getComputedStyle(e).display; if (d !== "inline" && d !== "contents") return e; } return pg; };
+  // ancestors that clip, the page itself included: a box outside them is not on the page
+  const clipped = (el, r) => {
+    for (let e = el; e && e !== pg.parentElement; e = e.parentElement) {
+      const cs = getComputedStyle(e);
+      if (cs.overflow !== "visible" || cs.clip !== "auto") {
+        const b = e.getBoundingClientRect();
+        if (r.right <= b.left + 0.5 || r.left >= b.right - 0.5 || r.bottom <= b.top + 0.5 || r.top >= b.bottom - 0.5) return true;
+        if (b.width <= 1 || b.height <= 1) return true;
+      }
+    }
+    return false;
+  };
+  const linkOf = (el) => {
+    const a = el.closest("a[href]");
+    if (!a || !pg.contains(a)) return null;
+    const h = a.getAttribute("href") || "";
+    return /^https?:/.test(h) ? { url: h } : null;
+  };
+  const alignOf = (cs) => ({ center: "ctr", right: "r", end: "r" })[cs.textAlign] || "l";
+
+  /* HTML text, character by character */
+  const chars = [];
+  const rg = document.createRange();
+  const tw = document.createTreeWalker(pg, NodeFilter.SHOW_TEXT);
+  let order = 0;
+  for (let n; (n = tw.nextNode());) {
+    const el = n.parentElement;
+    if (!el || el.closest("svg, script, style, template, .deco")) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility !== "visible") continue;
+    const col = rgba(cs.color);
+    const alpha = opacityOf(el) * (col ? col.a : 1);
+    if (alpha < 0.02) continue;
+    const block = blockOf(el);
+    const bcs = getComputedStyle(block);
+    const size = parseFloat(cs.fontSize);
+    const italic = cs.fontStyle !== "normal";
+    const face = pick(familyOf(cs.fontFamily), +cs.fontWeight || 400, italic);
+    const style = { face, italic, color: col ? hex(col) : "000000", alpha: +alpha.toFixed(3), ls: cs.letterSpacing === "normal" ? 0 : parseFloat(cs.letterSpacing) };
+    const upper = cs.textTransform === "uppercase";
+    const asc = faces[face].asc;
+    const t = n.data;
+    for (let i = 0; i < t.length; i++) {
+      rg.setStart(n, i); rg.setEnd(n, i + 1);
+      const rs = [...rg.getClientRects()].filter((r) => r.width > 0 || r.height > 0);
+      if (!rs.length) continue;
+      const r = rs[0];
+      let ch = t[i];
+      if (/\s/.test(ch)) { if (r.width < 0.01) continue; ch = " "; }
+      if (clipped(el, r)) continue;
+      chars.push({ ch: upper ? ch.toUpperCase() : ch, block, order: order++,
+        x0: X(r.left), x1: X(r.right), base: Y(r.top + Math.round(asc * size)), size, style, align: alignOf(bcs), link: linkOf(el) });
+    }
+  }
+
+  /* lines: consecutive characters of one block on one baseline, moving forward */
+  const lines = [];
+  let cur = null;
+  const flush = () => {
+    if (!cur) return;
+    while (cur.chars.length && cur.chars[0].ch === " ") cur.chars.shift();
+    while (cur.chars.length && cur.chars[cur.chars.length - 1].ch === " ") cur.chars.pop();
+    if (cur.chars.length) lines.push(cur);
+    cur = null;
+  };
+  for (const c of chars) {
+    const p = cur && cur.chars[cur.chars.length - 1];
+    const same = cur && c.block === cur.block &&
+      Math.abs(c.base - cur.base) < 0.35 * Math.min(c.size, cur.size) && c.x0 > p.x1 - Math.max(2, 0.3 * c.size);
+    if (!same) { flush(); cur = { block: c.block, base: c.base, chars: [] }; }
+    cur.chars.push(c);
+    if (c.size > (cur.size || 0)) { cur.size = c.size; cur.base = c.base; }
+  }
+  flush();
+
+  const blocks = new Map();
+  const out = lines.map((ln) => {
+    if (!blocks.has(ln.block)) blocks.set(ln.block, blocks.size);
+    // runs of one style; a character followed by space the text itself does
+    // not account for (an inline element's padding or margin) is a run of its
+    // own, its tracking widened by that gap
+    const runs = [];
+    ln.chars.forEach((c, i) => {
+      const nx = ln.chars[i + 1];
+      const gap = nx ? nx.x0 - c.x1 : 0;
+      const extra = gap > 0.5 ? gap : 0;
+      const k = JSON.stringify(c.style) + c.size;
+      const last = runs[runs.length - 1];
+      if (last && last.k === k && !last.extra && !extra) last.text += c.ch;
+      else runs.push({ k, text: c.ch, ...c.style, size: c.size, ls: c.style.ls + extra, extra });
+    });
+    runs.forEach((r) => { delete r.k; if (!r.extra) delete r.extra; });
+    const first = ln.chars[0], last = ln.chars[ln.chars.length - 1];
+    return { block: blocks.get(ln.block), kind: "html", x0: +first.x0.toFixed(2), x1: +last.x1.toFixed(2), base: +ln.base.toFixed(2), size: +ln.size.toFixed(3),
+      align: first.align, link: first.link, runs };
+  });
+
+  /* SVG text */
+  for (const t of pg.querySelectorAll("svg text")) {
+    if (t.closest(".deco")) continue;
+    const cs = getComputedStyle(t);
+    if (cs.visibility !== "visible" || cs.display === "none") continue;
+    const ctm = t.getScreenCTM();
+    if (!ctm) continue;
+    const k = Math.hypot(ctm.a, ctm.b);
+    const fill = rgba(cs.fill);
+    const alpha = opacityOf(t) * (fill ? fill.a : 1) * +cs.fillOpacity;
+    if (alpha < 0.02 || !t.textContent.trim()) continue;
+    const bb = t.getBoundingClientRect();
+    const base = new DOMPoint(t.x.baseVal[0]?.value || 0, t.y.baseVal[0]?.value || 0).matrixTransform(ctm);
+    const size = parseFloat(cs.fontSize) * k;
+    const anchor = cs.textAnchor;
+    const italic = cs.fontStyle !== "normal";
+    out.push({ block: blocks.size + out.length, kind: "svg", x0: +X(bb.left).toFixed(2), x1: +X(bb.right).toFixed(2), base: +Y(base.y).toFixed(2), size: +size.toFixed(3),
+      align: anchor === "middle" ? "ctr" : anchor === "end" ? "r" : "l", link: null,
+      runs: [{ text: t.textContent, size, face: pick(familyOf(cs.fontFamily), +cs.fontWeight || 400, italic), italic, color: fill ? hex(fill) : "000000", alpha: +alpha.toFixed(3), ls: 0 }] });
+  }
+
+  /* links */
+  const links = [];
+  for (const a of pg.querySelectorAll("a[href]")) {
+    const to = linkOf(a);
+    const r = a.getBoundingClientRect();
+    if (!to || !r.width || getComputedStyle(a).visibility !== "visible") continue;
+    links.push({ ...to, x: X(r.left), y: Y(r.top), w: r.width, h: r.height, text: a.textContent.trim().replace(/\s+/g, " ") });
+  }
+
+  return { n: index + 1, lines: out, links, subs: [...subs] };
+}

package/lib/surfaces.js

@@ -0,0 +1,62 @@
+/**
+ * lib/surfaces.js — the canvases: a slide, a printed page, a social card.
+ *
+ * A surface fixes what must not drift per output type — the frame, the
+ * margins, where the chrome sits, the type scale — and nothing else. The same
+ * components draw on every surface; they take their sizes from the custom
+ * properties written here, so a card on a slide and a card on a Letter page
+ * are one piece of CSS at two scales.
+ *
+ * The letter scale is the Franklin Templeton letter's (Oct 2026), the slide
+ * scale its deck's: both reviewed, both shipped.
+ */
+
+const LETTER = {
+  w: 816, h: 1056, x: 60, top: 92, bottom: 74, base: 11.6, min: 7, chars: 95,
+  chrome: { eyebrowTop: 44, eyebrowSize: 8.5, markTop: 36, markW: 30, markH: 28, footBottom: 34, footSize: 8.5, footRule: 1 },
+  t: { display: 56, h1: 40, h1md: 32, h2: 25, h3: 16.5, h4: 14.5, h5: 12, lead: 14.6, lede: 16, body: 11.6, sm: 10.6,
+       note: 8.8, tag: 7.8, label: 17, num: 10, stat: 34, hero: 40, quote: 11.6, name: 12, role: 10.5, meta: 10 },
+  m: { gap: 13, cardPad: "16px 18px", cardPadSm: "13px 15px", radius: 14, colGap: 14, secTop: 15, secGap: 9, chip: 18, arrow: 8, stroke: 1 },
+};
+
+export const SURFACES = {
+  letter: { ...LETTER, name: "letter", kind: "page", paper: "US Letter" },
+  a4: { ...LETTER, name: "a4", kind: "page", paper: "A4", w: 794, h: 1123 },
+  slide: {
+    name: "slide", kind: "slide", w: 1920, h: 1080, x: 72, top: 178, bottom: 112, base: 21, min: 13, chars: 95,
+    chrome: { eyebrowTop: 82, eyebrowSize: 16, markTop: 64, markW: 56, markH: 52, footBottom: 44, footSize: 14, footRule: 0 },
+    t: { display: 88, h1: 68, h1md: 56, h2: 38, h3: 28, h4: 26, h5: 21, lead: 26, lede: 28, body: 21, sm: 18.5,
+         note: 15.5, tag: 15, label: 30, num: 16, stat: 74, hero: 128, quote: 23, name: 22, role: 18.5, meta: 18 },
+    m: { gap: 30, cardPad: "36px 40px", cardPadSm: "30px 30px", radius: 24, colGap: 28, secTop: 0, secGap: 14, chip: 28, arrow: 13, stroke: 1.5 },
+  },
+  square: {
+    name: "square", kind: "card", w: 1080, h: 1080, x: 72, top: 150, bottom: 120, base: 22, min: 14, chars: 60,
+    chrome: { eyebrowTop: 72, eyebrowSize: 16, markTop: 56, markW: 56, markH: 52, footBottom: 56, footSize: 15, footRule: 0 },
+    t: { display: 84, h1: 64, h1md: 52, h2: 40, h3: 30, h4: 26, h5: 22, lead: 28, lede: 30, body: 22, sm: 19,
+         note: 16, tag: 15, label: 28, num: 16, stat: 96, hero: 140, quote: 26, name: 22, role: 19, meta: 18 },
+    m: { gap: 28, cardPad: "32px 36px", cardPadSm: "26px 28px", radius: 24, colGap: 24, secTop: 0, secGap: 12, chip: 28, arrow: 12, stroke: 1.5 },
+  },
+  og: {
+    name: "og", kind: "card", w: 1200, h: 630, x: 64, top: 120, bottom: 90, base: 20, min: 13, chars: 70,
+    chrome: { eyebrowTop: 56, eyebrowSize: 14, markTop: 44, markW: 48, markH: 44, footBottom: 40, footSize: 14, footRule: 0 },
+    t: { display: 72, h1: 56, h1md: 46, h2: 34, h3: 26, h4: 24, h5: 20, lead: 24, lede: 26, body: 20, sm: 18,
+         note: 15, tag: 14, label: 24, num: 14, stat: 80, hero: 110, quote: 22, name: 20, role: 17, meta: 16 },
+    m: { gap: 24, cardPad: "28px 32px", cardPadSm: "22px 24px", radius: 20, colGap: 22, secTop: 0, secGap: 10, chip: 26, arrow: 11, stroke: 1.5 },
+  },
+};
+
+export const surface = (name) => {
+  const s = SURFACES[name];
+  if (!s) throw new Error(`unknown surface "${name}" — one of ${Object.keys(SURFACES).join(", ")}`);
+  return s;
+};
+
+/** The surface as custom properties on `.page`, plus the page box itself. */
+export function surfaceCss(s) {
+  const t = Object.entries(s.t).map(([k, v]) => `--t-${k}:${v}px`).join(";");
+  const kebab = (k) => k.replace(/[A-Z]/g, (x) => "-" + x.toLowerCase());
+  const m = Object.entries(s.m).map(([k, v]) => `--m-${kebab(k)}:${typeof v === "number" ? v + "px" : v}`).join(";");
+  const c = Object.entries(s.chrome).map(([k, v]) => `--c-${kebab(k)}:${v}px`).join(";");
+  return `@page{size:${s.w}px ${s.h}px;margin:0}
+.page{width:${s.w}px;height:${s.h}px;--x:${s.x}px;--top:${s.top}px;--bottom:${s.bottom}px;--base:${s.base}px;font-size:${s.base}px;${t};${m};${c}}`;
+}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "wand-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "One HTML design surface for every sales and marketing material, on either Wand brand: decks, documents, one-pagers, case studies, social cards. Every export (PDF, PNG, PowerPoint, one-file HTML) is read from the page that was reviewed.",
+  "license": "SEE LICENSE IN PROMPT.md",
+  "bin": {
+    "wand-kit": "./wand.js"
+  },
+  "main": "./wand.js",
+  "dependencies": {
+    "fontkit": "^2.0.4",
+    "jszip": "^3.10.1",
+    "playwright-core": "^1.47.2",
+    "pptxgenjs": "^3.12.0"
+  },
+  "scripts": {
+    "doctor": "node wand.js doctor"
+  }
+}

package/templates/card.mjs

@@ -0,0 +1,30 @@
+/**
+ * __NAME__ — social cards on the Wand studio (square 1080 × 1080, or og 1200 × 630).
+ *
+ * One `c.page()` per card. Each page becomes a PNG in out/pages/; the PDF
+ * carries them all. `css` may only use the brand's custom properties.
+ */
+export default {
+  name: "__NAME__",
+  brand: "__BRAND__",          // current | next
+  surface: "__SURFACE__",      // square | og
+  tag: "Wand",
+  footer: "wand.ai",
+  css: `
+.quote-card .content{justify-content:center;gap:1.2em}
+.quote-card .lede{font-size:var(--t-h2);line-height:1.3;max-width:100%}
+`,
+  pages: (c) => [
+    c.page({ dark: true, art: "cover", eyebrow: "Announcement", cls: "quote-card", body: `
+      ${c.tag("Customer story")}
+      <p class="lede">Agentic AI, out of the lab and into <em>enterprise-scale production</em>.</p>
+      ${c.who("Wand × Franklin Templeton", "Multi-year strategic partnership")}
+    ` }),
+
+    c.page({ eyebrow: "By the numbers", cls: "quote-card", body: `
+      ${c.tag("Benchmark trajectory")}
+      ${c.stats([{ v: "70%", k: "Agentic GDP at Evolution" }, { v: "95%", k: "process penetration" }])}
+      ${c.note("Illustrative Wand Dual Workforce framework benchmarks.")}
+    ` }),
+  ],
+};

package/templates/page.mjs

@@ -0,0 +1,52 @@
+/**
+ * __NAME__ — a printed document on the Wand studio.
+ *
+ * `pages(c)` composes with the components (node wand.js components) and may
+ * write raw markup where none fits. `css` is this job's own; it may only use
+ * the brand's custom properties (--ink, --accent, --t-h2 …), never a hex.
+ *
+ * The words come from content.txt by line number (c.L(12)) when rebuilding a
+ * source, so coverage can read every line back off the page. Authored copy
+ * goes straight into the markup; then leave `content` out.
+ */
+export default {
+  name: "__NAME__",
+  brand: "__BRAND__",          // current | next
+  surface: "__SURFACE__",      // letter | a4
+  tag: "Wand",                 // the running tag, left of the eyebrow
+  footer: "Wand AI · Confidential",
+  content: "content.txt",      // delete this line when authoring from a brief
+  edits: {},                   // { 12: [["needle", "replacement"]] } — every departure from the source, declared
+  cut: [],                     // lines left out on purpose
+  denylist: [],                // names that must not appear, e.g. a previous client's
+  css: `
+.cover .top{margin-top:8%}
+`,
+  pages: (c) => [
+    c.cover({
+      label: "Wand × Client",
+      title: `A title with <em>one accent phrase</em>`,
+      lede: "One sentence that says what this document argues.",
+      meta: "Prepared for … · October 2026 · Strictly confidential",
+    }),
+
+    c.page({ eyebrow: "The starting point", body: `
+      ${c.sec("01", `Where growth outruns <em>the organisation</em>`)}
+      ${c.lead("The claim this page carries, in one sentence.")}
+      ${c.body("Running text. Keep a measure near 75 characters; let the grid, hairlines and type do the separating.")}
+      ${c.cols(3, [
+        c.card({ tag: "Layer 01", title: "Real agents", body: ["Persistent identity, memory, objectives and a full action history."] }),
+        c.card({ tag: "Layer 02", title: "An agentic workforce", body: ["Hired, onboarded, reviewed and retired like people, in one registry."] }),
+        c.card({ tag: "Layer 03", title: "Wand OS", emph: true, body: ["The control plane: policy, identity, audit and approval."] }),
+      ])}
+      ${c.sec("02", `Three <em>steps</em>`)}
+      ${c.steps([
+        { title: "Working session", when: "Within 3 weeks", body: "Two hours with the functions that own the shortlist." },
+        { title: "Deployment posture", when: "Weeks 3–5", body: "Environment, policies and approval gates agreed." },
+        { title: "First agents live", when: "Within 90 days", body: "Real work on real data, measured against the baseline.", emph: true },
+      ])}
+    ` }),
+
+    c.closing({ pair: "Wand × Client", title: "The Agentic Workforce", url: "www.wand.ai" }),
+  ],
+};