@elabs-ai/components-ai 4.1.0 → 4.2.0

package/src/_lazy-cjk.test.ts

@@ -0,0 +1,43 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { needsCjkPlugin, preloadCjk, useLazyCjkPlugin } from "./_lazy-cjk";
+
+const fakeCjkPlugin = {
+  name: "cjk",
+  remarkPlugins: [],
+  remarkPluginsAfter: [],
+  remarkPluginsBefore: [],
+  type: "cjk",
+};
+
+vi.mock("@streamdown/cjk", () => ({ cjk: fakeCjkPlugin }));
+
+describe("needsCjkPlugin", () => {
+  it("returns false for plain ASCII text", () => {
+    expect(needsCjkPlugin("plain text")).toBe(false);
+  });
+
+  it("matches CJK Unified Ideographs, Hiragana, Katakana and Hangul", () => {
+    expect(needsCjkPlugin("你好")).toBe(true);
+    expect(needsCjkPlugin("こんにちは")).toBe(true);
+    expect(needsCjkPlugin("コンニチハ")).toBe(true);
+    expect(needsCjkPlugin("안녕하세요")).toBe(true);
+  });
+});
+
+describe("useLazyCjkPlugin", () => {
+  it("returns undefined when the text has no CJK codepoints", () => {
+    const { result } = renderHook(() => useLazyCjkPlugin("plain text"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("loads and returns the plugin once the text needs CJK handling", async () => {
+    const { result } = renderHook(() => useLazyCjkPlugin("你好，世界"));
+    await waitFor(() => expect(result.current).toBe(fakeCjkPlugin));
+  });
+
+  it("preloadCjk resolves without throwing", () => {
+    expect(() => preloadCjk()).not.toThrow();
+  });
+});

package/src/_lazy-cjk.ts

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * Lazy-loaded replacement for `@streamdown/cjk`'s eager `cjk` export.
+ *
+ * Same rationale and mechanism as `_lazy-math.ts` — `remark-cjk-friendly` +
+ * `remark-cjk-friendly-gfm-strikethrough` load only once `needsCjkPlugin(text)`
+ * sees a CJK codepoint, instead of shipping in every consumer's entry chunk.
+ * See `_lazy-math.ts` for why a remark `Pluggable` cannot be deferred the way
+ * `DiagramPlugin` defers Mermaid's render, and for the one-paint literal-text
+ * cost this trades for it.
+ */
+import type { CjkPlugin } from "@streamdown/cjk";
+import { useEffect, useState } from "react";
+
+/**
+ * Hiragana, Katakana, CJK Unified Ideographs (+ Extension A), Hangul Syllables,
+ * CJK punctuation and halfwidth Katakana — the ranges `remark-cjk-friendly`
+ * exists to handle (emphasis/strikethrough boundary rules around CJK text).
+ */
+// The range's first codepoint is the ideographic full-width space, not
+// accidental whitespace — a deliberate boundary character, not noise.
+// eslint-disable-next-line no-irregular-whitespace -- see comment above
+const CJK_RANGE_RE = /[　-〿぀-ヿ㐀-䶿一-鿿가-힣･-ﾟ]/u;
+
+/** Does `text` contain a CJK codepoint? */
+export function needsCjkPlugin(text: string): boolean {
+  return CJK_RANGE_RE.test(text);
+}
+
+/** Module-level singleton: the plugin loads at most once. */
+let cachedPlugin: CjkPlugin | undefined;
+let loadPromise: Promise<CjkPlugin> | undefined;
+
+function loadCjkPlugin(): Promise<CjkPlugin> {
+  loadPromise ??= import("@streamdown/cjk").then((mod) => {
+    cachedPlugin = mod.cjk;
+    return cachedPlugin;
+  });
+  return loadPromise;
+}
+
+/**
+ * Start fetching the CJK plugin ahead of time (e.g. once a conversation's
+ * locale is known to be CJK). Optional; rendering CJK text loads it either way.
+ */
+export const preloadCjk = (): void => {
+  void loadCjkPlugin();
+};
+
+/**
+ * Returns the loaded `CjkPlugin` once `text` needs one, else `undefined`
+ * (Streamdown treats an absent `plugins.cjk` slot as "no CJK handling" — plain
+ * remark-gfm boundary rules apply until the plugin arrives).
+ */
+export function useLazyCjkPlugin(text: string): CjkPlugin | undefined {
+  const needed = needsCjkPlugin(text);
+  const [plugin, setPlugin] = useState<CjkPlugin | undefined>(cachedPlugin);
+
+  useEffect(() => {
+    if (!needed || cachedPlugin) return;
+    let cancelled = false;
+    loadCjkPlugin().then((loaded) => {
+      if (!cancelled) setPlugin(loaded);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [needed]);
+
+  if (!needed) return undefined;
+  return plugin ?? cachedPlugin;
+}

package/src/_lazy-math.test.ts

@@ -0,0 +1,63 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { needsMathPlugin, preloadMath, useLazyMathPlugin } from "./_lazy-math";
+
+/**
+ * The KaTeX-carrying `@streamdown/math` module is mocked so this file tests
+ * the lazy wrapper's *behaviour*. That the real dependency is genuinely
+ * absent from the entry chunk is a property of the BUILD, not of jsdom — see
+ * `pnpm check --rule eager-heavy-deps`, which
+ * asserts no `packages/ai/src` module statically imports `@streamdown/math`
+ * or `katex`.
+ */
+const fakeMathPlugin = {
+  name: "katex",
+  rehypePlugin: vi.fn(),
+  remarkPlugin: vi.fn(),
+  type: "math",
+};
+
+vi.mock("@streamdown/math", () => ({ math: fakeMathPlugin }));
+
+describe("needsMathPlugin", () => {
+  it("matches $$block$$ and $inline$ delimiters", () => {
+    expect(needsMathPlugin("plain text")).toBe(false);
+    expect(needsMathPlugin("$$x^2$$")).toBe(true);
+    expect(needsMathPlugin("the answer is $x + 1$ today")).toBe(true);
+  });
+
+  it("matches \\( \\) and \\[ \\] delimiters", () => {
+    expect(needsMathPlugin("\\(x^2\\)")).toBe(true);
+    expect(needsMathPlugin("\\[x^2\\]")).toBe(true);
+  });
+
+  it("does not false-positive on a bare dollar amount", () => {
+    // A single, unpaired `$` (no closing delimiter on the same line) is not math.
+    expect(needsMathPlugin("that costs $5")).toBe(false);
+  });
+});
+
+describe("useLazyMathPlugin", () => {
+  it("returns undefined when the text has no math delimiters", () => {
+    const { result } = renderHook(() => useLazyMathPlugin("plain text"));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("loads and returns the plugin once the text needs math", async () => {
+    const { result } = renderHook(() => useLazyMathPlugin("$$x^2$$"));
+    await waitFor(() => expect(result.current).toBe(fakeMathPlugin));
+  });
+
+  it("preloadMath resolves without throwing", () => {
+    expect(() => preloadMath()).not.toThrow();
+  });
+
+  it("serves a second, simultaneous consumer off the same cached load", async () => {
+    const first = renderHook(() => useLazyMathPlugin("$$x^2$$"));
+    const second = renderHook(() => useLazyMathPlugin("$y^2$"));
+
+    await waitFor(() => expect(first.result.current).toBe(fakeMathPlugin));
+    await waitFor(() => expect(second.result.current).toBe(fakeMathPlugin));
+  });
+});

package/src/_lazy-math.ts

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * Lazy-loaded replacement for `@streamdown/math`'s eager `math` export.
+ *
+ * Why this exists
+ * ----------------
+ * `@streamdown/math` bundles KaTeX (~600 KB unminified) plus `remark-math` and
+ * `rehype-katex`. `useStreamdownPlugins()` (`_streamdown-i18n.ts`) used to
+ * import it statically, so every consumer of `MessageResponse`/`MarkdownView`/
+ * `ReasoningContent` paid for KaTeX in their entry chunk whether or not a
+ * single conversation ever contains `$…$`.
+ *
+ * How it stays correct
+ * ---------------------
+ * Unlike Mermaid (`_lazy-mermaid.ts`), a remark/rehype `Pluggable` cannot be
+ * wrapped in a lazy accessor: `remark-math`'s micromark extension has to be
+ * registered on the unified processor BEFORE it parses, so there is no way to
+ * hand Streamdown a present-but-deferred math plugin the way `DiagramPlugin`
+ * defers its render. Instead:
+ *
+ *  1. `needsMathPlugin(text)` cheaply sniffs the RAW markdown source for `$…$`
+ *     / `\(…\)` / `\[…\]` delimiters — no parsing, just a regex.
+ *  2. `useLazyMathPlugin(text)` returns `undefined` until that sniff is true,
+ *     at which point it kicks off `import("@streamdown/math")` and returns the
+ *     loaded plugin once it resolves, triggering a re-render.
+ *
+ * The one user-visible cost: a message whose FIRST rendered chunk already
+ * contains math delimiters shows literal `$x^2$` for one paint before the
+ * import resolves (typically well under a frame from a warm cache, since the
+ * chunk is tiny next to KaTeX's own parse/layout work). Every subsequent
+ * message reuses the module-level cache and never re-pays it.
+ */
+import type { MathPlugin } from "@streamdown/math";
+import { useEffect, useState } from "react";
+
+/** Cheap, over-inclusive sniff — a false positive just means an unneeded fetch. */
+const MATH_DELIMITER_RE = /\$\$[\s\S]*?\$\$|\$[^\s$][^$\n]*\$|\\\(|\\\)|\\\[|\\\]/;
+
+/** Does `text` look like it contains LaTeX math delimiters? */
+export function needsMathPlugin(text: string): boolean {
+  return MATH_DELIMITER_RE.test(text);
+}
+
+/** Module-level singleton: the plugin (and its KaTeX bytes) load at most once. */
+let cachedPlugin: MathPlugin | undefined;
+let loadPromise: Promise<MathPlugin> | undefined;
+
+function loadMathPlugin(): Promise<MathPlugin> {
+  loadPromise ??= import("@streamdown/math").then((mod) => {
+    cachedPlugin = mod.math;
+    return cachedPlugin;
+  });
+  return loadPromise;
+}
+
+/**
+ * Start fetching the math plugin ahead of time (e.g. once a conversation is
+ * known to contain math, or on route entry). Optional; rendering math loads
+ * it either way.
+ */
+export const preloadMath = (): void => {
+  void loadMathPlugin();
+};
+
+/**
+ * Returns the loaded `MathPlugin` once `text` needs one, else `undefined`
+ * (Streamdown treats an absent `plugins.math` slot as "no math support" — the
+ * delimiters render as literal text until the plugin arrives).
+ */
+export function useLazyMathPlugin(text: string): MathPlugin | undefined {
+  const needed = needsMathPlugin(text);
+  const [plugin, setPlugin] = useState<MathPlugin | undefined>(cachedPlugin);
+
+  useEffect(() => {
+    if (!needed || cachedPlugin) return;
+    let cancelled = false;
+    loadMathPlugin().then((loaded) => {
+      if (!cancelled) setPlugin(loaded);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [needed]);
+
+  if (!needed) return undefined;
+  // `cachedPlugin` covers the case where another instance finished loading
+  // between this component's mount and this render (state update pending).
+  return plugin ?? cachedPlugin;
+}

package/src/_streamdown-i18n.ts

@@ -29,14 +29,15 @@ import {
   useStreamdownTranslations,
   type StreamdownTranslationKey,
 } from "@elabs-ai/components-ui";
-import { cjk } from "@streamdown/cjk";
 import { createCodePlugin } from "@streamdown/code";
-import { math } from "@streamdown/math";
-import { useEffect, useMemo, useState } from "react";
+import { useMemo } from "react";
 import type { StreamdownTranslations } from "streamdown";
 import { buildCodeBlockTheme } from "./_code-block-theme";
+import { useLazyCjkPlugin } from "./_lazy-cjk";
+import { useLazyMathPlugin } from "./_lazy-math";
 import { lazyMermaid } from "./_lazy-mermaid";
 import { MermaidErrorPanel } from "./_mermaid-error-panel";
+import { useThemeScopeRevision } from "./_theme-scope-store";
 
 /**
  * Reactive replacement for `@streamdown/code`'s pre-configured `code` export
@@ -55,24 +56,25 @@ import { MermaidErrorPanel } from "./_mermaid-error-panel";
  * theme the active `data-theme` resolves to — so whichever slot the `.dark`
  * selector picks, it's the CORRECT theme for whatever is actually active.
  *
- * Re-derives on every `data-theme` mutation (a `MutationObserver` on
- * `<html>`, mirroring `code-block.tsx`'s own) and returns a NEW plugin object
+ * Re-derives on every `data-theme` mutation and returns a NEW plugin object
  * each time, because Streamdown only re-reads `plugins.code.getThemes()` when
  * the `plugins.code` object's REFERENCE changes (see streamdown's internal
  * `shikiTheme` memo) — a mutated-in-place plugin would never be picked up.
+ *
+ * The mutation watch itself comes from the SHARED, ref-counted store in
+ * `./_theme-scope-store` (perf review §3.3) rather than a `MutationObserver`
+ * instantiated per hook call — every simultaneously-mounted
+ * `MessageResponse`/`MarkdownView` (and every `CodeBlock`) in a message-dense
+ * conversation now shares exactly one observer per distinct scope element,
+ * instead of one each. This hook has no element of its own to scope to (it
+ * runs before Streamdown renders anything), so it resolves to the document's
+ * theme scope (`getThemeScope(null)` → closest `[data-theme]` on `<html>`,
+ * same as its prior always-`<html>` behaviour) — a genuinely region-scoped
+ * derivation would need a ref to the rendered surface, which no current call
+ * site (`message.tsx`, `markdown-view.tsx`, `reasoning.tsx`) has available.
  */
 function useReactiveCodePlugin() {
-  const [revision, setRevision] = useState(0);
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-    const observer = new MutationObserver(() => setRevision((r) => r + 1));
-    observer.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ["data-theme"],
-    });
-    return () => observer.disconnect();
-  }, []);
+  const revision = useThemeScopeRevision(null);
 
   return useMemo(() => {
     const theme = buildCodeBlockTheme();
@@ -85,15 +87,65 @@ function useReactiveCodePlugin() {
  * The plugin set every `@elabs-ai/components-ai` markdown surface renders with.
  *
  * `mermaid` is the LAZY plugin (`./_lazy-mermaid`): the engine + d3 + DOMPurify
- * load on first diagram render, not in the entry chunk of every consumer. `code`
- * is the reactive, brand-token-derived plugin above (#315) — never the
+ * load on first diagram render, not in the entry chunk of every consumer.
+ * `math`/`cjk` are ALSO lazy (`./_lazy-math`, `./_lazy-cjk`, #perf-5): KaTeX
+ * (~600 KB) and the CJK remark plugins load only once `text` — the raw
+ * markdown source about to render — actually needs them, sniffed by a cheap
+ * regex rather than shipped unconditionally in every consumer's entry chunk.
+ * Both resolve to `undefined` (the slot is simply absent) until their content
+ * cue fires and the dynamic import resolves; see the two modules' docs for the
+ * one-paint tradeoff this makes and why it can't be avoided the way Mermaid's
+ * render-time laziness is.
+ *
+ * `code` is the reactive, brand-token-derived plugin above (#315) — never the
  * `@streamdown/code` package's static `github-light`/`github-dark` default.
  * Memoized so Streamdown sees a referentially stable `plugins` prop except when
- * the active theme actually changes.
+ * the active theme (or a lazy slot) actually changes.
+ *
+ * @param text The raw markdown source about to render — used only to decide
+ *   whether the math/CJK plugins are needed. Pass `""` to never load them
+ *   speculatively.
  */
-export function useStreamdownPlugins() {
+export function useStreamdownPlugins(text = "") {
   const code = useReactiveCodePlugin();
-  return useMemo(() => ({ cjk, code, math, mermaid: lazyMermaid }), [code]);
+  const math = useLazyMathPlugin(text);
+  const cjk = useLazyCjkPlugin(text);
+  return useMemo(() => ({ cjk, code, math, mermaid: lazyMermaid }), [cjk, code, math]);
+}
+
+/**
+ * A React `key` for the `<Streamdown>` element that renders with
+ * {@link useStreamdownPlugins}'s result — pass it as `key={getStreamdownPluginsKey(plugins)}`
+ * on the `<Streamdown>` JSX, never inside the `plugins` object itself.
+ *
+ * Why this exists (#perf-5 follow-up): Streamdown v2.5.0's `rehypePlugins`/
+ * `remarkPlugins` are `useMemo`'d with `plugins.math`/`plugins.cjk` in their
+ * dependency arrays, and its `Block`/`Streamdown` components' custom `memo`
+ * comparators do check plugin reference equality — on paper, a fresh
+ * `plugins.math` object arriving after the lazy `import()` resolves should be
+ * enough to make Streamdown rebuild its processing pipeline with the math
+ * plugin included. Empirically (verified directly against the real
+ * `streamdown` package, not a mock) it does not: once a block has rendered
+ * once without `plugins.math`/`plugins.cjk`, Streamdown's internal processor
+ * cache keeps serving the plugin-less result even after the reference
+ * changes, and the literal `$$…$$`/CJK-remark-less markdown source stays
+ * un-rendered indefinitely.
+ *
+ * Forcing React to unmount and remount the `<Streamdown>` element — by
+ * changing its `key` — sidesteps that internal cache entirely (a fresh
+ * instance has no stale cache to serve) and reliably picks up the lazily
+ * loaded plugin. The cost is a one-time full remount of that Streamdown
+ * instance the first time its lazy math/CJK slot resolves — at most once per
+ * mounted instance, since after that the key is stable again. Filed for
+ * upstream investigation; if a future `streamdown` release fixes the
+ * underlying cache, this key can be dropped without changing any call site's
+ * behavior (an unchanging key is a no-op).
+ */
+export function getStreamdownPluginsKey(plugins: {
+  readonly cjk?: unknown;
+  readonly math?: unknown;
+}): string {
+  return `${plugins.math ? "math" : "no-math"}:${plugins.cjk ? "cjk" : "no-cjk"}`;
 }
 
 /**

package/src/_streamdown-safety.ts

@@ -36,7 +36,7 @@
  * schema instead of replacing the pipeline outright.
  *
  * THIS LIST HAS A PARITY COUNTERPART, AND EDITING ONE SIDE FAILS CI (#75).
- * `scripts/check-sanitizer-passthrough.mjs` declares the same key set as
+ * `scripts/check/rules/sanitizer-passthrough.mjs` declares the same key set as
  * `SAFE_RENDERERS[streamdown].dangerousProps` and reads THIS array literal back
  * out of this file, asserting set-equality in BOTH directions — so removing a
  * key here (the runtime stops stripping it) and removing a key there (the gate
@@ -153,7 +153,7 @@ export function warnOnTrustedPluginSlots(overrides: object | undefined, internal
 
   if (isPluginObject(consumer.mermaid) && consumer.mermaid !== defaults.mermaid) {
     // The message describes React's `dangerouslySetInnerHTML` in prose rather than
-    // naming the identifier: `pnpm csp-sinks:check` preserves string literals on
+    // naming the identifier: the `trusted-types-sinks` check preserves string literals on
     // purpose (a sink hidden in a string is still a sink), so spelling the prop out
     // inside this warning makes the gate read THIS file as a new HTML-assigning
     // module. Comments like this one are stripped by that gate, so the name is safe

package/src/_theme-scope-store.test.ts

@@ -0,0 +1,83 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  _debugActiveThemeScopeCount,
+  getThemeScope,
+  useThemeScopeRevision,
+} from "./_theme-scope-store";
+
+afterEach(() => {
+  document.documentElement.removeAttribute("data-theme");
+  document.body.innerHTML = "";
+});
+
+describe("getThemeScope", () => {
+  it("resolves the nearest data-theme ancestor, falling back to <html>", () => {
+    expect(getThemeScope(document.body)).toBe(document.documentElement);
+
+    const scoped = document.createElement("div");
+    scoped.setAttribute("data-theme", "dark");
+    document.body.append(scoped);
+    expect(getThemeScope(scoped)).toBe(scoped);
+  });
+});
+
+describe("useThemeScopeRevision (perf review §3.3)", () => {
+  it("bumps the revision when the scoped element's data-theme mutates", async () => {
+    const { result } = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const before = result.current;
+
+    document.documentElement.setAttribute("data-theme", "dark");
+
+    await waitFor(() => expect(result.current).toBe(before + 1));
+  });
+
+  it("shares ONE MutationObserver across every subscriber of the same scope", async () => {
+    const before = _debugActiveThemeScopeCount();
+    const hookA = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const hookB = renderHook(() => useThemeScopeRevision(document.documentElement));
+    const hookC = renderHook(() => useThemeScopeRevision(document.documentElement));
+
+    // Three subscribers to the SAME scope element register as exactly one
+    // tracked scope, not three — this is the fix: previously each caller
+    // (CodeBlockContent, useReactiveCodePlugin) instantiated its own
+    // MutationObserver on the same ancestor.
+    expect(_debugActiveThemeScopeCount()).toBe(before + 1);
+
+    document.documentElement.setAttribute("data-theme", "dark");
+
+    // Every subscriber still gets notified through the single observer.
+    await waitFor(() => expect(hookA.result.current).toBe(1));
+    expect(hookB.result.current).toBe(1);
+    expect(hookC.result.current).toBe(1);
+
+    hookA.unmount();
+    hookB.unmount();
+    expect(_debugActiveThemeScopeCount()).toBe(before + 1); // still one listener left (hookC)
+    hookC.unmount();
+    expect(_debugActiveThemeScopeCount()).toBe(before); // the observer is disconnected once unused
+  });
+
+  it("scopes to the closest [data-theme] ancestor, not always <html>", async () => {
+    const outer = document.createElement("div");
+    outer.setAttribute("data-theme", "light");
+    const inner = document.createElement("div");
+    inner.setAttribute("data-theme", "dark");
+    outer.append(inner);
+    document.body.append(outer);
+
+    const { result } = renderHook(() => useThemeScopeRevision(inner));
+    const before = result.current;
+
+    // A mutation on the OUTER (non-closest) ancestor must not affect a
+    // consumer scoped to the inner region. There is nothing to `waitFor`
+    // here (a NEGATIVE assertion), so flush the microtask queue directly.
+    outer.setAttribute("data-theme", "light-updated");
+    await Promise.resolve();
+    expect(result.current).toBe(before);
+
+    // A mutation on the actually-closest scope element does.
+    inner.setAttribute("data-theme", "light");
+    await waitFor(() => expect(result.current).toBe(before + 1));
+  });
+});

package/src/_theme-scope-store.ts

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * Shared, ref-counted `data-theme` observation (perf review §3.3).
+ *
+ * `code-block.tsx`'s `CodeBlockContent` and `_streamdown-i18n.ts`'s
+ * `useReactiveCodePlugin` each used to instantiate their OWN
+ * `MutationObserver` to notice a `data-theme` flip and re-derive the Shiki
+ * theme — one observer PER rendered `CodeBlock`/`MessageResponse`/
+ * `MarkdownView` instance, all typically watching the exact same ancestor. In
+ * a message-dense conversation that is dozens of redundant observers doing
+ * the same job.
+ *
+ * This module keeps exactly ONE `MutationObserver` per distinct scope
+ * element (ref-counted: the observer is created on the first subscriber and
+ * disconnected when the last one unsubscribes), and exposes it through
+ * `useSyncExternalStore` so React's own re-render batching applies.
+ */
+import { useCallback, useSyncExternalStore } from "react";
+
+/**
+ * Nearest ancestor (inclusive) carrying `data-theme`, defaulting to `<html>`.
+ * Lets a themed surface rendered inside a region-scoped
+ * `<div data-theme="…">` (a supported `ThemeProvider`/decorator pattern —
+ * see @.claude/rules/theming.md) resolve THAT region's tokens instead of
+ * always the document root's.
+ */
+export function getThemeScope(el: Element | null): Element | null {
+  return (
+    el?.closest("[data-theme]") ??
+    (typeof document !== "undefined" ? document.documentElement : null)
+  );
+}
+
+interface ScopeEntry {
+  observer: MutationObserver;
+  revision: number;
+  listeners: Set<() => void>;
+}
+
+const scopes = new Map<Element, ScopeEntry>();
+
+function subscribe(scope: Element | null, onStoreChange: () => void): () => void {
+  if (!scope) return () => {};
+
+  let entry = scopes.get(scope);
+  if (!entry) {
+    // `entry` is assigned before `observer` fires, but TypeScript can't see
+    // that through the closure — the callback only ever runs after this
+    // function returns and `entry` has been set, and every existing
+    // subscriber to this scope uses the SAME entry.
+    const created: ScopeEntry = {
+      listeners: new Set(),
+      observer: new MutationObserver(() => {
+        created.revision += 1;
+        for (const listener of created.listeners) listener();
+      }),
+      revision: 0,
+    };
+    created.observer.observe(scope, { attributeFilter: ["data-theme"], attributes: true });
+    scopes.set(scope, created);
+    entry = created;
+  }
+
+  entry.listeners.add(onStoreChange);
+  return () => {
+    const current = scopes.get(scope);
+    if (!current) return;
+    current.listeners.delete(onStoreChange);
+    if (current.listeners.size === 0) {
+      current.observer.disconnect();
+      scopes.delete(scope);
+    }
+  };
+}
+
+function getSnapshot(scope: Element | null): number {
+  if (!scope) return 0;
+  return scopes.get(scope)?.revision ?? 0;
+}
+
+const getServerSnapshot = () => 0;
+
+/**
+ * Subscribes to `data-theme` mutations on `el`'s closest `[data-theme]`
+ * ancestor (default `<html>`) and returns a revision number that increments
+ * on each mutation. Any number of callers scoped to the SAME ancestor share
+ * one `MutationObserver`.
+ */
+export function useThemeScopeRevision(el: Element | null): number {
+  const scope = getThemeScope(el);
+  const subscribeToScope = useCallback(
+    (onStoreChange: () => void) => subscribe(scope, onStoreChange),
+    [scope],
+  );
+  const getScopeSnapshot = useCallback(() => getSnapshot(scope), [scope]);
+  return useSyncExternalStore(subscribeToScope, getScopeSnapshot, getServerSnapshot);
+}
+
+/** Test-only: the number of scope elements currently under observation. */
+export function _debugActiveThemeScopeCount(): number {
+  return scopes.size;
+}

package/src/agent-event.tsx

@@ -102,7 +102,7 @@ function AgentEventCheckRow({ check }: { check: CheckResult }) {
       {detail !== undefined && detail !== "" && (
         <p
           data-slot="agent-event-check-detail"
-          className="pl-5 text-caption text-muted-foreground break-words"
+          className="ps-5 text-caption text-muted-foreground break-words"
         >
           {detail}
         </p>