@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/useCoordinated/useCoordinatedPreference.mjs

@@ -2,7 +2,6 @@
 
 import { usePreference } from "../usePreference/usePreference.mjs";
 import { useCoordinated } from "./useCoordinated.mjs";
-
 /**
  * `usePreference` + {@link useCoordinated} in one call.
  *

package/useCrossTabState/index.d.mts

@@ -0,0 +1,2 @@
+export * from "./useCrossTabState.mjs";
+export * from "./useCrossTabMirror.mjs";

package/useCrossTabState/index.mjs

@@ -0,0 +1,2 @@
+export * from "./useCrossTabState.mjs";
+export * from "./useCrossTabMirror.mjs";

package/useCrossTabState/useCrossTabMirror.d.mts

@@ -0,0 +1,26 @@
+/**
+ * Mirrors a value you already own across same-origin browser tabs/windows through a
+ * `BroadcastChannel` — so, for example, two Chrome split-view tabs of the same page
+ * keep a live demo's edits in sync. The lower-level building block behind
+ * `useCrossTabState`: use it when the state lives elsewhere (a reducer, a store, a
+ * controller's own `useState`) and you only want to keep it in sync; reach for
+ * `useCrossTabState` when you just want a synced `useState`.
+ *
+ * Pass a `key` (the channel name) that is identical across the tabs meant to share
+ * state, and `null` to disable — no channel is opened, which also makes it SSR-safe
+ * and gives the caller a clean off switch. `value` is broadcast whenever it changes
+ * locally; an incoming remote value is handed to `applyRemote` WITHOUT being echoed
+ * back, so two tabs can't ping-pong. Last write wins.
+ *
+ * A tab opened mid-edit catches up: on mount it asks peers for the current state, and
+ * any tab already holding shared state replies. A fresh tab with nothing to share
+ * stays quiet, so it can never blank out the asker; and once a tab holds shared state
+ * it ignores further catch-up replies, keeping its own value authoritative.
+ *
+ * `value` must be structured-cloneable (plain data) — `postMessage` clones it.
+ *
+ * @param key The channel name; tabs sync only when their keys match. `null` disables syncing (and is SSR-safe).
+ * @param value The current value, broadcast to other tabs whenever it changes.
+ * @param applyRemote Called with a value received from another tab — apply it to your own state.
+ */
+export declare function useCrossTabMirror<T>(key: string | null, value: T, applyRemote: (value: T) => void): void;

package/useCrossTabState/useCrossTabMirror.mjs

@@ -0,0 +1,108 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Channel protocol: a `state` push (a local change, or a `reply` catching a newcomer
+ * up), or a newcomer's `request` for the current state.
+ */
+
+/**
+ * Mirrors a value you already own across same-origin browser tabs/windows through a
+ * `BroadcastChannel` — so, for example, two Chrome split-view tabs of the same page
+ * keep a live demo's edits in sync. The lower-level building block behind
+ * `useCrossTabState`: use it when the state lives elsewhere (a reducer, a store, a
+ * controller's own `useState`) and you only want to keep it in sync; reach for
+ * `useCrossTabState` when you just want a synced `useState`.
+ *
+ * Pass a `key` (the channel name) that is identical across the tabs meant to share
+ * state, and `null` to disable — no channel is opened, which also makes it SSR-safe
+ * and gives the caller a clean off switch. `value` is broadcast whenever it changes
+ * locally; an incoming remote value is handed to `applyRemote` WITHOUT being echoed
+ * back, so two tabs can't ping-pong. Last write wins.
+ *
+ * A tab opened mid-edit catches up: on mount it asks peers for the current state, and
+ * any tab already holding shared state replies. A fresh tab with nothing to share
+ * stays quiet, so it can never blank out the asker; and once a tab holds shared state
+ * it ignores further catch-up replies, keeping its own value authoritative.
+ *
+ * `value` must be structured-cloneable (plain data) — `postMessage` clones it.
+ *
+ * @param key The channel name; tabs sync only when their keys match. `null` disables syncing (and is SSR-safe).
+ * @param value The current value, broadcast to other tabs whenever it changes.
+ * @param applyRemote Called with a value received from another tab — apply it to your own state.
+ */
+export function useCrossTabMirror(key, value, applyRemote) {
+  const channelRef = React.useRef(null);
+  // The last value sent OR received on the channel. A local change whose value
+  // differs from it is broadcast; a value we just applied from a remote message
+  // matches it, so the broadcast effect below skips it — that's the echo guard.
+  const lastSyncedRef = React.useRef(value);
+  // Whether this tab holds shared state (has broadcast a change or adopted a peer's).
+  // Only a holder answers a newcomer's request, and a holder ignores catch-up replies.
+  const primedRef = React.useRef(false);
+  // Keep the latest `applyRemote` without re-opening the channel when an inline
+  // callback identity changes between renders.
+  const applyRemoteRef = React.useRef(applyRemote);
+  React.useEffect(() => {
+    applyRemoteRef.current = applyRemote;
+  });
+
+  // Open the channel (declared before the broadcast effect, so on mount the channel
+  // exists by the time that effect first runs and skips the initial value).
+  React.useEffect(() => {
+    if (key === null || typeof BroadcastChannel === 'undefined') {
+      return undefined;
+    }
+    const channel = new BroadcastChannel(key);
+    channelRef.current = channel;
+    channel.onmessage = event => {
+      const message = event.data;
+      if (message.kind === 'request') {
+        // A tab just came online and asked for the current state. Only a tab that
+        // holds shared state answers, so a fresh peer can't reply with a blank value.
+        if (primedRef.current) {
+          channel.postMessage({
+            kind: 'state',
+            value: lastSyncedRef.current,
+            reply: true
+          });
+        }
+        return;
+      }
+      // A catch-up reply must not overwrite state we already hold (a fast local edit,
+      // or an earlier reply we already took). A normal push — a peer's edit — always
+      // wins (last write wins).
+      if (message.reply && primedRef.current) {
+        return;
+      }
+      primedRef.current = true;
+      lastSyncedRef.current = message.value;
+      applyRemoteRef.current(message.value);
+    };
+    // Ask any existing tab to send its current state, so a tab opened mid-edit catches
+    // up instead of starting blank.
+    channel.postMessage({
+      kind: 'request'
+    });
+    return () => {
+      channel.close();
+      channelRef.current = null;
+    };
+  }, [key]);
+
+  // Broadcast local changes. A value we just received (so it equals `lastSyncedRef`)
+  // is not re-sent, which stops the echo.
+  React.useEffect(() => {
+    const channel = channelRef.current;
+    if (!channel || Object.is(value, lastSyncedRef.current)) {
+      return;
+    }
+    lastSyncedRef.current = value;
+    primedRef.current = true;
+    channel.postMessage({
+      kind: 'state',
+      value
+    });
+  }, [value]);
+}

package/useCrossTabState/useCrossTabState.d.mts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+/**
+ * A `useState` whose value is mirrored across same-origin browser tabs/windows of the
+ * same page through a `BroadcastChannel` — set it in one tab and the others follow.
+ * For example, edit a live demo in a Chrome split view and both panes stay in sync.
+ *
+ * Drop-in for `useState`: returns `[value, setValue]` and supports lazy initializers
+ * and functional updates. The extra `key` is the channel name — tabs sync only when
+ * their keys match, and `null` disables syncing (also SSR-safe; no channel opens on
+ * the server). State is EPHEMERAL: nothing is persisted, but a tab opened mid-session
+ * catches up from a peer that already holds it instead of starting at `initialValue`.
+ * For state that must survive a reload, use `useLocalStorageState` instead.
+ *
+ * `value` must be structured-cloneable (plain data) — `postMessage` clones it. When the
+ * state lives elsewhere (a reducer, a store, a controller) and you only want to sync
+ * it, use the lower-level {@link useCrossTabMirror} instead.
+ *
+ * @param key The channel name; tabs sync only when their keys match. `null` disables syncing (and is SSR-safe).
+ * @param initialValue The initial state, or a lazy initializer — exactly like `useState`.
+ */
+export declare function useCrossTabState<T>(key: string | null, initialValue: T | (() => T)): [T, React.Dispatch<React.SetStateAction<T>>];

package/useCrossTabState/useCrossTabState.mjs

@@ -0,0 +1,31 @@
+'use client';
+
+import * as React from 'react';
+import { useCrossTabMirror } from "./useCrossTabMirror.mjs";
+
+/**
+ * A `useState` whose value is mirrored across same-origin browser tabs/windows of the
+ * same page through a `BroadcastChannel` — set it in one tab and the others follow.
+ * For example, edit a live demo in a Chrome split view and both panes stay in sync.
+ *
+ * Drop-in for `useState`: returns `[value, setValue]` and supports lazy initializers
+ * and functional updates. The extra `key` is the channel name — tabs sync only when
+ * their keys match, and `null` disables syncing (also SSR-safe; no channel opens on
+ * the server). State is EPHEMERAL: nothing is persisted, but a tab opened mid-session
+ * catches up from a peer that already holds it instead of starting at `initialValue`.
+ * For state that must survive a reload, use `useLocalStorageState` instead.
+ *
+ * `value` must be structured-cloneable (plain data) — `postMessage` clones it. When the
+ * state lives elsewhere (a reducer, a store, a controller) and you only want to sync
+ * it, use the lower-level {@link useCrossTabMirror} instead.
+ *
+ * @param key The channel name; tabs sync only when their keys match. `null` disables syncing (and is SSR-safe).
+ * @param initialValue The initial state, or a lazy initializer — exactly like `useState`.
+ */
+export function useCrossTabState(key, initialValue) {
+  const [value, setValue] = React.useState(initialValue);
+  // `setValue` applies a peer's value directly; `useCrossTabMirror` broadcasts our
+  // resolved `value` on change and skips echoing back what it just handed us.
+  useCrossTabMirror(key, value, setValue);
+  return [value, setValue];
+}

package/useDemo/exportVariant.mjs

@@ -330,10 +330,8 @@ export function exportVariant(variantCode, config = {}) {
     },
     devDependencies: {
       ...(!isFramework && {
-        // Pinned to major versions instead of `latest` to work around
-        // https://github.com/stackblitz/webcontainer-core/issues/2104
-        '@vitejs/plugin-react': '^5',
-        vite: '^7'
+        '@vitejs/plugin-react': 'latest',
+        vite: 'latest'
       }),
       ...(useTypescript && {
         typescript: 'latest',

package/useDemo/exportVariantAsCra.d.mts

@@ -4,7 +4,7 @@
  * without library-specific dependencies
  */
 import type { VariantCode } from "../CodeHighlighter/types.mjs";
-import { type ExportConfig } from "./exportVariant.mjs";
+import type { ExportConfig } from "./exportVariant.mjs";
 /**
  * Export a VariantCode as a Create React App template
  * Returns an object with the exported VariantCode and entrypoint path

package/useDemo/exportVariantAsCra.mjs

@@ -5,7 +5,6 @@
  */
 
 import { exportVariant } from "./exportVariant.mjs";
-
 /**
  * Export a VariantCode as a Create React App template
  * Returns an object with the exported VariantCode and entrypoint path

package/useDemo/useDemo.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import type { UseCodeOpts } from "../useCode/index.mjs";
 import type { ContentProps } from "../CodeHighlighter/types.mjs";
-import { type ExportConfig } from "./exportVariant.mjs";
+import type { ExportConfig } from "./exportVariant.mjs";
 /**
  * Demo templates use the exportVariant/exportVariantAsCra with flattenCodeVariant pattern:
  *
@@ -74,6 +74,8 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   selectedTransform: string | null | undefined;
   selectTransform: (transformName: string | null) => void;
   pendingTransform: string | null | undefined;
+  editable: boolean;
+  setEditable?: (editable: boolean) => void;
   setSource?: (source: string, fileName?: string) => void;
   reset?: () => void;
   refresh?: () => void;
@@ -82,6 +84,7 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
     slug?: string;
   };
   component: string | number | bigint | true | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | Iterable<React.ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null;
+  error: string | null;
   focusRef: React.RefObject<HTMLButtonElement | null>;
   resetFocus: () => void;
   openStackBlitz: () => void;

package/useDemo/useDemo.mjs

@@ -81,6 +81,10 @@ export function useDemo(contentProps, opts) {
     return effectiveComponents[code.selectedVariant] || null;
   }, [effectiveComponents, code.selectedVariant]);
 
+  // Surface the selected variant's runtime error, reported by its preview
+  // component (e.g. `DemoRunner`) and bridged through `CodeHighlighterContext`.
+  const error = context?.errors?.[code.selectedVariant] ?? null;
+
   // Demo-specific ref and focus management. Typed as `HTMLButtonElement` since
   // the typical pattern is an invisible focus-target button rendered inside the
   // demo. `resetFocus` simply calls `.focus()` on it.
@@ -181,6 +185,7 @@ export function useDemo(contentProps, opts) {
     ...code,
     // Demo-specific additions
     component,
+    error,
     focusRef,
     resetFocus,
     openStackBlitz,

package/useDemoController/BuildEngine.d.mts

@@ -0,0 +1,2 @@
+export { buildScope } from "./buildScope.mjs";
+export { DemoRunner } from "./DemoRunner.mjs";

package/useDemoController/BuildEngine.mjs

@@ -0,0 +1,10 @@
+// The lazy "build engine" chunk for the live-demo runtime: both halves bundled together
+// so editing a demo fetches ONE chunk instead of two — the BUILD half (`buildScope` plus
+// its scope-assembly and eval machinery) and the RENDER half (`DemoRunner` plus the
+// react-runner reimplementation). It is imported DYNAMICALLY (never statically) from
+// `useVariantBuilds` (which needs `buildScope`) and `useDemoController` (which needs
+// `DemoRunner`), both under the `BuildEngine` webpack chunk name; see those files for
+// why the engine is deferred to the first edit. Keeping it out of the eager
+// `useDemoController` chunk is the whole point — don't add a static import of this file.
+export { buildScope } from "./buildScope.mjs";
+export { DemoRunner } from "./DemoRunner.mjs";

package/useDemoController/DemoRunner.d.mts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import type { Scope } from "./types.mjs";
+export interface DemoRunnerProps {
+  /** The already-transpiled entry code for the variant (from the transpile worker). */
+  runnerCode: string;
+  /** The built module registry the entry evaluates against. */
+  scope: Scope;
+  /** Compiled stylesheet text collected from the variant's CSS extra files. */
+  css?: string;
+  /**
+   * Called with the runner's current error message (or `null` when it renders
+   * cleanly). Lets the controller surface errors while the live preview keeps
+   * showing the last good render.
+   */
+  onError?: (message: string | null) => void;
+  /**
+   * Shown when the entry throws BEFORE any successful render (no last-good element to keep)
+   * — typically the host's build-time render, so a broken first edit shows the original
+   * instead of blanking. The host (`CodeHighlighterClient`) injects it per variant.
+   */
+  fallback?: React.ReactNode;
+}
+/**
+ * Renders one ready demo variant. Wraps the content in an {@link ErrorBoundary} as
+ * a backstop; runtime errors thrown while rendering the entry are already caught by
+ * the inner `Runner` and reported through `onError` the same way.
+ */
+export declare function DemoRunner({
+  runnerCode,
+  scope,
+  css,
+  onError,
+  fallback
+}: DemoRunnerProps): React.JSX.Element;

package/useDemoController/DemoRunner.mjs

@@ -0,0 +1,83 @@
+'use client';
+
+import * as React from 'react';
+import { useRunner } from "./useRunner.mjs";
+import { ErrorBoundary } from "./ErrorBoundary.mjs";
+
+// ---------------------------------------------------------------------------
+// Presentational preview for a single demo variant. The async transpilation +
+// scope build happen upstream in `useDemoController` (off the main thread, in a
+// worker), so this is mounted only once a variant is READY and stays fully
+// synchronous: it evaluates the already-transpiled entry, renders it, and reports
+// runtime errors. Not built for direct use — `useDemoController` owns it.
+// ---------------------------------------------------------------------------
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Renders one ready demo variant. Wraps the content in an {@link ErrorBoundary} as
+ * a backstop; runtime errors thrown while rendering the entry are already caught by
+ * the inner `Runner` and reported through `onError` the same way.
+ */
+export function DemoRunner({
+  runnerCode,
+  scope,
+  css,
+  onError,
+  fallback
+}) {
+  return /*#__PURE__*/_jsx(ErrorBoundary, {
+    resetKeys: [runnerCode, scope],
+    onError: caught => onError?.(caught.message),
+    children: /*#__PURE__*/_jsx(DemoRunnerContent, {
+      runnerCode: runnerCode,
+      scope: scope,
+      css: css,
+      onError: onError,
+      fallback: fallback
+    })
+  });
+}
+function DemoRunnerContent({
+  runnerCode,
+  scope,
+  css,
+  onError,
+  fallback
+}) {
+  const {
+    element,
+    error
+  } = useRunner({
+    transpiledCode: runnerCode,
+    scope,
+    fallback
+  });
+
+  // Report the current error (or `null` when clean) to the host without unmounting
+  // the live preview, which `useRunner` keeps showing. The latest `onError` is kept
+  // in a ref so an inline callback doesn't re-fire the report.
+  const onErrorRef = React.useRef(onError);
+  React.useEffect(() => {
+    onErrorRef.current = onError;
+  });
+  // Report on every change, but clear (`null`) only on unmount — clearing on each
+  // change would blink the error off and back on as the source is edited.
+  React.useEffect(() => {
+    onErrorRef.current?.(error);
+  }, [error]);
+  React.useEffect(() => () => {
+    onErrorRef.current?.(null);
+  }, []);
+
+  // Render the compiled module CSS as a `<style>` inside the output (rather than
+  // injecting it into `document.head`) so the scoped styles are co-located with the
+  // demo and easy to inspect. A plain `<style>` (no `precedence`) is not hoisted by
+  // React, and its rules still apply document-wide.
+  return /*#__PURE__*/_jsxs(React.Fragment, {
+    children: [css ? /*#__PURE__*/_jsx("div", {
+      "data-demo-styles": "",
+      children: /*#__PURE__*/_jsx("style", {
+        children: css
+      })
+    }) : null, element]
+  });
+}

package/useDemoController/ErrorBoundary.d.mts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+export interface ErrorBoundaryProps {
+  children: React.ReactNode;
+  /** Called with the error thrown while rendering `children`. */
+  onError?: (error: Error) => void;
+  /**
+   * When any value in this array changes, a caught error is cleared and
+   * `children` render again — letting a fixed input recover from a prior crash.
+   */
+  resetKeys?: ReadonlyArray<unknown>;
+  /** Rendered in place of `children` while an error is caught. Defaults to `null`. */
+  fallback?: React.ReactNode;
+}
+interface ErrorBoundaryState {
+  error: Error | null;
+  /** The `resetKeys` the current state was derived from, compared element-wise. */
+  resetKeys: ReadonlyArray<unknown>;
+}
+/**
+ * Generic error boundary: catches errors thrown while rendering its subtree,
+ * reports them through `onError`, and renders `fallback` instead of tearing down
+ * the surrounding tree. Pass `resetKeys` (e.g. the live-edited source) so a fixed
+ * input retries rendering after a previous crash.
+ *
+ * Implemented as a class because error boundaries require `getDerivedStateFromError`.
+ */
+export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState;
+  static getDerivedStateFromError(error: unknown): Partial<ErrorBoundaryState>;
+  static getDerivedStateFromProps(props: ErrorBoundaryProps, state: ErrorBoundaryState): Partial<ErrorBoundaryState> | null;
+  componentDidCatch(error: unknown): void;
+  render(): React.ReactNode;
+}
+export {};

package/useDemoController/ErrorBoundary.mjs

@@ -0,0 +1,49 @@
+'use client';
+
+import * as React from 'react';
+/** Normalizes an unknown thrown value into an `Error`. */
+function toError(thrown) {
+  return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+
+/** Whether two reset-key arrays differ in length or any element (`Object.is`). */
+function resetKeysChanged(a, b) {
+  return a.length !== b.length || a.some((value, index) => !Object.is(value, b[index]));
+}
+
+/**
+ * Generic error boundary: catches errors thrown while rendering its subtree,
+ * reports them through `onError`, and renders `fallback` instead of tearing down
+ * the surrounding tree. Pass `resetKeys` (e.g. the live-edited source) so a fixed
+ * input retries rendering after a previous crash.
+ *
+ * Implemented as a class because error boundaries require `getDerivedStateFromError`.
+ */
+export class ErrorBoundary extends React.Component {
+  state = {
+    error: null,
+    resetKeys: this.props.resetKeys ?? []
+  };
+  static getDerivedStateFromError(error) {
+    return {
+      error: toError(error)
+    };
+  }
+  static getDerivedStateFromProps(props, state) {
+    const nextKeys = props.resetKeys ?? [];
+    if (!resetKeysChanged(state.resetKeys, nextKeys)) {
+      return null;
+    }
+    // Inputs changed — clear any caught error so the children render again.
+    return {
+      error: null,
+      resetKeys: nextKeys
+    };
+  }
+  componentDidCatch(error) {
+    this.props.onError?.(toError(error));
+  }
+  render() {
+    return this.state.error ? this.props.fallback ?? null : this.props.children;
+  }
+}

package/useDemoController/Runner.d.mts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import type { Scope } from "./types.mjs";
+export interface RunnerProps {
+  /**
+   * Already-transpiled entry code (CommonJS, from the transpile worker). The
+   * Runner only evaluates + renders it; transpilation happens upstream (off the
+   * main thread), so a transpile error never reaches here.
+   */
+  transpiledCode: string;
+  /** Identifiers (and an `import` registry) exposed to the evaluated entry. */
+  scope?: Scope;
+  /**
+   * Called after every (re)render with the error that occurred while evaluating or
+   * rendering the entry, or `undefined` when it rendered cleanly.
+   */
+  onRendered?: (error?: Error) => void;
+}
+interface RunnerState {
+  element: React.ReactNode;
+  error: Error | null;
+  /** The transpiled code the current `element`/`error` was derived from. */
+  renderedCode: string | null;
+  /** The scope the current `element`/`error` was derived from (compared by reference). */
+  renderedScope: Scope | undefined;
+}
+/**
+ * Evaluates already-transpiled entry code and renders the React node it exports,
+ * doubling as an error boundary so a runtime error thrown while rendering that node
+ * is caught instead of tearing down the host tree. Evaluate-time errors (a throw in
+ * the module body) and render-time errors are both reported through `onRendered`.
+ *
+ * Implemented as a class because error boundaries require
+ * `getDerivedStateFromError`.
+ */
+export declare class Runner extends React.Component<RunnerProps, RunnerState> {
+  state: RunnerState;
+  static getDerivedStateFromProps(props: RunnerProps, state: RunnerState): Partial<RunnerState> | null;
+  static getDerivedStateFromError(error: unknown): Partial<RunnerState>;
+  componentDidMount(): void;
+  componentDidUpdate(): void;
+  shouldComponentUpdate(nextProps: RunnerProps, nextState: RunnerState): boolean;
+  render(): React.ReactNode;
+}
+export {};

package/useDemoController/Runner.mjs

@@ -0,0 +1,71 @@
+'use client';
+
+import * as React from 'react';
+import { instantiateElement } from "./instantiateElement.mjs";
+/** Normalizes an unknown thrown value into an `Error`. */
+function toError(thrown) {
+  return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+
+/**
+ * Evaluates already-transpiled entry code and renders the React node it exports,
+ * doubling as an error boundary so a runtime error thrown while rendering that node
+ * is caught instead of tearing down the host tree. Evaluate-time errors (a throw in
+ * the module body) and render-time errors are both reported through `onRendered`.
+ *
+ * Implemented as a class because error boundaries require
+ * `getDerivedStateFromError`.
+ */
+export class Runner extends React.Component {
+  state = {
+    element: null,
+    error: null,
+    renderedCode: null,
+    renderedScope: undefined
+  };
+  static getDerivedStateFromProps(props, state) {
+    // Regenerate only when an input changed; unrelated re-renders keep the element.
+    if (props.transpiledCode === state.renderedCode && props.scope === state.renderedScope) {
+      return null;
+    }
+    try {
+      return {
+        element: instantiateElement(props.transpiledCode, props.scope),
+        error: null,
+        renderedCode: props.transpiledCode,
+        renderedScope: props.scope
+      };
+    } catch (error) {
+      return {
+        element: null,
+        error: toError(error),
+        renderedCode: props.transpiledCode,
+        renderedScope: props.scope
+      };
+    }
+  }
+  static getDerivedStateFromError(error) {
+    // A runtime error thrown while React rendered the generated node.
+    return {
+      error: toError(error)
+    };
+  }
+  componentDidMount() {
+    this.props.onRendered?.(this.state.error ?? undefined);
+  }
+  componentDidUpdate() {
+    this.props.onRendered?.(this.state.error ?? undefined);
+  }
+  shouldComponentUpdate(nextProps, nextState) {
+    return nextProps.transpiledCode !== this.props.transpiledCode || nextProps.scope !== this.props.scope || nextState.error !== this.state.error ||
+    // Re-render (so `componentDidUpdate` re-reports via `onRendered`) when the
+    // callback changes even though the code/scope didn't — e.g. restoring the
+    // source to the exact code the cached element last rendered. Without this,
+    // `getDerivedStateFromProps` short-circuits, `onRendered` never fires, and a
+    // pending error never clears. The regenerate itself is still skipped.
+    nextProps.onRendered !== this.props.onRendered;
+  }
+  render() {
+    return this.state.error ? null : this.state.element;
+  }
+}

package/useDemoController/absolutizeImports.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Rewrites a source's relative imports (`./x`, `../x`) to absolute specifiers
+ * under the scope-import prefix, resolving each against the importing file's
+ * own directory. This lets every extra file be registered under a single absolute
+ * key that resolves regardless of where the file lives — e.g. `dir/file.ts`
+ * importing `../root` becomes `<prefix>root`, and `root.ts` importing `./dir/file`
+ * becomes `<prefix>dir/file`. External (bare) specifiers are left untouched.
+ *
+ * Only needed when extra files span subdirectories; flat demos resolve fine with
+ * their plain `./name` specifiers and should skip this. `fileName` is the file's
+ * path within the demo (e.g. `dir/file.ts`); the main source lives at the root.
+ */
+export declare function absolutizeImports(source: string, fileName: string, prefix?: string): string;