wand-decks-kit 0.8.0 → 0.8.2

package/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: wand-decks
+description: Rebrand, merge, edit or author a PowerPoint deck on the Wand design system. Use when a .pptx is attached for restyling, or a deck is wanted from a brief. Outputs a client-ready .pptx and QA gates.
+compatibility: Requires Node.js 18+ and code execution enabled in claude.ai (Settings > Features). No network access needed - dependencies are bundled. Python 3 is used to read a source .pptx and to embed fonts; without it the kit can still author and check a deck, but the output will render in Arial on machines without Geist.
+license: Proprietary - Wand AI
+metadata:
+  version: "0.7.0"
+---
+
+
+# Wand decks
+
+## First: find the kit and stand in it
+
+This file ships inside the kit, so if you are reading it you are close. The kit
+arrives one of three ways — work out which, then `cd` into the kit's folder and
+run everything from there:
+
+1. **Installed from npm** (the usual way): it is at `node_modules/wand-decks-kit/`.
+   If it is not there yet: `npm install wand-decks-kit@latest --no-audit --no-fund`.
+2. **Attached to the chat as a zip**: unzip it and enter the folder it makes.
+3. **You are already inside it**: `wand.js` is next to this file.
+
+Then confirm the ground you are standing on:
+
+```bash
+node wand.js doctor
+```
+
+If none of the three work — npm unreachable, nothing attached — **stop and say
+so, and ask the user to attach the kit zip.** Never improvise a deck, and never
+report checks you did not run; the gates are the only reason to trust the
+output.
+
+Every path below is relative to the kit folder.
+
+A deck engine: 28 layouts, real font metrics, embedded Geist, and six gates that
+each catch something the others cannot.
+
+**Read `PROMPT.md` before making any design decision.** It is the source of
+truth on canvas, colour, type, layout choice and content rules. This file is
+only the operating procedure.
+
+## Available scripts
+
+- **`wand.js`** — the front door - doctor, rebuild, layouts, glyphs, validate, check, preview, ship, spec, inspect
+- **`build.js`** — spec -> .pptx, or --check, or --preview
+- **`tools/extract.py`** — read a source deck: verbatim dump, geometry, analysis
+- **`embed_fonts.py`** — embed Geist unsubsetted, and carry the spec inside the deck
+- **`qa_coverage.py`** — diff the verbatim dump against the built deck
+
+## Setup
+
+None beyond the doctor check above. Dependencies come with the package —
+npm resolves them on install, and the zip carries them vendored.
+
+
+```bash
+node wand.js doctor
+```
+
+If `node_modules` is somehow missing, `npm install` in this directory.
+
+## The four jobs
+
+### Rebrand a deck they attached
+
+```bash
+node wand.js rebuild <their-deck>.pptx     # phases 0-3
+#   ...you write work/deck.json...
+node wand.js ship work/deck.json           # phases 4-6, prints the gate table
+```
+
+`rebuild` normalises the source onto the 10in grid, dumps every verbatim string
+and writes `work/PLAN.md` — per slide: the source's shape, a layout shortlist
+with reasons, the verbatim text grouped by frame, and a stub with the required
+fields. Choose the layout yourself; the shortlist is ranked by shape and cannot
+see meaning.
+
+### Author from a brief
+
+Skip `rebuild`. Write the spec against `node wand.js layouts` and
+`examples/template.json`, then `ship`. Coverage is skipped — there is no source
+to cover — and it says so.
+
+### Merge several decks
+
+`node wand.js rebuild` each one into its own work directory, then write a single
+spec. Ask which deck leads if they have not said. Flag duplicates rather than
+silently dropping them, and list every merge in the review note.
+
+### Edit a deck this kit built
+
+```bash
+node wand.js spec <their-deck>.pptx work/deck.json
+```
+
+Decks built here carry their own spec inside the file. Change only what was
+asked, then `ship`. If the deck carries no spec it was not built here — treat it
+as a rebrand.
+
+## Work in fast loops, ship once
+
+`node wand.js validate` and `node wand.js check` run in seconds; `ship` runs the
+whole pipeline. Iterate spec edits against the first two, and run `ship` when
+they are clean — never as your discovery tool.
+
+When one error reveals a pattern — a field on the wrong layout, a missing
+optional — **sweep the entire spec for that pattern before re-running anything**.
+Paying a full cycle per instance is the slow way to learn the same fact
+repeatedly.
+
+## Rules that decide whether the output is usable
+
+1. **Faithful means verbatim.** No consolidating slides, no paraphrasing to
+   tighten, no restructuring. Reflowing to fit is fine; rewording is not.
+   Paraphrase passes the schema check and passes the eye — only coverage catches
+   it.
+2. **A spec has no coordinates, colours or font sizes.** If a slide needs
+   geometry the layouts do not have, add a layout. Never leak positioning into
+   content.
+3. **Vary the layouts.** Three of the same in a row is a failure even if each is
+   correct. Across 15 slides aim for at least eight distinct ones, alternating
+   dark and light. `validate` warns when you do not.
+4. **Icons are named.** `node wand.js glyphs` lists all 75. Pick by meaning.
+   They recolour to the theme, so there is no polarity to get wrong.
+5. **Never invent content.** If the source is ambiguous, ask.
+
+## Useful commands
+
+| | |
+|---|---|
+| `node wand.js layouts [name]` | the catalog, and any layout's fields |
+| `node wand.js glyphs [search]` | the named icon set |
+| `node wand.js validate <spec>` | fields, types, item caps — run before building |
+| `node wand.js check <spec>` | fit in real Geist, bounds, assets |
+| `node wand.js preview <spec>` | writes `preview/trace.js` for the browser preview |
+| `node wand.js inspect <deck>` | parts, relationships, embedded fonts |
+
+## Deliver
+
+The `.pptx` first, then a review note: every split or merge, every fallback
+mapping, anything tight after fitting, and **everything dropped from the
+verbatim dump**. A rebuild that drops a string without saying so is not done.
+
+Tell them the gate table honestly. The visual gate is the one no script passes —
+say plainly that nobody has looked at the slides yet if nobody has.

package/build.js

@@ -129,7 +129,11 @@ function check(spec) {
               (bad ? `  — ${bad} overflow${bad > 1 ? "s" : ""} above` : "  — clean"));
   console.log(`bounds check: ${oob ? oob + " shape(s) outside the content band — listed above" : "clean"}`);
   console.log(`asset check : ${missing ? missing + " missing — listed above" : `${seen.size} resolved`}`);
-  return bad + oob + missing;
+  // A slide whose layout threw has no shapes, so nothing above can fail for
+  // it — a crash used to print an ERROR line and exit 0, and the spec author
+  // paid a full ship cycle to find out.
+  if (t.errors.length) console.log(`layout check: ${t.errors.length} slide(s) threw — listed above`);
+  return bad + oob + missing + t.errors.length;
 }
 
 /** The same trace, as a PDF. Fonts embedded, no LibreOffice, no conversion. */

package/lib/schema.js

@@ -32,7 +32,7 @@ const COMMON = {
 const L = {
   /* ------------------------------------------------------------ structural */
   cover: {
-    use: "Slide 1. Dark, full bleed, no footer",
+    use: "Slide 1. Always dark, full bleed, no footer. The lede goes in `body` — there is no subtitleText here",
     bleed: true,
     fields: {
       eyebrow: str(), body: str(), kickerPlain: str(), kickerBold: str(),
@@ -40,12 +40,12 @@ const L = {
     },
   },
   divider: {
-    use: "Section breaks and the agenda. Keeps the tag, drops the footer",
+    use: "Section breaks. Always dark, keeps the tag, drops the footer. Prose goes in `body`",
     bleed: true,
     fields: { eyebrow: str(), titleText: s("title", req()), body: str() },
   },
   closing: {
-    use: "Last slide. Centred, full bleed",
+    use: "Last slide. Always dark, centred, full bleed",
     bleed: true,
     fields: { eyebrow: str(), line1: str(req()), line2: str(), body: str(), url: str() },
   },
@@ -357,6 +357,18 @@ function validate(spec) {
     }
     if (sl.layout === "TODO") return;
     checkFields({ ...COMMON, ...def.fields }, sl, path, errs, warns);
+    // COMMON exempts fields every layout takes — but the full-bleed three do
+    // not take all of them, and a lede typed as subtitleText on a cover was
+    // silently dropped: valid name, wrong layout, no message, one ship cycle
+    // wasted finding out. Say it at validate time instead.
+    if (def.bleed) {
+      if (sl.subtitleText != null && !def.fields.subtitleText) {
+        errs.push(`${path}: ${sl.layout} does not render subtitleText — its lede goes in \`body\``);
+      }
+      if (sl.dark === false) {
+        warns.push(`${path}: ${sl.layout} is always dark — \`dark: false\` is ignored`);
+      }
+    }
     seen.push(sl.layout);
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wand-decks-kit",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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": {

package/wand_kit.js

@@ -273,7 +273,7 @@ function cover(pres, { eyebrow, titleLines, body, kickerPlain, kickerBold, tag }
   s.addImage({ path: `${ASSETS}/bg-cover-dark.png`, x: 0, y: 0, w: 10, h: 5.625 });
   s.addImage({ path: `${ASSETS}/orb-cover.png`, x: 5.72, y: 0.38, w: 4.61, h: 4.61 });
   if (tag) chrome(s, { tag, dark: true });
-  s.addText(eyebrow.toUpperCase(), {
+  if (eyebrow) s.addText(eyebrow.toUpperCase(), {
     x: 0.38, y: 1.24, w: 6.0, h: 0.4, margin: 0, isTextBox: true,
     fontFace: F.med, fontSize: 12, color: T.accentSoft, valign: "middle",
   });
@@ -290,10 +290,14 @@ function cover(pres, { eyebrow, titleLines, body, kickerPlain, kickerBold, tag }
     fontFace: F.reg, fontSize: 12.5, color: T.inkDark, valign: "top", lineSpacingMultiple: 1.12,
   });
   s.addShape("rect", { x: 0.38, y: 3.95, w: 0.60, h: 0.04, fill: { color: T.accent }, line: { width: 0 } });
-  s.addText([
-    { text: kickerPlain + "  ", options: { fontFace: F.reg, fontSize: 10, color: T.inkDark } },
-    { text: kickerBold,        options: { fontFace: F.reg, fontSize: 10, bold: true, color: T.white } },
-  ], { x: 0.39, y: 4.03, w: 6.0, h: 0.4, margin: 0, isTextBox: true, valign: "middle" });
+  // Concatenating an absent kicker used to paint the word "undefined" on the
+  // cover — visible only in a render, past every machine gate.
+  const kickerRuns = [
+    kickerPlain && { text: kickerPlain + "  ", options: { fontFace: F.reg, fontSize: 10, color: T.inkDark } },
+    kickerBold && { text: kickerBold, options: { fontFace: F.reg, fontSize: 10, bold: true, color: T.white } },
+  ].filter(Boolean);
+  if (kickerRuns.length) s.addText(kickerRuns,
+    { x: 0.39, y: 4.03, w: 6.0, h: 0.4, margin: 0, isTextBox: true, valign: "middle" });
   return s;
 }
 
@@ -303,7 +307,7 @@ function divider(pres, { tag, eyebrow, titleText, body }) {
   s.background = { color: T.bgDark };
   s.addImage({ path: `${ASSETS}/bg-statement-dark.png`, x: 0, y: 0, w: 10, h: 5.625 });
   chrome(s, { tag, dark: true });
-  s.addText(eyebrow.toUpperCase(), {
+  if (eyebrow) s.addText(eyebrow.toUpperCase(), {
     x: 0.38, y: 1.77, w: 8.9, h: 0.24, margin: 0, isTextBox: true,
     fontFace: F.med, fontSize: 12, color: T.accentSoft, valign: "middle",
   });
@@ -329,14 +333,14 @@ function closing(pres, { eyebrow, line1, line2, body, url }) {
   s.background = { color: T.bgDark };
   s.addImage({ path: `${ASSETS}/bg-statement-dark.png`, x: 0, y: 0, w: 10, h: 5.625 });
   s.addImage({ path: `${ASSETS}/wordmark-white.png`, x: 4.60, y: 0.98, w: 0.80, h: 0.22 });
-  s.addText(eyebrow.toUpperCase(), {
+  if (eyebrow) s.addText(eyebrow.toUpperCase(), {
     x: 0.55, y: 1.85, w: 8.9, h: 0.3, margin: 0, isTextBox: true,
     fontFace: F.med, fontSize: 12, color: T.accentSoft, align: "center", valign: "middle",
   });
   s.addText([
-    { text: line1 + "\n", options: { fontFace: F.reg, fontSize: 24, bold: true, color: T.white } },
-    { text: line2,        options: { fontFace: F.reg, fontSize: 24, bold: true, italic: true, color: T.accentSoft } },
-  ], { x: 0.55, y: 2.19, w: 8.9, h: 1.0, margin: 0, isTextBox: true, align: "center", valign: "top", lineSpacingMultiple: 1.15 });
+    line1 && { text: line1 + (line2 ? "\n" : ""), options: { fontFace: F.reg, fontSize: 24, bold: true, color: T.white } },
+    line2 && { text: line2, options: { fontFace: F.reg, fontSize: 24, bold: true, italic: true, color: T.accentSoft } },
+  ].filter(Boolean), { x: 0.55, y: 2.19, w: 8.9, h: 1.0, margin: 0, isTextBox: true, align: "center", valign: "top", lineSpacingMultiple: 1.15 });
   if (body) s.addText(body, {
     x: 1.5, y: 3.23, w: 7.0, h: 0.7, margin: 0, isTextBox: true,
     fontFace: F.reg, fontSize: 12.5, color: T.bodyDark, align: "center", valign: "top", lineSpacingMultiple: 1.25,
@@ -363,7 +367,7 @@ function threeUp(pres, { tag, titleText, subtitleText, items, dark = true, arrow
   items.slice(0, 3).forEach((it, i) => {
     const cx = x[i], cy = 2.02;
     card(s, { x: cx, y: cy, w, h: 2.70, dark, variant: it.emph ? "emph" : "glass" });
-    s.addText(it.eyebrow.toUpperCase(), {
+    if (it.eyebrow) s.addText(it.eyebrow.toUpperCase(), {
       x: cx + 0.22, y: cy + 0.22, w: w - 0.42, h: 0.20, margin: 0, isTextBox: true,
       fontFace: F.med, fontSize: 8, color: th.eyebrow, valign: "middle",
     });
@@ -917,6 +921,7 @@ function productMap(pres, { tag, titleText, subtitleText, bandRow, cards, split,
   if (subtitleText) subtitle(s, subtitleText, { dark, y: 1.16, h: 0.28 });
   const th = theme(dark);
   const rail = (label, y, h) => {
+    if (!label) return;
     s.addShape("roundRect", {
       x: 0.37, y, w: 1.0, h, rectRadius: radius(1.0, h),
       fill: { color: dark ? T.cardMuted : T.surface }, line: { width: 0 },
@@ -994,7 +999,7 @@ function productMap(pres, { tag, titleText, subtitleText, bandRow, cards, split,
 
 
 module.exports = {
-  VERSION: "0.8.0",
+  VERSION: "0.8.2",
   T, F, COLS, ASSETS, radius, theme, autoSize, measure: M,
   background, chrome, footer, title, subtitle, kicker, contentTop,
   card, iconTile, pill,