@brandon_m_behring/book-scaffold-astro 4.27.1 → 4.29.0

package/CLAUDE.md

@@ -108,7 +108,11 @@ Two callout families coexist. Authors import what they need.
 
 **Pedagogy family** (v4.1.0+, any profile, 4 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop), `Diagnostic` (v4.19.0, #110; teal; pre-reading "Do I Know This Already?" DIKTA self-check — a slotted question list + a skip/skim/read routing rubric via `skimTo`, plus an optional collapsible answer key via `slot="answers"`). Slot bullets/code freely; render at any preset.
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginFigure`, `MarginNote`, `Sidenote`, `EvidenceTag`, `Newthought`, `Epigraph`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `BookLink` (v4.16.0+; cross-book link — `<BookLink book="design" to="…"/>` resolves `book` against `defineBookConfig({ siblingBooks })` and throws on an unknown book; #147 adds `{ url, labels }` entries so `validate` checks literal fragment targets against a vendored sibling `labels.json`, while legacy URL strings warn/skip target validation; `<XRef>` is in-book only — #96), `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
+
+**Cross-book heading indexes (#147):** `book-scaffold build-labels` indexes h2–h6 with Astro's heading collector (inline formatting/smartypants plus GitHub duplicate slugs), alongside the historical component IDs. Emitted hrefs are base-less and resolve the evaluated `chapterRoute` / `bookField`; nested content IDs keep their directory. Heading keys are opaque and path-qualified so the same fragment can exist in multiple chapters; `validate` matches exact normalized href values, while component keys stay backward-compatible for XRef. This makes a generated sibling `labels.json` usable for literal `<BookLink ... to="...#anchor">` validation without assuming `/chapters/`. h1 stays excluded as the chapter title.
+
+**Interactive demo substrate (#143; opt-in):** `DemoFrame`, `Slider`, `StatCards`, and `useThemeColors` are named exports from `@brandon_m_behring/book-scaffold-astro/demo`. Import `@brandon_m_behring/book-scaffold-astro/styles/demo.css` on the page that mounts the consumer-owned Preact island; it is never included by a profile and nothing auto-mounts. The substrate owns figure/label/metric semantics, focus/reduced-motion styling, SVG token helpers, and theme-token resolution. Consumers own all data, kernels, charts, and domain interaction policy. See Recipe 23.
 
 **`MarginNote` vs `Sidenote` (don't let the names mislead).** `MarginNote` renders **inline** — a colored callout in the running text column; despite the name it does **not** go in the margin. It's for a load-bearing aside the reader must see. `Sidenote` is the one that **floats into the right gutter** (auto-numbered Tufte marginalia, reflowing inline on mobile). Reach for `Sidenote` for footnote-like asides; `MarginNote` for an inline colored callout.
 
@@ -124,27 +128,23 @@ Two callout families coexist. Authors import what they need.
 
 Full reference in `recipes/04-component-library.md`.
 
-### Theme-change event (v4.14.2)
+### Theme colors for JS visuals (v4.14.2 event; #143 hook)
 
 `Base.astro` emits `book:theme:change` on `window` whenever the **effective** theme changes — both the chrome's dark-mode toggle and a system `prefers-color-scheme` flip (the latter only when no explicit theme is pinned). Use it for **canvas / JS islands** that can't recolor via CSS alone; CSS-token elements recolor automatically from the `[data-theme]` attribute.
 
 ```ts
-// inside a Preact island (client:visible / client:idle)
-function currentTheme(): 'light' | 'dark' {
-  const t = document.documentElement.getAttribute('data-theme');
-  return t === 'light' || t === 'dark'
-    ? t
-    : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-}
-useEffect(() => {
-  draw(currentTheme());                                 // initial paint
-  const onChange = (e: Event) => draw((e as CustomEvent).detail.theme);
-  window.addEventListener('book:theme:change', onChange);
-  return () => window.removeEventListener('book:theme:change', onChange);
-}, []);
+import { useThemeColors } from '@brandon_m_behring/book-scaffold-astro/demo';
+
+const TOKENS = {
+  ink: ['--color-text', '#1a1a19'],
+  accent: ['--color-link', '#3b6fa0'],
+} as const;
+
+const { colors, theme, reducedMotion } = useThemeColors(TOKENS);
+// redraw from colors; animate only when reducedMotion === false
 ```
 
-`detail.theme` is `'light' | 'dark'`. Pull design-token colors via `getComputedStyle(document.documentElement).getPropertyValue('--…')` so the canvas matches the page, and respect `prefers-reduced-motion` for any redraw animation. (Event-only by design — a `useThemeColors` helper graduates with the demo kit, #103.)
+The hook is SSR-safe (`theme` and `reducedMotion` are `null` until the first client effect), resolves the explicit token map with fallbacks, refreshes on `book:theme:change`, system color-scheme changes, and reduced-motion changes, and removes all listeners on cleanup. Start animation only when `reducedMotion === false`. `detail.theme` on the underlying event remains `'light' | 'dark'` for non-Preact consumers. Prefer CSS variables or `demo.css`'s `data-demo-fill` / `data-demo-stroke` helpers for inline SVG; those recolor automatically and do not need the hook. See Recipe 23 for the complete composition.
 
 ## Citation patterns
 

package/README.md

@@ -26,6 +26,14 @@ security defaults. A consumer-owned `public/_headers` wins unchanged;
 and `securityHeaders.contentSecurityPolicy` replaces only the default CSP.
 See [Recipe 05](./recipes/05-deploy-cloudflare.md#default-security-headers).
 
+## Interactive demos
+
+The opt-in `@brandon_m_behring/book-scaffold-astro/demo` entry exports
+`DemoFrame`, `Slider`, `StatCards`, and `useThemeColors` for consumer-owned
+Preact islands. Import `styles/demo.css` explicitly; no demo is mounted and no
+domain kernel or data loader is bundled automatically. See
+[Recipe 23](./recipes/23-interactive-demo-substrate.md).
+
 ## Licensing
 
 Code, configuration, and scripts are MIT-licensed. Recipes, pedagogy, examples,

package/components/BookLink.astro

@@ -11,8 +11,9 @@
  * build (fail-loud, see `src/lib/book-link`), never a dead cross-origin link.
  *
  * `to` is a path within the sibling book (its router shape), e.g.
- * `chapters/<slug>/#<id>`. Phase 1 builds the href; Phase 2 (deferred) will
- * validate `to` against a vendored sibling `labels.json`.
+ * `chapters/<slug>/#<id>`. A `{ url, labels }` registry descriptor lets
+ * `book-scaffold validate` check literal path/fragment targets against a
+ * vendored sibling `labels.json`; URL strings remain runtime-compatible.
  *
  * Usage:
  *   For design depth see

package/components/demo/DemoFrame.tsx

@@ -0,0 +1,96 @@
+/**
+ * DemoFrame — accessible shell for a consumer-owned interactive teaching
+ * figure (#143).
+ *
+ * The scaffold owns only the stable chrome: figure semantics, an explicit
+ * accessible name/description, a body region, and an optional caption. The
+ * consumer still owns the visualization, data, and interaction model.
+ */
+import type { ComponentChildren } from 'preact';
+import { useId } from 'preact/hooks';
+
+export const DEMO_HEADING_LEVELS = [2, 3, 4, 5, 6] as const;
+export type DemoHeadingLevel = (typeof DEMO_HEADING_LEVELS)[number];
+
+export interface DemoFrameProps {
+  /** Visible accessible name for the teaching figure. */
+  title: string;
+  /** Short explanation rendered directly below the title. */
+  description?: string;
+  /** Figure caption rendered after the interactive body. */
+  caption?: ComponentChildren;
+  /** Consumer-owned controls and visualization. */
+  children?: ComponentChildren;
+  /** Optional stable root id for deep links and deterministic child ids. */
+  id?: string;
+  /** Additional class on the root figure. */
+  className?: string;
+  /** Reflect a consumer-owned recomputation/loading state to assistive tech. */
+  busy?: boolean;
+  /** Heading depth in the surrounding document outline. Defaults to 3. */
+  headingLevel?: DemoHeadingLevel;
+}
+
+function assertNonEmpty(value: string, prop: string): void {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`DemoFrame: ${prop} must be a non-empty string.`);
+  }
+}
+
+function generatedBaseId(id: string | undefined, generated: string): string {
+  if (id !== undefined) {
+    assertNonEmpty(id, 'id');
+    if (/\s/.test(id)) {
+      throw new Error('DemoFrame: id must not contain whitespace.');
+    }
+    return id;
+  }
+  return `demo-${generated.replace(/[^a-zA-Z0-9_-]/g, '')}`;
+}
+
+export function DemoFrame({
+  title,
+  description,
+  caption,
+  children,
+  id,
+  className,
+  busy = false,
+  headingLevel = 3,
+}: DemoFrameProps) {
+  assertNonEmpty(title, 'title');
+  if (description !== undefined) assertNonEmpty(description, 'description');
+  if (typeof caption === 'string') assertNonEmpty(caption, 'caption');
+  if (!(DEMO_HEADING_LEVELS as readonly number[]).includes(headingLevel)) {
+    throw new Error('DemoFrame: headingLevel must be one of 2 | 3 | 4 | 5 | 6.');
+  }
+
+  const baseId = generatedBaseId(id, useId());
+  const titleId = `${baseId}-title`;
+  const descriptionId = description ? `${baseId}-description` : null;
+  const captionId = caption != null ? `${baseId}-caption` : null;
+  const describedBy = [descriptionId, captionId].filter(Boolean).join(' ') || undefined;
+  const classes = ['demo-frame', className].filter(Boolean).join(' ');
+  const Heading = `h${headingLevel}` as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+  return (
+    <figure
+      id={id}
+      class={classes}
+      aria-labelledby={titleId}
+      aria-describedby={describedBy}
+      aria-busy={busy || undefined}
+    >
+      <header class="demo-frame__header">
+        <Heading id={titleId} class="demo-frame__title">{title}</Heading>
+        {description && (
+          <p id={descriptionId!} class="demo-frame__description">{description}</p>
+        )}
+      </header>
+      <div class="demo-frame__body">{children}</div>
+      {caption != null && (
+        <figcaption id={captionId!} class="demo-frame__caption">{caption}</figcaption>
+      )}
+    </figure>
+  );
+}

package/components/demo/Slider.tsx

@@ -0,0 +1,150 @@
+/** Controlled, visibly-labelled range input for interactive demos (#143). */
+import { useId } from 'preact/hooks';
+
+export interface SliderProps {
+  /** Visible label associated with the native range input. */
+  label: string;
+  /** Controlled numeric value. */
+  value: number;
+  min: number;
+  max: number;
+  /** Positive increment. Defaults to the native range-input step of 1. */
+  step?: number;
+  /** Receives the parsed numeric value for every native input event. */
+  onValueChange: (value: number) => void;
+  /** Optional stable input id. A hydration-stable id is generated otherwise. */
+  id?: string;
+  name?: string;
+  description?: string;
+  disabled?: boolean;
+  className?: string;
+  /** Formats the visible current-value output. */
+  formatValue?: (value: number) => string;
+  /** Optional spoken value text when the visible format is not descriptive. */
+  getValueText?: (value: number) => string;
+}
+
+function assertFinite(value: number, prop: string): void {
+  if (!Number.isFinite(value)) {
+    throw new Error(`Slider: ${prop} must be a finite number.`);
+  }
+}
+
+function isStepAligned(value: number, min: number, step: number): boolean {
+  const steps = (value - min) / step;
+  const nearest = Math.round(steps);
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(steps)) * 16;
+  return Math.abs(steps - nearest) <= tolerance;
+}
+
+function assertSliderProps({
+  label,
+  value,
+  min,
+  max,
+  step = 1,
+  id,
+  description,
+  onValueChange,
+  formatValue,
+  getValueText,
+}: SliderProps): void {
+  if (typeof label !== 'string' || label.trim() === '') {
+    throw new Error('Slider: label must be a non-empty string.');
+  }
+  assertFinite(value, 'value');
+  assertFinite(min, 'min');
+  assertFinite(max, 'max');
+  assertFinite(step, 'step');
+  if (max <= min) throw new Error('Slider: max must be greater than min.');
+  if (step <= 0) throw new Error('Slider: step must be greater than 0.');
+  if (value < min || value > max) {
+    throw new Error(`Slider: value ${value} must be within [${min}, ${max}].`);
+  }
+  if (!isStepAligned(value, min, step)) {
+    throw new Error('Slider: value must align with min + (n × step).');
+  }
+  if (id !== undefined && (
+    typeof id !== 'string' || id.trim() === '' || /\s/.test(id)
+  )) {
+    throw new Error('Slider: id must be a non-empty string without whitespace.');
+  }
+  if (description !== undefined && (
+    typeof description !== 'string' || description.trim() === ''
+  )) {
+    throw new Error('Slider: description must be a non-empty string.');
+  }
+  if (typeof onValueChange !== 'function') {
+    throw new Error('Slider: onValueChange must be a function.');
+  }
+  if (formatValue !== undefined && typeof formatValue !== 'function') {
+    throw new Error('Slider: formatValue must be a function.');
+  }
+  if (getValueText !== undefined && typeof getValueText !== 'function') {
+    throw new Error('Slider: getValueText must be a function.');
+  }
+}
+
+export function Slider(props: SliderProps) {
+  assertSliderProps(props);
+  const {
+    label,
+    value,
+    min,
+    max,
+    step = 1,
+    onValueChange,
+    id,
+    name,
+    description,
+    disabled = false,
+    className,
+    formatValue = String,
+    getValueText = formatValue,
+  } = props;
+
+  const generated = useId().replace(/[^a-zA-Z0-9_-]/g, '');
+  const inputId = id ?? `demo-slider-${generated}`;
+  const descriptionId = description ? `${inputId}-description` : undefined;
+  const displayValue = formatValue(value);
+  if (typeof displayValue !== 'string' || displayValue.trim() === '') {
+    throw new Error('Slider: formatValue must return a non-empty string.');
+  }
+  const valueText = getValueText(value);
+  if (typeof valueText !== 'string' || valueText.trim() === '') {
+    throw new Error('Slider: getValueText must return a non-empty string.');
+  }
+  const classes = ['demo-slider', className].filter(Boolean).join(' ');
+
+  return (
+    <div class={classes} data-disabled={disabled || undefined}>
+      <div class="demo-slider__head">
+        <label class="demo-slider__label" for={inputId}>{label}</label>
+        <output class="demo-slider__value" for={inputId}>{displayValue}</output>
+      </div>
+      {description && (
+        <p id={descriptionId} class="demo-slider__description">{description}</p>
+      )}
+      <input
+        id={inputId}
+        class="demo-slider__input"
+        type="range"
+        name={name}
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        disabled={disabled}
+        aria-describedby={descriptionId}
+        aria-valuetext={valueText}
+        onInput={(event) => {
+          const next = Number.parseFloat(event.currentTarget.value);
+          if (!Number.isFinite(next)) {
+            throw new Error('Slider: native input produced a non-finite value.');
+          }
+          onValueChange(next);
+        }}
+      />
+    </div>
+  );
+}

package/components/demo/StatCards.tsx

@@ -0,0 +1,100 @@
+/** Semantic metric-card list for interactive teaching figures (#143). */
+
+export const STAT_CARD_TONES = ['neutral', 'accent', 'positive', 'warning'] as const;
+export type StatCardTone = (typeof STAT_CARD_TONES)[number];
+
+export interface StatCardItem {
+  /** Optional stable key. Defaults to the label, which must then be unique. */
+  id?: string;
+  label: string;
+  value: string | number;
+  /** Optional unit rendered beside the primary value. */
+  unit?: string;
+  /** Secondary explanatory line. */
+  detail?: string;
+  tone?: StatCardTone;
+}
+
+export interface StatCardsProps {
+  items: readonly StatCardItem[];
+  /** Accessible name for the definition list. */
+  label?: string;
+  /** Opt-in announcements for values that change independently of a control. */
+  live?: 'off' | 'polite';
+  className?: string;
+}
+
+function assertText(value: string, path: string): void {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`StatCards: ${path} must be a non-empty string.`);
+  }
+}
+
+function assertItems(items: readonly StatCardItem[]): void {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error('StatCards: items must contain at least one statistic.');
+  }
+  const keys = new Set<string>();
+  for (const [index, item] of items.entries()) {
+    if (item === null || typeof item !== 'object') {
+      throw new Error(`StatCards: items[${index}] must be a statistic object.`);
+    }
+    assertText(item.label, `items[${index}].label`);
+    if (typeof item.value !== 'string' && typeof item.value !== 'number') {
+      throw new Error(`StatCards: items[${index}].value must be a string or number.`);
+    }
+    if (typeof item.value === 'number' && !Number.isFinite(item.value)) {
+      throw new Error(`StatCards: items[${index}].value must be finite.`);
+    }
+    if (typeof item.value === 'string') assertText(item.value, `items[${index}].value`);
+    if (item.unit !== undefined) assertText(item.unit, `items[${index}].unit`);
+    if (item.detail !== undefined) assertText(item.detail, `items[${index}].detail`);
+    const tone = item.tone ?? 'neutral';
+    if (!(STAT_CARD_TONES as readonly string[]).includes(tone)) {
+      throw new Error(
+        `StatCards: items[${index}].tone must be one of ${STAT_CARD_TONES.join(' | ')}.`,
+      );
+    }
+    const key = item.id ?? item.label;
+    assertText(key, `items[${index}].id`);
+    if (keys.has(key)) throw new Error(`StatCards: duplicate item key "${key}".`);
+    keys.add(key);
+  }
+}
+
+export function StatCards({
+  items,
+  label = 'Key statistics',
+  live = 'off',
+  className,
+}: StatCardsProps) {
+  assertItems(items);
+  assertText(label, 'label');
+  if (live !== 'off' && live !== 'polite') {
+    throw new Error('StatCards: live must be off | polite.');
+  }
+  const classes = ['demo-stat-cards', className].filter(Boolean).join(' ');
+
+  return (
+    <dl
+      class={classes}
+      aria-label={label}
+      aria-live={live}
+      aria-atomic={live === 'polite' || undefined}
+    >
+      {items.map((item) => {
+        const tone = item.tone ?? 'neutral';
+        return (
+          <div class="demo-stat-card" data-tone={tone} key={item.id ?? item.label}>
+            <dt class="demo-stat-card__label">{item.label}</dt>
+            <dd class="demo-stat-card__value">
+              {item.value}
+              {item.unit && <> <span class="demo-stat-card__unit">{item.unit}</span></>}
+            </dd>
+            {item.detail && <dd class="demo-stat-card__detail">{item.detail}</dd>}
+          </div>
+        );
+      })}
+    </dl>
+  );
+}

package/components/demo/index.ts

@@ -0,0 +1,24 @@
+/** Stable, consumer-agnostic interactive-demo substrate (#143). */
+export {
+  DemoFrame,
+  DEMO_HEADING_LEVELS,
+  type DemoFrameProps,
+  type DemoHeadingLevel,
+} from './DemoFrame.js';
+export { Slider, type SliderProps } from './Slider.js';
+export {
+  StatCards,
+  STAT_CARD_TONES,
+  type StatCardItem,
+  type StatCardTone,
+  type StatCardsProps,
+} from './StatCards.js';
+export {
+  useThemeColors,
+  type BookTheme,
+  type ResolvedThemeColors,
+  type ThemeColorMap,
+  type ThemeColorSpec,
+  type ThemeColorsSnapshot,
+  type ThemeColorToken,
+} from './useThemeColors.js';

package/components/demo/useThemeColors.ts

@@ -0,0 +1,141 @@
+/**
+ * Theme-token resolver for SVG/canvas islands (#143).
+ *
+ * CSS-authored visuals should keep using var(--token) directly. Canvas and
+ * SVG attributes sometimes need concrete strings, so this hook resolves an
+ * explicit token map, refreshes it on `book:theme:change`, and exposes the
+ * user's reduced-motion preference to consumer animation code.
+ */
+import { useEffect, useState } from 'preact/hooks';
+
+export type BookTheme = 'light' | 'dark';
+export type ThemeColorToken = `--${string}`;
+export type ThemeColorSpec = readonly [token: ThemeColorToken, fallback: string];
+export type ThemeColorMap = Readonly<Record<string, ThemeColorSpec>>;
+export type ResolvedThemeColors<T extends ThemeColorMap> = {
+  readonly [Key in keyof T]: string;
+};
+
+export interface ThemeColorsSnapshot<T extends ThemeColorMap> {
+  /** Null during SSR; resolved on the first client effect. */
+  theme: BookTheme | null;
+  colors: ResolvedThemeColors<T>;
+  /** Null until the client preference is known; animate only when explicitly false. */
+  reducedMotion: boolean | null;
+}
+
+interface StoredThemeColorsSnapshot<T extends ThemeColorMap> {
+  signature: string;
+  value: ThemeColorsSnapshot<T>;
+}
+
+function fallbackColors<T extends ThemeColorMap>(specs: T): ResolvedThemeColors<T> {
+  return Object.fromEntries(
+    Object.entries(specs).map(([key, [, fallback]]) => [key, fallback]),
+  ) as ResolvedThemeColors<T>;
+}
+
+function unresolvedSnapshot<T extends ThemeColorMap>(specs: T): ThemeColorsSnapshot<T> {
+  return {
+    theme: null,
+    colors: fallbackColors(specs),
+    reducedMotion: null,
+  };
+}
+
+function assertSpecs(specs: ThemeColorMap): void {
+  if (specs === null || typeof specs !== 'object' || Array.isArray(specs)) {
+    throw new Error('useThemeColors: specs must be a token-map object.');
+  }
+  const entries = Object.entries(specs);
+  if (entries.length === 0) {
+    throw new Error('useThemeColors: provide at least one CSS token mapping.');
+  }
+  for (const [key, spec] of entries) {
+    if (key.trim() === '') {
+      throw new Error('useThemeColors: color keys must be non-empty strings.');
+    }
+    if (!Array.isArray(spec) || spec.length !== 2) {
+      throw new Error(`useThemeColors: "${key}" must be a [token, fallback] pair.`);
+    }
+    const [token, fallback] = spec;
+    if (typeof token !== 'string' || !/^--\S+$/.test(token)) {
+      throw new Error(`useThemeColors: "${key}" token must start with -- and contain no whitespace.`);
+    }
+    if (typeof fallback !== 'string' || fallback.trim() === '') {
+      throw new Error(`useThemeColors: "${key}" fallback must be a non-empty string.`);
+    }
+  }
+}
+
+function effectiveTheme(): BookTheme {
+  const explicit = document.documentElement.getAttribute('data-theme');
+  if (explicit === 'light' || explicit === 'dark') return explicit;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function snapshot<T extends ThemeColorMap>(
+  specs: T,
+  themeHint?: BookTheme,
+): ThemeColorsSnapshot<T> {
+  const computed = getComputedStyle(document.documentElement);
+  const colors = Object.fromEntries(
+    Object.entries(specs).map(([key, [token, fallback]]) => {
+      const resolved = computed.getPropertyValue(token).trim();
+      return [key, resolved || fallback];
+    }),
+  ) as ResolvedThemeColors<T>;
+  return {
+    theme: themeHint ?? effectiveTheme(),
+    colors,
+    reducedMotion: window.matchMedia('(prefers-reduced-motion: reduce)').matches,
+  };
+}
+
+/**
+ * Resolve CSS custom properties and refresh after theme/motion changes.
+ *
+ * Keep the spec object outside the component (or otherwise stable) so its
+ * intent is obvious and the hook does not need to re-subscribe each render.
+ */
+export function useThemeColors<const T extends ThemeColorMap>(
+  specs: T,
+): ThemeColorsSnapshot<T> {
+  assertSpecs(specs);
+  const signature = JSON.stringify(specs);
+  const [current, setCurrent] = useState<StoredThemeColorsSnapshot<T>>(() => ({
+    signature,
+    value: unresolvedSnapshot(specs),
+  }));
+
+  useEffect(() => {
+    const refresh = (themeHint?: BookTheme) => setCurrent({
+      signature,
+      value: snapshot(specs, themeHint),
+    });
+    const onThemeChange = (event: Event) => {
+      const detail = (event as CustomEvent<{ theme?: unknown }>).detail;
+      const theme = detail?.theme === 'light' || detail?.theme === 'dark'
+        ? detail.theme
+        : undefined;
+      refresh(theme);
+    };
+    const onMediaChange = () => refresh();
+    const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
+    const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    refresh();
+    window.addEventListener('book:theme:change', onThemeChange);
+    colorScheme.addEventListener('change', onMediaChange);
+    reducedMotion.addEventListener('change', onMediaChange);
+    return () => {
+      window.removeEventListener('book:theme:change', onThemeChange);
+      colorScheme.removeEventListener('change', onMediaChange);
+      reducedMotion.removeEventListener('change', onMediaChange);
+    };
+    // signature tracks semantic changes while allowing an inline object whose
+    // identity changes but token/fallback pairs do not.
+  }, [signature]);
+
+  return current.signature === signature ? current.value : unresolvedSnapshot(specs);
+}