wand-kit 0.3.1 → 0.3.2

package/PROMPT.md

@@ -165,6 +165,12 @@ decide, and that make or break a page:
   never the place for the argument.
 - **Equal heights in a row** (`stretch`), titles at one height, and the empty
   space at the foot of a page shared by its sections, never left under one.
+- **A slide balances and sizes itself.** Its body sits in the space under the
+  title, not in the top quarter; a slide whose content fills under 55% of it
+  takes the type scale a step up (`.big`) when that still fits, and the space
+  gate names any slide still under 40%. A thin slide wants its proof, a
+  figure or a visual, or to be joined to the next; `autosize: false` on a page
+  keeps it as composed.
 
 ## 6. Pipeline
 
@@ -197,6 +203,7 @@ new ─▶ argue ─▶ content ─▶ compose ─▶ build ─▶ review ─▶
 | Gate | Fails when | Blind to |
 |---|---|---|
 | fit | anything in the content box runs past it, under the footer, or off the sides | a page that fits and reads badly |
+| space (warn, slides) | a slide still uses under 40% of its content area after sizing itself | whether the content deserves the slide |
 | coverage | a line of `content.txt` is not on the page (whole, or in its declared parts), less the `cut` lines | a line that is present and in the wrong place |
 | overlap | one text box sits on another | text on art |
 | brand | a computed colour, border or fill that is not a token or a declared theme colour | gradients and images |
@@ -322,9 +329,10 @@ direction (the line, camera, motion, on screen, sound, into next).
   after; a shot without voiceover `hold`s; `seconds` on a shot overrides the
   estimate once a real read exists. `target` warns when the board is more
   than 10% off. `timing.csv` and `captions.srt` ship with the board.
-- **A frame is drawn four ways:** `sketch` (people as dots, software as
+- **A frame is drawn five ways:** `sketch` (people as dots, software as
   labelled boxes, agents as sparks: the script's own vocabulary, in the
-  brand's colours), the job's own SVG on brand roles, an image (a product
+  brand's colours), `endcard` (the wordmark on the brand's ground, a line
+  under it when given), the job's own SVG on brand roles, an image (a product
   screen, a demo poster), or left to draw, which the frames gate counts. The
   first frame is on screen from the cut; the others land on their cues.
 - **The HTML plays the board:** the pages to read, and a player (P, or the

package/SKILL.md

@@ -4,7 +4,7 @@ description: Rebrand or create Wand material on the current or new brand - decks
 compatibility: Requires Node.js 18+, code execution enabled in claude.ai (Settings > Features), and a Chromium the kit can find (Playwright's cache or the system). No network needed once installed. Python 3 embeds fonts in the .pptx; without it the deck ships with the faces named, not embedded.
 license: Proprietary - Wand AI
 metadata:
-  version: "0.3.1"
+  version: "0.3.2"
 ---
 
 
@@ -125,7 +125,10 @@ talk adds:
 3. A live demo: one self-contained HTML file, then its poster on the deck's
    brand: `node wand.js poster demo.html --play 3 --brand <brand>`, and
    `c.demo({ src, poster })` on the slide. A clip: `c.video({ src, poster })`.
-4. `ship` drives the HTML like a presenter before it ships (the runtime row).
+4. Slides balance and size themselves; if the space row names one, it is
+   thin: add its proof or a figure, or join it to the next, rather than
+   stretching what is there.
+5. `ship` drives the HTML like a presenter before it ships (the runtime row).
    Deliver the HTML as the deck to present, with the PDF and .pptx beside it.
 
 ### A storyboard from a script
@@ -134,8 +137,9 @@ talk adds:
    edit will cut). `node wand.js new work/<name> --surface storyboard`.
 2. **Write the shot list in the chat first**: act, name, the line, and what
    each frame shows. Then the job: `c.storyboard({ title, wpm, target, shots })`.
-3. Frames: `sketch` for a quick one in the brand's colours, the job's own SVG,
-   an image, or left to draw (the frames gate counts them).
+3. Frames: `sketch` for a quick one in the brand's colours, `endcard: true`
+   for the wordmark close, the job's own SVG, an image, or left to draw (the
+   frames gate counts them). A held close is a shot with no `vo` and a `hold`.
 4. `ship`: the board as PDF and .pptx, `timing.csv`, `captions.srt`, and the
    HTML with its player. Say in the note that timing is scratch timing at the
    `wpm` given until a real read exists, and which frames are still to draw.

package/examples/storyboard/job.mjs

@@ -5,8 +5,8 @@
  * The script is the content file, one voiceover line a shot, so coverage
  * proves every word of it is on the board. Frames show each way a frame can
  * be drawn: a sketch in the brand's colours (people, software, agents), the
- * job's own SVG, an image (the talk example's demo poster), and one left to
- * draw, which the frames gate counts.
+ * job's own SVG, an image (the talk example's demo poster), and an end card
+ * (the wordmark on the brand's ground).
  *
  *   node wand.js ship examples/storyboard/job.mjs                  the current brand
  *   node wand.js ship examples/storyboard/job.mjs --brand next     the website's, in out-next/
@@ -61,7 +61,7 @@ export default {
         frames: [
           { cue: "identity", sketch: { agents: 1, apps: ["Identity", "Manager"], label: "An agent, provisioned" } },
           { cue: "budget", sketch: { agents: 1, apps: ["Budget", "Record"], label: "Governed like a person" } },
-          { cue: "record", caption: "End card for the governance beat: to draw." },
+          { cue: "record", endcard: "Identity · Manager · Budget · Record", caption: "The governance beat lands on the wordmark." },
         ] },
       { act: "Wand", name: "One workforce", vo: c.L(6),
         line: "The close: people and agents in one picture, then the wordmark.",

package/lib/components.js

@@ -52,11 +52,11 @@ export function bind({ brand, surface, job, content, dir: jobDir = process.cwd()
    * view; `seconds` is the slide's share of the talk, for the presenter's
    * pace; `motion: "none"` keeps a slide still when the deck animates.
    */
-  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true, seconds = 0, motion = "" } = {}) => {
+  const page = ({ eyebrow = "", dark = false, art = null, shade = dark, cls: k = "", body = "", notes = "", chrome = true, seconds = 0, motion = "", autosize = true } = {}) => {
     n += 1;
     const artSrc = art ? (/[\/.]/.test(art) && !brand.tokens.art[art] ? url(art) : brand.artUrl(art)) : null;
     const eb = job.tag && eyebrow ? `${esc(job.tag)}<span class="bar">|</span>${esc(eyebrow)}` : esc(job.tag || eyebrow || "");
-    return `<section class="page ${dark ? "dark" : "light"}${cls(k)}" data-n="${n}"${notes ? ` data-notes="${esc(notes)}"` : ""}${seconds ? ` data-seconds="${seconds}"` : ""}${motion ? ` data-motion="${esc(motion)}"` : ""}>
+    return `<section class="page ${dark ? "dark" : "light"}${cls(k)}" data-n="${n}"${notes ? ` data-notes="${esc(notes)}"` : ""}${seconds ? ` data-seconds="${seconds}"` : ""}${motion ? ` data-motion="${esc(motion)}"` : ""}${autosize ? "" : ' data-size="fixed"'}>
 ${artSrc ? `<img class="art deco" src="${artSrc}" alt="">${shade ? `<div class="shade deco"></div>` : ""}` : ""}
 ${chrome ? `<div class="eyebrow">${eb}</div>${mark(dark)}` : ""}
 <div class="content">${body}</div>
@@ -190,7 +190,8 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
    * on its `cue` word. The timeline is kept for the CSV, the captions and the
    * player in the HTML.
    * A shot: { act, name, vo, line, camera, motion, onscreen, sound, next,
-   *           lead, tail, hold, seconds, frames: [{ cue, caption, art | img | sketch }] }
+   *           lead, tail, hold, seconds, frames: [{ cue, caption, art | img | sketch | endcard }] }
+   * `endcard: true` draws the wordmark on the brand's ground; a string adds a line under it.
    */
   const storyboard = ({ title, lede = "", wpm = 150, target = 0, shots = [], dark = true, cover: withCover = true, index = true, audio = "" }) => {
     let t = 0;
@@ -204,14 +205,16 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
         const at = f.cue && vo ? vo.toLowerCase().indexOf(String(f.cue).toLowerCase()) : -1;
         // the first frame is on screen from the cut; the others land on their cue words
         const ft = j === 0 ? inT : at >= 0 ? voIn + voDur * (at / vo.length) : voIn + (voDur * j) / all.length;
-        return { ...f, id: `${String(i + 1).padStart(2, "0")}${"ABCD"[j]}`, t: +ft.toFixed(1), placeholder: !(f.art || f.img || f.sketch) };
+        return { ...f, id: `${String(i + 1).padStart(2, "0")}${"ABCD"[j]}`, t: +ft.toFixed(1), placeholder: !(f.art || f.img || f.sketch || f.endcard) };
       });
       return { ...s, n: i + 1, vo, in: +inT.toFixed(1), voIn: +voIn.toFixed(1), voOut: +voOut.toFixed(1), out: t, dur: +(t - inT).toFixed(1), frames: fr };
     });
     const total = t;
     job.__board = { wpm, target, total, audio: audio ? path.resolve(jobDir, audio) : "", shots: timeline.map(({ n, act, name, vo, in: i, voIn, voOut, out, dur, frames }) => ({ n, act: act || "", name: name || "", vo, in: i, voIn, voOut, out, dur, frames: frames.map(({ id, t: ft, cue, placeholder }) => ({ id, t: ft, cue: cue || "", placeholder })) })) };
 
-    const art = (f) => f.art ? f.art : f.img ? `<img src="${fileUrl(f.img)}" alt="">` : f.sketch ? sketch(f.sketch) : `<div class="todo"><span>${esc(f.cue ? `on ‘${f.cue}’` : "frame")}</span></div>`;
+    // an end card is the wordmark on the brand's ground, with a line under it when endcard is a string
+    const endcard = (f) => `<div class="endcard"><img src="${brand.artUrl(dark ? "wordmarkOnDark" : "wordmarkOnLight")}" alt="Wand">${typeof f.endcard === "string" ? `<span>${esc(f.endcard)}</span>` : ""}</div>`;
+    const art = (f) => f.art ? f.art : f.img ? `<img src="${fileUrl(f.img)}" alt="">` : f.sketch ? sketch(f.sketch) : f.endcard ? endcard(f) : `<div class="todo"><span>${esc(f.cue ? `on ‘${f.cue}’` : "frame")}</span></div>`;
     const DIR = [["line", "The line"], ["camera", "Camera"], ["motion", "Motion"], ["onscreen", "On screen"], ["sound", "Sound"], ["next", "Into next"]];
     const shotPage = (s) => page({ eyebrow: s.act || "", dark, cls: "shot", notes: s.vo, body: `
 <div class="shot-head"><div class="shot-id"><span class="tag">Shot</span><span class="no">${String(s.n).padStart(2, "0")}</span></div>
@@ -403,6 +406,9 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .tile{width:2.3em;height:2.3em;border-radius:calc(var(--m-radius) * .6 * var(--radius-k));background:var(--surface);display:flex;align-items:center;justify-content:center;color:var(--accent-text);flex:none;margin-bottom:.8em}
 .card.emph .tile{background:var(--emph-accent);color:var(--emph)}
 /* room */
+/* a slide's body sits in the space under its title, not in its top quarter */
+.surface-slide .page:not(.cover):not(.back):not(.shot):not(.run) .content>:is(h1,h2,.sec):first-child+*{margin-top:auto}
+.surface-slide .page:not(.cover):not(.back):not(.shot):not(.run) .content>:last-child{margin-bottom:auto}
 .roomy .content{gap:calc(var(--m-gap) * 1.3)}
 .roomy .cols{margin:auto 0}
 .roomy .lead{font-size:calc(var(--t-lead) * 1.15)}
@@ -448,6 +454,9 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .frame figcaption b{color:var(--label);font-weight:600}
 .frame figcaption span{display:block;color:var(--text);margin-top:.2em}
 .frame .todo{position:absolute;inset:0;display:grid;place-items:center;border:2px dashed var(--rule);border-radius:inherit}
+.frame-art .endcard{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:5%;background:var(--bg);box-shadow:inset 0 0 0 2px var(--rule);border-radius:inherit}
+.frame-art .endcard>img{position:static;width:30%;height:auto}
+.frame-art .endcard>span{font-family:var(--face-body);font-size:var(--t-sm);color:var(--soft);letter-spacing:.04em}
 .frame .todo span{font-size:var(--t-sm);color:var(--soft)}
 .direction{margin:0;display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:calc(var(--m-gap) * .5) var(--m-col-gap);border-top:var(--card-stroke) solid var(--rule);padding-top:calc(var(--m-gap) * .6)}
 .direction dt{font-family:var(--face-label);font-weight:var(--w-label);font-size:var(--t-tag);letter-spacing:.14em;text-transform:var(--caps-label);color:var(--label);margin-bottom:.3em}

package/lib/engine.js

@@ -172,6 +172,35 @@ function GATES({ min, chars, tokens, families, base }) {
   return res;
 }
 
+/**
+ * Runs inside the page. A slide whose content fills too little of it gets the
+ * type scale one step up (.big), kept only if nothing then overflows: a deck
+ * sizes itself to its slides, the same way on every run. Returns the pages
+ * it changed, and every slide's fill after.
+ */
+function AUTOSIZE() {
+  const fill = (pg) => {
+    const c = pg.querySelector(".content"); if (!c) return 1;
+    const kids = [...c.children].filter((k) => !k.classList.contains("deco") && k.getBoundingClientRect().height);
+    if (!kids.length) return 1;
+    const gap = parseFloat(getComputedStyle(c).rowGap) || 0;
+    return (kids.reduce((a, k) => a + k.getBoundingClientRect().height, 0) + gap * (kids.length - 1)) / c.getBoundingClientRect().height;
+  };
+  const overflows = (pg) => {
+    const c = pg.querySelector(".content"), box = c.getBoundingClientRect(), foot = pg.querySelector("footer")?.getBoundingClientRect();
+    const floor = foot ? Math.min(box.bottom, foot.top - 6) : box.bottom;
+    // as the fit gate reads it: an inline run's line box may rise above the content's top, a block may not
+    return [...c.querySelectorAll("*")].some((el) => { if (el.closest(".deco")) return false; const r = el.getBoundingClientRect(); return r.width && r.height && (r.bottom > floor + 0.5 || r.right > box.right + 1 || (getComputedStyle(el).display !== "inline" && r.top < box.top - 0.5)); }) || fill(pg) > 1;
+  };
+  const sized = [], fills = [];
+  document.querySelectorAll(".page").forEach((pg, i) => {
+    if (pg.matches(".cover, .back, .shot, .run, [data-size]")) return;
+    if (fill(pg) < 0.55 && !pg.classList.contains("big")) { pg.classList.add("big"); if (overflows(pg)) pg.classList.remove("big"); else sized.push(i + 1); }
+    fills.push({ page: i + 1, fill: fill(pg) });
+  });
+  return { sized, fills };
+}
+
 /* ------------------------------------------------------------------ build */
 
 /**
@@ -209,6 +238,9 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
   await page.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
   await page.waitForTimeout(120);
 
+  // a slide deck sizes itself before anything is measured or drawn; the file keeps the sizes it chose
+  const auto = surface.kind === "slide" ? await page.evaluate(AUTOSIZE) : { sized: [], fills: [] };
+  if (auto.sized.length) fs.writeFileSync(htmlPath, "<!doctype html>\n" + await page.evaluate(() => document.documentElement.outerHTML));
   const g = await page.evaluate(GATES, { min: surface.min, chars: surface.chars, tokens: [...brand.tokenSet], families: brand.families, base: surface.base });
   const pageCount = g.fit.length;
   const text = g.texts.join("\n");
@@ -231,6 +263,8 @@ export async function build(jobPath, { outputs: wantOutputs = true, outDir = nul
   row(!deny.length, "names", job.denylist?.length ? (deny.length ? `found ${deny.join(", ")}` : `none of ${job.denylist.length} denied names`) : "no denylist", !job.denylist?.length);
   row(!g.contrast.length, "contrast", g.contrast.length ? `${g.contrast.length} low: ` + g.contrast.slice(0, 3).map((o) => `p${o.page} ${o.el} ${o.ratio}:1 (needs ${o.need})`).join("; ") : "every text passes WCAG AA", true);
   row(!g.measure.length, "measure", g.measure.length ? `${g.measure.length} long: ` + g.measure.slice(0, 3).map((o) => `p${o.page} ${o.el} ~${o.chars} chars`).join("; ") : `no line over ${surface.chars} characters`, true);
+  const sparse = auto.fills.filter((f) => f.fill < 0.4);
+  if (surface.kind === "slide") row(!sparse.length, "space", sparse.length ? `${sparse.map((f) => `p${f.page} ${Math.round(f.fill * 100)}%`).join(", ")} of the slide used: add the proof, a figure or a visual, or join it to the next` : `every slide uses its space${auto.sized.length ? ` (type a step up on p${auto.sized.join(", p")})` : ""}`, true);
   row(!g.broken.length, "images", g.broken.length ? `${g.broken.length} did not load: ${g.broken.slice(0, 3).join(", ")}` : "every image loaded");
   if (absent.length || g.motion.demo || g.motion.video) row(!absent.length, "media", absent.length ? `missing: ${absent.map((p) => path.basename(p)).join(", ")}` : `${g.motion.demo} demo${g.motion.demo === 1 ? "" : "s"}, ${g.motion.video} clip${g.motion.video === 1 ? "" : "s"}, each with its poster`);
   const board = job.__board || null;

package/lib/surfaces.js

@@ -57,6 +57,9 @@ export function surfaceCss(s) {
   const kebab = (k) => k.replace(/[A-Z]/g, (x) => "-" + x.toLowerCase());
   const m = Object.entries(s.m).map(([k, v]) => `--m-${kebab(k)}:${typeof v === "number" ? v + "px" : v}`).join(";");
   const c = Object.entries(s.chrome).map(([k, v]) => `--c-${kebab(k)}:${v}px`).join(";");
+  // .big: the type scale one step up, which the engine gives a slide whose content fills too little of it
+  const big = Object.entries(s.t).map(([k, v]) => `--t-${k}:${+(v * 1.25).toFixed(1)}px`).join(";");
   return `@page{size:${s.w}px ${s.h}px;margin:0}
-.page{width:${s.w}px;height:${s.h}px;--x:${s.x}px;--top:${s.top}px;--bottom:${s.bottom}px;--base:${s.base}px;font-size:${s.base}px;${t};${m};${c}}`;
+.page{width:${s.w}px;height:${s.h}px;--x:${s.x}px;--top:${s.top}px;--bottom:${s.bottom}px;--base:${s.base}px;font-size:${s.base}px;${t};${m};${c}}
+.page.big{font-size:${+(s.base * 1.25).toFixed(1)}px;${big}}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wand-kit",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "One HTML design surface for every sales and marketing material, on either Wand brand: decks that animate and present, documents, one-pagers, case studies, storyboards from a script, social cards. Every export (PDF, PNG, PowerPoint, one-file HTML) is read from the page that was reviewed.",
   "license": "SEE LICENSE IN PROMPT.md",
   "bin": {