@mui/internal-docs-infra 0.11.1-canary.6 → 0.11.1-canary.8

package/cli/ensureDemoClients.mjs

@@ -174,9 +174,13 @@ function insertClientProviderImport(source, importsAndComments) {
 /**
  * Converts a Turbopack-style glob (e.g. `./app/**\/demos/*\/index.ts`) to a
  * RegExp that matches absolute filesystem paths. Mirrors the logic used by
- * `withDocsInfra` for webpack rule generation.
+ * `withDocsInfra` for webpack rule generation. Pass-through when the input is
+ * already a RegExp (webpack-rule `test` regexes).
  */
 function patternToRegExp(pattern) {
+  if (pattern instanceof RegExp) {
+    return pattern;
+  }
   const SEP = '\u0000SEP\u0000';
   const NOT_SEP = '\u0000NOT_SEP\u0000';
   const DOUBLE_STAR = '\u0000DOUBLE_STAR\u0000';
@@ -187,9 +191,13 @@ function patternToRegExp(pattern) {
 
 /**
  * Finds the longest fixed-prefix directory in a glob pattern so we can avoid
- * walking the entire workspace.
+ * walking the entire workspace. Webpack `test` regexes have no extractable
+ * prefix, so we fall back to walking from `baseDir`.
  */
 function patternBaseDir(pattern, baseDir) {
+  if (pattern instanceof RegExp) {
+    return baseDir;
+  }
   const stripped = pattern.replace(/^\.\//, '');
   const segments = stripped.split('/');
   const fixed = [];

package/cli/loadNextConfig.d.mts

@@ -1,8 +1,12 @@
 import type { DescriptionReplacement } from "../pipeline/loadServerTypesMeta/format.mjs";
 import type { OrderingConfig } from "../pipeline/loadServerTypesText/order.mjs";
 export interface DemoClientRequirement {
-  /** Glob pattern (Turbopack-style) used as the rule key, e.g. `./app/**\/demos/*\/index.ts`. */
-  pattern: string;
+  /**
+   * Either a Turbopack-style glob pattern (e.g. `./app/**\/demos/*\/index.ts`)
+   * or a webpack-style RegExp used as the rule's `test`. Globs are extracted
+   * from `turbopack.rules`; RegExps are extracted from `webpack` rules.
+   */
+  pattern: string | RegExp;
   /** Import specifier passed verbatim into the generated `client.ts`. */
   requireClient: string;
 }

package/cli/loadNextConfig.mjs

@@ -1,6 +1,7 @@
 import { access } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { createJiti } from 'jiti';
 const TYPES_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedTypes';
 const CODE_HIGHLIGHTER_LOADER = '@mui/internal-docs-infra/pipeline/loadPrecomputedCodeHighlighter';
 const TRANSFORM_METADATA_PLUGIN = '@mui/internal-docs-infra/pipeline/transformMarkdownMetadata';
@@ -83,43 +84,90 @@ function extractOptionsFromTurbopack(config) {
 }
 
 /**
- * Calls the webpack function with a minimal config and extracts docs-infra
- * options (ordering, descriptionReplacements, socketDir, useVisibleDescription)
- * from the resulting rules.
+ * Builds a mock webpack config rich enough to satisfy common patterns used by
+ * real `next.config` webpack functions (e.g. `config.resolve.extensions.filter`,
+ * `config.module.rules.forEach`, `config.externals.slice`). Real webpack passes
+ * an object with these properties populated, so a too-minimal mock causes
+ * configs to throw before we can read their rules.
  */
-function extractOptionsFromWebpack(config) {
-  if (typeof config?.webpack !== 'function') {
-    return {};
-  }
-  const webpackConfig = {
+function createMockWebpackConfig() {
+  return {
     module: {
       rules: []
     },
     resolve: {
-      alias: {}
+      alias: {},
+      extensions: ['.mjs', '.js', '.jsx', '.ts', '.tsx', '.json'],
+      modules: [],
+      fallback: {}
     },
-    plugins: []
+    plugins: [],
+    externals: [],
+    optimization: {},
+    output: {},
+    experiments: {}
   };
-  try {
-    const result = config.webpack(webpackConfig, {
-      defaultLoaders: {
-        babel: {}
-      }
-    });
-    const merged = {};
-    for (const rule of result?.module?.rules ?? []) {
-      const useEntries = Array.isArray(rule?.use) ? rule.use : [];
-      const extracted = extractOptionsFromLoaderEntries(useEntries);
-      merged.ordering ??= extracted.ordering;
-      merged.descriptionReplacements ??= extracted.descriptionReplacements;
-      merged.useVisibleDescription ??= extracted.useVisibleDescription;
-      merged.socketDir ??= extracted.socketDir;
-    }
-    return merged;
-  } catch {
-    // webpack function may throw without real webpack context — ignore
+}
+
+/**
+ * Calls the webpack function with mock config + options pairs for both client
+ * and server builds, returning a merged config or `null` if both variants
+ * throw. Some Next.js configs only add loader rules when `options.isServer`
+ * is true, so we need to evaluate both branches.
+ */
+function callWebpackSafely(config) {
+  if (typeof config?.webpack !== 'function') {
+    return null;
+  }
+  const results = [];
+  for (const isServer of [false, true]) {
+    try {
+      results.push(config.webpack(createMockWebpackConfig(), {
+        defaultLoaders: {
+          babel: {}
+        },
+        isServer,
+        nextRuntime: isServer ? 'nodejs' : undefined,
+        dev: false,
+        buildId: 'docs-infra-validate',
+        config: {
+          env: {}
+        },
+        webpack: () => ({})
+      }));
+    } catch {
+      // try next variant
+    }
+  }
+  if (results.length === 0) {
+    return null;
+  }
+  const mergedRules = results.flatMap(result => Array.isArray(result?.module?.rules) ? result.module.rules : []);
+  return {
+    ...results[0],
+    module: {
+      ...(results[0]?.module ?? {}),
+      rules: mergedRules
+    }
+  };
+}
+
+/**
+ * Calls the webpack function with a minimal config and extracts docs-infra
+ * options (ordering, descriptionReplacements, socketDir, useVisibleDescription)
+ * from the resulting rules.
+ */
+function extractOptionsFromWebpackResult(result) {
+  const merged = {};
+  for (const rule of result?.module?.rules ?? []) {
+    const useEntries = Array.isArray(rule?.use) ? rule.use : [];
+    const extracted = extractOptionsFromLoaderEntries(useEntries);
+    merged.ordering ??= extracted.ordering;
+    merged.descriptionReplacements ??= extracted.descriptionReplacements;
+    merged.useVisibleDescription ??= extracted.useVisibleDescription;
+    merged.socketDir ??= extracted.socketDir;
   }
-  return {};
+  return merged;
 }
 const NEXT_CONFIG_EXTENSIONS = ['.mjs', '.js', '.ts'];
 
@@ -154,28 +202,71 @@ function extractDemoClientRequirementsFromTurbopack(config) {
   }
   return requirements;
 }
+
+/**
+ * Walks webpack rules to collect demo `test` regexes that opted into automatic
+ * `client.ts` generation via the `requireClient` option. Mirrors the Turbopack
+ * extractor but uses the rule's RegExp `test` as the pattern.
+ */
+function extractDemoClientRequirementsFromWebpackResult(result) {
+  const requirements = [];
+  for (const rule of result?.module?.rules ?? []) {
+    if (!(rule?.test instanceof RegExp)) {
+      continue;
+    }
+    const useEntries = Array.isArray(rule.use) ? rule.use : [];
+    for (const loader of useEntries) {
+      if (loader?.loader === CODE_HIGHLIGHTER_LOADER && typeof loader?.options?.requireClient === 'string') {
+        requirements.push({
+          pattern: rule.test,
+          requireClient: loader.options.requireClient
+        });
+        break;
+      }
+    }
+  }
+  return requirements;
+}
 export async function extractDocsInfraOptionsFromNextConfig(dir) {
   const configPath = await findNextConfig(dir);
   if (!configPath) {
     return {};
   }
+  let config;
   try {
-    const configModule = await import(pathToFileURL(configPath).href);
-    const config = configModule.default;
-    const turbopack = extractOptionsFromTurbopack(config);
-    const webpack = extractOptionsFromWebpack(config);
-    const demoClientRequirements = extractDemoClientRequirementsFromTurbopack(config);
-    return {
-      ordering: turbopack.ordering ?? webpack.ordering,
-      descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
-      useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
-      socketDir: turbopack.socketDir ?? webpack.socketDir,
-      demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined
-    };
-  } catch {
-    // Config not importable — use defaults
+    if (configPath.endsWith('.ts')) {
+      // Use jiti so TypeScript configs (and their transitive .ts imports
+      // without extensions) load the same way Next.js itself loads them.
+      const jiti = createJiti(configPath, {
+        interopDefault: true
+      });
+      const configModule = await jiti.import(configPath);
+      config = configModule?.default ?? configModule;
+    } else {
+      const configModule = await import(pathToFileURL(configPath).href);
+      config = configModule.default;
+    }
+  } catch (error) {
+    // Surface the failure: a silently-swallowed import error here means
+    // demoClientRequirements (and other extracted options) end up empty,
+    // which usually presents to the user as `validate` doing nothing.
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[docs-infra] Failed to load ${path.relative(dir, configPath)} for option extraction: ${message}`);
+    return {};
   }
-  return {};
+  const turbopack = extractOptionsFromTurbopack(config);
+  const webpackResult = callWebpackSafely(config);
+  const webpack = webpackResult ? extractOptionsFromWebpackResult(webpackResult) : {};
+  const turbopackDemoClientRequirements = extractDemoClientRequirementsFromTurbopack(config);
+  const webpackDemoClientRequirements = webpackResult ? extractDemoClientRequirementsFromWebpackResult(webpackResult) : [];
+  const demoClientRequirements = [...new Map([...turbopackDemoClientRequirements, ...webpackDemoClientRequirements].map(requirement => [`${typeof requirement.pattern === 'string' ? requirement.pattern : requirement.pattern.toString()}::${requirement.requireClient}`, requirement])).values()];
+  return {
+    ordering: turbopack.ordering ?? webpack.ordering,
+    descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
+    useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
+    socketDir: turbopack.socketDir ?? webpack.socketDir,
+    demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined
+  };
 }
 async function findNextConfig(dir) {
   const checks = NEXT_CONFIG_EXTENSIONS.map(async ext => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.6",
+  "version": "0.11.1-canary.8",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "hast-util-to-jsx-runtime": "^2.3.6",
     "hast-util-to-text": "^4.0.2",
     "import-meta-resolve": "^4.2.0",
+    "jiti": "^2.7.0",
     "jsondiffpatch": "^0.7.3",
     "kebab-case": "^2.0.2",
     "lz-string": "^1.5.0",
@@ -686,5 +687,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "dc47acc4c60d02db487df3900491752cf51fe989"
+  "gitSha": "2d9566eb356cded76a38a33ebb312f2b3c46126c"
 }

package/useCode/Pre.mjs

@@ -9,6 +9,102 @@ import { hastToJsx, decompressHast } from "../pipeline/hastUtils/index.mjs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const hastChildrenCache = new WeakMap();
 const textChildrenCache = new WeakMap();
+
+// Document-level subscriber registry for `<details>` toggle events. Each
+// `<Pre>` would otherwise install its own capture-phase listener; on docs
+// pages with many code blocks that's N listeners all firing on every
+// toggle anywhere in the document. A single shared listener fans out to
+// the relevant subscribers instead.
+//
+// Subscribers register their `<pre>` element so the dispatcher can do a
+// single `target.contains(pre)` ancestry check per subscriber and skip
+// the nudge entirely for unrelated toggles — no JS-side work runs in
+// `<Pre>` instances whose subtree the toggle didn't touch.
+//
+// The value is a Set rather than a single function so the registry
+// tolerates the (unlikely but possible) case where two `<Pre>` instances
+// transiently share the same DOM node — e.g. a fast unmount/remount
+// where the next mount's setup runs before the prior mount's cleanup.
+// Without the set the second subscribe would silently overwrite the
+// first nudge and a single unsubscribe would orphan the other instance.
+
+const toggleSubscribers = new Map();
+let toggleListenerAttached = false;
+let sharedToggleListener = null;
+
+// Reconcile the document-level capture listener with the current
+// subscriber set. Idempotent: callable from any code path (including
+// test teardowns that want to defensively assert no leaked listener)
+// without risk of leaving the document in a half-attached state.
+function syncToggleListener() {
+  if (typeof document === 'undefined') {
+    if (toggleSubscribers.size === 0) {
+      sharedToggleListener = null;
+      toggleListenerAttached = false;
+    }
+    return;
+  }
+  if (toggleSubscribers.size === 0) {
+    if (toggleListenerAttached && sharedToggleListener) {
+      document.removeEventListener('toggle', sharedToggleListener, true);
+    }
+    sharedToggleListener = null;
+    toggleListenerAttached = false;
+    return;
+  }
+  if (!toggleListenerAttached || !sharedToggleListener) {
+    sharedToggleListener = event => {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+      // Snapshot before iterating: a nudge may synchronously trigger an
+      // unmount that mutates `toggleSubscribers` mid-dispatch. Iterating
+      // a snapshot keeps dispatch order independent of subscriber
+      // mutations and matches the snapshot pattern used by
+      // `sweepDetachedFrames` / `nudgeFrameObserver`.
+      Array.from(toggleSubscribers).forEach(([preNode, nudges]) => {
+        // Centralized ancestry filter: only nudge subscribers whose `<pre>`
+        // is a descendant of the toggled element. Done here (rather than
+        // in each subscriber) so unrelated toggles short-circuit before
+        // any subscriber-side work runs.
+        if (!target.contains(preNode)) {
+          return;
+        }
+        Array.from(nudges).forEach(nudge => nudge());
+      });
+    };
+    document.addEventListener('toggle', sharedToggleListener, true);
+    toggleListenerAttached = true;
+  }
+}
+function subscribeToggleNudge(preNode, nudge) {
+  // Defensive SSR no-op: there is no `document` to attach a listener to,
+  // and module state in Node persists across requests — leaking a
+  // subscriber here would also leak the closure it captures. `useEffect`
+  // already won't run on the server, but make the contract explicit so
+  // any future non-effect caller can't strand entries in the registry.
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+  let nudges = toggleSubscribers.get(preNode);
+  if (!nudges) {
+    nudges = new Set();
+    toggleSubscribers.set(preNode, nudges);
+  }
+  nudges.add(nudge);
+  syncToggleListener();
+  return () => {
+    const existing = toggleSubscribers.get(preNode);
+    if (existing) {
+      existing.delete(nudge);
+      if (existing.size === 0) {
+        toggleSubscribers.delete(preNode);
+      }
+    }
+    syncToggleListener();
+  };
+}
 const INITIAL_VISIBLE_FRAME_TYPES = new Set(['highlighted', 'focus', 'padding-top', 'padding-bottom']);
 function getInitialVisibleFrames(hast) {
   if (!hast) {
@@ -281,26 +377,142 @@ export function Pre({
     preParse
   });
   const observer = React.useRef(null);
+  const observedFrames = React.useRef(new Set());
   const frameIndexMap = React.useRef(new WeakMap());
-  const bindIntersectionObserver = React.useCallback(root => {
-    preRef.current = root;
-    if (!root) {
-      if (observer.current) {
-        observer.current.disconnect();
+
+  // Drop frame spans that have been detached from the DOM. Used as a
+  // defensive sweep in `nudgeFrameObserver` (and the IO effect) so the
+  // tracking sets don't grow unboundedly across re-renders, even on
+  // React 17/18 where the cleanup return value of `observeFrame` is
+  // ignored. `node.isConnected` is the cheapest available signal.
+  const sweepDetachedFrames = React.useCallback(() => {
+    const io = observer.current;
+    // Snapshot before iterating: we mutate `observedFrames` inside the
+    // loop, so iterating the live Set would rely on its (well-defined
+    // but subtle) skip-deleted-entries semantics. An array snapshot makes
+    // the intent explicit and decouples iteration order from insertion
+    // order should the storage ever change.
+    Array.from(observedFrames.current).forEach(frame => {
+      if (!frame.isConnected) {
+        observedFrames.current.delete(frame);
+        frameIndexMap.current.delete(frame);
+        io?.unobserve(frame);
       }
-      observer.current = null;
+    });
+  }, []);
+
+  // Re-observe every tracked frame so the IntersectionObserver re-evaluates
+  // visibility without a synchronous `getBoundingClientRect()` call. Used
+  // when ancestor layout changes (CSS-driven collapse/expand, <details>
+  // toggle, tab/accordion swaps) clip or unclip frames in ways that don't
+  // themselves trigger an IntersectionObserver entry. Mirrors the
+  // `nudgeObserver` pattern in `<TypeCode>`.
+  const nudgeFrameObserver = React.useCallback(() => {
+    const io = observer.current;
+    if (!io) {
+      return;
+    }
+    // Snapshot before iterating — see `sweepDetachedFrames` above.
+    Array.from(observedFrames.current).forEach(frame => {
+      if (!frame.isConnected) {
+        observedFrames.current.delete(frame);
+        frameIndexMap.current.delete(frame);
+        io.unobserve(frame);
+        return;
+      }
+      io.unobserve(frame);
+      io.observe(frame);
+    });
+  }, []);
+
+  // Holds the mounted `<pre>` element so the IO/RO/toggle setup effect can
+  // key on it. Using a state + callback-ref pair (rather than driving the
+  // setup from inside the ref callback) lets React's effect lifecycle
+  // guarantee teardown — including under StrictMode's double-invoke and
+  // for any abrupt unmount path — instead of relying on the ref callback
+  // being called with `null`.
+  const [preNode, setPreNode] = React.useState(null);
+
+  // Mirror the latest forwarded `ref` so `bindPre` can read it without
+  // depending on `ref` in its deps (which would re-create `bindPre` on
+  // every parent re-render and tear down the IO/RO/toggle setup effect
+  // below). Using `useLayoutEffect` (React 17 safe) keeps this in sync
+  // before any consumer's layout effect or imperative-handle read.
+  const forwardedRef = React.useRef(ref);
+  React.useLayoutEffect(() => {
+    const previous = forwardedRef.current;
+    forwardedRef.current = ref;
+    if (previous === ref) {
       return;
     }
-    const indexMap = frameIndexMap.current;
-    observer.current = new IntersectionObserver(entries => setVisibleFrames(prev => {
+    // Consumer swapped to a different ref function/object on a render
+    // where the DOM node didn't change (so `bindPre` wasn't called by
+    // React). Reconcile manually: detach the old, attach the new with
+    // the current node, matching React's standard callback-ref
+    // semantics for ref swaps.
+    const current = preRef.current;
+    if (typeof previous === 'function') {
+      previous(null);
+    } else if (previous) {
+      previous.current = null;
+    }
+    if (typeof ref === 'function') {
+      ref(current);
+    } else if (ref) {
+      ref.current = current;
+    }
+  }, [ref]);
+
+  // `bindPre` is stable (empty deps): if it depended on the forwarded
+  // `ref`, a parent re-render that supplies a new ref function would
+  // recreate `bindPre`, causing React to invoke the previous callback
+  // with `null` and the new one with the same DOM node. That sequence
+  // would tear down and rebuild the IO/RO/toggle subscription on every
+  // parent render. Ref-function swaps that don't change the DOM node
+  // are reconciled by the layout effect above.
+  //
+  // Forward the consumer's ref synchronously inside the callback (not in
+  // a separate `useEffect`) so any parent `useLayoutEffect` or
+  // imperative handle that reads `ref.current` right after mount sees
+  // the `<pre>` rather than `null`.
+  const bindPre = React.useCallback(root => {
+    // React 18+ StrictMode (and some normal-update paths) can invoke a
+    // ref callback with the same node it already holds. Short-circuit
+    // so we don't trigger an extra render via `setPreNode` or a
+    // redundant ref-forward cycle for the consumer.
+    if (preRef.current === root) {
+      return;
+    }
+    preRef.current = root;
+    const current = forwardedRef.current;
+    if (typeof current === 'function') {
+      current(root);
+    } else if (current) {
+      current.current = root;
+    }
+    setPreNode(root);
+  }, []);
+  const handleIntersection = React.useCallback(entries => {
+    setVisibleFrames(prev => {
       const visible = [];
       const invisible = [];
       entries.forEach(entry => {
-        const index = indexMap.get(entry.target);
+        const index = frameIndexMap.current.get(entry.target);
         if (index === undefined) {
           return;
         }
-        if (entry.isIntersecting) {
+        // A frame counts as visible only when it intersects the
+        // viewport AND its intersection rect has non-zero area.
+        // Frames hidden by a CSS-driven collapse (`max-height: 0;
+        // overflow: hidden;` or `visibility: hidden`) collapse to a
+        // zero-area rect; some browsers still report
+        // `isIntersecting: true` for them based on their geometric
+        // position in the document. Checking the rect dimensions
+        // matches what the user actually sees and prevents hidden
+        // frames from being upgraded to highlighted HAST.
+        const rect = entry.intersectionRect;
+        const isVisuallyVisible = entry.isIntersecting && rect.width > 0 && rect.height > 0;
+        if (isVisuallyVisible) {
           visible.push(index);
         } else {
           invisible.push(index);
@@ -330,54 +542,92 @@ export function Pre({
         }
       });
       return frames || prev;
-    }), {
-      rootMargin: hydrateMargin
     });
+  }, []);
 
-    // <pre><code><span class="frame">...</span><span class="frame">...</span>...</code></pre>
-    const codeElement = root.querySelector('code');
-    if (!codeElement) {
-      return;
+  // Set up IntersectionObserver, ResizeObserver, and the shared
+  // <details> toggle subscription whenever the pre element changes.
+  // Running this in `useEffect` (rather than in the ref callback)
+  // delegates teardown to React's effect lifecycle, so cleanup is
+  // guaranteed even under StrictMode's double-invoke and for any
+  // unmount path.
+  React.useEffect(() => {
+    if (!preNode) {
+      return undefined;
     }
-    let frameIndex = 0;
-    codeElement.childNodes.forEach(node => {
-      if (node.nodeType === Node.ELEMENT_NODE) {
-        const element = node;
-        if (!element.classList.contains('frame')) {
-          console.warn('Expected frame element in useCode <Pre>', element);
-          return;
-        }
-        indexMap.set(element, frameIndex);
-        frameIndex += 1;
-        observer.current?.observe(element);
-      }
+    const io = new IntersectionObserver(handleIntersection, {
+      rootMargin: hydrateMargin
     });
-    if (ref) {
-      if (typeof ref === 'function') {
-        ref(root);
-      } else {
-        ref.current = root;
-      }
+    observer.current = io;
+
+    // Sweep any spans that detached between the previous IO's teardown
+    // and this one, then start observing every frame whose ref callback
+    // has registered it.
+    sweepDetachedFrames();
+    observedFrames.current.forEach(frame => io.observe(frame));
+
+    // Watch the `<pre>` itself for size changes (CSS-driven collapse
+    // animations resize ancestors, accordions/tabs swap layout). When
+    // the pre resizes, re-observe every frame so the IO re-evaluates
+    // their clipped-vs-unclipped state. Guarded so older runtimes (and
+    // JSDOM in unit tests) without ResizeObserver still work.
+    let ro = null;
+    if (typeof ResizeObserver !== 'undefined') {
+      ro = new ResizeObserver(nudgeFrameObserver);
+      ro.observe(preNode);
     }
-  }, [ref, hydrateMargin]);
+
+    // Native <details> toggle events do not bubble, but a capture-phase
+    // listener on the document still intercepts them. A single shared
+    // listener (see `subscribeToggleNudge`) fans the event out only to
+    // mounted `<Pre>` instances whose `<pre>` is a descendant of the
+    // toggled element, so unrelated toggles elsewhere in the document
+    // don't trigger any per-instance work.
+    const unsubscribeToggle = subscribeToggleNudge(preNode, nudgeFrameObserver);
+    return () => {
+      io.disconnect();
+      observer.current = null;
+      ro?.disconnect();
+      unsubscribeToggle();
+    };
+  }, [preNode, hydrateMargin, handleIntersection, nudgeFrameObserver, sweepDetachedFrames]);
   const observeFrame = React.useCallback(node => {
-    if (node) {
-      // Derive frame index from DOM position among .frame siblings.
-      // This avoids putting data-frame in server-rendered HTML.
-      let index = 0;
-      let sibling = node.previousElementSibling;
-      while (sibling) {
-        if (sibling.classList.contains('frame')) {
-          index += 1;
-        }
-        sibling = sibling.previousElementSibling;
-      }
-      frameIndexMap.current.set(node, index);
-      if (observer.current) {
-        observer.current.observe(node);
+    if (!node) {
+      // React 17/18 invoke ref callbacks with `null` on detach but
+      // ignore the cleanup return value below, and a single shared
+      // callback can't tell which span detached. Prune any tracked
+      // frame that's no longer in the DOM so detached nodes don't
+      // accumulate strongly-referenced inside `observedFrames` for
+      // the lifetime of the `<Pre>` instance.
+      sweepDetachedFrames();
+      return undefined;
+    }
+    // Derive frame index from DOM position among .frame siblings.
+    // This avoids putting data-frame in server-rendered HTML.
+    let index = 0;
+    let sibling = node.previousElementSibling;
+    while (sibling) {
+      if (sibling.classList.contains('frame')) {
+        index += 1;
       }
+      sibling = sibling.previousElementSibling;
     }
-  }, []);
+    frameIndexMap.current.set(node, index);
+    observedFrames.current.add(node);
+    if (observer.current) {
+      observer.current.observe(node);
+    }
+    // React 19 ref-callback cleanup. On React 17/18 the return value is
+    // ignored; the `if (!node)` branch above + `sweepDetachedFrames`
+    // (also called from `nudgeFrameObserver` and the IO setup effect)
+    // drop entries whose `node.isConnected` is false, so the tracking
+    // sets stay bounded on those versions too.
+    return () => {
+      observedFrames.current.delete(node);
+      frameIndexMap.current.delete(node);
+      observer.current?.unobserve(node);
+    };
+  }, [sweepDetachedFrames]);
   const frames = React.useMemo(() => {
     let frameIndex = 0;
     return hast?.children.map((child, index) => {
@@ -505,7 +755,7 @@ export function Pre({
   // useEditable). jsx-a11y can't see that, so disable its rule here.
   // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
   _jsx("pre", {
-    ref: bindIntersectionObserver,
+    ref: bindPre,
     className: className,
     spellCheck: false,
     tabIndex: isEditable ? -1 : undefined,