wand-decks-kit 0.8.0

package/docs/PIPELINE.md

@@ -0,0 +1,116 @@
+# Pipeline
+
+The §6 phases, as commands. Two of them do everything; the rest exist so a
+failed stage can be re-run on its own.
+
+```bash
+node wand.js doctor                  # before anything: what works in this container
+node wand.js rebuild source.pptx     # phases 0-3
+# ... you write work/deck.json ...
+node wand.js ship work/deck.json     # phases 4-6, every gate, one table at the end
+```
+
+## 0–1 · Normalize and extract — `rebuild`, stage 1
+
+Reports the source canvas and the scale factor onto the 10" grid; most decks are
+13.333" × 7.5" and need ×0.75. Writes into `work/`:
+
+| File | What |
+|---|---|
+| `visible_dump.txt` | every verbatim string — the contract coverage checks against |
+| `all_text.json` | per-slide, per-frame, per-paragraph structure |
+| `geometry.txt` | every shape, normalised to the Wand grid |
+| `analysis.json` | text frames with box, point size and weight, plus the slide background |
+| `deck.skeleton.json` | one entry per visible slide, `layout: "TODO"` |
+
+Standalone: `node wand.js extract source.pptx -o work/`
+
+## 2–3 · Classify and map — `rebuild`, stage 2
+
+Writes `work/PLAN.md`. Per slide: how many cards in how many columns over how
+many bands, the tag / title / subtitle already identified by point size, a
+shortlist of layouts with the reason for each, every verbatim string grouped by
+frame, and a stub carrying the top candidate's required fields with the theme
+read off the source background.
+
+The shortlist is ranked by **shape**. It cannot see meaning, and §6 Phase 3
+orders on meaning — structural first, then quotes, timelines, data, comparisons,
+stacks, assertions, numbered asks, and only then item count. Overrule it freely.
+
+Emit the mapping plan before writing any JSON:
+
+```
+S07 (timeline, 6 phases + trajectory band) → phaseCards-D
+```
+
+Standalone: `node wand.js plan work/`
+
+## 4 · Build — `ship`, stages 1–4
+
+```
+1 spec          fields, types, and item counts against the layout catalog
+2 fit           every text box measured in real Geist
+  bounds        every shape inside the content band
+  asset         every glyph and image the spec names actually exists
+3 build         .pptx
+4 embed fonts   required (§7). Without it the deck renders as Arial
+```
+
+Iterate in the browser rather than round-tripping the file:
+
+```bash
+node wand.js preview work/deck.json    # then open preview/preview.html
+```
+
+The preview renders the same recorded geometry the `.pptx` gets, in real Geist,
+with overflow flagging and the §1 rails as a toggle.
+
+`node wand.js layouts <name>` prints any layout's fields when you are writing the
+spec; `node wand.js validate work/deck.json` checks them before you build.
+
+## 5 · Review note
+
+Markdown, slide-numbered. Every split or merge, every fallback mapping, anything
+tight after fitting, anything off-brand you couldn't rebrand, **everything
+dropped from the verbatim dump**, and any place a reference deck and the spec
+disagreed.
+
+## 6 · QA — `ship`, stages 5–7
+
+```
+5 coverage      every source string present, and how many were too short to compare
+6 file          parts, relationships, embedded and unsubsetted fonts
+7 visual        the preview — the only gate that sees a slide that is merely ugly
+```
+
+`ship` prints a gate table and exits non-zero if any of them failed.
+
+If LibreOffice is installed you can also render:
+
+```bash
+soffice --headless --convert-to pdf work/deck.pptx
+pdftoppm -jpeg -r 150 deck.pdf slide
+```
+
+Plus the subset check — empty output is a pass:
+
+```bash
+python3 -c "import subprocess; t=subprocess.run(['pdftotext','deck.pdf','-'],capture_output=True,text=True).stdout; print([c for c in t if 0x01C9<=ord(c)<=0x024F] or 'clean')"
+```
+
+Deliver the `.pptx` first, then the review note.
+
+## What QA can and can't tell you
+
+LibreOffice ignores embedded fonts and substitutes DejaVu. So:
+
+- **Don't trust it on fit.** DejaVu is wider than Geist, so renders over-report
+  overflow. Use the fit check, which measures the real face.
+- **Don't trust it on weight.** `Geist ExtraBold` renders regular. Verify the
+  accent-italic device and any hierarchy question in the XML or the preview.
+- **Do trust it on** geometry, overlap, alignment, gaps, contrast, leftover
+  placeholders, orphaned decoration, mispositioned art.
+
+And when it isn't installed at all — which is the normal case in a fresh
+container — the browser preview covers everything in that last list, in the real
+faces, which LibreOffice cannot do.

package/docs/SPEC.md

@@ -0,0 +1,89 @@
+# Deck spec format
+
+A deck is data. `build.js` turns a spec into a `.pptx`; `--preview` turns the
+same spec into a browser preview. Neither re-implements the other, so they can't
+disagree.
+
+```bash
+node wand.js validate deck.json      # fields, types, item counts. Run this first
+node wand.js layouts numberedCards   # what a layout takes, with the caps
+node wand.js check    deck.json      # fit, bounds and assets. Exit 1 on any
+node wand.js preview  deck.json      # write preview/trace.js, then open preview/preview.html
+node wand.js ship     deck.json      # every gate, then the .pptx
+```
+
+`lib/schema.js` is the machine-readable version of this document: every layout's
+fields, their types, and the number of items it can actually draw. `validate`,
+`layouts` and the `plan` worksheet all read it, so they cannot drift from each
+other. If a layout gains a field, it goes there.
+
+## Shape
+
+```json
+{
+  "deck": "WAND × ACME",
+  "confidential": "CONFIDENTIAL",
+  "slides": [
+    { "layout": "cover",  "eyebrow": "...", "titleLines": ["...", "..."] },
+    { "layout": "rows",   "dark": true, "tag": "THE FULL STACK", "items": [] }
+  ]
+}
+```
+
+`deck` and `confidential` fill the footer and can be overridden per slide.
+Page numbers are computed — never write them into a spec.
+
+Full-bleed layouts (`cover`, `divider`, `closing`) get no footer automatically.
+
+## Every slide takes
+
+| Key | Meaning |
+|---|---|
+| `layout` | required — a function name exported by `wand_kit.js` |
+| `tag` | the caps label top-left |
+| `dark` | `true` dark theme, `false` light. Alternate across the deck |
+| `titleText` | string, or `["before ", "accent phrase", " after"]` for the accent-italic device |
+| `subtitleText` | the lede under the title |
+
+Everything else is layout-specific — see `docs/LAYOUTS.md`, or run
+`node wand.js layouts <name>`, which prints the same thing from the schema and
+marks the required fields.
+
+## Item caps are enforced
+
+Every layout slices its items to what it can draw. A 7th item on a `sixUpIcon`
+used to vanish silently and turn up as a coverage miss three steps later;
+`validate` now fails on it, and says how many would have been dropped.
+
+## The accent-italic device
+
+```json
+"titleText": ["Two kinds of colleagues. ", "One set of drives", "."]
+```
+
+Element 1 renders accent + italic. The trailing period stays in ink. One per
+title, never two. A plain string is fine when a title needs no emphasis.
+
+## Line breaks
+
+Use `\n` inside a title or caption where the source deck breaks a line. The kit
+splits on it and carries the break explicitly — an embedded newline used to
+push every following run onto its own line.
+
+## What the spec deliberately cannot do
+
+No coordinates, no colours, no font sizes. If a slide needs geometry the
+layouts don't provide, add a layout — don't leak positioning into content.
+That separation is what makes a rebuild reviewable: the spec diffs against the
+source's verbatim text, and the layout diffs against the design system.
+
+## Starting from a source deck
+
+```bash
+node wand.js rebuild source.pptx
+```
+
+writes `work/PLAN.md` — the worksheet you fill in. Per slide it carries the
+source's shape, a layout shortlist with reasons, every verbatim string grouped
+by frame, and a stub with the top candidate's required fields already present.
+Choose the layout by §6 Phase 3, transcribe the text, `validate`, `ship`.

package/embed_fonts.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+embed_fonts.py — embed the five Geist families into a .pptx, unsubsetted.
+
+    python embed_fonts.py deck.pptx [-o out.pptx] [--fonts DIR]
+
+Why this exists: a Geist deck without embedded fonts renders as Arial on the
+client's machine. Spec §7.
+
+Two things this does that the reference decks get wrong:
+  * writes UNCOMPRESSED EOT and sets saveSubsetFonts="0", so digits don't
+    garble in exported PDFs (spec §9)
+  * ships full faces, not subsets
+
+The .fntdata part is an EOT (Embedded OpenType) container — magic 0x504C,
+version 2.1, TTCOMPRESSED flag clear, raw TTF appended.
+"""
+
+import argparse, os, re, shutil, struct, sys, tempfile, 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 ttf as _ttf
+
+# family -> (regular, bold, italic, boldItalic) source stems
+FAMILIES = {
+    "Geist":            ("Geist-Regular",   "Geist-Bold",       "Geist-Italic",         "Geist-BoldItalic"),
+    "Geist Medium":     ("Geist-Medium",    "Geist-SemiBold",   "Geist-MediumItalic",   "Geist-SemiBoldItalic"),
+    "Geist SemiBold":   ("Geist-SemiBold",  "Geist-ExtraBold",  "Geist-SemiBoldItalic", "Geist-ExtraBoldItalic"),
+    "Geist ExtraBold":  ("Geist-ExtraBold", "Geist-ExtraBold",  "Geist-ExtraBoldItalic","Geist-ExtraBoldItalic"),
+    "Geist Light":      ("Geist-Light",     "Geist-Medium",     "Geist-LightItalic",    "Geist-MediumItalic"),
+}
+FACES = ("regular", "bold", "italic", "boldItalic")
+
+NS_R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+REL_FONT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font"
+
+
+def retag(ttf_path, family, italic):
+    """Rewrite the TTF name table so its family matches the name used in the XML.
+
+    Weight is carried by the family name in this system, so all five families
+    must report distinct names or PowerPoint collapses them onto one face.
+    """
+    f = _ttf.load(ttf_path)
+    sub = "Italic" if italic else "Regular"
+    full = f"{family} Italic" if italic else family
+    data = f.retagged(family, sub, full, full.replace(" ", ""))
+    return data, _ttf.TTF(data)
+
+
+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", 0x0000, 0x504C)       # fsType(installable), 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 brand_dir(name):
+    """Locate the shared brand payload. Bundled beside the kit when packaged,
+    at the repo root when running from the repo. WAND_BRAND_DIR overrides."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    for d in filter(None, [os.environ.get("WAND_BRAND_DIR"),
+                           here,
+                           os.path.join(here, "..", "..", "..", "brand")]):
+        p = os.path.join(d, name)
+        # prove it is the brand payload, not a directory that shares its name
+        if os.path.isdir(p) and (name != "fonts" or os.path.isfile(os.path.join(p, "Geist-Regular.ttf"))):
+            return os.path.normpath(p)
+    raise SystemExit(f"brand/{name} not found")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("pptx")
+    ap.add_argument("-o", "--out")
+    ap.add_argument("--fonts", default=None)
+    ap.add_argument("--spec", help="carry this spec inside the deck, so the deck can be edited later "
+                                   "without the spec having to travel beside it")
+    a = ap.parse_args()
+    fonts = a.fonts or brand_dir("fonts")
+    out = a.out or a.pptx
+
+    work = tempfile.mkdtemp()
+    with zipfile.ZipFile(a.pptx) 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, font_lst, made = [], [], 0
+    for family, stems in FAMILIES.items():
+        entries = []
+        for face, stem in zip(FACES, stems):
+            src = os.path.join(fonts, stem + ".ttf")
+            if not os.path.exists(src):
+                print(f"  ! missing {stem}.ttf — skipping {family}/{face}", file=sys.stderr)
+                continue
+            italic = "italic" in face.lower()
+            data, font = retag(src, family, italic)
+            name = f"{family.replace(' ', '')}-{face}.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:{face} r:id="{rid}"/>')
+            made += 1
+        if entries:
+            font_lst.append(
+                f'<p:embeddedFont><p:font typeface="{family}" pitchFamily="34" charset="0"/>'
+                + "".join(entries) + "</p:embeddedFont>")
+
+    rels = rels.replace("</Relationships>", "".join(new_rels) + "</Relationships>")
+    open(rels_path, "w", encoding="utf-8").write(rels)
+
+    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)
+    if "<p:embeddedFontLst" not in p:
+        block = "<p:embeddedFontLst>" + "".join(font_lst) + "</p:embeddedFontLst>"
+        # 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()] + block + p[anchor.end():]
+    open(p_path, "w", encoding="utf-8").write(p)
+
+    if os.path.exists(out):
+        os.remove(out)
+    zf = zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED)
+    for root, _, files in os.walk(work):
+        for fn in files:
+            full = os.path.join(root, fn)
+            zf.write(full, os.path.relpath(full, work))
+    # A deck that carries its own spec can be edited a month later by someone
+    # who has only the .pptx. PowerPoint ignores parts it does not know about.
+    if a.spec and os.path.exists(a.spec):
+        zf.writestr("wand/spec.json", open(a.spec, "rb").read())
+    zf.close()
+    shutil.rmtree(work)
+    print(f"embedded {made} faces across {len(font_lst)} families{' + spec' if a.spec and os.path.exists(a.spec) else ''} -> {out}")
+
+
+if __name__ == "__main__":
+    main()

package/examples/template.json

@@ -0,0 +1,164 @@
+{
+  "deck": "WAND TEMPLATE",
+  "confidential": "TEMPLATE",
+  "slides": [
+    { "layout": "cover", "eyebrow": "REPLACE THIS EYEBROW",
+      "titleLines": ["Your headline here.", "One line per line."],
+      "body": "The cover takes an eyebrow, up to three title lines, a body paragraph and a kicker. The title shrinks itself if it runs long.",
+      "kickerPlain": "Delete what you don't need. ", "kickerBold": "Keep the structure." },
+
+    { "layout": "divider", "tag": "SECTION", "eyebrow": "Use a divider between sections",
+      "titleText": ["One idea. ", "Stated plainly", "."],
+      "body": "Dividers carry a tag, an eyebrow, one big line and a paragraph. They have no footer and no page number." },
+
+    { "layout": "numberedList", "tag": "AGENDA", "dark": true,
+      "titleText": ["What we'll ", "cover", "."],
+      "subtitleText": "numberedList is the agenda and the ask. Up to six rows, numbered for you.",
+      "items": [
+        { "title": "Where you are today", "body": "One sentence of context per row. The number is drawn automatically." },
+        { "title": "What changes", "body": "Keep rows parallel in length — the layout reads best when they are." },
+        { "title": "What it takes", "body": "Six rows is the maximum. Past that, split the slide." },
+        { "title": "What happens next", "body": "The closing lines and sign-off below are both optional." }
+      ],
+      "closing": { "line1": "One line to close.", "line2": "One more if you need it." },
+      "signoff": "A sign-off sits at the very bottom." },
+
+    { "layout": "threeUp", "tag": "THREE THINGS", "dark": false, "arrows": true,
+      "titleText": ["Three comparable things. ", "One of them yours", "."],
+      "subtitleText": "threeUp is for three options, three stages, or three audiences. Set arrows: true when it is a progression.",
+      "items": [
+        { "eyebrow": "TODAY", "title": "The status quo", "pill": "where most people are", "body": "Each card takes an eyebrow, a title, a pill and a body." },
+        { "eyebrow": "THE SHIFT", "title": "What you propose", "pill": "the recommendation", "emph": true, "body": "Exactly one card per slide can be the emphasis card. Set emph: true on it." },
+        { "eyebrow": "THE HORIZON", "title": "Where it leads", "pill": "the end state", "body": "Keep the three bodies roughly the same length." }
+      ] },
+
+    { "layout": "sixUpIcon", "tag": "CAPABILITIES", "dark": true,
+      "titleText": ["Six things, ", "evenly weighted", "."],
+      "subtitleText": "sixUpIcon is for features or capabilities. Icons are named — run `node wand.js glyphs` for the list.",
+      "items": [
+        { "icon": "shield-check", "title": "Named icons", "body": "Say icon: \"shield-check\", not a filename. They recolour to the theme.", "note": "75 to choose from" },
+        { "icon": "users", "title": "The note line", "body": "Each card can carry a small accent line under the body — a target, a figure, a date.", "note": "Optional" },
+        { "icon": "network", "title": "Four to six", "body": "Fewer than four looks sparse; the layout draws at most six." },
+        { "icon": "gauge", "title": "Keep bodies short", "body": "Two lines each is the sweet spot. Longer text shrinks to fit, which reads as an accident." },
+        { "icon": "workflow", "title": "Don't repeat it", "body": "Three sixUpIcon slides in a row is a failure even if each one is correct." },
+        { "icon": "sparkles", "title": "Vary the layouts", "body": "Across fifteen slides, aim for at least eight distinct ones." }
+      ] },
+
+    { "layout": "statGrid", "tag": "THE NUMBERS", "dark": false,
+      "titleText": ["Figures, ", "not adjectives", "."],
+      "subtitleText": "statGrid holds three to six figures. statQuad does four larger ones; heroQuad leads with a single headline number.",
+      "items": [
+        { "value": "60%", "label": "The headline figure", "caption": "value, label and caption", "emph": true },
+        { "value": "2×", "label": "Second figure", "caption": "One card can be the emphasis card" },
+        { "value": "13 wks", "label": "Third figure", "caption": "Keep captions to one line" },
+        { "value": "$1.2M", "label": "Fourth figure", "caption": "Currency and units read fine" },
+        { "value": "30+", "label": "Fifth figure", "caption": "Six is the maximum" },
+        { "value": "24/7", "label": "Sixth figure", "caption": "Cut to four if any caption wraps" }
+      ],
+      "footnote": "A footnote line sits under the grid. Use it for the source." },
+
+    { "layout": "colCards", "tag": "THE LAYERS", "dark": true,
+      "titleText": ["Two or three things, ", "each with a list", "."],
+      "items": [
+        { "eyebrow": "Layer 01", "title": "Prose and bullets", "sub": "colCards carries both",
+          "body": "Use colCards when each of two or three things needs a paragraph and a list. The body is optional — drop it and the bullets take the room.",
+          "bullets": ["Up to five bullets", "Keep them short", "They shrink to fit", "Parallel phrasing reads best"] },
+        { "eyebrow": "Layer 02", "title": "Keep them parallel", "sub": "same shape, same length",
+          "body": "Three columns of very different lengths is the most common way this layout goes wrong.",
+          "bullets": ["Same number of bullets", "Same rough length", "Same grammatical form"] },
+        { "eyebrow": "Layer 03", "title": "Three is the maximum", "sub": "past that, use a grid",
+          "body": "For four or more categories, matrixGrid or stripGrid will hold them properly.",
+          "bullets": ["matrixGrid: 4 x 3 cells", "stripGrid: figures over columns", "compareGrid: 3 columns x 6 rows"] }
+      ] },
+
+    { "layout": "phaseCards", "tag": "ROADMAP", "dark": false,
+      "titleText": ["A plan in ", "four steps", "."],
+      "subtitleText": "phaseCards is the roadmap layout. Card one is the emphasis card.",
+      "phases": [
+        { "period": "Weeks 1–4", "title": "Foundation", "bullets": ["A period, a title and up to five bullets", "Keep bullets to one line each"] },
+        { "period": "Months 2–6", "title": "First results", "bullets": ["Four cards is the maximum", "Three reads well too"] },
+        { "period": "Months 6–12", "title": "Scale", "bullets": ["Name the outcome, not the activity", "Dates beat adjectives"] },
+        { "period": "Year 2", "title": "Steady state", "bullets": ["End on what changes for them", "Not on what you deliver"] }
+      ] },
+
+    { "layout": "splitPanel", "tag": "THE ARGUMENT", "dark": true,
+      "titleText": ["Half argument, ", "half evidence", "."],
+      "subtitleText": "splitPanel puts the claim on the left and the proof on the right.",
+      "left": { "eyebrow": "THE CLAIM", "heading": "State it in one line.",
+        "body": "The left panel is the emphasis card: an eyebrow, a heading, a paragraph and an optional note. Use it for the argument you want remembered.",
+        "note": "The note is italic and accented — good for a consequence or a result." },
+      "right": { "eyebrow": "THE EVIDENCE", "heading": "Up to four supporting rows",
+        "items": [
+          { "label": "Label and body", "body": "render as one line, so the source reads exactly as written." },
+          { "label": "Or no label", "body": "Leave it out and the row is a single sentence." },
+          { "body": "Like this one — body only, no label." },
+          { "label": "Four is the maximum", "body": "A fifth row will be refused by validate rather than silently dropped." }
+        ] } },
+
+    { "layout": "compareGrid", "tag": "BEFORE AND AFTER", "dark": false,
+      "titleText": ["A comparison ", "wider than two columns", "."],
+      "subtitleText": "compareGrid does up to three headed columns over six labelled rows. The last column is yours and is tinted.",
+      "heads": ["TODAY", "WITH YOU", "WHY ONLY YOU"],
+      "rows": [
+        { "label": "Speed", "cells": [{ "body": "The status quo, stated plainly and without strawmanning it." }, { "lead": "The improvement.", "body": "A short second line if it helps." }, { "body": "The reason nobody else can claim it." }] },
+        { "label": "Cost", "cells": [{ "body": "Keep every cell to roughly the same length." }, { "lead": "The number.", "body": "Lead with it." }, { "body": "The structural reason, not the feature." }] },
+        { "label": "Risk", "cells": [{ "body": "Six rows is the maximum." }, { "lead": "What changes." }, { "body": "Two columns work too — drop a head and a cell." }] }
+      ] },
+
+    { "layout": "stripGrid", "tag": "THE YEAR", "dark": true,
+      "titleText": ["Figures over ", "a column grid", "."],
+      "subtitleText": "stripGrid is the densest layout here: a strip of figures, a statement, a column grid and a closing band — all optional except the geometry.",
+      "stats": [
+        { "value": "8%", "label": "First metric" }, { "value": "12%", "label": "Second" },
+        { "value": "8K", "label": "Third" }, { "value": "30%", "label": "Fourth" },
+        { "value": "18%", "label": "Fifth" }, { "value": "25%", "label": "Sixth" }
+      ],
+      "columns": [
+        { "label": "WHAT YOU DELIVER", "items": [
+          { "body": "Up to six rows per column, up to four columns." },
+          { "body": "A row can be a body alone, or a title plus a body." },
+          { "body": "Everything measures itself and shrinks to fit." } ] },
+        { "label": "WHAT THEY COMMIT", "items": [
+          { "body": "Use two columns for a delivers/commits split." },
+          { "body": "Three or four for categories." },
+          { "body": "One wide column for a single block of prose." } ] }
+      ] },
+
+    { "layout": "archStack", "tag": "ARCHITECTURE", "dark": false,
+      "titleText": ["One layer ", "above the rest", "."],
+      "subtitleText": "archStack is the platform slide: who sits on top, what you provide in the middle, what it governs below.",
+      "top": { "label": "THE PEOPLE ON TOP", "body": "Who uses it, and what they see" },
+      "middle": { "label": "YOUR LAYER — what it does",
+        "modules": [
+          { "title": "Module one", "body": "Up to six modules. The band grows to fit the longest one." },
+          { "title": "Module two", "body": "Keep the bodies short and parallel." },
+          { "title": "Module three", "body": "Leave modules empty and the band becomes a connector line." },
+          { "title": "Module four", "body": "A note line can sit under the row." }
+        ] },
+      "note": "An optional note line sits between the modules and the systems below.",
+      "sources": { "eyebrow": "WHAT IT GOVERNS", "cards": [
+        { "title": "System one", "body": "ours: true is a first-party card", "ours": true },
+        { "title": "System two", "body": "ours: false gets the dashed treatment", "ours": false } ] },
+      "outcome": "THE OUTCOME BAND  •  ONE LINE  •  ALL CAPS READS BEST HERE" },
+
+    { "layout": "logoBands", "tag": "PROOF", "dark": true,
+      "titleText": ["Figures over ", "names", "."],
+      "subtitleText": "logoBands is the proof slide: a few figures, then rows of customer or investor names.",
+      "stats": [
+        { "value": "$120M+", "caption": "A figure and\na two-line caption" },
+        { "value": ">$1B", "caption": "Up to four\nfigures" },
+        { "value": "80+", "caption": "Keep the captions\nparallel" },
+        { "value": "3", "caption": "Offices, markets,\nwhatever counts" }
+      ],
+      "bands": [
+        { "label": "CUSTOMERS", "names": "Name  •  Name  •  Name  •  Name  •  Name  •  Name",
+          "note": "A note under the row is optional." },
+        { "label": "INVESTORS", "names": "Name  •  Name  •  Name  •  Name  •  Name" }
+      ] },
+
+    { "layout": "closing", "eyebrow": "THE CLOSE",
+      "line1": "The last thing they read.", "line2": "Make it the ask.",
+      "body": "closing is centred and full bleed, with no footer. Two lines, a paragraph and a URL.",
+      "url": "wand.ai" }
+  ]
+}

package/lib/README.md

@@ -0,0 +1,23 @@
+# Shared libraries
+
+Code that is about the *brand payload* rather than about any one output format,
+so decks and docs cannot drift apart on it.
+
+| | |
+|---|---|
+| `measure.js` | Real Geist metrics via fontkit. Fit is measured, never guessed |
+| `glyphs.js` | The named Lucide set, recoloured per theme |
+| `pdf.js` | A PDF writer — embedded TrueType, paths, images. Both kits render PDF |
+| `ttf.py` | The 1% of TrueType `embed_fonts.py` needs, without fontTools |
+| `wandxml.py` | XML parsing that works with nothing installed |
+
+Each kit keeps its own `lib/brand.js` — that one *is* kit-local, because it
+resolves paths relative to the kit — and reaches these through it:
+
+```js
+const brand = require("./brand");
+const M = require(path.join(brand.resolve("lib"), "measure.js"));
+```
+
+`tools/package.mjs` copies this directory into every zip, so a packaged kit
+still resolves everything locally.