@codepress/design-kit 0.9.0 → 0.11.0

package/README.md

@@ -351,7 +351,7 @@ fresh browser context, signed in from `auth.storageState` (a Playwright
 storage state file) or from the state the `auth.setup` module's default
 export returns (`async ({ browser, baseUrl, config }) => state`).
 
-- `pages[]`: `{name, title?, path, ready, sourceFile?, slots, layoutSlots?}`.
+- `pages[]`: `{name, title?, path, ready, sourceFile?, slots, layoutSlots?, widths?}`. `widths` names which of `pages.widths` a page is captured at, for a view the app draws at some sizes only; it defaults to all of them.
   `ready` is a Playwright selector that shows once the page has its content.
   `slots` names the regions a mockup replaces: the first selector that matches
   a visible, non-empty element gets `data-kit-slot="<name>"`, and `main` is
@@ -526,7 +526,7 @@ node kit.mjs find button             # ≤ 30 lines: id, kind, width, bytes, tit
 node kit.mjs find "transfer app"     # the words on screen work too
 node kit.mjs show <id> [--full]      # path, size and an outline (≤ 2 KB) or the markup
 node kit.mjs compose --frame route:dashboard@1280 --slot main=new.html \
-  [--theme light|dark] [--show-new] --out page.html
+  [--theme light|dark] [--show-new] [--css pruned|full] --out page.html
 ```
 
 `find` lists the rows holding every word of the query in their id, title,
@@ -558,11 +558,79 @@ the frame, the snippet ids and how many `data-kit-new` elements the page has.
 The record stays in the page: `kit.mjs` makes no network call. Scripts, event handlers,
 `<link>`s and SVG animation are removed, and URLs pass an allowlist: only
 relative references, fragments and `data:` survive, read the way the browser
-reads them. `--theme dark` applies the manifest's theme. Elements marked
-`data-kit-new` get a visible outline with `--show-new`. An unknown frame, slot
+reads them. The one exception is your own code: an inline `<script>` (no
+`src`) in a `--slot` fragment file is kept in place, with only its `type` and
+`id`. Nothing executable from the kit's captured markup survives, a fragment's
+`<script src>` is removed, and `on…=` handlers are removed everywhere, your
+fragments included. `--theme dark` applies the manifest's theme. Elements marked
+`data-kit-new` get a visible outline with `--show-new`, and behaviour triggers
+(below) a blue one. An unknown frame, slot
 or snippet id exits 2, naming near matches. `--kit <dir>` (or
 `DESIGN_KIT_DIR`) points at a kit other than the tool's own folder.
 
+`compose` inlines only the CSS the page can use. Once the body is final, it
+collects every class and id on the page's elements (hidden ones and
+`<template>` content included), every word in your inline scripts (so a class
+a script adds keeps its rules) and the theme classes. A style rule is dropped
+only when every selector in its list needs a class or id the page lacks;
+pseudo-classes, pseudo-elements, attribute parts and the arguments of `:is`,
+`:where`, `:has` and `:not` never count, and escapes (`hover\:bg-muted`,
+`w-\[38px\]`) are read as the browser reads them. Rules inside `@media`,
+`@supports`, `@layer`, `@container` and `@scope` are pruned the same way and
+an emptied block goes (a named `@layer` stays, since it sets the layer
+order). `@font-face`, `@keyframes`, `@property`, other at-rules and rules with
+no class or id are kept as written. A rule repeated in the same at-rule
+context is written once, its last copy. A composed screen drops from
+megabytes to a few hundred KB with identical pixels. A class your script
+builds from pieces (`"is-" + state`) is not seen; `--css full` (option
+`css: "full"`) keeps every rule, as before 0.11.
+
+### Clickable mockups
+
+A composed page can switch tabs, open and close menus and swap between a
+component's captured states on click or tap. Mark it up with these attributes
+in your slot fragment, and `compose` inlines a small behaviour script once, at
+the end of the body (no network, no storage; it works in a
+`sandbox="allow-scripts"` frame). A page that uses none of them composes
+exactly as before.
+
+| Attribute                                       | What a click does                                                                                                                                                                                    |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-kit-toggle="<id>"` on a trigger           | Shows or hides the element with that id and sets `aria-expanded`. A click outside it, or Esc, closes what a toggle opened.                                                                           |
+| `data-kit-tabs` on a container                  | Its `[data-kit-tab="<name>"]` triggers show the matching `[data-kit-panel="<name>"]` and hide the others, with `aria-selected`. The first tab starts selected unless one has `aria-selected="true"`. |
+| `data-kit-state="<group>:<name>"` on each state | Nothing by itself: the group starts in the state of its first element without `hidden`.                                                                                                              |
+| `data-kit-set="<group>:<name>"` on a trigger    | Shows every element of the group in that state and hides the rest of the group.                                                                                                                      |
+
+To make captured stories interactive, compose each state as its own snippet
+and put the attributes on the `<kit-snippet>`: they (and `hidden`) are copied
+onto every top-level element the snippet expands to, a story's portal
+included.
+
+```html
+<kit-snippet
+  id="story:primitives-dropdownmenu--closed@1280"
+  data-kit-state="menu:closed"
+  data-kit-set="menu:open"
+></kit-snippet>
+<kit-snippet
+  id="story:primitives-dropdownmenu--open@1280"
+  data-kit-state="menu:open"
+  data-kit-set="menu:closed"
+  hidden
+></kit-snippet>
+```
+
+A click anywhere on the closed story shows the open one, and a click on the
+open one goes back. Links and buttons inside a trigger only switch the state;
+they do not navigate or submit. A trigger that already has `data-state`
+(Radix-style markup) gets `open`/`closed` or `active`/`inactive` there too, so
+its own styling follows, and a trigger that is not a button or link gets
+`tabindex="0"` so Enter and Space work. Elements the behaviours hide are
+hidden even when their own CSS sets a `display`. Native interactivity needs
+nothing: `<details>`/`<summary>`, `popover` with `popovertarget`, form
+controls and `aria-*` all survive compose. Anything else is a few lines of
+your own `<script>` in the fragment.
+
 ## Programmatic use
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {

package/schema/design-kit.config.schema.json

@@ -280,6 +280,12 @@
           "description": "The page's source module, shown by `kit show` and searched by `kit find`."
         },
         "slots": { "$ref": "#/$defs/slots" },
+        "widths": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "integer", "minimum": 1 },
+          "description": "Only these of `pages.widths`, for a page the app draws at some sizes only (a laptop-only rail tab). Default: every width."
+        },
         "layoutSlots": {
           "type": "object",
           "description": "Slots for a layout the detector reports, replacing `slots` there.",

package/src/capture-pages.mjs

@@ -543,6 +543,7 @@ export async function capturePages(config, options = {}) {
     for (const viewport of settings.widths) {
       for (const page of pages) {
         if (session.interrupted) return 130;
+        if (page.widths && !page.widths.includes(viewport.width)) continue;
         const id = kitRouteId(page.name, viewport.width);
         const context = await session.browser.newContext({
           baseURL: baseUrl,

package/src/kit.d.ts

@@ -95,9 +95,21 @@ export function compose(
     showNew?: boolean;
     /** Bytes of markup the page may grow to through snippets. */
     maxBytes?: number;
+    /**
+     * `pruned` (the default) keeps only the CSS rules the page's classes and
+     * ids can use, each repeated rule once; `full` keeps every rule.
+     */
+    css?: "pruned" | "full";
   },
 ): string;
 
+/**
+ * The stylesheet without the style rules that need a class or id missing
+ * from `names`, and with each rule repeated in the same at-rule context
+ * written once (its last copy).
+ */
+export function pruneCss(css: string, names: Set<string>): string;
+
 /** The default `maxBytes` of `compose`: 32 MB. */
 export const COMPOSE_MAX_BYTES: number;
 

package/src/kit.mjs

@@ -7,11 +7,12 @@
  *   node kit.mjs find <query>        (ids, titles and the words on screen)
  *   node kit.mjs show <id> [--full]
  *   node kit.mjs compose --frame <id> [--slot <name>=<file>]… [--theme light|dark]
- *                        [--show-new] --out <file>
+ *                        [--show-new] [--css pruned|full] --out <file>
  *
  * `--kit <dir>` (or DESIGN_KIT_DIR) points at a kit; the default is the
  * folder this file sits in. Format: the @codepress/design-kit README.
  */
+import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -185,11 +186,34 @@ function parseAttributes(source) {
   const pattern = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
   let match;
   while ((match = pattern.exec(source))) {
-    attrs[match[1].toLowerCase()] = match[2] ?? match[3] ?? match[4] ?? "";
+    const name = match[1].toLowerCase();
+    // The browser keeps the first of two same-named attributes, so the
+    // sanitizer must check that one: `<img src="https://…" src="a.png">`
+    // loads the remote one.
+    if (!Object.hasOwn(attrs, name))
+      attrs[name] = match[2] ?? match[3] ?? match[4] ?? "";
   }
   return attrs;
 }
 
+/**
+ * Where the comment opening at `lt` ends, as the browser reads it: `<!-->`
+ * and `<!--->` are empty comments, and `--!>` closes a comment as well as
+ * `-->`. Reading a comment as longer than the browser does would let markup
+ * after its real end pass the sanitizer as comment text.
+ */
+function commentEnd(html, lt) {
+  if (html.startsWith(">", lt + 4)) return lt + 5;
+  if (html.startsWith("->", lt + 4)) return lt + 6;
+  const ends = [
+    [html.indexOf("-->", lt + 4), 3],
+    [html.indexOf("--!>", lt + 4), 4],
+  ].filter(([at]) => at >= 0);
+  if (!ends.length) return html.length;
+  const [at, length] = ends.reduce((a, b) => (b[0] < a[0] ? b : a));
+  return at + length;
+}
+
 /** Tokens with offsets: open / close / text / comment. */
 export function tokenize(html) {
   return [...scan(html)];
@@ -207,10 +231,8 @@ function* scan(html) {
     }
     if (lt > i) yield { type: "text", start: i, end: lt };
     if (html.startsWith("<!--", lt)) {
-      const close = html.indexOf("-->", lt + 4);
-      const end = close < 0 ? html.length : close + 3;
-      yield { type: "comment", start: lt, end };
-      i = end;
+      yield { type: "comment", start: lt, end: commentEnd(html, lt) };
+      i = commentEnd(html, lt);
       continue;
     }
     const closing = html[lt + 1] === "/";
@@ -339,6 +361,8 @@ const DROPPED = new Set(["script", "link", "base", "meta", "set", "animate"]);
 /** Dropped with everything inside them: scripts, and SVG animation, which can
  *  set an href to a remote URL after load. */
 const DROPPED_WITH_CONTENT = new Set(["script", "set", "animate"]);
+/** Elements this scanner reads as raw text that foreign content parses as markup. */
+const RAW_TEXT = new Set(["style", "title", "textarea"]);
 
 /**
  * Named character references the decoder knows: every HTML name for an ASCII
@@ -528,10 +552,23 @@ export function sanitizeMarkup(html) {
   for (let t = 0; t < tokens.length; t += 1) {
     const token = tokens[t];
     if (token.type !== "open") continue;
-    if (DROPPED.has(token.name)) {
+    // Inside <svg> or <math> the browser parses a <style>, <title> or
+    // <textarea>'s content as markup (`<svg><style><img onerror=…>`), where
+    // this scanner reads raw text. One whose text holds anything tag-like is
+    // dropped with its content, wherever it sits.
+    const text = tokens[t + 1];
+    const markupInRaw =
+      RAW_TEXT.has(token.name) &&
+      !token.selfClosing &&
+      text?.type === "text" &&
+      /<[a-z!/?]/i.test(html.slice(text.start, text.end));
+    if (DROPPED.has(token.name) || markupInRaw) {
       out += html.slice(i, token.start);
       i = token.end;
-      if (DROPPED_WITH_CONTENT.has(token.name) && !token.selfClosing) {
+      if (
+        (DROPPED_WITH_CONTENT.has(token.name) || markupInRaw) &&
+        !token.selfClosing
+      ) {
         const close = tokens.findIndex(
           (n, k) => k > t && n.type === "close" && n.name === token.name,
         );
@@ -594,7 +631,6 @@ export function sanitizeMarkup(html) {
       out += `${html.slice(i, token.start)}<${token.name}${attrs}${token.selfClosing && !VOID.has(token.name) ? " /" : ""}>`;
       i = token.end;
     }
-    const text = tokens[t + 1];
     if (token.name === "style" && text?.type === "text") {
       out +=
         html.slice(i, text.start) +
@@ -709,6 +745,596 @@ export function inlineAssets(kit, css, cssDir = join(kit.dir, "css")) {
   );
 }
 
+// ── behaviours (clickable mockups) ──────────────────────────────────────────
+
+/** Attributes that make compose inline the behaviour script. */
+const BEHAVIOUR_ATTRS = [
+  "data-kit-toggle",
+  "data-kit-tabs",
+  "data-kit-tab",
+  "data-kit-panel",
+  "data-kit-state",
+  "data-kit-set",
+];
+
+/**
+ * Hides what the behaviours hide even when the element's own CSS sets a
+ * display (a captured story root with `display:flex` would ignore `hidden`).
+ * The script marks toggle targets with `data-kit-target`.
+ */
+const BEHAVIOURS_CSS =
+  "\n[data-kit-panel][hidden],[data-kit-state][hidden],[data-kit-target][hidden]{display:none !important}";
+
+/** --show-new outlines behaviour triggers too, in a second colour. */
+const SHOW_TRIGGERS_CSS =
+  "\n[data-kit-toggle],[data-kit-tab],[data-kit-set]{outline:2px dashed #0090ff !important;outline-offset:2px}";
+
+/**
+ * The behaviour layer compose inlines once, at the end of the body, when the
+ * page uses one of BEHAVIOUR_ATTRS. Plain DOM, no network and no storage, so
+ * it runs in a `sandbox="allow-scripts"` frame with an opaque origin.
+ *
+ * - `data-kit-toggle="<id>"`: a click shows or hides the element with that
+ *   id and sets `aria-expanded` on its triggers; a click outside it, or Esc,
+ *   closes what a toggle opened.
+ * - `data-kit-tabs` holds `[data-kit-tab="<name>"]` triggers and
+ *   `[data-kit-panel="<name>"]` panels; a click shows its panel, hides the
+ *   others and sets `aria-selected`.
+ * - `data-kit-set="<group>:<name>"` shows every `[data-kit-state]` of the
+ *   group in that state and hides the rest of the group.
+ *
+ * A trigger that already has `data-state` (Radix-style markup) gets
+ * open/closed or active/inactive there as well, so its captured styling
+ * follows. Triggers that are not focusable get `tabindex="0"`, and Enter or
+ * Space clicks them.
+ */
+const BEHAVIOURS_JS = `(function () {
+  "use strict";
+  if (window.__designKitBehaviours) return;
+  window.__designKitBehaviours = true;
+  var doc = document;
+  var TRIGGERS = "[data-kit-toggle],[data-kit-tab],[data-kit-set]";
+  var NATIVE = /^(A|BUTTON|INPUT|SELECT|TEXTAREA|SUMMARY)$/;
+  var opened = [];
+  function list(selector, root) {
+    return Array.prototype.slice.call((root || doc).querySelectorAll(selector));
+  }
+  function show(el, on) {
+    if (on) el.removeAttribute("hidden");
+    else el.setAttribute("hidden", "");
+  }
+  function pair(value) {
+    var at = (value || "").indexOf(":");
+    return at > 0 ? [value.slice(0, at), value.slice(at + 1)] : null;
+  }
+  function mirror(el, value) {
+    if (el.hasAttribute("data-state")) el.setAttribute("data-state", value);
+  }
+  function focusable(el) {
+    if (NATIVE.test(el.tagName) || el.hasAttribute("tabindex")) return;
+    el.setAttribute("tabindex", "0");
+    if (!el.hasAttribute("role")) {
+      el.setAttribute("role", el.hasAttribute("data-kit-tab") ? "tab" : "button");
+    }
+  }
+
+  function triggersOf(id) {
+    return list("[data-kit-toggle]").filter(function (t) {
+      return t.getAttribute("data-kit-toggle") === id;
+    });
+  }
+  function setOpen(target, open) {
+    show(target, open);
+    triggersOf(target.id).forEach(function (t) {
+      t.setAttribute("aria-expanded", open ? "true" : "false");
+      mirror(t, open ? "open" : "closed");
+    });
+    var at = opened.indexOf(target);
+    if (open && at < 0) opened.push(target);
+    if (!open && at >= 0) opened.splice(at, 1);
+  }
+  function closeOpened(clicked) {
+    opened.slice().forEach(function (target) {
+      var inside =
+        clicked &&
+        (target.contains(clicked) ||
+          triggersOf(target.id).some(function (t) {
+            return t.contains(clicked);
+          }));
+      if (!inside) setOpen(target, false);
+    });
+  }
+
+  function own(box, selector) {
+    return list(selector, box).filter(function (el) {
+      return el.closest("[data-kit-tabs]") === box;
+    });
+  }
+  function selectTab(box, name) {
+    own(box, "[data-kit-tab]").forEach(function (t) {
+      var on = t.getAttribute("data-kit-tab") === name;
+      t.setAttribute("aria-selected", on ? "true" : "false");
+      mirror(t, on ? "active" : "inactive");
+    });
+    own(box, "[data-kit-panel]").forEach(function (p) {
+      var on = p.getAttribute("data-kit-panel") === name;
+      show(p, on);
+      mirror(p, on ? "active" : "inactive");
+    });
+  }
+
+  function setState(group, name) {
+    list("[data-kit-state]").forEach(function (el) {
+      var state = pair(el.getAttribute("data-kit-state"));
+      if (state && state[0] === group) show(el, state[1] === name);
+    });
+  }
+
+  list("[data-kit-toggle]").forEach(function (t) {
+    focusable(t);
+    var target = doc.getElementById(t.getAttribute("data-kit-toggle"));
+    if (!target) return;
+    target.setAttribute("data-kit-target", "");
+    t.setAttribute("aria-controls", target.id);
+    t.setAttribute("aria-expanded", target.hasAttribute("hidden") ? "false" : "true");
+  });
+  list("[data-kit-tabs]").forEach(function (box) {
+    var tabs = own(box, "[data-kit-tab]");
+    if (!tabs.length) return;
+    tabs.forEach(focusable);
+    var current = tabs.filter(function (t) {
+      return t.getAttribute("aria-selected") === "true" || t.getAttribute("data-state") === "active";
+    })[0] || tabs[0];
+    selectTab(box, current.getAttribute("data-kit-tab"));
+  });
+  // Each group starts in the state of its first visible element.
+  var groups = Object.create(null);
+  list("[data-kit-state]").forEach(function (el) {
+    var state = pair(el.getAttribute("data-kit-state"));
+    if (state && !(state[0] in groups) && !el.hasAttribute("hidden")) groups[state[0]] = state[1];
+  });
+  Object.keys(groups).forEach(function (group) {
+    setState(group, groups[group]);
+  });
+  list("[data-kit-set]").forEach(focusable);
+
+  doc.addEventListener("click", function (event) {
+    var el = event.target;
+    if (!el || !el.closest) return;
+    closeOpened(el);
+    var trigger = el.closest(TRIGGERS);
+    if (!trigger) return;
+    // A link or button in a trigger (a captured story's own links) would
+    // navigate the mockup away or submit; the click only switches state.
+    var control = el.closest("a,button");
+    if (control && trigger.contains(control)) event.preventDefault();
+    var state = pair(trigger.getAttribute("data-kit-set"));
+    if (state) setState(state[0], state[1]);
+    var box = trigger.hasAttribute("data-kit-tab") && trigger.closest("[data-kit-tabs]");
+    if (box) selectTab(box, trigger.getAttribute("data-kit-tab"));
+    if (trigger.hasAttribute("data-kit-toggle")) {
+      var target = doc.getElementById(trigger.getAttribute("data-kit-toggle"));
+      if (target) setOpen(target, target.hasAttribute("hidden"));
+    }
+  });
+  doc.addEventListener("keydown", function (event) {
+    var el = event.target;
+    if (event.key === "Escape" && opened.length) {
+      var back = triggersOf(opened[opened.length - 1].id)[0];
+      closeOpened(null);
+      if (back && back.focus) back.focus();
+      return;
+    }
+    if (
+      (event.key === "Enter" || event.key === " ") &&
+      el && el.matches && el.matches(TRIGGERS) && !NATIVE.test(el.tagName)
+    ) {
+      event.preventDefault();
+      el.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    }
+  });
+})();`;
+
+/**
+ * The author's own inline scripts in a slot fragment, held out of compose:
+ * each becomes a comment placeholder carrying `key` (random per compose, so
+ * kit markup cannot name one) before snippets expand and the sanitizer runs,
+ * and comes back after. A script with `src`, `href` or `xlink:href` stays in
+ * place for the sanitizer to drop, as does an unterminated one and an earlier
+ * compose's behaviour script (compose inlines a fresh one). Only `type` and
+ * `id` are kept on the tag.
+ */
+function holdAuthorScripts(content, key, held) {
+  if (!/<script/i.test(content)) return content;
+  const tokens = tokenize(content);
+  let out = "";
+  let i = 0;
+  for (let t = 0; t < tokens.length; t += 1) {
+    const token = tokens[t];
+    if (token.type !== "open" || token.name !== "script" || token.selfClosing)
+      continue;
+    let close = t + 1;
+    if (tokens[close]?.type === "text") close += 1;
+    if (tokens[close]?.type !== "close" || tokens[close].name !== "script")
+      continue;
+    t = close;
+    const attrs = token.attrs;
+    if (
+      ["src", "href", "xlink:href", "data-kit-behaviours"].some((name) =>
+        Object.hasOwn(attrs, name),
+      )
+    )
+      continue;
+    const kept = ["type", "id"]
+      .filter((name) => Object.hasOwn(attrs, name))
+      .map((name) => ` ${name}="${escapeAttr(decodeEntities(attrs[name]))}"`)
+      .join("");
+    out += `${content.slice(i, token.start)}<!--kit-author-script ${key} ${held.length}-->`;
+    held.push(
+      `<script${kept}>${content.slice(token.end, tokens[close].start)}</script>`,
+    );
+    i = tokens[close].end;
+  }
+  return out + content.slice(i);
+}
+
+/** Each held script back in its placeholder's place, once. */
+function restoreAuthorScripts(html, key, held) {
+  if (!held.length) return html;
+  const placed = new Set();
+  return html.replace(
+    new RegExp(`<!--kit-author-script ${key} (\\d+)-->`, "g"),
+    (_, n) => {
+      const index = Number(n);
+      if (placed.has(index) || index >= held.length) return "";
+      placed.add(index);
+      return held[index];
+    },
+  );
+}
+
+// ── CSS pruning ─────────────────────────────────────────────────────────────
+//
+// A composed page carries the kit's whole stylesheets, megabytes of rules for
+// classes the page never names. compose keeps only the rules a page can use:
+// a style rule goes only when every selector in its list needs a class or id
+// the page lacks, and of rules repeated in the same at-rule context only the
+// last stays (it is the one the cascade uses). Everything else (@font-face,
+// @keyframes, @property, rules with no class or id) stays as written.
+
+/** At-rules whose blocks hold rules that are pruned like the top level. */
+const CSS_WRAPPERS = new Set([
+  "media",
+  "supports",
+  "layer",
+  "container",
+  "scope",
+]);
+
+const CSS_IDENT_CHAR = /[A-Za-z0-9_\-\u0080-￿]/;
+
+/**
+ * Where the CSS token at `i` ends when it is one whose characters never count
+ * as structure (an escape, a comment, a string or an unquoted `url(…)`);
+ * otherwise -1.
+ */
+function cssSkip(css, i) {
+  const ch = css[i];
+  if (ch === "\\") return Math.min(i + 2, css.length);
+  if (ch === "/" && css[i + 1] === "*") {
+    const end = css.indexOf("*/", i + 2);
+    return end < 0 ? css.length : end + 2;
+  }
+  if (ch === '"' || ch === "'") {
+    let j = i + 1;
+    while (j < css.length) {
+      const c = css[j];
+      if (c === "\\") j += 2;
+      else if (c === ch) return j + 1;
+      // An unterminated string ends at the line's end, as the browser reads it.
+      else if (c === "\n") return j;
+      else j += 1;
+    }
+    return css.length;
+  }
+  if (
+    (ch === "u" || ch === "U") &&
+    (i === 0 || !CSS_IDENT_CHAR.test(css[i - 1])) &&
+    /^url\(\s*[^\s"')]/i.test(css.slice(i, i + 64))
+  ) {
+    let j = css.indexOf("(", i) + 1;
+    while (j < css.length && css[j] !== ")") j += css[j] === "\\" ? 2 : 1;
+    return Math.min(j + 1, css.length);
+  }
+  return -1;
+}
+
+/** The first `{`, `;` or `}` outside brackets from `i`, or `end`. */
+function cssPreludeEnd(css, i, end) {
+  let nested = 0;
+  while (i < end) {
+    const skip = cssSkip(css, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = css[i];
+    if (ch === "(" || ch === "[") nested += 1;
+    else if ((ch === ")" || ch === "]") && nested > 0) nested -= 1;
+    else if (!nested && (ch === "{" || ch === ";" || ch === "}")) return i;
+    i += 1;
+  }
+  return end;
+}
+
+/** Just past the `}` that closes the block opening at `open`, or -1. */
+function cssBlockEnd(css, open, end) {
+  let depth = 0;
+  let i = open;
+  while (i < end) {
+    const skip = cssSkip(css, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    if (css[i] === "{") depth += 1;
+    else if (css[i] === "}" && --depth === 0) return i + 1;
+    i += 1;
+  }
+  return -1;
+}
+
+/**
+ * A list of rules as nodes: `rule` (a style rule, kept or dropped whole),
+ * `wrapper` (an at-rule from CSS_WRAPPERS, pruned inside) and `keep`
+ * (everything else, written back as it was). Comments between rules go.
+ */
+function parseCssList(css, start, end) {
+  const nodes = [];
+  let i = start;
+  while (i < end) {
+    const ch = css[i];
+    if (/\s/.test(ch)) {
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && css[i + 1] === "*") {
+      i = cssSkip(css, i);
+      continue;
+    }
+    const stop = cssPreludeEnd(css, i, end);
+    if (stop >= end || css[stop] !== "{") {
+      // A statement (`@layer a, b;`) or junk the browser skips: as written.
+      const through = Math.min(stop + 1, end);
+      nodes.push({ type: "keep", text: css.slice(i, through) });
+      i = through;
+      continue;
+    }
+    const closedAt = cssBlockEnd(css, stop, end);
+    const closed = closedAt >= 0;
+    const blockEnd = closed ? closedAt : end;
+    const prelude = css.slice(i, stop);
+    const atRule = /^@([A-Za-z-]+)/.exec(prelude);
+    const name = atRule?.[1].toLowerCase();
+    if (name && CSS_WRAPPERS.has(name)) {
+      const layerName = prelude.slice(atRule[0].length).trim();
+      nodes.push({
+        type: "wrapper",
+        head: css.slice(i, stop + 1),
+        // A named layer's first block sets the layer order, so even an
+        // emptied one stays; each unnamed layer is a layer of its own.
+        named: name === "layer" && layerName !== "",
+        anonymous: name === "layer" && layerName === "",
+        children: parseCssList(css, stop + 1, closed ? blockEnd - 1 : blockEnd),
+      });
+    } else if (name) {
+      nodes.push({ type: "keep", text: css.slice(i, blockEnd) });
+    } else {
+      nodes.push({ type: "rule", prelude, text: css.slice(i, blockEnd) });
+    }
+    i = blockEnd;
+  }
+  return nodes;
+}
+
+/**
+ * A rule's text with comments gone and whitespace outside strings collapsed,
+ * so the same rule written by two sheets compares equal.
+ */
+function cssKey(text) {
+  let out = "";
+  // Whether `out` ends in an escape, string or url(): its last character is
+  // then not the punctuation it looks like (`.\\{ .a` keeps its space).
+  let quoted = false;
+  let i = 0;
+  while (i < text.length) {
+    const skip = cssSkip(text, i);
+    if (skip >= 0) {
+      if (text[i] !== "/") {
+        out += text.slice(i, skip);
+        quoted = true;
+      }
+      i = skip;
+      continue;
+    }
+    if (/\s/.test(text[i])) {
+      while (i < text.length && /\s/.test(text[i])) i += 1;
+      const afterPunctuation = !quoted && /[{};,]$/.test(out);
+      if (!afterPunctuation && !/^[{};,]/.test(text[i] ?? "")) out += " ";
+      continue;
+    }
+    out += text[i];
+    quoted = false;
+    i += 1;
+  }
+  return out.trim();
+}
+
+/** The parts of a selector list, split on commas outside brackets. */
+function selectorParts(prelude) {
+  const parts = [];
+  let nested = 0;
+  let from = 0;
+  let i = 0;
+  while (i < prelude.length) {
+    const skip = cssSkip(prelude, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = prelude[i];
+    if (ch === "(" || ch === "[") nested += 1;
+    else if ((ch === ")" || ch === "]") && nested > 0) nested -= 1;
+    else if (ch === "," && !nested) {
+      parts.push(prelude.slice(from, i));
+      from = i + 1;
+    }
+    i += 1;
+  }
+  parts.push(prelude.slice(from));
+  return parts;
+}
+
+/** Just past the bracket closing the one at `i`. */
+function closeBracket(text, i) {
+  let depth = 0;
+  while (i < text.length) {
+    const skip = cssSkip(text, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    const ch = text[i];
+    if (ch === "(" || ch === "[") depth += 1;
+    else if ((ch === ")" || ch === "]") && --depth === 0) return i + 1;
+    i += 1;
+  }
+  return text.length;
+}
+
+/** The identifier at `i`, escapes resolved, and where it ends. */
+function readCssIdent(text, i) {
+  let j = i;
+  while (j < text.length) {
+    if (text[j] === "\\" && j + 1 < text.length && text[j + 1] !== "\n") {
+      const hex = /^[0-9a-fA-F]{1,6}\s?/.exec(text.slice(j + 1, j + 8));
+      j += 1 + (hex ? hex[0].length : 1);
+    } else if (CSS_IDENT_CHAR.test(text[j])) j += 1;
+    else break;
+  }
+  return [unescapeCss(text.slice(i, j)), j];
+}
+
+/**
+ * Whether one selector can match on the page: every class and id it needs is
+ * there. Attribute parts and the arguments of functional pseudo-classes and
+ * pseudo-elements (`:is`, `:where`, `:has`, `:not`, `::part`, …) never count.
+ */
+function selectorCanMatch(selector, names) {
+  let i = 0;
+  while (i < selector.length) {
+    const ch = selector[i];
+    if (ch === "[" || ch === "(") {
+      i = closeBracket(selector, i);
+      continue;
+    }
+    const skip = cssSkip(selector, i);
+    if (skip >= 0) {
+      i = skip;
+      continue;
+    }
+    if (ch === "." || ch === "#") {
+      const [name, next] = readCssIdent(selector, i + 1);
+      if (name && !names.has(name)) return false;
+      i = Math.max(next, i + 1);
+      continue;
+    }
+    if (CSS_IDENT_CHAR.test(ch)) {
+      // A tag name or pseudo name: read whole, so a `.` cannot start inside.
+      i = readCssIdent(selector, i)[1];
+      continue;
+    }
+    i += 1;
+  }
+  return true;
+}
+
+/**
+ * Kept rules as text, last-first so the last copy of a repeated rule is the
+ * one kept. `context` names the at-rules around them; `seen` is shared.
+ */
+function prunedCss(nodes, names, context, seen, counter) {
+  const out = [];
+  for (let n = nodes.length - 1; n >= 0; n -= 1) {
+    const node = nodes[n];
+    if (node.type === "rule") {
+      if (
+        !selectorParts(node.prelude).some((part) =>
+          selectorCanMatch(part, names),
+        )
+      )
+        continue;
+      const key = `${context}\u0000${cssKey(node.text)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(node.text);
+    } else if (node.type === "wrapper") {
+      const inner = prunedCss(
+        node.children,
+        names,
+        `${context}\u0001${cssKey(node.head)}${node.anonymous ? `#${(counter.n += 1)}` : ""}`,
+        seen,
+        counter,
+      );
+      if (!inner.length && !node.named) continue;
+      out.push(`${node.head}\n${inner.join("\n")}\n}`);
+    } else {
+      out.push(node.text);
+    }
+  }
+  return out.reverse();
+}
+
+/**
+ * The stylesheet with every style rule no element can match removed and
+ * repeated rules written once (see the section comment). `names` holds every
+ * class and id the page can have.
+ */
+export function pruneCss(css, names) {
+  return prunedCss(parseCssList(css, 0, css.length), names, "", new Set(), {
+    n: 0,
+  }).join("\n");
+}
+
+/**
+ * Every class and id a composed page can show: those on its elements (hidden
+ * ones and <template> content included), every word in the author's own
+ * scripts (one may add a class), and the theme classes.
+ */
+function pageNames(elementList, scripts, theme) {
+  const names = new Set(["dark", "light"]);
+  if (theme.attribute === "class") {
+    for (const value of [theme.dark, theme.light]) if (value) names.add(value);
+  }
+  for (const element of elementList) {
+    const { class: classes, id } = element.attrs;
+    if (classes) {
+      for (const name of decodeEntities(classes).split(/[\t\n\f\r ]+/)) {
+        if (name) names.add(name);
+      }
+    }
+    if (id) names.add(decodeEntities(id));
+  }
+  for (const script of scripts) {
+    for (const word of script.split(/[\s"'`]+/)) {
+      if (!word) continue;
+      names.add(word);
+      names.add(word.replace(/^[.#]+/, ""));
+    }
+  }
+  return names;
+}
+
 // ── compose ─────────────────────────────────────────────────────────────────
 
 /**
@@ -717,23 +1343,37 @@ export function inlineAssets(kit, css, cssDir = join(kit.dir, "css")) {
  * nested `<kit-snippet>` at the top is left alone: its own expansion stamps
  * the elements that replace it.
  */
-function stampSnippetRoots(html, id) {
-  const roots = elements(html).filter(
-    (e) =>
-      e.depth === 0 &&
-      e.name !== "kit-snippet" &&
-      !("data-kit-snippet" in e.attrs),
-  );
+function stampSnippetRoots(html, id, carried = "") {
   let out = "";
   let i = 0;
-  for (const root of roots) {
+  for (const root of elements(html)) {
+    if (root.depth !== 0) continue;
+    const stamp =
+      root.name !== "kit-snippet" && !("data-kit-snippet" in root.attrs)
+        ? ` data-kit-snippet="${escapeAttr(id)}"`
+        : "";
+    if (!stamp && !carried) continue;
     const at = root.start + 1 + root.name.length;
-    out += `${html.slice(i, at)} data-kit-snippet="${escapeAttr(id)}"`;
+    out += `${html.slice(i, at)}${stamp}${carried}`;
     i = at;
   }
   return out + html.slice(i);
 }
 
+/**
+ * The behaviour attributes a `<kit-snippet>` passes on to the top-level
+ * elements of the markup it expands to, so a captured story can be one state
+ * of a group (`data-kit-state`), a trigger, a tab or a panel. They go first
+ * in the tag, so they win over any the captured element already has.
+ */
+const CARRIED_ATTRS = ["hidden", ...BEHAVIOUR_ATTRS];
+
+function carriedAttributes(attrs) {
+  return CARRIED_ATTRS.filter((name) => Object.hasOwn(attrs, name))
+    .map((name) => ` ${name}="${escapeAttr(decodeEntities(attrs[name]))}"`)
+    .join("");
+}
+
 function expandSnippets(kit, html, used, budget, depth = 0, ids = []) {
   const found = elements(html).filter((e) => e.name === "kit-snippet");
   if (!found.length) return html;
@@ -763,7 +1403,7 @@ function expandSnippets(kit, html, used, budget, depth = 0, ids = []) {
       html.slice(i, element.start) +
       expandSnippets(
         kit,
-        stampSnippetRoots(markup, row.id),
+        stampSnippetRoots(markup, row.id, carriedAttributes(element.attrs)),
         used,
         budget,
         depth + 1,
@@ -887,7 +1527,12 @@ function attributes(captured, extraClass, theme, choice, target, fixed) {
 /**
  * One self-contained page: the frame's markup with slots filled and
  * snippets expanded, its CSS (and that of any other source a snippet came
- * from) inlined with fonts as data URIs, and no scripts or remote URLs.
+ * from) inlined with fonts as data URIs, and no remote URLs. Only the rules
+ * the page's classes and ids can use are kept, each once (see pruneCss);
+ * `css: "full"` keeps every rule. The only
+ * scripts are the inline ones the slot fragments brought and, when the page
+ * uses a behaviour attribute, the behaviour layer; nothing executable from
+ * the kit's own markup survives.
  */
 export function compose(
   kit,
@@ -897,16 +1542,30 @@ export function compose(
     theme = "light",
     showNew = false,
     maxBytes = COMPOSE_MAX_BYTES,
+    css: cssMode = "pruned",
   },
 ) {
   const row = requireRow(kit, frame, "frame");
   if (theme !== "light" && theme !== "dark") {
     throw new KitError(`unknown theme "${theme}". Use light or dark.`);
   }
+  if (cssMode !== "pruned" && cssMode !== "full") {
+    throw new KitError(`unknown css "${cssMode}". Use pruned or full.`);
+  }
   const used = new Set([rowCssFile(kit, row)]);
-  const filled = fillSlots(kit, row, readSnippet(kit, row), slots);
+  // The author's inline scripts sit out the sanitizer; everything else in
+  // the fragments (handlers, remote scripts, snippets) goes through it.
+  const scriptKey = randomBytes(16).toString("hex");
+  const heldScripts = [];
+  const authored = Array.isArray(slots)
+    ? slots.map((slot) => ({
+        ...slot,
+        content: holdAuthorScripts(slot.content, scriptKey, heldScripts),
+      }))
+    : slots;
+  const filled = fillSlots(kit, row, readSnippet(kit, row), authored);
   const snippetIds = [];
-  const body = sanitizeMarkup(
+  const sanitized = sanitizeMarkup(
     expandSnippets(
       kit,
       filled,
@@ -916,6 +1575,11 @@ export function compose(
       snippetIds,
     ),
   );
+  const bodyElements = elements(sanitized);
+  const behaves = bodyElements.some((e) =>
+    BEHAVIOUR_ATTRS.some((name) => Object.hasOwn(e.attrs, name)),
+  );
+  const body = restoreAuthorScripts(sanitized, scriptKey, heldScripts);
 
   // Stories' sheet first, then the route sheets, as before page sources.
   const storiesCss = cssFile(kit, "stories");
@@ -931,8 +1595,14 @@ export function compose(
       return inlineAssets(kit, readFileSync(file, "utf8"), dirname(file));
     })
     .join("\n");
-  const showNewCss = showNew
-    ? "\n[data-kit-new]{outline:2px dashed #e5484d !important;outline-offset:2px}"
+  const showNewCss =
+    (showNew
+      ? "\n[data-kit-new]{outline:2px dashed #e5484d !important;outline-offset:2px}"
+      : "") +
+    (behaves ? BEHAVIOURS_CSS : "") +
+    (showNew && behaves ? SHOW_TRIGGERS_CSS : "");
+  const behaviourScript = behaves
+    ? `<script data-kit-behaviours>\n${BEHAVIOURS_JS}\n</script>\n`
     : "";
 
   const switcher = kitTheme(kit.manifest);
@@ -950,13 +1620,30 @@ export function compose(
     "body",
     {},
   );
+  // The kit's CSS, cut to the rules this page's classes and ids can use
+  // (`css: "full"` keeps every rule).
+  const safeCss = sanitizeCss(css);
+  const pageCss =
+    cssMode === "full"
+      ? safeCss
+      : pruneCss(
+          safeCss,
+          pageNames(
+            [
+              ...bodyElements,
+              ...elements(`<html${htmlAttrs}><body${bodyAttrs}>`),
+            ],
+            heldScripts,
+            switcher,
+          ),
+        );
   // What this page used, for whoever wants to count it later. Recorded in
   // the page only; kit.mjs never sends it anywhere.
   const usage = {
     kit_sha: sha,
     frame,
     snippets: snippetIds,
-    new_parts: elements(body).filter((e) => "data-kit-new" in e.attrs).length,
+    new_parts: bodyElements.filter((e) => "data-kit-new" in e.attrs).length,
   };
   const page = `<!doctype html>
 <html${htmlAttrs}>
@@ -966,12 +1653,12 @@ export function compose(
 <meta name="design-kit-usage" content="${escapeAttr(JSON.stringify(usage))}">
 <title>${escapeAttr(row.title ?? frame)}</title>
 <style>
-${sanitizeCss(css)}${showNewCss}
+${pageCss}${showNewCss}
 </style>
 </head>
 <body${bodyAttrs}>
 ${body}
-</body>
+${behaviourScript}</body>
 </html>
 `;
   return page;
@@ -1330,7 +2017,9 @@ const USAGE = `usage: kit.mjs [--kit <dir>] <command>
   info                         print the manifest
   find <query>                 list up to ${FIND_LIMIT} rows whose id, title or on-screen text holds every word
   show <id> [--full]           path, size and an outline (--full: the markup)
-  compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] --out <file>`;
+  compose --frame <id> [--slot <name>=<file>]… [--theme light|dark] [--show-new] [--css pruned|full] --out <file>
+                               --css full keeps every rule of the kit's CSS; the default
+                               keeps only rules the page's classes and ids can use`;
 
 function parseArgs(argv) {
   const options = { slots: [], positional: [] };
@@ -1347,6 +2036,7 @@ function parseArgs(argv) {
     else if (arg === "--slot") options.slots.push(value());
     else if (arg === "--theme") options.theme = value();
     else if (arg === "--out") options.out = value();
+    else if (arg === "--css") options.css = value();
     else if (arg === "--full") options.full = true;
     else if (arg === "--show-new") options.showNew = true;
     else if (arg === "--help" || arg === "-h") options.help = true;
@@ -1396,6 +2086,7 @@ export function run(
         slots,
         theme: options.theme ?? "light",
         showNew: options.showNew,
+        css: options.css ?? "pruned",
       });
       writeFileSync(resolve(options.out), page);
       io.out(