@hajimism/dek 0.2.1 → 0.2.2

package/src/core/pptx-text.ts

@@ -0,0 +1,363 @@
+/// <reference lib="dom" />
+// What a PPTX takes from a slide as the browser drew it: each line of the text in its HTML flow,
+// where it was laid out and how it was set, so PowerPoint can set it there again; and the slide
+// drawn with that text taken out, as the picture under it.
+
+import type { PptxRun, PptxTextBox } from "./pptx-package.ts";
+
+/** A run as the page measures it: the element that owns its text, for its font to be looked up. */
+type MeasuredRun = Omit<PptxRun, "font"> & { owner: number };
+
+type MeasuredBox = Omit<PptxTextBox, "runs"> & { runs: MeasuredRun[] };
+
+export type PptxPageTexts = {
+  boxes: MeasuredBox[];
+  /** How many elements own text, marked `data-dek-pptx-font="<n>"` for their fonts. */
+  owners: number;
+  /** The alternative texts the slide's pictures carry, for the slide's picture as a whole. */
+  description: string;
+};
+
+/** The attribute that marks each element owning measured text, by its number. */
+export const PPTX_OWNER_ATTR = "data-dek-pptx-font";
+
+/**
+ * Measures every text in the slide's HTML flow, line by line, then hides it from the drawing with
+ * a highlight, which changes no layout, so a shot taken next is the picture under the text. What
+ * is not measured stays drawn: SVG, decoration under `aria-hidden`, what a pseudo-element draws,
+ * text a transform rotates or skews, text with no fill of its own, and every text's shadow.
+ *
+ * Runs in the page, shipped by `page.evaluate`, so it references nothing outside itself.
+ */
+export function measurePptxTextsInPage(): PptxPageTexts {
+  const slide = document.querySelector("#deck > .slide");
+  if (!(slide instanceof HTMLElement)) {
+    return { boxes: [], owners: 0, description: "" };
+  }
+  const origin = slide.getBoundingClientRect();
+
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const paint = canvas.getContext("2d", { willReadFrequently: true });
+  const colors = new Map<string, { rgb: [number, number, number]; alpha: number }>();
+  /** A computed color as sRGB, whatever space it is written in, by drawing it. */
+  const rgba = (value: string): { rgb: [number, number, number]; alpha: number } => {
+    const known = colors.get(value);
+    if (known) {
+      return known;
+    }
+    let found = { rgb: [0, 0, 0] as [number, number, number], alpha: 0 };
+    if (paint) {
+      paint.clearRect(0, 0, 1, 1);
+      paint.fillStyle = value;
+      paint.fillRect(0, 0, 1, 1);
+      const [r = 0, g = 0, b = 0, a = 0] = paint.getImageData(0, 0, 1, 1).data;
+      found = { rgb: [r, g, b], alpha: a / 255 };
+    }
+    colors.set(value, found);
+    return found;
+  };
+
+  /**
+   * How much the element and what it is in, up to the slide, scale it; none when one of them
+   * rotates or skews it, or scales it unevenly, which a text box cannot follow.
+   */
+  const scaleOf = (el: Element): number | undefined => {
+    let scale = 1;
+    for (
+      let node: Element | null = el;
+      node && node !== slide.parentElement;
+      node = node.parentElement
+    ) {
+      const transform = getComputedStyle(node).transform;
+      if (transform === "none" || transform === "") {
+        continue;
+      }
+      const matrix = new DOMMatrixReadOnly(transform);
+      if (!matrix.is2D || Math.abs(matrix.b) > 1e-6 || Math.abs(matrix.c) > 1e-6) {
+        return undefined;
+      }
+      if (Math.abs(matrix.a - matrix.d) > 1e-6 || matrix.a <= 0) {
+        return undefined;
+      }
+      scale *= matrix.a;
+    }
+    return scale;
+  };
+
+  const opacityOf = (el: Element): number => {
+    let opacity = 1;
+    for (
+      let node: Element | null = el;
+      node && node !== slide.parentElement;
+      node = node.parentElement
+    ) {
+      opacity *= Number(getComputedStyle(node).opacity);
+    }
+    return opacity;
+  };
+
+  /** The nearest element around `el` laid out as a block of its own, `el` included. */
+  const blockOf = (el: Element): Element => {
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const display = getComputedStyle(node).display;
+      if (node === slide || (display !== "inline" && display !== "contents")) {
+        return node;
+      }
+    }
+    return slide;
+  };
+
+  /** The decorations an element's text is drawn with: its own, and its inline ancestors' up to its block. */
+  const decorationsOf = (el: Element, block: Element): { underline: boolean; strike: boolean } => {
+    let underline = false;
+    let strike = false;
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const line = getComputedStyle(node).textDecorationLine;
+      underline ||= line.includes("underline");
+      strike ||= line.includes("line-through");
+      if (node === block) {
+        break;
+      }
+    }
+    return { underline, strike };
+  };
+
+  const transformText = (text: string, transform: string, lang: string): string => {
+    if (transform === "uppercase") {
+      return text.toLocaleUpperCase(lang || undefined);
+    }
+    if (transform === "lowercase") {
+      return text.toLocaleLowerCase(lang || undefined);
+    }
+    if (transform === "capitalize") {
+      return text.replace(
+        /(^|\s)(\p{L})/gu,
+        (_, space: string, letter: string) =>
+          `${space}${letter.toLocaleUpperCase(lang || undefined)}`,
+      );
+    }
+    return text;
+  };
+
+  type Fragment = {
+    text: string;
+    /** Where its first glyph that is not a collapsible space starts. */
+    ink: number;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    block: Element;
+    run: MeasuredRun;
+  };
+  const fragments: Fragment[] = [];
+  const ranges: Range[] = [];
+  const owners = new Map<Element, number>();
+  const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+  const walker = document.createTreeWalker(slide, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const text = node as Text;
+    const parent = text.parentElement;
+    if (!parent || !/[^ \t\n\r\f]/.test(text.data)) {
+      continue;
+    }
+    if (parent.closest('svg, script, style, template, [aria-hidden="true"]')) {
+      continue;
+    }
+    const style = getComputedStyle(parent);
+    if (style.visibility !== "visible") {
+      continue;
+    }
+    const fill = rgba(style.webkitTextFillColor || style.color);
+    const opacity = opacityOf(parent);
+    const scale = scaleOf(parent);
+    if (fill.alpha === 0 || opacity === 0 || scale === undefined) {
+      continue;
+    }
+    const block = blockOf(parent);
+    const owner = owners.get(parent) ?? owners.size;
+    owners.set(parent, owner);
+    const weight = Number(style.fontWeight);
+    const letterSpacing =
+      style.letterSpacing === "normal" ? 0 : Number.parseFloat(style.letterSpacing);
+    const run: MeasuredRun = {
+      text: "",
+      size: Number.parseFloat(style.fontSize) * scale,
+      bold: weight >= 600,
+      italic: style.fontStyle !== "normal",
+      ...decorationsOf(parent, block),
+      color: fill.rgb,
+      alpha: Math.round(fill.alpha * opacity * 1000) / 1000,
+      letterSpacing: (Number.isFinite(letterSpacing) ? letterSpacing : 0) * scale,
+      owner,
+    };
+    const collapse = !/^(pre|pre-wrap|break-spaces)$/.test(style.whiteSpace);
+    const lang = parent.closest("[lang]")?.getAttribute("lang") ?? "";
+
+    // The lines the text is drawn on, each the graphemes on it and the box they cover.
+    const range = document.createRange();
+    const lines: Array<{
+      text: string;
+      ink: number;
+      left: number;
+      top: number;
+      right: number;
+      bottom: number;
+    }> = [];
+    for (const { segment, index } of segmenter.segment(text.data)) {
+      range.setStart(text, index);
+      range.setEnd(text, index + segment.length);
+      const rect = [...range.getClientRects()].find((box) => box.width > 0 || box.height > 0);
+      // Only the white space CSS collapses; an ideographic space is a character like any other.
+      const space = /^[ \t\n\r\f]+$/.test(segment);
+      if (!rect || (space && rect.width === 0)) {
+        continue;
+      }
+      const glyph = space && collapse ? " " : segment;
+      const line = lines.at(-1);
+      const sameLine =
+        line !== undefined &&
+        rect.top < line.bottom - (line.bottom - line.top) / 2 &&
+        rect.left >= line.right - Math.max(2, run.size / 2);
+      if (sameLine) {
+        if (!(collapse && glyph === " " && line.text.endsWith(" "))) {
+          line.text += glyph;
+        }
+        if (!space && line.ink === Number.POSITIVE_INFINITY) {
+          line.ink = rect.left;
+        }
+        line.left = Math.min(line.left, rect.left);
+        line.top = Math.min(line.top, rect.top);
+        line.right = Math.max(line.right, rect.right);
+        line.bottom = Math.max(line.bottom, rect.bottom);
+      } else {
+        lines.push({
+          text: glyph,
+          ink: space ? Number.POSITIVE_INFINITY : rect.left,
+          left: rect.left,
+          top: rect.top,
+          right: rect.right,
+          bottom: rect.bottom,
+        });
+      }
+    }
+    if (lines.length === 0) {
+      continue;
+    }
+    const all = document.createRange();
+    all.selectNodeContents(text);
+    ranges.push(all);
+    for (const line of lines) {
+      fragments.push({
+        ...line,
+        text: transformText(line.text, style.textTransform, lang),
+        block,
+        run,
+      });
+    }
+  }
+
+  // Pieces of one line in one block that sit together are one box, a run each; a gap wider than
+  // a space, such as the padding of a chip, starts another.
+  const boxes: MeasuredBox[] = [];
+  let open: { box: MeasuredBox; block: Element; right: number } | undefined;
+  for (const fragment of fragments) {
+    const height = fragment.bottom - fragment.top;
+    const gap = open ? fragment.left - open.right : Number.POSITIVE_INFINITY;
+    const joins =
+      open !== undefined &&
+      open.block === fragment.block &&
+      Math.abs(fragment.top - open.box.y - origin.top) < height / 2 &&
+      gap > -fragment.run.size / 2 &&
+      gap <= fragment.run.size * 0.3;
+    if (open && joins) {
+      const { box } = open;
+      const left = Math.min(box.x + origin.left, fragment.left);
+      const top = Math.min(box.y + origin.top, fragment.top);
+      const right = Math.max(box.x + origin.left + box.width, fragment.right);
+      const bottom = Math.max(box.y + origin.top + box.height, fragment.bottom);
+      Object.assign(box, {
+        x: left - origin.left,
+        y: top - origin.top,
+        width: right - left,
+        height: bottom - top,
+        lineHeight: Math.max(box.lineHeight, height),
+      });
+      const last = box.runs.at(-1);
+      if (last && sameStyle(last, fragment.run)) {
+        last.text += fragment.text;
+      } else {
+        box.runs.push({ ...fragment.run, text: fragment.text });
+      }
+      open.right = fragment.right;
+      continue;
+    }
+    // A box starts at its first glyph: a space it would start with is not set.
+    const start = Number.isFinite(fragment.ink) ? fragment.ink : fragment.left;
+    const box: MeasuredBox = {
+      x: start - origin.left,
+      y: fragment.top - origin.top,
+      width: Math.max(0, fragment.right - start),
+      height,
+      lineHeight: height,
+      runs: [{ ...fragment.run, text: fragment.text }],
+    };
+    boxes.push(box);
+    open = { box, block: fragment.block, right: fragment.right };
+  }
+  for (const box of boxes) {
+    const first = box.runs[0];
+    const last = box.runs.at(-1);
+    if (first) {
+      first.text = first.text.replace(/^[ \t\n\r\f]+/, "");
+    }
+    if (last) {
+      last.text = last.text.replace(/[ \t\n\r\f]+$/, "");
+    }
+    box.runs = box.runs.filter((run) => run.text !== "");
+  }
+
+  for (const [el, owner] of owners) {
+    el.setAttribute("data-dek-pptx-font", String(owner));
+  }
+  const style = document.createElement("style");
+  style.textContent =
+    "::highlight(dek-pptx) { color: transparent; -webkit-text-fill-color: transparent; text-decoration-color: transparent; }";
+  document.head.append(style);
+  CSS.highlights.set("dek-pptx", new Highlight(...ranges));
+
+  const described = [...slide.querySelectorAll("img[alt], [aria-label], svg > title")].flatMap(
+    (el) => {
+      if (el.closest('[aria-hidden="true"]')) {
+        return [];
+      }
+      const said =
+        (el.tagName.toLowerCase() === "title"
+          ? el.textContent
+          : (el.getAttribute("alt") ?? el.getAttribute("aria-label"))) ?? "";
+      return said.trim() === "" ? [] : [said.trim()];
+    },
+  );
+  return {
+    boxes: boxes.filter((box) => box.runs.length > 0),
+    owners: owners.size,
+    description: described.join(" / "),
+  };
+
+  function sameStyle(a: MeasuredRun, b: MeasuredRun): boolean {
+    return (
+      a.owner === b.owner &&
+      a.size === b.size &&
+      a.bold === b.bold &&
+      a.italic === b.italic &&
+      a.underline === b.underline &&
+      a.strike === b.strike &&
+      a.alpha === b.alpha &&
+      a.letterSpacing === b.letterSpacing &&
+      a.color.join() === b.color.join()
+    );
+  }
+}

package/src/core/pptx.ts

@@ -0,0 +1,75 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type DistOptions, distFile } from "./path.ts";
+import { type PlaywrightRunner, requirePlaywright } from "./playwright.ts";
+import { pptxPackage } from "./pptx-package.ts";
+import { presenterSlides } from "./presenter.ts";
+import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
+import { writeInside } from "./safe-fs.ts";
+import { logicalSize } from "./size.ts";
+import { lastStop } from "./step.ts";
+import { loadSlideSources, renderSlideHtml } from "./still-page.ts";
+
+export type PptxResult = { outPath: string };
+
+export type PptxOptions = DistOptions & {
+  /** For anyone who has the file: the notes leave out the stage directions and comments. */
+  public?: boolean;
+  runner?: PlaywrightRunner;
+};
+
+/**
+ * The deck as a PowerPoint file: each slide at its last beat, as the PDF prints it, drawn as a
+ * picture with its text laid over it in text boxes a recipient can edit, and its script in the
+ * notes. A slide script that cannot run stops it, as it stops the PDF.
+ */
+export async function pptxDeck(dir: string, options?: PptxOptions): Promise<PptxResult>;
+export async function pptxDeck(source: ResolvedDeck, options?: PptxOptions): Promise<PptxResult>;
+export async function pptxDeck(
+  input: string | ResolvedDeck,
+  options: PptxOptions = {},
+): Promise<PptxResult> {
+  const { project, deck } = asResolvedDeck(input);
+  const outPath = distFile(project, deck, "pptx", options);
+  const size = logicalSize(deck.deck.ratio);
+  const sources = loadSlideSources(deck, { strict: true });
+  const { sections } = deck.deck;
+  // Rendered before Chromium starts, so a slide that cannot be drawn stops it with nothing written.
+  const pages = sections.map((section, index) => ({
+    html: renderSlideHtml(sources, section.slug, lastStop(section.beats)),
+    slug: section.slug,
+    index,
+  }));
+  const shots = mkdtempSync(join(tmpdir(), "dek-pptx-"));
+  try {
+    const answer = await requirePlaywright(
+      {
+        kind: "pptx",
+        viewport: size,
+        pages: pages.map(({ html, slug, index }) => ({
+          html,
+          slug,
+          screenshotPath: join(shots, `${index + 1}.png`),
+        })),
+      },
+      options.runner,
+    );
+    const scripts = presenterSlides(deck, options.public ? "audience" : "speaker");
+    const bytes = pptxPackage({
+      title: deck.deck.title,
+      lang: deck.deck.lang,
+      size,
+      slides: answer.slides.map((slide, index) => ({
+        picture: readFileSync(join(shots, `${index + 1}.png`)),
+        description: slide.description || (sections[index]?.title ?? slide.slug),
+        texts: slide.boxes,
+        notes: scripts[index]?.script ?? "",
+      })),
+    });
+    writeInside(outPath, bytes, project.root);
+  } finally {
+    rmSync(shots, { recursive: true, force: true });
+  }
+  return { outPath };
+}

package/src/core/slide-measure.ts

@@ -90,6 +90,7 @@ export function measureSlideInPage(): SlideMeasure {
   if (!slide) {
     return { slideBox: undefined, elements: [], pseudoTexts: [] };
   }
+  // RUNTIME_CLASSES from theme-facts.ts, written out: this function cannot import.
   const runtimeClasses = new Set(["is-current", "is-shown"]);
   const pictures = new Set(["img", "svg", "video", "canvas", "iframe", "object", "embed"]);
   // Computed colors come back as rgba() or, from a newer syntax, with a "/ alpha" at the end.

package/src/core/sync.ts

@@ -250,13 +250,16 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 ## Conventions
 
 - One \`##\` heading is one slide. HTML lives in \`slides/<id>.html\`.
-- Each deck owns its \`theme.css\`. Before writing a slide, run \`dekc theme\` in the deck for the classes, tokens, and layouts it defines, and \`dekc theme <layout>\` for a layout's markup.
-- Shared look lives in \`theme.css\`. Decoration only one slide uses lives in \`slides/<id>.css\`, which is scoped to that slide.
+- Each deck owns its \`theme.css\`, \`decks/<deck>/theme.css\`: lint, the build, and \`dekc theme\` read that one, and it is the \`theme.css\` this file and every hint mean. The \`theme.css\` at the project root is only the template \`dekc new\` copies into a new deck; editing it changes no deck that exists.
+- Before writing a slide, run \`dekc theme\` in the deck for the classes, tokens, and layouts it defines, and \`dekc theme <layout>\` for a layout's markup.
+- Shared look lives in the deck's \`theme.css\`. Decoration only one slide uses lives in \`slides/<id>.css\`, which is scoped to that slide.
 - Use only classes defined in \`theme.css\` or in that slide's own \`slides/<id>.css\`. The theme holds at most \`max_classes\` in the frontmatter of \`script.md\`, 40 by default (\`DEK013\`); classes in \`slides/<id>.css\` do not count, so keep a class only one slide uses there.
+- \`is-current\` and \`is-shown\` are states the player sets: \`is-current\` on the slide on screen, \`is-shown\` on each \`data-step\` element once its beat plays. \`dekc theme\` lists them apart, as state classes. Select them in CSS, never write them in markup (\`DEK010\`).
 - A rule in \`slides/<id>.css\` weighs as if it were written at the end of \`theme.css\`: it beats the theme's \`.slide .x\`, but not a more specific rule such as a layout's \`.slide[data-layout="split"] .x\` or the beat state \`.slide.is-current [data-step]\`. To override one of those, write the same selector.
-- Color, type, space, radius, and motion in either stylesheet use token \`var()\` only. A value only one slide uses can be a token of its own on that slide's \`.slide\` rule in \`slides/<id>.css\`.
+- In either stylesheet, colors, font families, easings, and lengths and times in an absolute, viewport, container, or root unit (\`px\`, \`rem\`, \`vw\`, \`ms\`, and the like) come from a token's \`var()\` (\`DEK014\`). Keywords such as \`bold\` or \`thin\`, unitless numbers, \`%\`, and units of the element's own font (\`em\`, \`ch\`, \`lh\`) are not raw values and pass. A value only one slide uses can be a token of its own on that slide's \`.slide\` rule in \`slides/<id>.css\`.
 - Do not add \`<style>\`, \`style=\`, \`<script>\`, event handler attributes (\`onclick=\` and the like), or \`javascript:\` URLs inside slide HTML.
 - Motion CSS cannot express lives in \`slides/<id>.ts\`: \`export default { motion: { <step>: ms }, draw(slide, { index, step, t }) {} } satisfies DekSlide\`. \`DekSlide\` is global, from \`.dek/slide.d.ts\`; do not import it. Key the slide's arrival, before its first beat, as \`"0"\`: every \`data-step\` element is hidden there, so draw what the slide shows before anything happens. Draw from \`t\` alone and set everything you touch on every call, with no timers and no imports, so video and screenshots can seek it. In \`draw\`, find elements by data-* attributes from the slide it is given, never by class or through \`document\`: the built deck holds every slide.
+- Every picture says what it shows, or that it is decoration (\`DEK034\`). An \`<img>\` takes \`alt\`, \`alt=""\` for decoration. An \`<svg>\` with no text of its own takes \`role="img"\` and an \`aria-label\`, or \`aria-hidden="true"\` when it is decoration; one with \`<text>\` is read as it is. An element with \`role="img"\` takes an \`aria-label\`.
 - Keep the deck self-contained: no remote URLs and no paths outside the deck.
 - Every slide carries its place in \`script.md\` as \`--dek-slide-number\` and \`--dek-slide-count\`. Print a folio from them in \`theme.css\`, never by hand: \`.slide { counter-reset: folio var(--dek-slide-number) }\`, then \`content: counter(folio)\`. It follows the script as slides move.
 
@@ -267,14 +270,19 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 - A shot's path names what it drew, and an edit to the slide or the theme replaces the file. Never reuse a shot's path from before an edit: run \`dekc shot <slug>\` again, which shoots only what changed, and read the path it prints.
 - \`dekc shot --sheet\` tiles every slide on one image: read it to judge the deck's balance in one look, then open a slide's own shot for detail.
 - Mark decoration \`aria-hidden="true"\`: a glow that bleeds off the slide, or a sample of text the talk shows as unreadable. Lint measures neither overflow nor contrast on it, and screen readers skip it, so never mark text the audience should read: \`DEK029\` warns of text under it.
-- When a hint sends a fix to \`theme.css\`, make it there, not in \`slides/<id>.css\`: the theme alone draws it that way, so other slides share the problem, and one change fixes them all.
-- One shot shows no motion. \`dekc shot <slug> --motion\` lays the slide's beats out as rows, each held at moments through everything it moves and ending as the shot does. \`dekc shot <a> --to <b> --at 0.5\` freezes the view transition between any two slides.
+- When a hint sends a fix to the deck's \`theme.css\`, make it there, not in \`slides/<id>.css\`: the theme alone draws it that way, so other slides share the problem, and one change fixes them all.
+- One shot shows no motion. \`dekc shot <slug> --motion\` lays the slide's beats out as rows, each held at moments through everything it moves and ending as the shot does. Its \`--json\` puts the sheets under \`sheets\` and each beat's frames under \`motion\`; \`shots\` is empty. \`dekc shot <a> --to <b> --at 0.5\` freezes the view transition between any two slides.
 
 ## After a rehearsal
 
 - \`dekc marks\` lists the beats the speaker marked while rehearsing aloud (\`m\` in the presenter view): the words they stumbled over are \`was\`, at \`line\` in \`script.md\`. Rewrite those beats to be easier to say, and keep each beat's heading so its mark follows it; \`status\` turns \`edited\` once the words changed.
 - Leave \`dekc marks clear\` to the speaker: only saying the new words aloud tells whether they work.
 
+## When the human points at an element
+
+- \`dekc annotations\` lists the notes the human wrote on elements of the slides (\`a\` on the dev server's page): each element at \`path\`, \`line\`, and \`column\` in the file as it is now, with its \`name\`, the note's \`text\`, and the \`shot\` that shows the slide at the beat the human saw. Read them yourself when the human says to deal with their notes. Fix each, then list them again: \`status\` turns \`edited\` once the slide's own files changed and \`gone\` once none of the note's elements is left. \`edited\` does not mean a note is dealt with: compare the \`shot\` with the note.
+- Leave \`dekc annotations clear\` to the human: they wrote the notes and judge the result.
+
 ## Before you report a deck as done
 
 - \`dekc lint --visual\` passes.

package/src/core/theme-excerpt.ts

@@ -6,10 +6,9 @@ import {
   selectorLayouts,
   splitSelectorList,
 } from "./css.ts";
+import { blankStringsAndComments } from "./css-scan.ts";
 import { escapeRegExp } from "./escape.ts";
-
-/** Classes the player adds at runtime, so a slide's markup never names them. */
-const RUNTIME_CLASSES = ["is-current", "is-shown"];
+import { RUNTIME_CLASSES } from "./theme-facts.ts";
 
 export type SlideUsage = {
   /** Classes the slide's markup uses. */
@@ -18,8 +17,17 @@ export type SlideUsage = {
   layout?: string;
   /** The slide's own stylesheet, whose `var()` and animations reach into the theme too. */
   css?: Stylesheet;
+  /**
+   * The element tags and attribute names the slide's markup has. Given, a rule that needs an
+   * element or an attribute the slide lacks, as `.slide ul` or `[data-step]`, is left out; left
+   * out, every element and attribute rule under `.slide` is kept.
+   */
+  markup?: { tags: Iterable<string>; attributes: Iterable<string> };
 };
 
+/** The markup as a selector meets it: lowercased, with what the build stamps on every slide. */
+type Markup = { tags: Set<string>; attributes: Set<string> };
+
 type ExcerptEntry = {
   atPath: string[];
   selector: string;
@@ -29,9 +37,9 @@ type ExcerptEntry = {
 
 /**
  * The part of a theme one slide depends on, as CSS that reads on its own: the
- * rules its classes and layout select, element and state rules under `.slide`,
- * the keyframes those rules animate with, and only the tokens they reach
- * through `var()`. It errs toward keeping a rule, since a rule left out misleads
+ * rules its classes and layout select, element and state rules under `.slide`
+ * for the elements and attributes it has, the keyframes those rules animate
+ * with, and only the tokens they reach through `var()`. It errs toward keeping a rule, since a rule left out misleads
  * a reader silently while an extra one only costs a line.
  */
 export function themeExcerpt(sheet: Stylesheet, usage: SlideUsage): string {
@@ -66,6 +74,10 @@ export function themeExcerpt(sheet: Stylesheet, usage: SlideUsage): string {
  */
 function excerptEntries(sheet: Stylesheet, usage: SlideUsage): ExcerptEntry[] {
   const used = new Set([...usage.classes, "slide", ...RUNTIME_CLASSES]);
+  const markup = usage.markup && {
+    tags: new Set([...usage.markup.tags].map((tag) => tag.toLowerCase())),
+    attributes: new Set([...usage.markup.attributes].map((name) => name.toLowerCase())),
+  };
   const entries: ExcerptEntry[] = [];
   for (const rule of sheet.rules) {
     // An at-rule's block reads here only where it styles its parent's elements.
@@ -82,7 +94,7 @@ function excerptEntries(sheet: Stylesheet, usage: SlideUsage): ExcerptEntry[] {
     }
     const parts = splitSelectorList(selector)
       .map((part) => part.trim())
-      .filter((part) => part && selectorPartApplies(part, used, usage.layout));
+      .filter((part) => part && selectorPartApplies(part, used, usage.layout, markup));
     if (parts.length > 0) {
       entries.push({ atPath, selector: parts.join(", "), decls: rule.decls });
     }
@@ -104,13 +116,53 @@ function animatedKeyframes(styled: CssDeclaration[], entries: ExcerptEntry[]): S
   );
 }
 
-function selectorPartApplies(part: string, used: Set<string>, layout?: string): boolean {
+function selectorPartApplies(
+  part: string,
+  used: Set<string>,
+  layout: string | undefined,
+  markup: Markup | undefined,
+): boolean {
   if (part.startsWith("::view-transition")) {
     return false;
   }
   return (
     selectorClasses(part).every((name) => used.has(name)) &&
-    selectorLayouts(part).every((name) => name === layout)
+    selectorLayouts(part).every((name) => name === layout) &&
+    (markup === undefined || selectorFitsMarkup(part, markup))
+  );
+}
+
+/** Attributes the build sets on every slide, or that the layout check already decides. */
+const STAMPED_ATTRIBUTES = new Set(["data-layout", "data-slug", "style"]);
+
+/**
+ * Whether the markup has every element and attribute a selector needs. Only what the selector
+ * requires outright counts: a name inside `:not()`, `:is()`, `:has()`, or any other parenthesis
+ * may be absent, so it keeps the rule.
+ */
+function selectorFitsMarkup(part: string, markup: Markup): boolean {
+  let outside = "";
+  let depth = 0;
+  for (const ch of blankStringsAndComments(part)) {
+    if (ch === "(") {
+      depth++;
+    } else if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+    } else if (depth === 0) {
+      outside += ch;
+    }
+  }
+  const attributes = [...outside.matchAll(/\[\s*([-\w]+)/g)].map((m) => (m[1] ?? "").toLowerCase());
+  const bare = outside.replace(/\[[^\]]*\]/g, "").replace(/::?[-\w]+/g, "");
+  const tags = [...bare.matchAll(/(?:^|[\s>+~])([A-Za-z][-\w]*)/g)].map((m) =>
+    (m[1] ?? "").toLowerCase(),
+  );
+  return (
+    tags.every((tag) => markup.tags.has(tag)) &&
+    attributes.every(
+      (name) =>
+        markup.attributes.has(name) || STAMPED_ATTRIBUTES.has(name) || name.startsWith("data-dek-"),
+    )
   );
 }
 

package/src/core/theme-facts.ts

@@ -8,13 +8,21 @@ import {
 
 export type ThemeLayout = { name: string; example?: string };
 
+/**
+ * The state classes the player sets at runtime: `is-current` on the slide on screen, `is-shown`
+ * on each beat element that has appeared. A theme selects them; a slide's markup never writes them.
+ */
+export const RUNTIME_CLASSES: ReadonlySet<string> = new Set(["is-current", "is-shown"]);
+
 /**
  * What a theme offers a slide, read once: AGENTS.md, `dekc theme`, and lint all say the same
  * thing about it because they all read it here.
  */
 export type ThemeFacts = {
-  /** Every class the theme's selectors name. */
+  /** Every class the theme's selectors name for markup to use: its vocabulary. */
   classes: Set<string>;
+  /** The runtime state classes its selectors name, which the player sets and markup never does. */
+  stateClasses: Set<string>;
   /** The layouts it styles, by name, each with its example markup when it has one. */
   layouts: ThemeLayout[];
   /** The tokens every slide can `var()`, with their values, in source order. */
@@ -22,8 +30,10 @@ export type ThemeFacts = {
 };
 
 export function themeFacts(sheet: Stylesheet): ThemeFacts {
+  const named = [...cssClassNames(sheet)];
   return {
-    classes: cssClassNames(sheet),
+    classes: new Set(named.filter((name) => !RUNTIME_CLASSES.has(name))),
+    stateClasses: new Set(named.filter((name) => RUNTIME_CLASSES.has(name))),
     layouts: themeLayouts(sheet),
     tokens: publishedTokens(sheet),
   };