footprint-storydeck 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.0 — a part can have its own look (data-theme)
+
+- **A part can have its own look: `data-theme`.** `<section … data-theme="ledger">` in clicks.html puts
+  `data-theme="ledger"` on each slide of that part (plain or on a map), so a deck's theme.css can give one part its own
+  tokens and pieces — a talk in several parts, each dressed for its subject. A theme is one lower-case name (letters,
+  digits, dashes; 40 at most), refused otherwise with the part's name. A part without one is drawn byte for byte as
+  before.
+  The title and closing slides are parts, so they can have a look of their own. `check` warns (`theme-unstyled`) when a
+  part asks for a theme that theme.css never selects, and `review` ends a click's first line with its theme. The README
+  shows how the page around the slide follows the part on screen (`:root:has([data-deck-active][data-theme=…])`).
+
 ## 0.7.0 — a deck from a folder, an editing loop, co-editing and wire motion
 
 - **A packet rides its wire's curve, and a wire shows itself in.** On a `path` click, a `pkt` packet now follows the

package/README.md

@@ -399,10 +399,20 @@ npx footprint-storydeck build my-talk     # my-talk/index.html — one page, eve
   ticks the line (`- [x]`). Pointing costs the person a second and the agent no screenshot. Each note is signed with a
   key kept with you (`~/.storydeck/key`) for that deck's folder, so a feedback.md that came with someone else's deck is
   never read as your requests: its lines are counted, never listed.
+- **A part can have its own look.** `<section data-label="3 · Storage" … data-theme="ledger">` puts
+  `data-theme="ledger"` on each of that part's slides, so `theme.css` can dress it: redefine the tokens for it
+  (`[data-theme="ledger"] { --bg: …; --text: …; }`, and `:root.dark [data-theme="ledger"]` for dark) and give its pieces
+  their own style. Tokens inherit, so the chrome, the focus and every piece of that part follow. A theme is one
+  lower-case name (letters, digits and dashes); a part without one is drawn as before, byte for byte. The title and the
+  closing slide are parts too, so they can have their own look. To have the page around the slide (the letterbox)
+  follow the part on screen as well, select the active slide in the same rule:
+  `[data-theme="ledger"], :root:has([data-deck-active][data-theme="ledger"]) { … }`. `check` warns about a theme
+  that theme.css never selects (a misspelt name changes nothing), and `review` names each click's theme.
 - **Read first, look last.** A reviewer — a person, or a model that pays for every screenshot — reads the deck as text:
   `outline` (a line per click), `review --click 14` (its headline and words, what it lights, greys, brings in and moves,
   its route, its notes), `check` (what to fix, each with its click and its fix: a headline over 12 words, pieces that
-  light just by coming in, a click that changes nothing, a piece never shown, clicks without notes). `check --layout`
+  light just by coming in, a click that changes nothing, a piece never shown, clicks without notes, a theme theme.css
+  never styles). `check --layout`
   opens the page in a browser, offline, and finds text that spills out of its box (it needs Playwright installed beside
   StoryDeck: `npm i -D footprint-storydeck playwright-core`; without it, it says so and the other checks run). `mcp` serves the same tools to an AI assistant:
   `claude mcp add storydeck -- npx footprint-storydeck mcp my-talk`.

package/dist/deck/check.js

@@ -43,6 +43,16 @@ function missingNotes(compiled) {
   if (!without.length || without.length * 2 > compiled.clicks.length) return [];
   return [problem("info", "no-notes", null, `click${without.length === 1 ? "" : "s"} ${without.map((c) => c.n).join(", ")} ha${without.length === 1 ? "s" : "ve"} no notes \u2014 the presenter view shows nothing there and listen mode skips ${without.length === 1 ? "it" : "them"}`)];
 }
+function unstyledThemes(compiled) {
+  const out = [], seen = /* @__PURE__ */ new Set();
+  for (const c of compiled.clicks) {
+    if (!c.theme || seen.has(c.theme)) continue;
+    seen.add(c.theme);
+    const selects = new RegExp(`\\[\\s*data-theme\\s*[~|^$*]?=\\s*(["']?)${c.theme}\\1\\s*(?:[is]\\s*)?\\]`).test(compiled.themeCss ?? "");
+    if (!selects) out.push(problem("warn", "theme-unstyled", c, `part "${c.part}" asks for data-theme="${c.theme}", which theme.css never selects \u2014 fix the name, or give it its tokens there ([data-theme="${c.theme}"] { --bg: \u2026; })`));
+  }
+  return out;
+}
 function checkDeck(compiled) {
   const out = [];
   compiled.clicks.forEach((c, i) => {
@@ -50,7 +60,7 @@ function checkDeck(compiled) {
     if (c.kind === "map") out.push(...litOnEntry(c, compiled.maps[c.map].pieces));
     out.push(...noChange(c, compiled.clicks[i - 1]));
   });
-  out.push(...neverShown(compiled), ...missingNotes(compiled));
+  out.push(...neverShown(compiled), ...missingNotes(compiled), ...unstyledThemes(compiled));
   return out;
 }
 const failure = (error) => [problem("error", "compile", null, error.message)];

package/dist/deck/compile.js

@@ -73,7 +73,7 @@ function planClicks(parts, maps, { area, canvas, icons }) {
 const head = (kicker, headline) => `<div class="head" data-chrome><div class="kicker">${esc(kicker)}</div>${headline ? `<h2>${headline}</h2>` : ""}</div>`;
 const foot = (footer, n, total) => `<div class="foot" data-chrome><span>${esc(footer)}</span><span class="count">${n} / ${total}</span></div>`;
 function drawClick(c, i, total, { footer, area, canvas }) {
-  const open = `<section data-label="${esc(c.label)}"`;
+  const open = `<section data-label="${esc(c.label)}"${c.part.theme ? ` data-theme="${esc(c.part.theme)}"` : ""}`;
   if (c.kind === "plain") return `${open} class="slide plain">${head(c.part.kicker, "")}${c.inner}${foot(footer, i + 1, total)}</section>`;
   return `${open} class="slide on-map ${slideClass(c.look)}">${head(c.part.kicker, c.headline)}<div class="map map-${c.map.name}">${wrapStage(drawFocus(c.map.html, c.look), c.look)}</div>${focusOverlay(c.look, { area, canvas: { w: canvas[0], h: canvas[1] } })}${foot(footer, i + 1, total)}</section>`;
 }
@@ -108,6 +108,7 @@ function compileDeck(source, { dev = false } = {}) {
     label: c.label,
     part: c.part.label,
     kicker: c.part.kicker,
+    theme: c.part.theme ?? null,
     kind: c.kind,
     map: c.kind === "map" ? c.map.name : null,
     headline: plainText(c.headline),

package/dist/deck/init.js

@@ -24,6 +24,7 @@ const MAP = `<!--
 const CLICKS = `<!--
   The deck, click by click.
   <section data-label="\u2026" data-kicker="\u2026">          one part of the story; without data-map it is one plain slide
+  <section \u2026 data-theme="ledger">                   optional: its slides carry data-theme, so theme.css can dress that part
   <section \u2026 data-map="map">                        a part told on map.html: every <step> inside is ONE click
     <step data-in="\u2026" data-out="\u2026" data-on="\u2026" data-focus="\u2026">
       data-in    pieces that come in (they stay)     data-out   pieces that leave

package/dist/deck/parse.js

@@ -84,6 +84,13 @@ function takeNotes(html) {
 }
 const without = (html, ranges) => ranges.reduceRight((out, r) => out.slice(0, r.start) + out.slice(r.end), html);
 const where = (label) => `"${label}"`;
+const THEME = /^[a-z][a-z0-9-]{0,39}$/;
+function themeOf(label, attrs) {
+  const theme = attrOf(attrs, "data-theme");
+  if (theme === null) return null;
+  if (!THEME.test(theme)) throw new Error(`${where(label)}: data-theme="${theme}" \u2014 a theme is one lower-case name (letters, digits and dashes, at most 40), such as "ledger"`);
+  return theme;
+}
 function readMapStep(label, k, attrs, inner) {
   const { html, notes } = takeNotes(inner);
   let heads;
@@ -113,10 +120,11 @@ function parseClicks(html) {
     seen.add(label);
     const kicker = attrOf(attrs, "data-kicker") ?? "";
     const map = attrOf(attrs, "data-map");
+    const theme = themeOf(label, attrs);
     if (map === null) {
       if (/<step\b/i.test(body)) throw new Error(`${where(label)} has <step> clicks but no data-map \u2014 name the map they are told on (data-map="map")`);
       const { html: inner, notes } = takeNotes(body);
-      parts.push({ label, kicker, map: null, body: inner, notes });
+      parts.push({ label, kicker, theme, map: null, body: inner, notes });
       continue;
     }
     if (!map.trim()) throw new Error(`${where(label)}: data-map is empty \u2014 name a map (a file in the deck, e.g. data-map="map")`);
@@ -129,7 +137,7 @@ function parseClicks(html) {
     if (!steps.length) throw new Error(`${where(label)} is told on map "${map}" but has no <step> \u2014 a map part is one click per <step>`);
     const outside = plainText(takeNotes(without(body, steps)).html);
     if (outside) throw new Error(`${where(label)}: "${outside.slice(0, 60)}" is outside every <step> \u2014 put a headline or notes inside the step they belong to`);
-    parts.push({ label, kicker, map: map.trim(), steps: steps.map(({ attrs: a, inner }, k) => readMapStep(label, k, a, inner)) });
+    parts.push({ label, kicker, theme, map: map.trim(), steps: steps.map(({ attrs: a, inner }, k) => readMapStep(label, k, a, inner)) });
   }
   if (!parts.length) throw new Error('the clicks file has no <section> \u2014 a deck is one <section data-label="\u2026"> per part');
   return parts;

package/dist/deck/review.js

@@ -2,6 +2,7 @@ import { wordCount } from "./parse.js";
 const nameOf = (pieces, i) => pieces[i].keys[0];
 const unique = (names) => [...new Set(names)];
 const list = (names, max = 14) => names.length ? `${names.slice(0, max).join(", ")}${names.length > max ? `, \u2026 (${names.length - max} more)` : ""}` : "\u2014";
+const themed = (c) => c.theme ? ` \xB7 theme ${c.theme}` : "";
 const quote = (s, max = 160) => s.length > max ? `"${s.slice(0, max - 1)}\u2026"` : `"${s}"`;
 function pieceGroups(click, pieces) {
   const by = (pred) => unique(click.look.pieces.map((p, i) => pred(p) ? nameOf(pieces, i) : null).filter(Boolean));
@@ -56,10 +57,10 @@ function reviewClick(compiled, which, { maxWords = compiled.config?.checks?.maxW
   const lines = [];
   const words = (n) => `${n} word${n === 1 ? "" : "s"}`;
   if (c.kind === "plain") {
-    lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (plain slide)`);
+    lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (plain slide)${themed(c)}`);
     lines.push(`text (${words(wordCount(c.text))}): ${quote(c.text, 300)}`);
   } else {
-    lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (map "${c.map}", step ${c.stepIndex + 1} of ${c.steps})`);
+    lines.push(`click ${c.n} of ${compiled.clicks.length} \xB7 "${c.label}" (map "${c.map}", step ${c.stepIndex + 1} of ${c.steps})${themed(c)}`);
     const hw = wordCount(c.headline);
     lines.push(`headline: ${c.headline ? `${quote(c.headline)} (${words(hw)}${hw > maxWords ? `, over ${maxWords}` : ""})` : "\u2014"}`);
     const pieces = compiled.maps[c.map].pieces;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprint-storydeck",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "One source, many lenses — render structured content as a Read article, a Scroll (scrollytelling) story, or a Watch deck; and make a deck from a folder with a live dev loop.",
   "type": "module",
   "license": "MIT",