wand-kit 0.3.2 → 0.5.0

package/brands/interim/lib/composition.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/composition.mjs — the approved social composition, ready to draw.
+ *
+ *   import { composition } from "<brand-interim>/lib/composition.mjs";
+ *   const comp = composition(brandDir);
+ *   comp.page({ w: 1200, h: 630, ...comp.window({ w: 1200, h: 630 }, { left: 520, right: 3310, centreY: 467 }), mode: "dark" })
+ *
+ * `page(card)` returns the HTML of one card: the brand's faces, the canvas,
+ * `window.CARD` and lib/composition.js, which draws it. Render it at any device
+ * scale; the gate it writes into <script id="gate"> says whether the card keeps
+ * the rules. Colours come from ../tokens.json through the composition's palette
+ * for the card's ground (`mode`), the ring from assets/story, the wordmark's paths
+ * from the brand's own SVG; nothing here carries a hex.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const url = (p) => "file://" + p;
+const NUM = /-?\d+(?:\.\d+)?/g;
+
+/** Extents of an SVG path made of M, L, H, V, A and Z commands, from its end points: right for the spark, whose tips are its extremes. */
+function extents(d) {
+  const xs = [], ys = [];
+  let x = 0, y = 0;
+  for (const [, cmd, args] of d.matchAll(/([MLHVAZ])([^MLHVAZ]*)/g)) {
+    const v = (args.match(NUM) || []).map(Number);
+    if (cmd === "M" || cmd === "L") for (let i = 0; i < v.length; i += 2) { x = v[i]; y = v[i + 1]; xs.push(x); ys.push(y); }
+    else if (cmd === "H") for (const n of v) { x = n; xs.push(x); ys.push(y); }
+    else if (cmd === "V") for (const n of v) { y = n; xs.push(x); ys.push(y); }
+    else if (cmd === "A") for (let i = 0; i < v.length; i += 7) { x = v[i + 5]; y = v[i + 6]; xs.push(x); ys.push(y); }
+  }
+  return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)];
+}
+
+export function composition(brandDir) {
+  const read = (...p) => fs.readFileSync(path.join(brandDir, ...p), "utf8");
+  const tokens = JSON.parse(read("tokens.json"));
+  const comp = JSON.parse(read("assets", tokens.art.composition));
+  const story = JSON.parse(read("assets", "story", "index.json"));
+  const sw = tokens.swatch;
+
+  /** The composition's palette for a ground, swatch names resolved to hex. */
+  function palette(mode) {
+    const p = comp.palettes[mode];
+    if (!p) throw new Error(`composition: no palette for "${mode}" (${Object.keys(comp.palettes).join(", ")})`);
+    return Object.fromEntries(Object.entries(p).filter(([k]) => k !== "_").map(([k, v]) => {
+      if (typeof v === "number") return [k, v];
+      if (!sw[v]) throw new Error(`composition palette ${mode}.${k}: "${v}" is not in the swatch`);
+      return [k, sw[v]];
+    }));
+  }
+
+  /** The wordmark's letters and spark for a ground, with the extents the lockup is placed by. */
+  function paths(mode) {
+    const svg = read("assets", tokens.art[mode === "dark" ? "wordmarkSvgOnDark" : "wordmarkSvgOnLight"]);
+    const [letters, spark] = [...svg.matchAll(/<path d="([^"]+)"/g)].map((m) => m[1]);
+    if (!letters || !spark) throw new Error("wordmark SVG: expected two paths, letters then spark");
+    const [lx0, ly0, lx1, ly1] = comp.lockup.wordmark.letters, [, sy0] = extents(spark);
+    return { letters, spark, lettersTop: ly0, lettersH: ly1 - ly0, lettersW: lx1 - lx0, sparkTop: sy0 };
+  }
+
+  /** The ring's image for a ground: the alpha capture on dark; on light the same capture with its inner rings tinted (tools/art.mjs). */
+  function ringFile(mode) {
+    const key = mode === "light" ? comp.ring.stage.replace(/-alpha$/, "-light") : comp.ring.stage;
+    const s = story[key];
+    if (!s) throw new Error(`composition: story/index.json has no "${key}"${mode === "light" ? " (run tools/art.mjs)" : ""}`);
+    return path.join(brandDir, "assets", "story", s.file);
+  }
+
+  /** A wide window: the master x-range [left, right] fills the card's width, centred on master y `centreY`. */
+  function window(card, { left, right, centreY }) {
+    const s = card.w / (right - left);
+    return { s, x0: left, y0: centreY - card.h / s / 2 };
+  }
+
+  const L = comp.lockup;
+  const faces = [L.lead, L.phrase].map((f) => {
+    const file = tokens.faces.files.find((x) => x.family === f.family && x.weight === f.weight && !!x.italic === !!f.italic);
+    if (!file) throw new Error(`composition: no ${f.family} ${f.weight}${f.italic ? " italic" : ""} in tokens.faces.files`);
+    return { ...f, file: path.join(brandDir, "fonts", file.file) };
+  });
+  const FACES = faces.map((f) => `@font-face{font-family:"${f.family}";src:url("${url(f.file)}");font-weight:${f.weight};font-style:${f.italic ? "italic" : "normal"}}`).join("\n");
+  const LOADS = faces.map((f) => `${f.italic ? "italic " : ""}${f.weight} ${f.size}px "${f.family}"`);
+  const script = read("lib", "composition.js");
+
+  /** The page for one card: { w, h, s, x0, y0, mode, lockup?: {dx, dy} | false, ring?: {dx, dy}, set?, text?: {lead, phrase}, photo?: path, rules?, id? }. */
+  function page(card) {
+    const P = palette(card.mode), R = tokens.roles[card.mode];
+    const photo = card.photo ? { src: url(path.resolve(card.photo)), low: R.gradeLow, high: R.gradeHigh } : null;
+    const cfg = { ...card, photo, composition: comp, palette: P, paths: paths(card.mode), fonts: card.lockup === false ? [] : LOADS, ringSrc: url(card.ringFile || ringFile(card.mode)) };
+    const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;");
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(card.id || "card")}</title><style>${FACES}
+html,body{margin:0;background:#${P.ground}}canvas{display:block}</style></head><body>
+<canvas id="card"></canvas>
+<script>window.CARD=${JSON.stringify(cfg).replace(/</g, "\\u003c")};</script>
+<script>${script}</script>
+</body></html>`;
+  }
+
+  return { tokens, comp, story, palette, paths, ringFile, window, page, extents };
+}

package/brands/interim/lib/glyphs.js

@@ -0,0 +1,89 @@
+/**
+ * lib/glyphs.js — the named icon set.
+ *
+ * The old library was 36 PNGs named after their extraction order, half baked
+ * white and half baked accent. That produced two standing bugs: a white glyph on
+ * a light tile is invisible, and nobody could pick an icon by meaning because
+ * the names carried none.
+ *
+ * These are Lucide's single-colour stroke SVGs. `stroke="currentColor"` means
+ * the kit substitutes the theme's colour at build time, so polarity cannot be
+ * wrong. They go into the deck as vector — pptxgenjs writes the OOXML
+ * `asvg:svgBlip` extension with a raster fallback — so nothing is rasterised
+ * and the kit keeps needing no native dependency.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DIR = path.join(__dirname, "..", "assets", "glyphs");
+let INDEX = null, BUNDLE = null;
+
+function index() {
+  if (!INDEX) INDEX = JSON.parse(fs.readFileSync(path.join(DIR, "index.json"), "utf8"));
+  return INDEX;
+}
+
+/**
+ * 75 SVGs is 75 files, and a packaged skill is capped at 200 of them. The
+ * packager collapses them into one `glyphs.json`; loose files still win when
+ * they are there, so the repo keeps its readable one-file-per-icon layout.
+ */
+function bundle() {
+  if (BUNDLE === null) {
+    const f = path.join(DIR, "glyphs.json");
+    BUNDLE = fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, "utf8")) : false;
+  }
+  return BUNDLE;
+}
+
+/** The raw SVG source for a glyph. */
+function svg(name) {
+  const b = bundle();
+  if (b && b[name]) return b[name];
+  return fs.readFileSync(path.join(DIR, name + ".svg"), "utf8");
+}
+
+/** Every glyph name, for validation and for `wand.js glyphs`. */
+const names = () => index().icons;
+const has = (name) => typeof name === "string" && index().icons.includes(name);
+
+const cache = new Map();
+
+/**
+ * A recoloured glyph as a data URI, ready for `addImage({ data })`.
+ * Returns null for anything that isn't a known glyph name, so callers can fall
+ * back to the legacy PNG path.
+ */
+function dataUri(name, color, { strokeWidth } = {}) {
+  if (!has(name)) return null;
+  const key = `${name}|${color}|${strokeWidth || ""}`;
+  if (cache.has(key)) return cache.get(key);
+  let src = svg(name).replace(/currentColor/g, "#" + String(color).replace(/^#/, ""));
+  // the site draws its line art at a hairline; Lucide's 2px reads heavy beside it
+  if (strokeWidth) src = src.replace(/stroke-width="[\d.]+"/g, `stroke-width="${strokeWidth}"`);
+  const uri = "image/svg+xml;base64," + Buffer.from(src, "utf8").toString("base64");
+  cache.set(key, uri);
+  return uri;
+}
+
+/** Nearest names, for a useful error when someone mistypes one. */
+function suggest(name, n = 4) {
+  const q = String(name || "").toLowerCase();
+  return index().icons
+    .map((g) => [g, g.includes(q) || q.includes(g) ? 0 : distance(q, g)])
+    .sort((a, b) => a[1] - b[1]).slice(0, n).map((r) => r[0]);
+}
+
+function distance(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+  }
+  return d[a.length][b.length];
+}
+
+module.exports = { names, has, svg, dataUri, suggest, index, DIR };

package/brands/interim/lib/measure.js

@@ -0,0 +1,121 @@
+/**
+ * lib/measure.js — real text metrics against the brand's actual faces.
+ *
+ * Why this exists: LibreOffice ignores embedded fonts and substitutes DejaVu,
+ * so QA renders over-report overflow and lose all weight information. This
+ * module measures the real font, so overflow is a build-time error rather than
+ * a judgement call about a screenshot.
+ *
+ * What differs from the Geist-era copy in brand/lib: the face table is data
+ * (`fonts/faces.json`), not code, and every family carries its letter-spacing.
+ * The website sets headings at -0.07em and body at -0.02em, the kit writes the
+ * same spacing into every run, and this module measures with it — so a title
+ * is judged at the width it is actually drawn, not at the font's default.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const FONTS = path.join(__dirname, "..", "fonts");
+const TABLE = JSON.parse(fs.readFileSync(path.join(FONTS, "faces.json"), "utf8"));
+
+let FONTKIT = null;
+const cache = new Map();
+
+/** The faces.json entry for a family, falling back to the default body face. */
+function familyOf(family) {
+  return TABLE.families[family] || TABLE.families[TABLE.default];
+}
+
+/** The TTF stem that draws a family in a given style. */
+function stemOf(family, bold = false, italic = false) {
+  const set = familyOf(family);
+  return set[bold && italic ? "bi" : bold ? "b" : italic ? "i" : "r"];
+}
+
+/** Letter-spacing for a family, in em. */
+const trackingEm = (family) => familyOf(family).tracking || 0;
+
+/** Letter-spacing in points at a size — the unit PowerPoint's `spc` and PDF's `Tc` take. */
+const trackingPt = (family, fontSize) => +(trackingEm(family) * fontSize).toFixed(2);
+
+function face(family, { bold = false, italic = false } = {}) {
+  if (!FONTKIT) throw new Error("measure.js was loaded without fontkit — require it through the kit's lib/shared.js");
+  const stem = stemOf(family, bold, italic);
+  if (!cache.has(stem)) cache.set(stem, FONTKIT.openSync(path.join(FONTS, stem + ".ttf")));
+  return cache.get(stem);
+}
+
+/** Width of a single line, in inches, tracking included. */
+function widthIn(text, { family, fontSize, bold, italic } = {}) {
+  if (!text) return 0;
+  const f = face(family, { bold, italic });
+  const run = f.layout(String(text));
+  const glyphs = run.glyphs.length;
+  return (run.advanceWidth / f.unitsPerEm) * (fontSize / 72) + (trackingPt(family, fontSize) * glyphs) / 72;
+}
+
+/**
+ * Greedy word wrap at a given box width. Returns the lines it would occupy.
+ * Honours explicit \n. Matches how PowerPoint breaks closely enough to catch
+ * the failures that matter (a line too many, a word that can't fit at all).
+ */
+function wrap(text, boxWidthIn, opts = {}) {
+  const out = [];
+  for (const para of String(text).split("\n")) {
+    const words = para.split(/\s+/).filter(Boolean);
+    if (!words.length) { out.push(""); continue; }
+    let line = words[0];
+    for (let i = 1; i < words.length; i++) {
+      const test = line + " " + words[i];
+      if (widthIn(test, opts) <= boxWidthIn) line = test;
+      else { out.push(line); line = words[i]; }
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+/** Rendered height in inches for text wrapped into a box. */
+function heightIn(text, boxWidthIn, opts = {}) {
+  const leading = opts.lineSpacingMultiple || 1.2;
+  return wrap(text, boxWidthIn, opts).length * (opts.fontSize / 72) * leading;
+}
+
+/** Does this text fit the box? A verdict object, so callers can report why. */
+function fits(text, boxWidthIn, boxHeightIn, opts = {}) {
+  const lines = wrap(text, boxWidthIn, opts);
+  const h = heightIn(text, boxWidthIn, opts);
+  const widest = Math.max(...lines.map((l) => widthIn(l, opts)));
+  return {
+    ok: h <= boxHeightIn + 1e-6 && widest <= boxWidthIn + 1e-6,
+    lines: lines.length,
+    heightIn: +h.toFixed(3),
+    widestIn: +widest.toFixed(3),
+    overflowIn: +Math.max(0, h - boxHeightIn).toFixed(3),
+  };
+}
+
+/** Largest size at or below `fontSize` that fits, stepping by `step`, never below `min`. */
+function fitSize(text, boxWidthIn, boxHeightIn, opts = {}) {
+  const { fontSize, min = 7, step = 0.5 } = opts;
+  for (let s = fontSize; s >= min; s -= step) {
+    if (fits(text, boxWidthIn, boxHeightIn, { ...opts, fontSize: s }).ok) return s;
+  }
+  return min;
+}
+
+/** Line count only — the common case for "will this title be 2 lines or 3?". */
+const lineCount = (text, boxWidthIn, opts = {}) => wrap(text, boxWidthIn, opts).length;
+
+/** Every family the brand knows, for the gates that check a deck stays inside them. */
+const families = () => Object.keys(TABLE.families);
+
+/**
+ * This module lives in the brand payload, outside any kit's node_modules, so
+ * Node cannot resolve `fontkit` from here. The kit that loads it hands its own
+ * copy in.
+ */
+module.exports = function create(fontkit) {
+  FONTKIT = fontkit;
+  return { widthIn, wrap, heightIn, fits, fitSize, lineCount, face, stemOf, trackingEm, trackingPt, families, TABLE };
+};