@elabs-ai/components-ai 4.1.0 → 5.0.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/_persona-rive.tsx

@@ -40,8 +40,7 @@ import type { RiveParameters } from "@rive-app/react-webgl2";
 // below to `undefined`, and the guard turns that into the render-phase throw
 // `LazyEngineBoundary` (see `persona.tsx`) already catches.
 import * as RiveModule from "@rive-app/react-webgl2";
-import type { ReactNode } from "react";
-import { memo, useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 
 import type { AssertAssignable } from "./_lazy-boundary-conformance";
 import type { PersonaRiveEventCallback } from "./persona";
@@ -132,39 +131,6 @@ const useTheme = (enabled: boolean) => {
   return theme;
 };
 
-interface PersonaWithModelProps {
-  rive: ReturnType<typeof useRive>["rive"];
-  source: PersonaSource;
-  children: ReactNode;
-}
-
-const PersonaWithModel = memo(({ rive, source, children }: PersonaWithModelProps) => {
-  const theme = useTheme(source.dynamicColor);
-  const viewModel = useViewModel(rive, { useDefault: true });
-  const viewModelInstance = useViewModelInstance(viewModel, {
-    rive,
-    useDefault: true,
-  });
-  const viewModelInstanceColor = useViewModelInstanceColor("color", viewModelInstance);
-
-  useEffect(() => {
-    if (!(viewModelInstanceColor && source.dynamicColor)) {
-      return;
-    }
-
-    const [r, g, b] = theme === "dark" ? [255, 255, 255] : [0, 0, 0];
-    viewModelInstanceColor.setRgb(r, g, b);
-  }, [viewModelInstanceColor, theme, source.dynamicColor]);
-
-  return children;
-});
-
-PersonaWithModel.displayName = "PersonaWithModel";
-
-const PersonaWithoutModel = memo(({ children }: { children: ReactNode }) => children);
-
-PersonaWithoutModel.displayName = "PersonaWithoutModel";
-
 export interface PersonaRiveProps {
   className?: string;
   onLoad?: PersonaRiveEventCallback;
@@ -268,13 +234,33 @@ const PersonaRive = ({
     }
   }, [state, listeningInput, thinkingInput, speakingInput, asleepInput]);
 
-  const Wrapper = source.hasModel ? PersonaWithModel : PersonaWithoutModel;
+  // The view-model hooks run here rather than in a child that takes `rive` as
+  // a prop. React 19.2's development build logs each re-render's changed props
+  // to the browser's performance track by walking every object prop a few
+  // levels deep. That walk never finished on a loaded Rive instance: handing
+  // one to a component as a prop froze the tab until it ran out of memory, in
+  // development builds only. Keep the instance out of props. Each hook accepts
+  // `null`, which is how a source without a view model opts out.
+  const modelRive = source.hasModel ? rive : null;
+  const dynamicColor = source.hasModel && source.dynamicColor;
+  const theme = useTheme(dynamicColor);
+  const viewModel = useViewModel(modelRive, { useDefault: true });
+  const viewModelInstance = useViewModelInstance(viewModel, {
+    rive: modelRive,
+    useDefault: true,
+  });
+  const viewModelInstanceColor = useViewModelInstanceColor("color", viewModelInstance);
 
-  return (
-    <Wrapper rive={rive} source={source}>
-      <RiveComponent className={cn("size-16 shrink-0", className)} />
-    </Wrapper>
-  );
+  useEffect(() => {
+    if (!(viewModelInstanceColor && dynamicColor)) {
+      return;
+    }
+
+    const [r, g, b] = theme === "dark" ? [255, 255, 255] : [0, 0, 0];
+    viewModelInstanceColor.setRgb(r, g, b);
+  }, [viewModelInstanceColor, theme, dynamicColor]);
+
+  return <RiveComponent className={cn("size-16 shrink-0", className)} />;
 };
 
 export default PersonaRive;

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));
+  });
+});