@hajimism/dek 0.1.0

package/src/core/text-contrast.ts

@@ -0,0 +1,466 @@
+/**
+ * Text contrast measured from pixels. The page is drawn four ways: as shown,
+ * with every glyph transparent, and with every glyph filled white and black.
+ * White minus black is where glyphs cover, whatever their color and whatever
+ * sits above them; within that, the shown pixel is the text as the audience
+ * sees it and the bare pixel is what it sits on. Gradients, images, glows,
+ * opacity, blend modes, and colors no parser reads are all measured as drawn.
+ *
+ * A text's shadow can set it off, as a halo does, but does not hide it: where
+ * a text casts one, the page is drawn once more with no shadows, and each
+ * pixel reads against its shadow or what is behind it, whichever it stands out
+ * from. An offset shadow is decoration; a glow is what the text is read on.
+ *
+ * The pure functions below run in Node for tests and in the page as source,
+ * so each references nothing outside this file.
+ */
+import type { Box } from "./slide-measure.ts";
+
+export type Rgb = [number, number, number];
+
+/** RGBA bytes, row by row, as `ImageData` holds them. */
+export type Pixels = { width: number; height: number; data: ArrayLike<number> };
+
+export type TextLayers = {
+  /** The page as the audience sees it. */
+  shown: Pixels;
+  /** Every glyph transparent: what the text sits on. */
+  bare: Pixels;
+  /** The bare layer with no text casting a shadow; drawn only when some text casts one. */
+  shadowless?: Pixels;
+  /** Every glyph filled white. */
+  white: Pixels;
+  /** Every glyph filled black. */
+  black: Pixels;
+};
+
+/** The layers the page is redrawn as; `shown` needs no change. */
+type TextLayer = Exclude<keyof TextLayers, "shown">;
+
+type TextContrast = {
+  ratio: number;
+  /** The text's color at the pixel that reads worst. */
+  fg: Rgb;
+  /** What that pixel sits on. */
+  bg: Rgb;
+};
+
+function relativeLuminance([r, g, b]: Rgb): number {
+  const linear = (channel: number): number => {
+    const value = channel / 255;
+    return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+export function contrastRatio(foreground: Rgb, background: Rgb): number {
+  const first = relativeLuminance(foreground);
+  const second = relativeLuminance(background);
+  const [hi, lo] = first > second ? [first, second] : [second, first];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+type TextSample = {
+  fontSize?: number;
+  fontWeight?: number;
+};
+
+/** WCAG large text: 24px (18pt) regular, or 18.66px (14pt) bold. */
+const LARGE_TEXT_PX = 24;
+const LARGE_BOLD_TEXT_PX = 18.66;
+const BOLD_WEIGHT = 700;
+
+function isLargeText(sample: TextSample): boolean {
+  if (sample.fontSize === undefined) {
+    return false;
+  }
+  if (sample.fontSize >= LARGE_TEXT_PX) {
+    return true;
+  }
+  return sample.fontSize >= LARGE_BOLD_TEXT_PX && (sample.fontWeight ?? 400) >= BOLD_WEIGHT;
+}
+
+/** 3:1 for large text, 4.5:1 otherwise. Unknown size falls back to 4.5:1. */
+export function contrastThreshold(sample: TextSample): 3 | 4.5 {
+  return isLargeText(sample) ? 3 : 4.5;
+}
+
+export function parseCssRgb(color: string): Rgb | undefined {
+  const match = color.match(/rgba?\(\s*([\d.]+)(?:\s*,\s*|\s+)([\d.]+)(?:\s*,\s*|\s+)([\d.]+)/i);
+  if (!match) {
+    return undefined;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/** One text to measure. */
+type TextBoxes = {
+  /** The line boxes of its own text. */
+  rects: Box[];
+  /** The boxes of other texts that cross them. */
+  overlaps?: Box[];
+  /** Its opacity with every ancestor's multiplied in; 1 when left out. */
+  opacity?: number;
+};
+
+/**
+ * The contrast of one text, or undefined when none of its glyphs shows.
+ *
+ * Only the pixels its glyphs cover most are read, and each is taken back to
+ * the color a glyph covering the whole pixel would draw: the blend is undone
+ * by the coverage the masks show, less the text's own opacity, which the
+ * audience does see. A solid color measures exactly, and a hyphen too thin to
+ * cover any pixel still reads at its own color. The ratio is the one all but
+ * the worst 2% of those pixels reach: a gradient is judged by the part that
+ * reads worst, a stray pixel does not decide the verdict.
+ *
+ * The masks cannot tell one text's glyphs from another's, so pixels inside
+ * `overlaps` are read only when nothing else is.
+ */
+export function measureTextContrast(
+  layers: TextLayers,
+  { rects, overlaps = [], opacity = 1 }: TextBoxes,
+): TextContrast | undefined {
+  // One step of an 8-bit channel.
+  const COVERAGE_SLACK = 1 / 255;
+  const WORST_SHARE = 0.02;
+  // Fully transparent text draws nothing; any glyph pixel under it belongs to another text.
+  if (opacity <= 0) {
+    return undefined;
+  }
+  const { shown, bare, shadowless, white, black } = layers;
+  const behind = shadowless ? [bare, shadowless] : [bare];
+  const at = (image: Pixels, i: number): Rgb => [
+    image.data[i] ?? 0,
+    image.data[i + 1] ?? 0,
+    image.data[i + 2] ?? 0,
+  ];
+  const inside = (x: number, y: number, box: Box): boolean =>
+    x >= box.left && x < box.right && y >= box.top && y < box.bottom;
+  const covered: Array<{ i: number; coverage: number; shared: boolean }> = [];
+  for (const rect of rects) {
+    const top = Math.max(0, Math.floor(rect.top));
+    const bottom = Math.min(shown.height, Math.ceil(rect.bottom));
+    const left = Math.max(0, Math.floor(rect.left));
+    const right = Math.min(shown.width, Math.ceil(rect.right));
+    for (let y = top; y < bottom; y++) {
+      for (let x = left; x < right; x++) {
+        const i = (y * shown.width + x) * 4;
+        const [wr, wg, wb] = at(white, i);
+        const [kr, kg, kb] = at(black, i);
+        const coverage = (wr - kr + wg - kg + wb - kb) / (3 * 255);
+        if (coverage > 0) {
+          const shared = overlaps.some((box) => inside(x + 0.5, y + 0.5, box));
+          covered.push({ i, coverage, shared });
+        }
+      }
+    }
+  }
+  const own = covered.filter((pixel) => !pixel.shared);
+  const read = own.length > 0 ? own : covered;
+  let most = 0;
+  for (const pixel of read) {
+    most = Math.max(most, pixel.coverage);
+  }
+  const samples = read
+    .filter((pixel) => pixel.coverage >= most - COVERAGE_SLACK)
+    .map(({ i, coverage }) => {
+      // The glyph was drawn over its shadow, so the blend is undone against the bare layer.
+      const under = at(bare, i);
+      const [r, g, b] = at(shown, i);
+      // The blend a glyph covering the whole pixel would make, at the text's own opacity.
+      const whole = Math.min(1, opacity) / coverage;
+      const unblend = (drawn: number, below: number): number =>
+        Math.round(Math.min(255, Math.max(0, below + (drawn - below) * whole)));
+      const fg: Rgb = [unblend(r, under[0]), unblend(g, under[1]), unblend(b, under[2])];
+      return behind
+        .map((layer) => {
+          const bg = at(layer, i);
+          return { ratio: contrastRatio(fg, bg), fg, bg };
+        })
+        .reduce((best, reading) => (reading.ratio > best.ratio ? reading : best));
+    })
+    .sort((a, b) => a.ratio - b.ratio);
+  return samples[Math.floor(samples.length * WORST_SHARE)];
+}
+
+/**
+ * The stylesheet that redraws the page as one layer. Transitions stop so the
+ * change lands at once. SVG text is filled rather than text-filled, so its fill
+ * changes with the layer, and its stroke goes. A pseudo-element keeps its own fill, since what it
+ * draws is decoration and belongs to the background in every layer, unless it
+ * was marked as drawing text (`PseudoText`), which is measured as text is.
+ *
+ * The white and black layers only find where glyphs are, so text is drawn unblended there: a
+ * blend mode would scale white and black by what is under them. The other layers keep it.
+ */
+export function textLayerCss(layer: TextLayer): string {
+  const glyphless = layer === "bare" || layer === "shadowless";
+  const fill = glyphless ? "transparent" : { white: "#fff", black: "#000" }[layer];
+  const clipped = glyphless ? "\n[data-dek-clip-text] { background: none !important; }" : "";
+  const unblended = glyphless ? "" : "\n[data-dek-blend] { mix-blend-mode: normal !important; }";
+  const unshadowed =
+    layer === "shadowless" ? "\n*, *::before, *::after { text-shadow: none !important; }" : "";
+  return `*, *::before, *::after { transition: none !important; }
+* { -webkit-text-fill-color: ${fill} !important; }
+*::before, *::after { -webkit-text-fill-color: initial !important; }
+[data-dek-text-before]::before, [data-dek-text-after]::after { -webkit-text-fill-color: ${fill} !important; }
+svg text, svg tspan, svg textPath { fill: ${fill} !important; stroke: transparent !important; }${clipped}${unblended}${unshadowed}`;
+}
+
+/**
+ * Runs in the page: marks text whose background is clipped to its glyphs, so the bare layer can
+ * take that background away with the glyphs, and each element that blends text into what is under
+ * it, so the masks can draw it unblended. Says whether any text casts a shadow.
+ */
+function markTextLayers(): { shadowed: boolean } {
+  let shadowed = false;
+  for (const el of document.querySelectorAll("*")) {
+    const style = getComputedStyle(el);
+    if (style.backgroundClip === "text") {
+      el.setAttribute("data-dek-clip-text", "");
+    }
+    if (style.mixBlendMode !== "normal" && el.textContent?.trim()) {
+      el.setAttribute("data-dek-blend", "");
+    }
+    shadowed ||= [style, getComputedStyle(el, "::before"), getComputedStyle(el, "::after")].some(
+      (drawn) => drawn.textShadow !== "none",
+    );
+  }
+  return { shadowed };
+}
+
+/** Each layer as a base64 PNG; the shadowless one only when it was drawn. */
+type EncodedLayers = { [layer in keyof TextLayers]: string };
+
+type SamplerInput = { layers: EncodedLayers; texts: TextBoxes[] };
+
+/** Each text, with the boxes of every other text that crosses one of its own. */
+export function withOverlaps(texts: TextBoxes[]): TextBoxes[] {
+  const crosses = (a: Box, b: Box): boolean =>
+    a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+  return texts.map((text, index) => ({
+    ...text,
+    overlaps: texts.flatMap((other, at) =>
+      at === index
+        ? []
+        : other.rects.filter((box) => text.rects.some((rect) => crosses(rect, box))),
+    ),
+  }));
+}
+
+/** Runs in the page, with `measureTextContrast` in scope: decodes the layers and measures each text. */
+async function sampleTextContrasts({
+  layers,
+  texts,
+}: SamplerInput): Promise<Array<TextContrast | null>> {
+  const decode = async (base64: string): Promise<Pixels> => {
+    const blob = await (await fetch(`data:image/png;base64,${base64}`)).blob();
+    const bitmap = await createImageBitmap(blob);
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = canvas.getContext("2d");
+    if (!context) {
+      throw new Error("no 2d context");
+    }
+    context.drawImage(bitmap, 0, 0);
+    return context.getImageData(0, 0, bitmap.width, bitmap.height);
+  };
+  const decoded: TextLayers = {
+    shown: await decode(layers.shown),
+    bare: await decode(layers.bare),
+    ...(layers.shadowless ? { shadowless: await decode(layers.shadowless) } : {}),
+    white: await decode(layers.white),
+    black: await decode(layers.black),
+  };
+  return texts.map((text) => measureTextContrast(decoded, text) ?? null);
+}
+
+/** Defines `window.__dekTextContrast`, the in-page sampler, from this file's own source. */
+export function textContrastScript(): string {
+  return `window.__dekTextContrast = (function () {
+${relativeLuminance}
+${contrastRatio}
+${measureTextContrast}
+return ${sampleTextContrasts};
+})();
+`;
+}
+
+type LayerPage = {
+  screenshot(options: { type: "png" }): Promise<Uint8Array>;
+  evaluate<T, A>(fn: (arg: A) => T | Promise<T>, arg?: A): Promise<T>;
+  addScriptTag(options: { content: string }): Promise<unknown>;
+};
+
+/**
+ * Draws the page as each layer, measures each text, and takes the layer's
+ * stylesheet away again, so the page renders as shown for whatever runs next.
+ * Entries are null for text none of whose glyphs shows.
+ */
+export async function measurePageTextContrasts(
+  page: LayerPage,
+  texts: TextBoxes[],
+): Promise<Array<TextContrast | null>> {
+  if (texts.length === 0) {
+    return [];
+  }
+  const { shot, setLayer } = layerDrawer(page);
+  const shown = await shot();
+  const { shadowed } = await page.evaluate(markTextLayers);
+  const layers = { shown } as EncodedLayers;
+  const drawn = (["bare", "shadowless", "white", "black"] as const).filter(
+    (layer) => shadowed || layer !== "shadowless",
+  );
+  for (const layer of drawn) {
+    await setLayer(textLayerCss(layer));
+    layers[layer] = await shot();
+  }
+  await setLayer(null);
+  await page.addScriptTag({ content: textContrastScript() });
+  return page.evaluate(
+    (input) =>
+      (
+        window as unknown as {
+          __dekTextContrast: (arg: SamplerInput) => Promise<Array<TextContrast | null>>;
+        }
+      ).__dekTextContrast(input),
+    { layers, texts: withOverlaps(texts) },
+  );
+}
+
+/**
+ * Shots of the page and a stylesheet to redraw it with. `setLayer(null)` takes the layer away
+ * again: the glyphs go back first, with transitions still off, so they do not fade back from the
+ * last layer's fill in whatever is drawn next.
+ */
+function layerDrawer(page: LayerPage) {
+  const shot = async (): Promise<string> =>
+    Buffer.from(await page.screenshot({ type: "png" })).toString("base64");
+  const setLayer = (css: string | null): Promise<void> =>
+    page.evaluate((text) => {
+      let style = document.getElementById("dek-text-layer");
+      if (text === null) {
+        if (style) {
+          style.textContent = "*, *::before, *::after { transition: none !important; }";
+          // Reading layout applies the change now, while transitions are still off.
+          void document.body.offsetWidth;
+          style.remove();
+        }
+        return;
+      }
+      if (!style) {
+        style = document.createElement("style");
+        style.id = "dek-text-layer";
+        document.head.append(style);
+      }
+      style.textContent = text;
+    }, css);
+  return { shot, setLayer };
+}
+
+/**
+ * A text to draw alone, with the boxes to look for its glyphs in: an element's own text, by the
+ * element's place among the slide's elements as `measureSlideInPage` lists them, or the text a
+ * pseudo-element draws, by the mark on its host.
+ */
+export type GlyphTarget = { rects: Box[] } & (
+  | { element: number }
+  | { host: string; pseudo: "before" | "after" }
+);
+
+/** The attribute that marks an element whose own text is drawn alone. */
+const GLYPHS_MARK = "data-dek-glyphs";
+
+/**
+ * The box each text's glyphs show in, inside its own boxes. Each is drawn alone, every other glyph
+ * transparent, in white and in black; where the two differ is where its glyphs show. That can be
+ * far smaller than the box it is laid out in: a running head is often a full-width block holding a
+ * few words. A text whose every glyph lies under a box drawn above it shows none, as a number is
+ * when the next beat's paints its box over it: undefined.
+ */
+export async function measureGlyphBoxes(
+  page: LayerPage,
+  targets: GlyphTarget[],
+): Promise<Array<Box | undefined>> {
+  if (targets.length === 0) {
+    return [];
+  }
+  const { shot, setLayer } = layerDrawer(page);
+  const elements = targets.flatMap((target) => ("element" in target ? [target.element] : []));
+  await page.evaluate(
+    ({ mark, indices }) => {
+      const all = [...(document.querySelector(".slide")?.querySelectorAll("*") ?? [])];
+      for (const index of indices) {
+        all[index]?.setAttribute(mark, String(index));
+      }
+    },
+    { mark: GLYPHS_MARK, indices: elements },
+  );
+  const alone = (target: GlyphTarget, fill: string): string =>
+    `*, *::before, *::after { transition: none !important; -webkit-text-fill-color: transparent !important; }
+svg text, svg tspan, svg textPath { fill: transparent !important; stroke: transparent !important; }
+${
+  "element" in target
+    ? `[${GLYPHS_MARK}="${target.element}"] { -webkit-text-fill-color: ${fill} !important; fill: ${fill} !important; }`
+    : `[data-dek-text="${target.host}"][data-dek-text-${target.pseudo}]::${target.pseudo} { -webkit-text-fill-color: ${fill} !important; }`
+}`;
+  const pairs: Array<{ white: string; black: string; rects: Box[] }> = [];
+  for (const target of targets) {
+    await setLayer(alone(target, "#fff"));
+    const white = await shot();
+    await setLayer(alone(target, "#000"));
+    pairs.push({ white, black: await shot(), rects: target.rects });
+  }
+  await setLayer(null);
+  await page.evaluate((mark) => {
+    for (const el of document.querySelectorAll(`[${mark}]`)) {
+      el.removeAttribute(mark);
+    }
+  }, GLYPHS_MARK);
+  const found = await page.evaluate(async (input) => {
+    const decode = async (base64: string) => {
+      const blob = await (await fetch(`data:image/png;base64,${base64}`)).blob();
+      const bitmap = await createImageBitmap(blob);
+      const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+      const context = canvas.getContext("2d");
+      if (!context) {
+        throw new Error("no 2d context");
+      }
+      context.drawImage(bitmap, 0, 0);
+      return context.getImageData(0, 0, bitmap.width, bitmap.height);
+    };
+    const boxes: Array<Box | null> = [];
+    for (const { white, black, rects } of input) {
+      const [w, k] = [await decode(white), await decode(black)];
+      let box: Box | null = null;
+      for (const rect of rects) {
+        const top = Math.max(0, Math.floor(rect.top));
+        const bottom = Math.min(w.height, Math.ceil(rect.bottom));
+        const left = Math.max(0, Math.floor(rect.left));
+        const right = Math.min(w.width, Math.ceil(rect.right));
+        for (let y = top; y < bottom; y++) {
+          for (let x = left; x < right; x++) {
+            const i = (y * w.width + x) * 4;
+            const differs =
+              (w.data[i] ?? 0) !== (k.data[i] ?? 0) ||
+              (w.data[i + 1] ?? 0) !== (k.data[i + 1] ?? 0) ||
+              (w.data[i + 2] ?? 0) !== (k.data[i + 2] ?? 0);
+            if (differs) {
+              box = box
+                ? {
+                    left: Math.min(box.left, x),
+                    top: Math.min(box.top, y),
+                    right: Math.max(box.right, x + 1),
+                    bottom: Math.max(box.bottom, y + 1),
+                  }
+                : { left: x, top: y, right: x + 1, bottom: y + 1 };
+            }
+          }
+        }
+      }
+      boxes.push(box);
+    }
+    return boxes;
+  }, pairs);
+  return found.map((box) => box ?? undefined);
+}

package/src/core/theme-excerpt.ts

@@ -0,0 +1,187 @@
+import {
+  type CssDeclaration,
+  isKeyframesPrelude,
+  type Stylesheet,
+  selectorClasses,
+  selectorLayouts,
+  splitSelectorList,
+} from "./css.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"];
+
+export type SlideUsage = {
+  /** Classes the slide's markup uses. */
+  classes: Iterable<string>;
+  /** The slide's `data-layout`. */
+  layout?: string;
+  /** The slide's own stylesheet, whose `var()` and animations reach into the theme too. */
+  css?: Stylesheet;
+};
+
+type ExcerptEntry = {
+  atPath: string[];
+  selector: string;
+  decls: CssDeclaration[];
+  keyframes?: string;
+};
+
+/**
+ * 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
+ * a reader silently while an extra one only costs a line.
+ */
+export function themeExcerpt(sheet: Stylesheet, usage: SlideUsage): string {
+  const entries = excerptEntries(sheet, usage);
+  const own = usage.css?.decls ?? [];
+  const styled = [
+    ...entries.filter((entry) => !entry.keyframes).flatMap((entry) => entry.decls),
+    ...own,
+  ].filter((decl) => !decl.property.startsWith("--"));
+  const keyframes = animatedKeyframes(styled, entries);
+  const kept = entries.filter((entry) => !entry.keyframes || keyframes.has(entry.keyframes));
+  const tokens = reachedTokens(
+    [...styled, ...kept.filter((entry) => entry.keyframes).flatMap((entry) => entry.decls)],
+    sheet.decls,
+  );
+
+  return renderExcerpt(
+    kept
+      .map((entry) => ({
+        ...entry,
+        decls: entry.decls.filter(
+          (decl) => !decl.property.startsWith("--") || tokens.has(decl.property),
+        ),
+      }))
+      .filter((entry) => entry.decls.length > 0),
+  );
+}
+
+/**
+ * Every keyframe stop, and every block of declarations with at least one selector part the slide
+ * selects. A nested rule reads with its selector resolved, so the excerpt stands on its own.
+ */
+function excerptEntries(sheet: Stylesheet, usage: SlideUsage): ExcerptEntry[] {
+  const used = new Set([...usage.classes, "slide", ...RUNTIME_CLASSES]);
+  const entries: ExcerptEntry[] = [];
+  for (const rule of sheet.rules) {
+    // An at-rule's block reads here only where it styles its parent's elements.
+    const parent = rule.kind === "at" ? rule.parent : undefined;
+    if (rule.kind === "at" && (rule.descriptors || !parent)) {
+      continue;
+    }
+    const selector = rule.kind === "style" ? rule.selector : (parent?.selector ?? "");
+    const atPath = rule.kind === "at" ? [...rule.atPath, rule.prelude] : rule.atPath;
+    const keyframes = rule.keyframe ? atPath.find(isKeyframesPrelude) : undefined;
+    if (keyframes) {
+      entries.push({ atPath, selector, decls: rule.decls, keyframes: keyframesName(keyframes) });
+      continue;
+    }
+    const parts = splitSelectorList(selector)
+      .map((part) => part.trim())
+      .filter((part) => part && selectorPartApplies(part, used, usage.layout));
+    if (parts.length > 0) {
+      entries.push({ atPath, selector: parts.join(", "), decls: rule.decls });
+    }
+  }
+  return entries;
+}
+
+/** The names of the keyframes the kept declarations animate with. */
+function animatedKeyframes(styled: CssDeclaration[], entries: ExcerptEntry[]): Set<string> {
+  const animations = styled
+    .filter((decl) => /^animation(-name)?$/.test(decl.property))
+    .map((decl) => decl.value);
+  return new Set(
+    entries.flatMap((entry) =>
+      entry.keyframes && animations.some((value) => mentionsName(value, entry.keyframes ?? ""))
+        ? [entry.keyframes]
+        : [],
+    ),
+  );
+}
+
+function selectorPartApplies(part: string, used: Set<string>, layout?: string): boolean {
+  if (part.startsWith("::view-transition")) {
+    return false;
+  }
+  return (
+    selectorClasses(part).every((name) => used.has(name)) &&
+    selectorLayouts(part).every((name) => name === layout)
+  );
+}
+
+function keyframesName(at: string): string {
+  return at
+    .replace(/^@(-\w+-)?keyframes\b/i, "")
+    .trim()
+    .replace(/^(["'])(.*)\1$/, "$2");
+}
+
+function mentionsName(value: string, name: string): boolean {
+  return new RegExp(`(^|[\\s,])${escapeRegExp(name)}($|[\\s,])`).test(value);
+}
+
+function varNames(value: string): string[] {
+  return [...value.matchAll(/var\(\s*(--[-\w]+)/g)].map((match) => match[1] ?? "");
+}
+
+/** The tokens `decls` use, following each token's own `var()` to the ones it is built from. */
+function reachedTokens(decls: CssDeclaration[], all: CssDeclaration[]): Set<string> {
+  const definitions = new Map<string, string[]>();
+  for (const decl of all) {
+    if (decl.property.startsWith("--")) {
+      definitions.set(decl.property, [...(definitions.get(decl.property) ?? []), decl.value]);
+    }
+  }
+  const reached = new Set<string>();
+  const queue = decls.flatMap((decl) => varNames(decl.value));
+  for (let name = queue.pop(); name !== undefined; name = queue.pop()) {
+    if (reached.has(name)) {
+      continue;
+    }
+    reached.add(name);
+    for (const value of definitions.get(name) ?? []) {
+      queue.push(...varNames(value));
+    }
+  }
+  return reached;
+}
+
+function renderExcerpt(entries: ExcerptEntry[]): string {
+  const lines: string[] = [];
+  const open: string[] = [];
+  const pad = (depth: number) => "  ".repeat(depth);
+  for (const entry of entries) {
+    let common = 0;
+    while (
+      common < open.length &&
+      common < entry.atPath.length &&
+      open[common] === entry.atPath[common]
+    ) {
+      common++;
+    }
+    while (open.length > common) {
+      open.pop();
+      lines.push(`${pad(open.length)}}`);
+    }
+    for (const at of entry.atPath.slice(open.length)) {
+      lines.push(`${pad(open.length)}${at} {`);
+      open.push(at);
+    }
+    const indent = pad(open.length);
+    lines.push(
+      `${indent}${entry.selector} {`,
+      ...entry.decls.map((decl) => `${indent}  ${decl.property}: ${decl.value};`),
+      `${indent}}`,
+    );
+  }
+  while (open.length > 0) {
+    open.pop();
+    lines.push(`${pad(open.length)}}`);
+  }
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}

package/src/core/theme-facts.ts

@@ -0,0 +1,51 @@
+import {
+  type CssToken,
+  cssClassNames,
+  cssLayoutNames,
+  publishedTokens,
+  type Stylesheet,
+} from "./css.ts";
+
+export type ThemeLayout = { name: string; example?: string };
+
+/**
+ * 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. */
+  classes: 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. */
+  tokens: CssToken[];
+};
+
+export function themeFacts(sheet: Stylesheet): ThemeFacts {
+  return {
+    classes: cssClassNames(sheet),
+    layouts: themeLayouts(sheet),
+    tokens: publishedTokens(sheet),
+  };
+}
+
+const LAYOUT_EXAMPLE_RE = /\/\*\s*@layout\s+([A-Za-z0-9_-]+)[ \t]*\r?\n([\s\S]*?)\*\//g;
+
+/**
+ * The layouts a theme defines, sorted by name, each with the markup its
+ * `/* @layout <name> ... *\/` comment gives. A theme documents how a layout
+ * expects to be filled that way, and the example travels with the theme.
+ */
+function themeLayouts(sheet: Stylesheet): ThemeLayout[] {
+  const examples = new Map<string, string>();
+  for (const match of sheet.source.matchAll(LAYOUT_EXAMPLE_RE)) {
+    const [, name, body] = match;
+    if (name && body !== undefined && !examples.has(name)) {
+      examples.set(name, body.trim());
+    }
+  }
+  return [...cssLayoutNames(sheet)].sort().map((name) => {
+    const example = examples.get(name);
+    return example === undefined ? { name } : { name, example };
+  });
+}