wand-kit 0.0.0-stage → 0.2.0

package/templates/slide.mjs

@@ -0,0 +1,46 @@
+/**
+ * __NAME__ — a 16:9 deck on the Wand studio.
+ *
+ * One `c.page()` per slide. `notes` on a page become speaker notes in the
+ * .pptx. `pages(c)` composes with the components (node wand.js components)
+ * and may write raw markup where none fits; `css` may only use the brand's
+ * custom properties (--ink, --accent, --t-h1 …), never a hex.
+ */
+export default {
+  name: "__NAME__",
+  brand: "__BRAND__",          // current | next
+  surface: "slide",
+  tag: "Wand × Client",
+  footer: "Wand AI · Strictly confidential",
+  content: "content.txt",      // delete this line when authoring from a brief
+  edits: {},
+  cut: [],
+  denylist: [],
+  css: ``,
+  pages: (c) => [
+    c.cover({
+      label: "Wand × Client",
+      title: `Building the <em>Dual Workforce</em>`,
+      lede: "One sentence that says what this deck argues.",
+      meta: "Prepared for … · October 2026",
+      notes: "Open on the claim; the next slide carries the evidence.",
+    }),
+
+    c.page({ eyebrow: "The shift", cls: "roomy", notes: "Left is where every airline is today; right is what we deploy.", body: `
+      ${c.h1(`Two <em>Models</em>`)}
+      ${c.cols(2, [
+        c.card({ tag: "Today · every organisation", title: "Human-centric", level: "h3", body: `<div class="sub">100% human</div><p class="body">Humans think, decide and execute. AI shows up in pockets, as tools.</p>` }),
+        c.card({ tag: "The target model", title: "Dual workforce", level: "h3", emph: true, body: `<div class="sub">Humans + AI agents</div><p class="body">One workforce, two kinds of colleagues; agent workers carry the volume growth.</p>` }),
+      ])}
+    ` }),
+
+    c.page({ eyebrow: "The journey", body: `
+      ${c.strip(["Foundation", "Beachhead", "Controlled expansion", "Enterprise scale"], { on: 0 })}
+      ${c.h1("One registry, one identity", "md")}
+      ${c.cols(2, [c.body("The first move was structural: one workforce registry for humans and agents."), c.body("Every agent is provisioned through the firm's standard identity infrastructure.")], { stretch: false })}
+      ${c.callout({ tag: "Why identity-first matters", text: "Treating agents as governed identities is what lets a regulated firm scale AI safely." })}
+    ` }),
+
+    c.closing({ pair: "Wand × Client", title: "Building the Dual Workforce", url: "www.wand.ai", eyebrow: "The road ahead" }),
+  ],
+};

package/tools/embed_fonts.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+tools/embed_fonts.py: embed the faces a studio .pptx uses, and only those.
+
+    python3 embed_fonts.py --faces faces.json --fonts <brand fonts dir> --lib <brand lib dir> in.pptx out.pptx
+
+faces.json is { "<typeface>": { "regular": "<file.ttf>", "italic": "<file.ttf>" } },
+written by lib/pptx.js: one PowerPoint family per face the slides set. Weight
+rides on the family name in this system ("Geist SemiBold" regular, not
+"Geist" bold), so each family gets its regular slot and, when an italic file
+was used, its italic slot, and never a bold slot. A renderer that matches by
+name rather than by slot (LibreOffice does) then has one face per name and
+cannot draw one weight for another, which the decks kit's all-slots embedding
+let it do.
+
+Why embed at all: a deck without its faces renders in Arial and Times on the
+client's machine. The brand's ttf.py rewrites each file's name table so the
+face reports the family the slides address it by; eot() wraps it the way
+PowerPoint wants it, an uncompressed EOT, unsubsetted, with
+saveSubsetFonts="0", so digits do not garble in exported PDFs. Standard
+library only, plus ttf.py.
+"""
+
+import argparse, json, os, re, shutil, struct, sys, tempfile, zipfile
+
+REL_FONT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font"
+SLOTS = ("regular", "italic")
+_ttf = None
+
+
+def eot(ttf_bytes, font, family, italic):
+    """Wrap raw TTF bytes in an uncompressed EOT v2.1 container."""
+    os2 = font.os2
+    panose = os2["panose"]
+
+    def lpstr(s):
+        b = s.encode("utf-16-le")
+        return struct.pack("<HH", 0, len(b)) + b  # padding + size + string
+
+    body = b""
+    body += panose                                   # FontPANOSE[10]
+    body += struct.pack("<BB", 1, 1 if italic else 0)  # Charset(DEFAULT), Italic
+    body += struct.pack("<I", os2["usWeightClass"])  # Weight
+    body += struct.pack("<HH", os2.get("fsType", 0), 0x504C)  # the font's own embedding flags, MagicNumber
+    body += struct.pack("<IIII", *os2["ulUnicodeRange"])
+    body += struct.pack("<II", *os2["ulCodePageRange"])
+    body += struct.pack("<I", font.check_sum_adjustment)
+    body += struct.pack("<IIII", 0, 0, 0, 0)         # Reserved1-4
+    body += lpstr(family)                            # FamilyName
+    body += lpstr("Italic" if italic else "Regular") # StyleName
+    body += lpstr("Version 1.0")                     # VersionName
+    body += lpstr(f"{family} Italic" if italic else family)  # FullName
+    body += struct.pack("<HH", 0, 0)                 # v2.1: RootString (empty)
+
+    # EOTSize, FontDataSize, Version, Flags(0 = uncompressed, not subsetted)
+    prefix = struct.pack("<IIII", 16 + len(body) + len(ttf_bytes),
+                         len(ttf_bytes), 0x00020001, 0x00000000)
+    return prefix + body + ttf_bytes
+
+
+def retag(ttf_path, family, italic):
+    """The file with its name table rewritten to the family the slides use.
+
+    Without this PowerPoint matches the embedded face to nothing and falls
+    back; with it, every family reports exactly one regular and one italic.
+    """
+    f = _ttf.load(ttf_path)
+    sub = "Italic" if italic else "Regular"
+    full = f"{family} Italic" if italic else family
+    ps = family.replace(" ", "") + ("-Italic" if italic else "")
+    data = f.retagged(family, sub, full, ps)
+    return data, _ttf.TTF(data)
+
+
+def main():
+    global _ttf
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--faces", required=True)
+    ap.add_argument("--fonts", required=True)
+    ap.add_argument("--lib", required=True)
+    ap.add_argument("src")
+    ap.add_argument("out")
+    a = ap.parse_args()
+    if not os.path.isfile(os.path.join(a.lib, "ttf.py")):
+        sys.exit(f"no ttf.py in {a.lib}")
+    sys.path.insert(0, a.lib)
+    import ttf
+    _ttf = ttf
+    faces = json.load(open(a.faces, encoding="utf-8"))
+
+    work = tempfile.mkdtemp()
+    with zipfile.ZipFile(a.src) as z:
+        z.extractall(work)
+    fdir = os.path.join(work, "ppt", "fonts")
+    os.makedirs(fdir, exist_ok=True)
+    rels_path = os.path.join(work, "ppt", "_rels", "presentation.xml.rels")
+    rels = open(rels_path, encoding="utf-8").read()
+    next_id = max([int(m) for m in re.findall(r'Id="rId(\d+)"', rels)] or [0]) + 1
+
+    new_rels, blocks, made = [], [], 0
+    for family, slots in faces.items():
+        entries = []
+        for slot in SLOTS:
+            fn = slots.get(slot)
+            if not fn:
+                continue
+            src = os.path.join(a.fonts, fn)
+            if not os.path.isfile(src):
+                sys.exit(f"{family}/{slot}: {src} not found")
+            italic = slot == "italic"
+            data, font = retag(src, family, italic)
+            name = f"{family.replace(' ', '')}-{slot}.fntdata"
+            open(os.path.join(fdir, name), "wb").write(eot(data, font, family, italic))
+            rid = f"rId{next_id}"
+            next_id += 1
+            new_rels.append(f'<Relationship Id="{rid}" Type="{REL_FONT}" Target="fonts/{name}"/>')
+            entries.append(f'<p:{slot} r:id="{rid}"/>')
+            made += 1
+        if entries:
+            blocks.append(f'<p:embeddedFont><p:font typeface="{family}" pitchFamily="34" charset="0"/>'
+                          + "".join(entries) + "</p:embeddedFont>")
+
+    open(rels_path, "w", encoding="utf-8").write(rels.replace("</Relationships>", "".join(new_rels) + "</Relationships>"))
+    ct_path = os.path.join(work, "[Content_Types].xml")
+    ct = open(ct_path, encoding="utf-8").read()
+    if "fntdata" not in ct:
+        ct = ct.replace("<Default", '<Default Extension="fntdata" ContentType="application/x-fontdata"/><Default', 1)
+        open(ct_path, "w", encoding="utf-8").write(ct)
+    p_path = os.path.join(work, "ppt", "presentation.xml")
+    p = open(p_path, encoding="utf-8").read()
+    p = re.sub(r'\s(embedTrueTypeFonts|saveSubsetFonts)="[^"]*"', "", p)
+    p = re.sub(r"(<p:presentation\b)", r'\1 embedTrueTypeFonts="1" saveSubsetFonts="0"', p, count=1)
+    p = re.sub(r"<p:embeddedFontLst>.*?</p:embeddedFontLst>", "", p, flags=re.S)
+    # schema-fixed position: immediately after <p:notesSz/>
+    anchor = re.search(r"<p:notesSz[^/]*/>", p) or re.search(r"<p:sldSz[^/]*/>", p)
+    if not anchor:
+        sys.exit("no <p:notesSz>/<p:sldSz> anchor in presentation.xml")
+    p = p[:anchor.end()] + "<p:embeddedFontLst>" + "".join(blocks) + "</p:embeddedFontLst>" + p[anchor.end():]
+    open(p_path, "w", encoding="utf-8").write(p)
+
+    if os.path.exists(a.out):
+        os.remove(a.out)
+    with zipfile.ZipFile(a.out, "w", zipfile.ZIP_DEFLATED) as zf:
+        names = sorted((os.path.relpath(os.path.join(r, f), work) for r, _, fs in os.walk(work) for f in fs),
+                       key=lambda n: (n != "[Content_Types].xml", n))
+        for n in names:
+            zf.write(os.path.join(work, n), n)
+    shutil.rmtree(work)
+    print(f"embedded {made} faces in {len(blocks)} families: "
+          + "; ".join(f"{fam} ({', '.join(s for s in SLOTS if s in sl)})" for fam, sl in faces.items()))
+
+
+if __name__ == "__main__":
+    main()

package/wand.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * wand.js — the studio's front door.
+ *
+ *   node wand.js doctor                               what works here, and the brand rule
+ *   node wand.js new <dir> [--surface letter] [--brand current|next] [--name "Title"]
+ *                                                     a job folder to compose in, on the default brand
+ *                                                     unless --brand names the other
+ *   node wand.js build <job.mjs>                      gates, then the PDF, a PNG per page, the sheet
+ *   node wand.js check <job.mjs>                      gates only
+ *   node wand.js ship  <job.mjs> [--pptx] [--no-html] everything: build, one-file HTML, PowerPoint
+ *   node wand.js watch <job.mjs>                      rebuild on save, the browser kept warm
+ *   node wand.js gallery [--brand current|next]       every component, light and dark, on one surface each
+ *   node wand.js components                           the vocabulary
+ *   node wand.js brands                               the brands this kit can draw with
+ *
+ * A job is a folder with `job.mjs` (the composition) and, for a rebuild,
+ * `content.txt` (the words, one per line). Outputs land in `<job>/out/`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { execFileSync, spawnSync } from "node:child_process";
+import { BRANDS, DEFAULT_BRAND, ASKED_AS, brandRule } from "./lib/brand.js";
+
+const require = createRequire(import.meta.url);
+const KIT = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (k, d = null) => { const i = args.indexOf(k); return i < 0 ? d : args[i + 1] ?? d; };
+const on = (k) => args.includes(k);
+const die = (m, c = 2) => { console.error(`\n${m}\n`); process.exit(c); };
+const rel = (p) => path.relative(process.cwd(), p) || ".";
+
+async function doctor() {
+  const { findChrome, has } = await import("./lib/engine.js");
+  const { loadBrand } = await import("./lib/brand.js");
+  const rows = [];
+  rows.push(["node", process.version, +process.version.slice(1).split(".")[0] >= 18 ? "ok" : "MISSING - Node 18 or newer"]);
+  for (const d of ["playwright-core", "pptxgenjs", "jszip", "fontkit"]) { let s = "ok"; try { require.resolve(d); } catch { s = `MISSING - npm install in ${rel(KIT)}`; } rows.push([d, s === "ok" ? "bundled" : "-", s]); }
+  const chrome = findChrome();
+  rows.push(["chromium", chrome ? chrome.replace(process.env.HOME || "~", "~") : "MISSING", chrome ? "ok" : "no renderer - set WAND_CHROME, or `npx playwright-core install chromium`"]);
+  for (const b of BRANDS) { try { const br = loadBrand(b); rows.push([`brand ${b}`, rel(br.dir), "ok"]); } catch (e) { rows.push([`brand ${b}`, "MISSING", e.message.split("\n")[0]]); } }
+  const py = ["python3", "python"].find((c) => spawnSync(c, ["-c", "import sys;print(sys.version_info[0])"], { encoding: "utf8" }).stdout?.trim() === "3");
+  rows.push(["python3", py ? execFileSync(py, ["-V"], { encoding: "utf8" }).trim() : "absent", py ? "ok" : "the .pptx ships without embedded fonts"]);
+  rows.push(["pdftotext", has("pdftotext") ? "found" : "absent", has("pdftotext") ? "ok" : "coverage is read from the DOM only (poppler adds the PDF read-back)"]);
+  const w = Math.max(...rows.map((r) => r[0].length));
+  console.log("");
+  for (const [k, v, s] of rows) console.log(`${s === "ok" ? "  " : "! "}${k.padEnd(w)}  ${String(v).padEnd(36)}${s === "ok" ? "" : s}`);
+  const blocked = rows.some((r) => r[2].startsWith("MISSING") || r[2].startsWith("no renderer"));
+  console.log(`\n  brand rule  ${brandRule()}`);
+  console.log(blocked ? "\nBLOCKED - fix the rows marked !\n" : "\nready - node wand.js new <dir>, then build <dir>/job.mjs\n");
+  return blocked ? 1 : 0;
+}
+
+function newJob() {
+  const dir = args[1]; if (!dir) die("usage: node wand.js new <dir> [--surface letter|a4|slide|square|og] [--brand current|next] [--name \"Title\"]");
+  const surface = flag("--surface", "letter"), brand = flag("--brand", DEFAULT_BRAND), name = flag("--name", path.basename(dir));
+  if (!BRANDS.includes(brand)) die(`unknown brand "${brand}" - one of ${BRANDS.join(", ")}`);
+  const tpl = path.join(KIT, "templates", `${["slide", "square", "og"].includes(surface) ? (surface === "slide" ? "slide" : "card") : "page"}.mjs`);
+  if (!fs.existsSync(tpl)) die(`no template for surface "${surface}"`);
+  if (fs.existsSync(path.join(dir, "job.mjs"))) die(`${dir}/job.mjs already exists`);
+  fs.mkdirSync(dir, { recursive: true });
+  const src = fs.readFileSync(tpl, "utf8").replace(/__NAME__/g, name.replace(/"/g, '\\"')).replace(/__SURFACE__/g, surface).replace(/__BRAND__/g, brand);
+  fs.writeFileSync(path.join(dir, "job.mjs"), src);
+  if (!fs.existsSync(path.join(dir, "content.txt"))) fs.writeFileSync(path.join(dir, "content.txt"), "");
+  console.log(`${dir}/\n  job.mjs       the composition — pages(c) and css\n  content.txt   the words, one source string per line (leave empty when authoring)\n\nnext: node ${rel(path.join(KIT, "wand.js"))} build ${path.join(dir, "job.mjs")}`);
+}
+
+async function build(jobPath, opts) {
+  if (!jobPath) die("usage: node wand.js build <job.mjs>");
+  const { build } = await import("./lib/engine.js");
+  return build(jobPath, opts);
+}
+
+async function ship(jobPath) {
+  if (!jobPath) die("usage: node wand.js ship <job.mjs> [--pptx] [--no-html]");
+  const { build, closeBrowser } = await import("./lib/engine.js");
+  const r = await build(jobPath, { quiet: true });
+  const { surface } = await import("./lib/surfaces.js");
+  const s = surface(r.surface);
+  if (!on("--no-html")) {
+    const { singleFile } = await import("./lib/html_export.js");
+    const out = path.join(path.dirname(r.outputs.pdf), `${r.name}.html`);
+    const sf = singleFile(r.outputs.html, out, { kind: s.kind, w: s.w, h: s.h });
+    r.outputs.single = sf.out;
+    if (sf.missing.length) r.rows.push({ ok: false, gate: "html", msg: `missing files: ${sf.missing.join(", ")}` });
+  }
+  if (on("--pptx")) {
+    try {
+      const { exportPptx } = await import("./lib/pptx.js");
+      const out = path.join(path.dirname(r.outputs.pdf), `${r.name}.pptx`);
+      const px = await exportPptx({ htmlPath: r.outputs.html, outPath: out, brand: r.brand, surface: s, notes: r.notes, name: r.name });
+      r.outputs.pptx = out;
+      r.rows.push({ ok: px.ok, gate: "pptx", msg: px.msg, warn: px.warn });
+    } catch (e) { r.rows.push({ ok: false, gate: "pptx", msg: e.message.split("\n")[0] }); }
+  }
+  r.ok = r.rows.every((x) => x.ok || x.warn);
+  const { printReport } = await import("./lib/engine.js");
+  printReport(r);
+  await closeBrowser();
+  return r.ok ? 0 : 1;
+}
+
+async function watch(jobPath) {
+  if (!jobPath) die("usage: node wand.js watch <job.mjs>");
+  const { build, closeBrowser } = await import("./lib/engine.js");
+  const dir = path.dirname(path.resolve(jobPath));
+  let busy = false, again = false, timer = null;
+  const run = async () => {
+    if (busy) { again = true; return; }
+    busy = true;
+    try { console.clear(); console.log(`${new Date().toLocaleTimeString()}  ${rel(jobPath)}`); await build(jobPath, {}); }
+    catch (e) { console.error(`\n  FAIL  ${e.message}\n`); }
+    busy = false;
+    if (again) { again = false; run(); }
+  };
+  fs.watch(dir, { recursive: false }, (ev, f) => { if (f && !/^out\b/.test(f)) { clearTimeout(timer); timer = setTimeout(run, 150); } });
+  for (const d of ["lib", "templates"]) fs.watch(path.join(KIT, d), () => { clearTimeout(timer); timer = setTimeout(run, 150); });
+  await run();
+  console.log("\n  watching — save to rebuild, Ctrl-C to stop");
+  process.on("SIGINT", async () => { await closeBrowser(); process.exit(0); });
+}
+
+async function gallery() {
+  const brand = flag("--brand", DEFAULT_BRAND);
+  const { build, closeBrowser } = await import("./lib/engine.js");
+  process.env.WAND_GALLERY_BRAND = brand;
+  const r = await build(path.join(KIT, "examples", "gallery", "job.mjs"), {});
+  await closeBrowser();
+  return r.ok ? 0 : 1;
+}
+
+async function components() {
+  const { bind } = await import("./lib/components.js");
+  const { loadBrand } = await import("./lib/brand.js");
+  const { surface } = await import("./lib/surfaces.js");
+  const c = bind({ brand: loadBrand("current"), surface: surface("letter"), job: {}, content: { L: () => "", lines: [] } });
+  const doc = {
+    page: "page({ eyebrow, dark, art, cls, body, notes })  a page with the chrome", cover: "cover({ label, title, lede, body, meta, extra, art })", closing: "closing({ pair, title, url, lede })",
+    sec: "sec(num, titleHtml, { stack })  numbered section heading", h1: "h1(html, cls) … h5", lead: "lead(html)  the standfirst", body: "body(html)  running text", small: "small(html)", note: "note(html)  small print",
+    tag: "tag(text)  a caps label", cols: "cols(n, [items], { stretch })  a grid", card: "card({ tag, title, level, body, out, emph, sm })", callout: "callout({ tag, text, emph })",
+    strip: "strip([labels], { on })  numbered chips with arrows", chip: "chip(i, label, state)", phase: "phase(i, label, line)  chip then heading", flow: "flow({ label, nodes: [[who, verb, 'a'|'p']], note })",
+    table: "table({ head, rows, emph })  cells: string or { v, meter, cls }", quote: "quote({ text, by, emph })", who: "who(name, role)", stats: "stats([{ v, k, hero }])", delta: "delta(from, to)",
+    steps: "steps([{ title, when, body, emph }])", list: "list([items])", chapter: "chapter(num)  the deck's numeral panel", img: "img(src, cls, alt)", icon: "icon(name)  a brand glyph", tile: "tile(name)  a glyph on a tile",
+    accent: "accent(text, phrase)  the phrase in the accent colour", split: "split(line, sep)", L: "L(n)  line n of content.txt", esc: "esc(s)", art: "art(role)  a brand art url", asset: "asset(file)",
+  };
+  console.log("");
+  for (const k of Object.keys(doc)) console.log(`  ${k.padEnd(9)} ${doc[k]}`);
+  console.log(`\n  ${Object.keys(c).length} helpers bound per job; see PROMPT.md §5 for when each is right.\n`);
+}
+
+async function brands() {
+  const { loadBrand } = await import("./lib/brand.js");
+  for (const b of BRANDS) { const br = loadBrand(b); console.log(`\n  ${b.padEnd(8)} ${br.title}${b === DEFAULT_BRAND ? "  (default)" : ""}\n  ${"".padEnd(8)} ${rel(br.dir)} · faces: ${br.families.join(", ")} · ${br.faceFiles.length} files · ${Object.keys(br.tokens.art).length} art roles\n  ${"".padEnd(8)} asked for as: ${ASKED_AS[b].join(", ")}`); }
+  console.log(`\n  rule: ${brandRule()}\n`);
+}
+
+try {
+  switch (cmd) {
+    case "doctor": process.exit(await doctor());
+    case "new": newJob(); break;
+    case "build": { const r = await build(args[1], {}); const { closeBrowser } = await import("./lib/engine.js"); await closeBrowser(); process.exit(r.ok ? 0 : 1); }
+    case "check": { const r = await build(args[1], { outputs: false }); const { closeBrowser } = await import("./lib/engine.js"); await closeBrowser(); process.exit(r.ok ? 0 : 1); }
+    case "ship": process.exit(await ship(args[1]));
+    case "watch": await watch(args[1]); break;
+    case "gallery": process.exit(await gallery());
+    case "components": await components(); break;
+    case "brands": await brands(); break;
+    default:
+      console.log(fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("*/")[0].split("\n").slice(2).map((l) => l.replace(/^ \* ?/, "")).join("\n"));
+      process.exit(cmd ? 2 : 0);
+  }
+} catch (e) {
+  const { closeBrowser } = await import("./lib/engine.js").catch(() => ({ closeBrowser: async () => {} }));
+  await closeBrowser();
+  die(`${e.message}${process.env.WAND_DEBUG ? "\n" + e.stack : ""}`);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.