wand-decks-kit 0.8.0

package/lib/wandxml.py

@@ -0,0 +1,37 @@
+"""
+wandxml.py — XML parsing that works with nothing installed.
+
+The kit has to run wherever someone unzips it. `defusedxml` is the better
+parser and we use it when it's there, but requiring a pip install to get past
+Phase 0 means the engine is unusable in exactly the situation it was built for:
+a fresh container with a zip and a .pptx in it.
+
+The stdlib fallback is guarded against the one attack that matters for a parser
+pointed at an untrusted .pptx — entity expansion — by refusing any document with
+a DOCTYPE. Office files never have one.
+"""
+
+try:
+    from defusedxml import minidom as _md
+    HARDENED = True
+except ImportError:                                    # stdlib fallback
+    from xml.dom import minidom as _md
+    HARDENED = False
+
+
+class UnsafeXML(ValueError):
+    pass
+
+
+def parse(data):
+    """Parse .pptx part bytes (or str) into a minidom Document."""
+    probe = data[:8192]
+    if isinstance(probe, bytes):
+        probe = probe.decode("utf-8", "ignore")
+    if not HARDENED and ("<!DOCTYPE" in probe or "<!ENTITY" in probe):
+        raise UnsafeXML(
+            "document declares a DOCTYPE or ENTITY. Office parts never do. "
+            "Refusing to parse it with the stdlib parser — `pip install defusedxml` "
+            "if this file is genuinely trusted."
+        )
+    return _md.parseString(data)

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "wand-decks-kit",
+  "version": "0.8.0",
+  "description": "Rebuilds or authors a client-ready .pptx on the Wand design system: measured fit, embedded Geist, verbatim content.",
+  "license": "SEE LICENSE IN PROMPT.md",
+  "bin": {
+    "wand-decks-kit": "./wand.js"
+  },
+  "main": "./wand_kit.js",
+  "dependencies": {
+    "fontkit": "^2.0.0",
+    "pptxgenjs": "^3.12.0"
+  },
+  "scripts": {
+    "doctor": "node wand.js doctor"
+  }
+}

package/preview/preview.css

@@ -0,0 +1,112 @@
+/* preview.css — the Wand design system as CSS.
+   Tokens mirror wand_kit.js §2 exactly. If you change one, change both. */
+
+/* @font-face is injected by preview.js - the path to brand/fonts depends on
+   whether the kit is running from the repo or from a packaged zip. */
+
+:root {
+  --accent: #8B7CF6;
+  --accent-deep: #6C5CE7;
+  --accent-soft: #A99CF8;
+  --accent-pale: #C4B5F4;
+
+  --bg-dark: #0F0C26;
+  --ink-dark: #F3F1FA;
+  --body-dark: #B7B0DC;
+  --body-dark-alt: #CCC0F2;
+  --card-stroke: #2E2757;
+  --card-solid: #2C2460;
+  --card-muted: #241D4F;
+  --card-muted-stroke: #4A3F8C;
+  --card-emph-flat: #352B70;
+
+  --bg-light: #F8F6FB;
+  --ink-light: #1D1A33;
+  --body-light: #5C5779;
+  --muted-light: #555077;
+  --surface: #EBE8F8;
+  --track: #E9E6F5;
+  --divider: #E4E0F2;
+
+  /* 1 inch on the 10" canvas, in px. Set by preview.js from the zoom control. */
+  --in: 96px;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  padding: 28px 24px 64px;
+  background: #14121f;
+  color: #cfc9e6;
+  font-family: "Geist", system-ui, sans-serif;
+  font-size: 13px;
+}
+
+header {
+  position: sticky; top: 0; z-index: 20;
+  display: flex; align-items: center; gap: 16px; flex-wrap: wrap;
+  margin: -28px -24px 24px; padding: 12px 24px;
+  background: rgba(20, 18, 31, .92);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid #2a2540;
+}
+header h1 { margin: 0; font-family: "Geist SemiBold"; font-size: 14px; color: #fff; letter-spacing: .01em; }
+header .spacer { flex: 1; }
+header label { display: flex; align-items: center; gap: 6px; color: #9b93bd; font-size: 12px; cursor: pointer; }
+header input[type="range"] { width: 120px; accent-color: var(--accent); }
+
+.errors {
+  margin: 0 0 20px; padding: 10px 14px;
+  background: #3a1d2c; border: 1px solid #7a3050; border-radius: 8px;
+  color: #ffb3c8; font-size: 12px; white-space: pre-wrap;
+}
+.errors:empty { display: none; }
+
+.deck { display: flex; flex-direction: column; align-items: center; gap: 28px; }
+
+.slide-wrap { position: relative; }
+
+.slide {
+  position: relative;
+  width: calc(10 * var(--in));
+  height: calc(5.625 * var(--in));
+  overflow: hidden;
+  border-radius: 4px;
+  box-shadow: 0 8px 30px rgba(0,0,0,.45);
+}
+.slide.dark  { background: var(--bg-dark); }
+.slide.light { background: var(--bg-light); }
+
+.slide-no {
+  position: absolute; top: 0; left: calc(-1 * var(--in) * .52);
+  font-family: "Geist SemiBold"; font-size: 12px; color: #5d5680;
+}
+
+/* every traced shape is absolutely positioned in inches */
+.sh { position: absolute; }
+.sh.text { display: flex; white-space: pre-wrap; overflow: visible; }
+.sh.text > span { display: block; width: 100%; }
+
+.sh.rect      { border-radius: 0; }
+.sh.roundRect { border-radius: calc(var(--in) * .10); }
+.sh.ellipse   { border-radius: 50%; }
+
+.sh.image { object-fit: contain; }
+
+/* overflow flagging, driven by the same measurement the build uses */
+.slide.flag .sh.overflow { outline: 1.5px solid #ff5c8a; outline-offset: 1px; }
+.slide.flag .sh.overflow::after {
+  content: "▲"; position: absolute; top: -9px; right: -9px;
+  font-size: 10px; color: #ff5c8a;
+}
+
+/* the §1 layout rails, toggled on to check alignment */
+.grid-overlay { position: absolute; inset: 0; pointer-events: none; display: none; }
+.slide.grid .grid-overlay { display: block; }
+.grid-overlay i {
+  position: absolute; background: rgba(139,124,246,.38);
+}
+.grid-overlay i.v { top: 0; bottom: 0; width: 1px; }
+.grid-overlay i.h { left: 0; right: 0; height: 1px; }
+.grid-overlay i.hot { background: rgba(255,92,138,.55); }

package/preview/preview.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Wand deck preview</title>
+<link rel="stylesheet" href="preview.css">
+</head>
+<body>
+
+<header>
+  <h1 id="title">Wand deck preview</h1>
+  <div class="spacer"></div>
+  <label><input type="checkbox" id="flag" checked> flag overflow</label>
+  <label><input type="checkbox" id="grid"> §1 rails</label>
+  <label>zoom <input type="range" id="zoom" min="60" max="170" value="96"></label>
+</header>
+
+<pre class="errors" id="errors"></pre>
+<div class="deck" id="deck"></div>
+
+<script src="trace.js"></script>
+<script src="preview.js"></script>
+</body>
+</html>

package/preview/preview.js

@@ -0,0 +1,169 @@
+/* preview.js — render a shape trace to the DOM at the 10" x 5.625" grid.
+   Knows nothing about layouts: it draws whatever wand_kit recorded, so the
+   preview and the .pptx cannot disagree about geometry. */
+
+(function () {
+  const T = window.__WAND_TRACE__;
+  const deck = document.getElementById("deck");
+  const errBox = document.getElementById("errors");
+  const zoom = document.getElementById("zoom");
+  const flag = document.getElementById("flag");
+  const grid = document.getElementById("grid");
+
+  // @font-face lives here, not in preview.css: the path to the faces depends on
+  // where brand/ resolved, and CSS cannot be told. One source of truth.
+  const FACES = [
+    ["Geist", "Geist-Regular", 400, "normal"], ["Geist", "Geist-Bold", 700, "normal"],
+    ["Geist", "Geist-Italic", 400, "italic"], ["Geist", "Geist-BoldItalic", 700, "italic"],
+    ["Geist Medium", "Geist-Medium", 400, "normal"], ["Geist Medium", "Geist-MediumItalic", 400, "italic"],
+    ["Geist SemiBold", "Geist-SemiBold", 400, "normal"], ["Geist SemiBold", "Geist-SemiBoldItalic", 400, "italic"],
+    ["Geist ExtraBold", "Geist-ExtraBold", 400, "normal"], ["Geist ExtraBold", "Geist-ExtraBoldItalic", 400, "italic"],
+    ["Geist Light", "Geist-Light", 400, "normal"], ["Geist Light", "Geist-LightItalic", 400, "italic"],
+  ];
+  const base = T.fontsBase || "../fonts/";
+  document.head.appendChild(Object.assign(document.createElement("style"), {
+    textContent: FACES.map(([fam, file, w, st]) =>
+      `@font-face{font-family:"${fam}";src:url("${base}${file}.ttf");font-weight:${w};font-style:${st};}`).join("\n"),
+  }));
+
+  document.getElementById("title").textContent = T.title || "Wand deck preview";
+  if (T.errors && T.errors.length) errBox.textContent = T.errors.join("\n");
+
+  const inch = (v) => `calc(${v} * var(--in))`;
+  const hex = (c) => (typeof c === "string" ? "#" + c.replace(/^#/, "") : null);
+
+  /** pptxgenjs fill/line objects -> CSS */
+  function paint(el, o) {
+    if (o.fill && o.fill.color) {
+      const a = o.fill.transparency ? 1 - o.fill.transparency / 100 : 1;
+      el.style.background = a < 1 ? withAlpha(o.fill.color, a) : hex(o.fill.color);
+    }
+    if (o.line && o.line.width) {
+      const style = o.line.dashType === "dash" ? "dashed" : "solid";
+      el.style.border = `${o.line.width}px ${style} ${hex(o.line.color || "000000")}`;
+    }
+    if (o.rectRadius != null) el.style.borderRadius = inch(o.rectRadius);
+  }
+
+  function withAlpha(c, a) {
+    const h = c.replace(/^#/, "");
+    const n = parseInt(h, 16);
+    return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${a.toFixed(3)})`;
+  }
+
+  const ALIGN = { left: "flex-start", center: "center", right: "flex-end" };
+  const VALIGN = { top: "flex-start", middle: "center", bottom: "flex-end" };
+
+  function textEl(sh) {
+    const el = document.createElement("div");
+    el.className = "sh text";
+    const first = (sh.runs[0] && sh.runs[0].options) || {};
+    el.style.justifyContent = ALIGN[sh.align || "left"];
+    el.style.alignItems = VALIGN[sh.valign || "top"];
+    el.style.lineHeight = String(sh.lineSpacingMultiple || 1.2);
+    const span = document.createElement("span");
+    span.style.textAlign = sh.align || "left";
+
+    sh.runs.forEach((r) => {
+      const o = r.options || {};
+      const s = document.createElement("span");
+      s.textContent = r.text;
+      s.style.fontFamily = `"${o.fontFace || sh.fontFace || "Geist"}"`;
+      s.style.fontSize = inch((o.fontSize || sh.fontSize || 12) / 72);
+      s.style.color = hex(o.color || sh.color || "000000");
+      if (o.bold ?? sh.bold) s.style.fontWeight = "700";
+      if (o.italic ?? sh.italic) s.style.fontStyle = "italic";
+      span.appendChild(s);
+      if (o.breakLine) span.appendChild(document.createElement("br"));
+      if (o.bullet) { s.textContent = "▪ " + r.text; s.style.display = "block"; }
+    });
+    el.appendChild(span);
+    el.dataset.size = String(first.fontSize || sh.fontSize || 12);
+    return el;
+  }
+
+  function render() {
+    deck.innerHTML = "";
+    T.slides.forEach((sl) => {
+      const wrap = document.createElement("div");
+      wrap.className = "slide-wrap";
+
+      const no = document.createElement("div");
+      no.className = "slide-no";
+      no.textContent = String(sl.index).padStart(2, "0");
+      wrap.appendChild(no);
+
+      const s = document.createElement("div");
+      const bg = sl.background && sl.background.color;
+      s.className = "slide " + (bg && bg.toUpperCase() === "0F0C26" ? "dark" : "light");
+      if (flag.checked) s.classList.add("flag");
+      if (grid.checked) s.classList.add("grid");
+      s.title = sl.layout;
+
+      sl.shapes.forEach((sh) => {
+        let el;
+        if (sh.kind === "image") {
+          el = document.createElement("img");
+          el.className = "sh image";
+          // a named glyph arrives as an inline data URI, a legacy PNG as a path
+          el.src = sh.data ? "data:" + sh.data
+                 : sh.path ? (T.assetsBase || "../assets/") + sh.path.split(/[\\/]assets[\\/]/).pop()
+                 : "";
+        } else if (sh.kind === "text") {
+          el = textEl(sh);
+        } else {
+          el = document.createElement("div");
+          el.className = "sh " + (sh.type || "rect");
+          paint(el, sh);
+        }
+        el.style.left = inch(sh.x || 0);
+        el.style.top = inch(sh.y || 0);
+        el.style.width = inch(sh.w || 0);
+        el.style.height = inch(sh.h || 0);
+        if (sh.kind === "text" && sh.margin === 0) el.style.padding = "0";
+        s.appendChild(el);
+      });
+
+      // §1 rails
+      const g = document.createElement("div");
+      g.className = "grid-overlay";
+      [[0.37, 1], [9.62, 1], [3.58, 0], [6.78, 0]].forEach(([x, hot]) => {
+        const i = document.createElement("i");
+        i.className = "v" + (hot ? " hot" : "");
+        i.style.left = inch(x); g.appendChild(i);
+      });
+      [[0.62, 1], [1.60, 0], [5.05, 1], [5.21, 0]].forEach(([y, hot]) => {
+        const i = document.createElement("i");
+        i.className = "h" + (hot ? " hot" : "");
+        i.style.top = inch(y); g.appendChild(i);
+      });
+      s.appendChild(g);
+
+      wrap.appendChild(s);
+      deck.appendChild(wrap);
+      if (flag.checked) markOverflow(s);
+    });
+  }
+
+  /** Browser-side overflow detection: does the laid-out text exceed its box? */
+  function markOverflow(slideEl) {
+    slideEl.querySelectorAll(".sh.text").forEach((el) => {
+      const span = el.firstElementChild;
+      if (!span) return;
+      if (span.scrollHeight - el.clientHeight > 1.5 || span.scrollWidth - el.clientWidth > 1.5) {
+        el.classList.add("overflow");
+      }
+    });
+  }
+
+  function setZoom() {
+    document.documentElement.style.setProperty("--in", zoom.value + "px");
+    if (flag.checked) document.querySelectorAll(".slide").forEach(markOverflow);
+  }
+
+  zoom.addEventListener("input", setZoom);
+  flag.addEventListener("change", render);
+  grid.addEventListener("change", render);
+  setZoom();
+  render();
+})();

package/qa_coverage.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+qa_coverage.py — makes "faithful = verbatim" enforceable instead of aspirational.
+
+    python qa_coverage.py visible_dump.txt output.pptx [--min 4] [--json report.json]
+
+Reads every string from the Phase 1 verbatim dump, reads every string out of the
+built deck, and reports what didn't make it. Exit 1 if anything is missing, so it
+can gate a build.
+
+Matching is whitespace- and case-normalised, and normalises the typographic
+characters that get swapped in transit (curly quotes, dashes, non-breaking
+spaces). It is deliberately NOT fuzzy beyond that: a string that was reworded is
+supposed to fail.
+"""
+
+import argparse, json, os, re, sys, unicodedata, zipfile
+
+def _brand_lib():
+    """brand/lib in the repo, or lib/ beside the kit once packaged."""
+    import os
+    here = os.path.dirname(os.path.abspath(__file__))
+    for d in filter(None, [os.environ.get("WAND_BRAND_DIR"),
+                           os.path.join(here, "lib"),
+                           os.path.join(here, "..", "lib"),
+                           os.path.join(here, "..", "..", "..", "..", "brand", "lib"),
+                           os.path.join(here, "..", "..", "..", "brand", "lib")]):
+        if os.path.isfile(os.path.join(d, "wandxml.py")):
+            return os.path.normpath(d)
+    raise SystemExit("brand/lib not found")
+
+sys.path.insert(0, _brand_lib())
+import wandxml
+
+TRANS = str.maketrans({
+    "\u2018": "'", "\u2019": "'", "\u201c": '"', "\u201d": '"',
+    "\u2013": "-", "\u2014": "-", "\u2212": "-", "\u00a0": " ",
+    "\u2026": "...", "\u00b7": "·",
+})
+
+
+def norm(s):
+    s = unicodedata.normalize("NFKC", s).translate(TRANS)
+    return re.sub(r"\s+", " ", s).strip().lower()
+
+
+def strings_from_pptx(path):
+    out = []
+    with zipfile.ZipFile(path) as z:
+        names = sorted((n for n in z.namelist()
+                        if re.fullmatch(r"ppt/slides/slide\d+\.xml", n)),
+                       key=lambda n: int(re.findall(r"\d+", n)[0]))
+        for i, n in enumerate(names, 1):
+            doc = wandxml.parse(z.read(n))
+            for sp in doc.getElementsByTagName("p:txBody"):
+                # join runs within a paragraph, paragraphs with a space — a line
+                # break in the deck is a space in the source string
+                paras = []
+                for p in sp.getElementsByTagName("a:p"):
+                    runs = [t.firstChild.nodeValue for t in p.getElementsByTagName("a:t") if t.firstChild]
+                    if runs:
+                        paras.append("".join(runs))
+                if paras:
+                    out.append((i, " ".join(paras)))
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("dump")
+    ap.add_argument("pptx")
+    ap.add_argument("--min", type=int, default=4,
+                    help="ignore source strings shorter than this (default 4)")
+    ap.add_argument("--json")
+    a = ap.parse_args()
+
+    source = [l.rstrip("\n") for l in open(a.dump, encoding="utf-8")]
+    short = [s for s in source if 0 < len(s.strip()) < a.min]
+    source = [s for s in source if len(s.strip()) >= a.min]
+
+    built = strings_from_pptx(a.pptx)
+    haystack = norm(" \u241e ".join(t for _, t in built))
+    per_slide = [(i, norm(t)) for i, t in built]
+
+    missing, found = [], []
+    for s in source:
+        n = norm(s)
+        if not n:
+            continue
+        if n in haystack:
+            where = next((i for i, t in per_slide if n in t), None)
+            found.append((s, where))
+        else:
+            missing.append(s)
+
+    total = len(found) + len(missing)
+    pct = (100.0 * len(found) / total) if total else 100.0
+    print(f"coverage: {len(found)}/{total} strings ({pct:.1f}%)  across {len(set(i for i,_ in built))} slides")
+    if short:
+        # Say this out loud. Stat values and ordinals are often 1-3 characters,
+        # so a silent length filter is a coverage number that flatters itself.
+        missed = [s for s in short if norm(s) not in haystack]
+        print(f"          {len(short)} string(s) under {a.min} chars not compared" +
+              (f" - {len(missed)} of them are absent from the deck: " +
+               ", ".join(repr(s.strip()) for s in missed[:8]) if missed else " - all present anyway"))
+
+    if missing:
+        print(f"\nMISSING ({len(missing)}) — each must land on a slide or be listed in the Review Note:")
+        for s in missing:
+            print("   ·", s[:110] + ("…" if len(s) > 110 else ""))
+
+    if a.json:
+        json.dump({"total": total, "found": len(found), "missing": missing},
+                  open(a.json, "w"), indent=2, ensure_ascii=False)
+
+    sys.exit(1 if missing else 0)
+
+
+if __name__ == "__main__":
+    main()

package/requirements.txt

@@ -0,0 +1,9 @@
+# Optional. The kit runs with nothing installed.
+#
+# pylib/wandxml.py falls back to stdlib xml.dom.minidom, and pylib/ttf.py reads
+# and rewrites the font tables embed_fonts.py needs without fontTools. Install
+# these only if you want the hardened XML parser or are working on the font code.
+#
+#   pip install -r requirements.txt
+defusedxml>=0.7      # tools/extract.py, qa_coverage.py - entity-safe XML
+fonttools>=4.50      # cross-checking pylib/ttf.py output