wand-kit 0.3.1 → 0.3.3

package/PROMPT.md

@@ -80,13 +80,24 @@ the ground's values, so one component draws on both.
 | `label` | 6C5CE7 | A78BFA | tags, section numbers |
 | `emph` / `emphInk` / `emphText` / `emphAccent` | 251C63 / FFF / DCD6F5 / AA9BFF | 4D2E8C / FFF / DCD6F5 / C4B5F4 | the emphasis card and what sits on it |
 | `stroke` / `rule` / `track` / `surface` | E4E0F2 / E4E0F2 / E9E6F5 / EBE8F8 | 5B4BB0 / 3A2E63 / 1A1033 / 1A1033 | card strokes, hairlines, meter tracks, tiles |
+| `second` / `secondSm` | 6C5CE7 / 6C5CE7 | 9481FF / 9481FF | a title's phrase, large / small (on this brand, the accent itself) |
+| `gradeLow` / `gradeHigh` | 240F48 / F8F6FB | the same | the photograph grade: where blacks lift to, where highlights settle |
 
 The next brand fills the same roles from the website (gold the one accent,
-violets as grounds, beige as paper); see `brand-next/tokens.json`.
+violets as grounds, beige as paper); see `brand-next/tokens.json`. Its
+`second` is a quiet tone, not gold (7B7B79 on light, 9D99A8 on dark, large
+type only; `secondSm`, the text grey, below that size).
 
 **Rules.**
 - One accent. The accent phrase in a title is the single most recognisable
   device in the system: one per title, never two, the sentence period in ink.
+- **On the next brand a title has two tones and gold is rare.** The phrase
+  takes `second`, a quieter tone of the ink; gold stays for the pages that
+  carry the brand's art (the cover, a statement, the close), for figures and
+  for the spark. The website's own headings carry no gold at all, and the
+  wand.ai rebuild (October 2026) read as a template while every heading's
+  second line was gold: when gold is everywhere it means nothing. On the
+  current brand `second` is the accent, so nothing changes there.
 - One emphasis card per row, at most one or two per page.
 - Light pages carry no art. Dark pages carry art on the cover, the closing and
   a statement; a dark content page is flat.
@@ -142,6 +153,7 @@ The components (`node wand.js components`; `kit/lib/components.js`):
 | `quote({ text, by, emph })`, `who` | testimonial cards, name over role, no photographs |
 | `stats`, `delta(from, to)` | figures, before-and-after |
 | `steps(items)` | next steps with arrows |
+| `photo(name, { pos })` | a brand photograph filling its box, with the brand's grade |
 | `callout`, `list`, `chapter`, `img`, `icon`, `tile` | the rest |
 | `enter(kind, i)`, `step(n, html)`, `countup(text)`, `stat({ count })` | motion in a talk (§12) |
 | `video({ src, poster })`, `demo({ src, poster })` | a clip or a live page on a slide (§12) |
@@ -165,6 +177,26 @@ 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.
+- **One arc.** Night, then day, then first light: the dark cover with its
+  art, the argument on light pages, one dark statement where the piece turns,
+  and the close. A piece that switches ground on every page reads as a
+  slideshow of boxes.
+- **No composition three pages running.** The same heading, then the same
+  three cards, page after page, is what makes a set of pages read as a
+  template; the variety gate names the run. Vary it: a statement set large,
+  a split with a photograph, a figure, a page that is one exhibit.
+- **Photographs large or not at all**, through `photo()`: full bleed or a full
+  column, never a thumbnail; architecture and light from the brand's set,
+  never stock (a person at a desk, a stethoscope, a form, a highway). Every
+  photograph takes the brand's one grade, so they read as one shoot.
+- **An exhibit on hairlines, not in a box.** A diagram or a flow sits on the
+  ground with rules; a frame around it reads as a dashboard widget.
+- **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
 
@@ -185,7 +217,12 @@ new ─▶ argue ─▶ content ─▶ compose ─▶ build ─▶ review ─▶
    per page, the contact sheet. `watch` does this on every save in under a
    second with the browser kept warm.
 6. **review** — look at `out/sheet.png`, then at any page the gates named.
-   Read the pages as the reader will: does each carry its claim?
+   Read the pages as the reader will: does each carry its claim? Then read
+   the sheet as a creative director would, the questions the build prints
+   under it: is one page memorable, and which; is the accent rare;
+   are photographs large or absent; are hairlines and type doing the
+   separating. A piece where no page would stop someone who has seen a
+   hundred decks is not finished: make one page that does.
 7. **ship** — `node wand.js ship <job> [--pptx]`: the build, the one-file HTML,
    the PowerPoint. A deck's HTML is a talk (§12), a storyboard's plays (§13),
    and either runtime is driven before it ships. `--brand next` (or `current`)
@@ -197,6 +234,8 @@ 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 |
+| variety (warn) | three pages running share one composition (the same blocks in the same order) | two pages composed alike but far apart |
 | 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 |
@@ -286,7 +325,11 @@ figure final, every poster.
 - **Kinds.** `rise` (the default), `fade`, `pop` for a mark or a figure,
   `grow` for a bar going up, `widen` for a bar going across, `draw` for a
   line that tells a trend (an SVG path with `pathLength="1"`), `count` for a
-  figure the room should watch arrive (`stat({ count: true })`, `countup()`).
+  figure the room should watch arrive (`stat({ count: true })`, `countup()`),
+  `words` for a title whose words rise out of their lines (every title does
+  this under `motion: "auto"`), `lit` for a statement that lights word by
+  word, `window` for a photograph that opens like a window. A page's art
+  (the cover's light, a statement, the close) comes up like first light.
 - **Steps** when the order of the argument is the point: `step(1, html)`, then
   2, then 3. Never more than four on a slide. Going back undoes the last step.
 - **Notes on every slide of a talk**, and `seconds` on each when the talk has a
@@ -322,9 +365,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.3"
 ---
 
 
@@ -94,7 +94,9 @@ beside the first. Nothing in the job changes.
    in `edits` (no em dashes: swap them for commas or semicolons there) and
    every line left out in `cut`.
 4. `node wand.js build work/<name>/job.mjs` until every hard gate is ok. Look
-   at `out/sheet.png`. Open a page only where something looks off.
+   at `out/sheet.png`. Open a page only where something looks off. Then answer
+   the review questions the build prints under the gates, as a creative
+   director would; if the variety row names a run of pages, recompose it.
 5. `node wand.js ship work/<name>/job.mjs --pptx` for a deck; without `--pptx`
    for a document. Deliver the PDF (and the .pptx, and the .html) with the
    review note.
@@ -105,6 +107,10 @@ Skip `content.txt` (delete the `content:` line in the job). Write the page list
 with its claims first, then the pages. Coverage is skipped and says so; the
 review reads the argument instead. Three sections a page, not four.
 
+On the next brand, a title's phrase is its quiet second tone and gold is kept
+for the cover, a statement, the close and the figures; photographs go through
+`c.photo("walk")` (the brand's set, graded), large or not at all.
+
 ### Make it generic (an industry version of a client piece)
 
 Author from the client piece: remove the client's figures, names, quotes and
@@ -120,12 +126,16 @@ talk adds:
 1. Notes on every slide, and `seconds` on each when the talk has a slot.
 2. Motion where it carries the argument (PROMPT.md §12): `step(n, html)` for
    a reveal in order, `stat({ count: true })` for a figure to watch arrive,
-   `enter("draw")` on a trend line, `enter("grow", i)` on bars. Restraint: one
-   moment a slide.
+   `enter("draw")` on a trend line, `enter("grow", i)` on bars, `enter("lit")`
+   on a statement, `enter("window")` on a photograph. Titles rise word by word
+   on their own. Restraint: one moment a slide.
 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 +144,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/brands/current/tokens.json

@@ -54,7 +54,11 @@
       "rule": "E4E0F2",
       "track": "E9E6F5",
       "surface": "EBE8F8",
-      "emphLabel": "AA9BFF"
+      "emphLabel": "AA9BFF",
+      "second": "6C5CE7",
+      "secondSm": "6C5CE7",
+      "gradeLow": "240F48",
+      "gradeHigh": "F8F6FB"
     },
     "dark": {
       "bg": "240F48",
@@ -74,7 +78,11 @@
       "rule": "3A2E63",
       "track": "1A1033",
       "surface": "1A1033",
-      "emphLabel": "C4B5F4"
+      "emphLabel": "C4B5F4",
+      "second": "9481FF",
+      "secondSm": "9481FF",
+      "gradeLow": "240F48",
+      "gradeHigh": "F8F6FB"
     }
   },
   "faces": {

package/brands/next/tokens.json

@@ -34,6 +34,10 @@
       "hex": "C4C1CA",
       "from": "white @ 70% on violet200, lists inside dark cards"
     },
+    "secondDark": {
+      "hex": "9D99A8",
+      "from": "white @ 55% on violet300 - a title's quiet second tone on dark (5.7:1)"
+    },
     "footDark": {
       "hex": "888394",
       "from": "white @ 45% on violet300"
@@ -60,7 +64,11 @@
       "rule": "D5CEC2",
       "track": "D5CEC2",
       "surface": "EBE8E2",
-      "emphLabel": "B79A5E"
+      "emphLabel": "B79A5E",
+      "second": "7B7B79",
+      "secondSm": "686766",
+      "gradeLow": "261D3D",
+      "gradeHigh": "F1EFEB"
     },
     "dark": {
       "bg": "261D3D",
@@ -80,7 +88,11 @@
       "rule": "504666",
       "track": "504666",
       "surface": "3A314E",
-      "emphLabel": "C4C1CA"
+      "emphLabel": "C4C1CA",
+      "second": "9D99A8",
+      "secondSm": "BEBBC5",
+      "gradeLow": "261D3D",
+      "gradeHigh": "F1EFEB"
     }
   },
   "faces": {

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

@@ -18,9 +18,10 @@
  * content lines. A job's `pages(c)` composes with them and may add its own
  * CSS on top; nothing stops it writing raw markup where no component fits.
  */
+import fs from "node:fs";
 import path from "node:path";
 import { esc } from "./content.js";
-import { url } from "./brand.js";
+import { url, brandDir, BRANDS } from "./brand.js";
 
 export const ARROW = `<svg class="arrow deco" viewBox="0 0 10 10" aria-hidden="true"><path d="M2 1 L9 5 L2 9 Z"/></svg>`;
 
@@ -52,11 +53,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>
@@ -130,13 +131,29 @@ ${chrome ? `<footer><span>${esc(job.footer || "")}</span><span class="pn">${Stri
   /** A big outlined numeral in a dark panel on the right (the deck's chapter pages). */
   const chapter = (num) => `<div class="chapter deco"><span>${esc(num)}</span></div>`;
 
+  /**
+   * A photograph, filling its box and given the brand's one grade: blacks lift toward the dark ground,
+   * highlights settle toward the light one, so photographs from different shoots read as one set.
+   * `src` is a photograph of the brands' set by name ("walk", "corridor"; `brand-next/assets/photos`, which
+   * the current brand shares, graded on its own grounds) or a path.
+   */
+  const photo = (src, { cls: k = "", alt = "", pos = "" } = {}) => {
+    let href = /^(file|https?|data):/.test(src) ? src : url(src);
+    if (!/[\/.]/.test(src)) {
+      const dirs = [brand.assets, ...BRANDS.filter((b) => b !== brand.name).map((b) => { try { return path.join(brandDir(b), "assets"); } catch { return null; } }).filter(Boolean)];
+      const hit = dirs.map((d) => path.join(d, "photos", `${src}.jpg`)).find((f) => fs.existsSync(f));
+      if (!hit) throw new Error(`photo("${src}"): no photograph of that name in ${dirs.map((d) => path.join(d, "photos")).join(" or ")}`);
+      href = url(hit);
+    }
+    return `<figure class="photo${cls(k)}"><img src="${href}" alt="${esc(alt)}"${pos ? ` style="object-position:${esc(pos)}"` : ""}><span class="grade"></span></figure>`;
+  };
   const img = (src, k = "", alt = "") => `<img class="img${cls(k)}" src="${/^(file|https?|data):/.test(src) ? src : url(src)}" alt="${esc(alt)}">`;
   const icon = (name, k = "") => brand.glyph(name).replace("<svg", `<svg class="icon deco${cls(k)}" aria-hidden="true"`);
   const tile = (name) => `<div class="tile deco">${icon(name)}</div>`;
 
   /* ---------------------------------------------------------- motion */
 
-  /** An entrance, as attributes for raw markup: `<div${c.enter("pop", 2)}>`. Kinds: rise (default), fade, pop, grow (bars, up), widen (bars, across), draw (an SVG path with pathLength="1"), count. */
+  /** An entrance, as attributes for raw markup: `<div${c.enter("pop", 2)}>`. Kinds: rise (default), fade, pop, grow (bars, up), widen (bars, across), draw (an SVG path with pathLength="1"), count, words (a title rising word by word), lit (a statement lighting word by word), window (a photograph opening). */
   const enter = (kind = "", i = null) => ` data-a="${esc(kind)}"${i != null ? ` style="--i:${+i}"` : ""}`;
   /** Held back until the presenter moves on; steps of one number come in together. */
   const step = (nth, html, { a = "", tag: t = "div", cls: k = "" } = {}) => `<${t} data-step="${+nth}"${a ? ` data-a="${esc(a)}"` : ""}${k ? ` class="${k}"` : ""}>${html}</${t}>`;
@@ -190,7 +207,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 +222,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>
@@ -232,7 +252,7 @@ ${DIR.some(([k]) => s[k]) ? `<dl class="direction">${DIR.filter(([k]) => s[k]).m
     page, sec, h1: h("h1"), h2: h("h2"), h3: h("h3"), h4: h("h4"), h5: h("h5"),
     lead: p("lead"), body: p("body"), note: p("note"), small: p("body sm"), tag, p: (html, k = "") => `<p${cls(k) ? ` class="${k}"` : ""}>${html}</p>`,
     cols, card, chip, strip, phase, flow, table, who, quote, stat, stats, delta, steps, callout, list: listOf,
-    cover, closing, chapter, img, icon, tile, mark, wordmark,
+    cover, closing, chapter, img, photo, icon, tile, mark, wordmark,
     asset: brand.assetUrl, art: brand.artUrl,
     enter, step, countup, video, demo, sketch, storyboard,
     brand: brand.name, surface: surface.name, count: () => n,
@@ -262,7 +282,11 @@ footer .pn{font-weight:500}
 /* type */
 h1,h2,h3,h4,h5,.display{font-family:var(--face-display);font-weight:var(--w-display);letter-spacing:var(--tr-display);line-height:var(--lh-display);color:var(--ink)}
 h1{font-size:var(--t-h1)}h1.md{font-size:var(--t-h1md)}h2{font-size:var(--t-h2)}h3{font-size:var(--t-h3);line-height:1.22}h4{font-size:var(--t-h4);line-height:1.2}h5{font-size:var(--t-h5);line-height:1.25}
-h1 em,h2 em,h3 em,h4 em,.display em,.lede em{font-style:normal;color:var(--accent-text)}
+/* a title's phrase is its second tone (on the current brand, the accent itself); on the cover, a statement
+   and the close, the pages that carry the brand's art, it keeps the accent */
+h1 em,h2 em,.display em{font-style:normal;color:var(--second)}
+h3 em,h4 em,h5 em,.lede em{font-style:normal;color:var(--second-sm)}
+.page:has(>.art) :is(h1,h2,h3,h4,h5,.display,.lede) em{color:var(--accent-text)}
 .label{font-family:var(--face-display);font-weight:500;font-size:var(--t-label);letter-spacing:var(--tr-display);color:var(--label);line-height:1.2}
 .label.sm{font-size:calc(var(--t-label) * .8)}
 .lead{font-size:var(--t-lead);line-height:1.5;color:var(--ink)}
@@ -398,11 +422,20 @@ table.grid{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums
 .has-chapter .left{width:62%;display:flex;flex-direction:column;gap:var(--m-gap)}
 /* images, icons */
 .img{display:block;max-width:100%}
+.photo{position:relative;margin:0;overflow:hidden;border-radius:calc(var(--m-radius) * var(--radius-k));background:var(--grade-high)}
+.photo>img{display:block;width:100%;height:100%;object-fit:cover}
+.photo>.grade{position:absolute;inset:0;pointer-events:none}
+.photo>.grade::before,.photo>.grade::after{content:"";position:absolute;inset:0}
+.photo>.grade::before{background:var(--grade-low);mix-blend-mode:lighten;opacity:.42}
+.photo>.grade::after{background:var(--grade-high);mix-blend-mode:darken;opacity:.55}
 .figure{border-radius:calc(var(--m-radius) * var(--radius-k));overflow:hidden}
 .icon{width:1.25em;height:1.25em;stroke:currentColor;fill:none}
 .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 +481,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

@@ -113,6 +113,13 @@ function GATES({ min, chars, tokens, families, base }) {
     motion: { a: document.querySelectorAll("[data-a]").length, steps: document.querySelectorAll("[data-step]").length, video: document.querySelectorAll(".media.video").length, demo: document.querySelectorAll(".media.demo").length, placeholders: document.querySelectorAll(".frame.placeholder").length } };
   document.querySelectorAll("img").forEach((im) => { if (im.getAttribute("src") && !(im.complete && im.naturalWidth)) res.broken.push(decodeURIComponent(im.getAttribute("src").replace(/^file:\/\//, "")).split("/").slice(-2).join("/")); });
   const seen = new Set();
+  // a page's composition, coarsely: the blocks of its content in order, and how many a grid holds
+  const kindOf = (el) => { const c = [...el.classList].filter((x) => !/^(deco|big|wide|stretch|centre|sm|md)$/.test(x)).slice(0, 2); return el.tagName.toLowerCase() + (c.length ? "." + c.join(".") : ""); };
+  res.sig = pages.map((pg) => {
+    const c = pg.querySelector(".content");
+    if (!c || pg.matches(".cover, .back, .shot, .run")) return null;
+    return [...c.children].filter((k) => !k.classList.contains("deco")).map((k) => kindOf(k) + (/\b(cols|strip|stats|steps|grid)\b/.test(k.className) ? `[${k.children.length}]` : "")).join(" ");
+  });
   pages.forEach((pg, pi) => {
     const n = pi + 1;
     const content = pg.querySelector(".content");
@@ -172,6 +179,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 +245,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 +270,16 @@ 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);
+  // the same composition page after page is what makes a set of pages read as a template
+  const runs = [], composed = !job.__board && surface.kind !== "card";
+  if (composed) for (let i = 1, start = 0; i <= g.sig.length; i++) {
+    if (i < g.sig.length && g.sig[i] && g.sig[i] === g.sig[i - 1]) continue;
+    if (i - start >= 3 && g.sig[start]) runs.push([start + 1, i]);
+    start = i;
+  }
+  if (composed) row(!runs.length, "variety", runs.length ? runs.map(([a, z]) => `p${a}–p${z}`).join(", ") + " share one composition: vary it (a statement, a split, a figure, a photograph) or join them" : "no composition repeats three pages running", 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;
@@ -286,6 +335,8 @@ export function printReport(r) {
   if (r.outputs.pdf) console.log(`\n  ${path.relative(process.cwd(), r.outputs.pdf)}  (${(fs.statSync(r.outputs.pdf).size / 1e6).toFixed(1)} MB, ${r.pages} page${r.pages === 1 ? "" : "s"}, ${r.brand} brand, ${r.surface}, ${(r.ms / 1000).toFixed(1)}s)`);
   if (r.outputs.pptx) console.log(`  ${path.relative(process.cwd(), r.outputs.pptx)}  (${(fs.statSync(r.outputs.pptx).size / 1e6).toFixed(1)} MB)`);
   if (r.outputs.single) console.log(`  ${path.relative(process.cwd(), r.outputs.single)}  (${(fs.statSync(r.outputs.single).size / 1e6).toFixed(1)} MB, one file, opens offline)`);
+  // what no gate sees: read the sheet the way a creative director would, before anyone else does
+  if (r.outputs.sheet) console.log(`\n  review  ${path.relative(process.cwd(), r.outputs.sheet)}, as a creative director:\n          does every page carry its one claim? is one page memorable, and which?\n          is the accent rare (cover, statement, close, figures)? photographs large or absent?\n          hairlines and type doing the separating, not boxes?`);
   console.log(r.ok ? "" : "\n  FAILED — fix the rows marked FAIL\n");
 }
 

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/lib/talk.js

@@ -10,9 +10,11 @@
  * What it adds to the pages, none of which the PDF, the PNGs or the .pptx see
  * (they are read from the static render):
  *   - a crossfade between slides, the slide being left kept under the next;
- *   - entrances: `data-a` (rise, fade, pop, grow, widen, draw, count) with `--i` as
- *     the stagger, played going forward; with `motion: "auto"` a slide that
- *     marks nothing has its blocks staggered in for it;
+ *   - entrances: `data-a` (rise, fade, pop, grow, widen, draw, count, words,
+ *     lit, window) with `--i` as the stagger, played going forward; with
+ *     `motion: "auto"` a slide that marks nothing has its blocks staggered in
+ *     for it, its title's words rising out of their lines, and a page's art
+ *     comes up like first light;
  *   - steps: `data-step="n"` holds an element back until the presenter moves
  *     on, a group per number; going back undoes the last group;
  *   - media: a `.media.video` plays while its slide is on, a `.media.demo`
@@ -137,6 +139,19 @@ body.notes-open .viewport{grid-template-columns:1fr min(440px,34vw)}
 @keyframes wa-grow{from{transform:scaleY(0)}}
 @keyframes wa-widen{from{transform:scaleX(0)}}
 @keyframes wa-draw{from{stroke-dashoffset:1}to{stroke-dashoffset:0}}
+/* a title's words rise out of their lines; a statement lights word by word; a photograph opens like a window */
+.wa-w{display:inline-block;overflow:clip;overflow-clip-margin:.14em;vertical-align:top;padding-bottom:.08em;margin-bottom:-.08em}
+.wa-wi{display:inline-block}
+.page.play [data-a="words"],.page.play [data-a="lit"]{animation:none}
+.page.play [data-a="words"] .wa-wi{animation:wa-word 760ms var(--ease) both;animation-delay:calc(min(var(--i,0),12) * 70ms + min(var(--wi,0),24) * 40ms + 60ms)}
+.page.play [data-a="lit"] .wa-wi{animation:wa-lit 420ms linear both;animation-delay:calc(min(var(--i,0),12) * 70ms + min(var(--wi,0),40) * 70ms + 240ms)}
+.page.play [data-a="window"]{animation-name:wa-window;animation-duration:1300ms}
+/* the art of a page (the cover's light, a statement, the close) comes up like first light */
+.page.play>.art{animation:wa-dawn 1800ms var(--ease) both}
+@keyframes wa-word{from{transform:translateY(105%)}}
+@keyframes wa-lit{from{opacity:.16}}
+@keyframes wa-window{from{clip-path:inset(16% 24%);transform:scale(1.06)}to{clip-path:inset(0)}}
+@keyframes wa-dawn{from{opacity:0;transform:translateY(3%)}}
 
 /* media: posters until the slide is on and the media is ready */
 .talk-on .stage .media.video.playing>.poster,.talk-on .stage .media.demo.is-ready>.poster{opacity:0;transition:opacity 400ms var(--ease-io)}
@@ -270,11 +285,29 @@ export const TALK_JS = String.raw`(() => {
     if (s.dataset.motion === "none" || $('[data-a]:not([data-a="count"]), [data-step]', s)) return;
     const content = $(".content", s); if (!content) return;
     let i = 0;
-    const mark = (el) => { if (el.classList.contains("deco") || el.matches("script, style")) return; if (!el.hasAttribute("data-a")) el.setAttribute("data-a", ""); el.style.setProperty("--i", i++); };
+    const mark = (el) => { if (el.classList.contains("deco") || el.matches("script, style")) return; if (!el.hasAttribute("data-a")) el.setAttribute("data-a", el.matches("h1, h2, .display") ? "words" : ""); el.style.setProperty("--i", i++); };
     const walk = (el) => { for (const ch of el.children) { if (ch.matches(GROUPS) && ch.children.length > 1) { for (const g of ch.children) mark(g); } else if (ch.matches(".top, .bottom") ) walk(ch); else mark(ch); } };
     walk(content);
   });
 
+  /* the words of a rising title or a lit statement, each in its own line box (spaces stay text, so lines break as before) */
+  $$('[data-a="words"], [data-a="lit"]').forEach((el) => {
+    let n = 0;
+    const walk = (node) => [...node.childNodes].forEach((ch) => {
+      if (ch.nodeType === 3) {
+        const frag = document.createDocumentFragment();
+        ch.data.split(/(\s+)/).forEach((part) => {
+          if (!part) return;
+          if (/^\s+$/.test(part)) { frag.append(document.createTextNode(part)); return; }
+          const w = document.createElement("span"), i = document.createElement("span");
+          w.className = "wa-w"; i.className = "wa-wi"; i.style.setProperty("--wi", n++); i.textContent = part; w.append(i); frag.append(w);
+        });
+        ch.replaceWith(frag);
+      } else if (ch.nodeType === 1 && !ch.classList.contains("wa-w")) walk(ch);
+    });
+    walk(el);
+  });
+
   /* ------------------------------------------------------------- the scale */
   function fit(box) { const k = box.clientWidth / W; if (k) box.style.setProperty("--k", k); }
   new ResizeObserver(() => { fit(stage); $$(".mini").forEach(fit); }).observe(stage);

package/package.json

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

package/wand.js

@@ -185,7 +185,7 @@ async function components() {
     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",
+    steps: "steps([{ title, when, body, emph }])", list: "list([items])", chapter: "chapter(num)  the deck's numeral panel", img: "img(src, cls, alt)", photo: "photo(nameOrPath, { cls, alt, pos })  a photograph, filled and graded", 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("");