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

package/useDemoController/importCode.d.mts

@@ -0,0 +1,11 @@
+import type { Scope } from "./types.mjs";
+/**
+ * Transpiles and evaluates a module's source, returning its exports. Unlike the
+ * element runner the source is not normalized, so it must declare its own
+ * `export`s. Use this to register a file's exports under a specifier in a scope's
+ * `import` registry, letting other sources `import` from it.
+ *
+ * A one-shot wrapper over {@link compileModule}; callers that re-evaluate the same
+ * source as siblings change should cache the `compileModule` runner instead.
+ */
+export declare function importCode(code: string, scope?: Scope): Scope;

package/useDemoController/importCode.mjs

@@ -0,0 +1,15 @@
+import { compileModule } from "./compileModule.mjs";
+/**
+ * Transpiles and evaluates a module's source, returning its exports. Unlike the
+ * element runner the source is not normalized, so it must declare its own
+ * `export`s. Use this to register a file's exports under a specifier in a scope's
+ * `import` registry, letting other sources `import` from it.
+ *
+ * A one-shot wrapper over {@link compileModule}; callers that re-evaluate the same
+ * source as siblings change should cache the `compileModule` runner instead.
+ */
+export function importCode(code, scope) {
+  const exports = {};
+  compileModule(code)(scope?.import ?? {}, exports);
+  return exports;
+}

package/useDemoController/index.d.mts

@@ -0,0 +1 @@
+export * from "./useDemoController.mjs";

package/useDemoController/index.mjs

@@ -0,0 +1 @@
+export * from "./useDemoController.mjs";

package/useDemoController/instantiateElement.d.mts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { Scope } from "./types.mjs";
+/**
+ * Registry key (deliberately not a valid import specifier, so no demo source can
+ * import it) under which the scope may hold the exports object the entry should
+ * populate. When `buildScope` registers the main source so an extra can import the
+ * entry, it points this — and the entry's `./index` keys — at one object, so the
+ * rendered entry and the importing extra share a SINGLE evaluation.
+ */
+export declare const ENTRY_EXPORTS_KEY = "\0entry-exports";
+/**
+ * Evaluates ALREADY-TRANSPILED entry code and returns the React node it exports
+ * as its default. This is the main-thread half of rendering the entry: the
+ * `evalCode`/`new Function` here cannot run in a Web Worker, while the
+ * `transformCode`/`normalizeCode` that produce `transpiled` can run off-thread.
+ *
+ * A source can expose its default three ways: an explicit `export default`, a
+ * call to the injected `render(value)` callback, or a bare leading expression
+ * promoted to a default export by `normalizeCode` (applied before transpiling).
+ * The resolved default is coerced to something renderable — an element is
+ * returned as-is, a component type is instantiated with no props, and a string is
+ * returned verbatim. A falsy/non-renderable default (or empty code) yields `null`.
+ */
+export declare function instantiateElement(transpiled: string, scope?: Scope): React.ReactNode;

package/useDemoController/instantiateElement.mjs

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { evalCode } from "./evalCode.mjs";
+/**
+ * Registry key (deliberately not a valid import specifier, so no demo source can
+ * import it) under which the scope may hold the exports object the entry should
+ * populate. When `buildScope` registers the main source so an extra can import the
+ * entry, it points this — and the entry's `./index` keys — at one object, so the
+ * rendered entry and the importing extra share a SINGLE evaluation.
+ */
+export const ENTRY_EXPORTS_KEY = '\0entry-exports';
+
+/**
+ * Evaluates ALREADY-TRANSPILED entry code and returns the React node it exports
+ * as its default. This is the main-thread half of rendering the entry: the
+ * `evalCode`/`new Function` here cannot run in a Web Worker, while the
+ * `transformCode`/`normalizeCode` that produce `transpiled` can run off-thread.
+ *
+ * A source can expose its default three ways: an explicit `export default`, a
+ * call to the injected `render(value)` callback, or a bare leading expression
+ * promoted to a default export by `normalizeCode` (applied before transpiling).
+ * The resolved default is coerced to something renderable — an element is
+ * returned as-is, a component type is instantiated with no props, and a string is
+ * returned verbatim. A falsy/non-renderable default (or empty code) yields `null`.
+ */
+export function instantiateElement(transpiled, scope) {
+  // Evaluate into the shared registry object when present (see ENTRY_EXPORTS_KEY),
+  // so this entry and any extra that imports it see the same exports; otherwise a
+  // fresh object.
+  const shared = scope?.import?.[ENTRY_EXPORTS_KEY];
+  const exports = shared && typeof shared === 'object' ? shared : {};
+  const render = value => {
+    exports.default = value;
+  };
+
+  // Spread `scope` FIRST so the injected `render` escape hatch and `exports` sink
+  // always win over a same-named scope entry rather than being shadowed by one.
+  evalCode(transpiled, {
+    ...scope,
+    render,
+    exports
+  });
+  const exported = exports.default;
+  if (!exported) {
+    return null;
+  }
+  if (/*#__PURE__*/React.isValidElement(exported)) {
+    return exported;
+  }
+  if (typeof exported === 'function') {
+    // Verified as a function above; treat it as a component and render it.
+    return /*#__PURE__*/React.createElement(exported);
+  }
+  if (typeof exported === 'string') {
+    return exported;
+  }
+  return null;
+}

package/useDemoController/instantiateModule.d.mts

@@ -0,0 +1,17 @@
+import type { ModuleRun } from "./types.mjs";
+/**
+ * Compiles ALREADY-TRANSPILED CommonJS-style module code into a runner that
+ * evaluates it against a `require` registry, writing into a caller-provided
+ * `exports`. This is the main-thread half of loading a module: `new Function`
+ * (and the eval it produces) cannot run in a Web Worker, so it stays here — while
+ * the heavy `transformCode` transpile that produces `transpiled` can run
+ * off-thread.
+ *
+ * `new Function` compiles the transpiled body once; the returned closure re-runs
+ * it with the current registry, so changing one sibling doesn't re-transpile the
+ * others. It can't close over the surrounding lexical scope. The caller registers
+ * the `exports` object BEFORE running, so a circular import re-entering this
+ * module sees the in-progress exports instead of looping forever (CommonJS
+ * semantics).
+ */
+export declare function instantiateModule(transpiled: string): ModuleRun;

package/useDemoController/instantiateModule.mjs

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import { createRequire } from "./createRequire.mjs";
+/**
+ * Compiles ALREADY-TRANSPILED CommonJS-style module code into a runner that
+ * evaluates it against a `require` registry, writing into a caller-provided
+ * `exports`. This is the main-thread half of loading a module: `new Function`
+ * (and the eval it produces) cannot run in a Web Worker, so it stays here — while
+ * the heavy `transformCode` transpile that produces `transpiled` can run
+ * off-thread.
+ *
+ * `new Function` compiles the transpiled body once; the returned closure re-runs
+ * it with the current registry, so changing one sibling doesn't re-transpile the
+ * others. It can't close over the surrounding lexical scope. The caller registers
+ * the `exports` object BEFORE running, so a circular import re-entering this
+ * module sees the in-progress exports instead of looping forever (CommonJS
+ * semantics).
+ */
+export function instantiateModule(transpiled) {
+  // eslint-disable-next-line no-new-func
+  const evaluate = new Function('React', 'require', 'exports', transpiled);
+  return (imports, exports) => {
+    evaluate(React, createRequire(imports), exports);
+  };
+}

package/useDemoController/resolveCssImports.d.mts

@@ -0,0 +1,27 @@
+/** A compiled CSS-module's single-file form, awaiting cross-file resolution. */
+export interface CssModuleToResolve {
+  /** The registry key this module is exported under (used verbatim in the output). */
+  key: string;
+  /** The module's path within the demo (e.g. `dir/theme.module.css`) — drives `from` resolution. */
+  fileName: string;
+  /** Single-file exports; a `composes ... from` value still holds opaque placeholder tokens. */
+  exports: Record<string, string>;
+  /** `{ './other.module.css': { '<placeholder>': 'importedName' } }` from `compileCssModule`. */
+  imports: Record<string, Record<string, string>>;
+}
+/**
+ * Resolves cross-file `composes ... from` references across a set of compiled
+ * CSS modules, returning each module's final exports keyed by registry key.
+ *
+ * Each module's single-file exports may carry opaque placeholder tokens standing
+ * in for a class composed from a sibling (see {@link CssModuleToResolve.imports}).
+ * This swaps every token for the sibling's resolved scoped name — recursively, so
+ * a chain (`a` composes from `b` composes from `c`) flattens fully, with a stack
+ * guard breaking any composition cycle. A placeholder whose sibling or name is
+ * missing is dropped (the rest of the value survives).
+ *
+ * This runs on every assembly rather than being cached per file: a module's
+ * resolved value depends on its SIBLINGS' exports, which change when a sibling is
+ * edited even though this module's own source — and its cache entry — did not.
+ */
+export declare function resolveCssImports(modules: CssModuleToResolve[]): Map<string, Record<string, string>>;

package/useDemoController/resolveCssImports.mjs

@@ -0,0 +1,79 @@
+/** A compiled CSS-module's single-file form, awaiting cross-file resolution. */
+
+/**
+ * Resolves a relative CSS `composes ... from` path against the importing file,
+ * using plain `/` segment math (no `path` module, so it runs in the browser).
+ * Returns a normalized file name to look the sibling up by.
+ */
+function resolveRelativePath(fromFileName, importPath) {
+  const lastSlash = fromFileName.lastIndexOf('/');
+  const segments = lastSlash === -1 ? [] : fromFileName.slice(0, lastSlash).split('/');
+  for (const segment of importPath.split('/')) {
+    if (segment === '' || segment === '.') {
+      continue;
+    }
+    if (segment !== '..') {
+      segments.push(segment);
+    } else if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+      // Step up into a real parent directory.
+      segments.pop();
+    } else {
+      // Already at (or above) the base — keep the `..` so a path that legitimately
+      // points above the importing file's directory (e.g. a root-level module that
+      // composes from `../shared/x`) survives instead of being silently flattened.
+      segments.push('..');
+    }
+  }
+  return segments.join('/');
+}
+
+/** Replaces placeholder tokens in a space-separated class value, dropping empties. */
+function applyReplacements(value, replacements) {
+  return value.split(' ').map(token => token in replacements ? replacements[token] : token).filter(Boolean).join(' ');
+}
+
+/**
+ * Resolves cross-file `composes ... from` references across a set of compiled
+ * CSS modules, returning each module's final exports keyed by registry key.
+ *
+ * Each module's single-file exports may carry opaque placeholder tokens standing
+ * in for a class composed from a sibling (see {@link CssModuleToResolve.imports}).
+ * This swaps every token for the sibling's resolved scoped name — recursively, so
+ * a chain (`a` composes from `b` composes from `c`) flattens fully, with a stack
+ * guard breaking any composition cycle. A placeholder whose sibling or name is
+ * missing is dropped (the rest of the value survives).
+ *
+ * This runs on every assembly rather than being cached per file: a module's
+ * resolved value depends on its SIBLINGS' exports, which change when a sibling is
+ * edited even though this module's own source — and its cache entry — did not.
+ */
+export function resolveCssImports(modules) {
+  const byFileName = new Map(modules.map(module => [module.fileName, module]));
+  const resolvedByKey = new Map();
+  const resolve = (module, ancestors) => {
+    const cached = resolvedByKey.get(module.key);
+    if (cached) {
+      return cached;
+    }
+
+    // Build the token → resolved-value map from this module's cross-file imports.
+    const replacements = {};
+    for (const [importPath, tokens] of Object.entries(module.imports)) {
+      const target = byFileName.get(resolveRelativePath(module.fileName, importPath));
+      const targetExports = target && !ancestors.has(target.key) ? resolve(target, new Set(ancestors).add(module.key)) : {};
+      for (const [token, name] of Object.entries(tokens)) {
+        replacements[token] = targetExports[name] ?? '';
+      }
+    }
+    const resolvedExports = {};
+    for (const [local, value] of Object.entries(module.exports)) {
+      resolvedExports[local] = applyReplacements(value, replacements);
+    }
+    resolvedByKey.set(module.key, resolvedExports);
+    return resolvedExports;
+  };
+  for (const module of modules) {
+    resolve(module, new Set());
+  }
+  return resolvedByKey;
+}

package/useDemoController/transformCode.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Transpiles a TypeScript/JSX source string into plain JavaScript that uses
+ * CommonJS-style `require`/`exports`, ready to run with `evalCode`.
+ *
+ * JSX is emitted with the classic runtime (`React.createElement`), so `React`
+ * must be in scope when the result is evaluated.
+ */
+export declare function transformCode(code: string): string;
+/**
+ * Promotes a bare leading expression to the module's default export, so a snippet
+ * like `<App />` can be run on its own. Sources that already declare their own
+ * exports — or lead with anything else — are returned unchanged.
+ */
+export declare function normalizeCode(code: string): string;

package/useDemoController/transformCode.mjs

@@ -0,0 +1,42 @@
+import { transform as sucraseTransform } from 'sucrase';
+
+/**
+ * Sucrase prefixes its output with a `"use strict";` prologue. The evaluated body
+ * already runs in strict mode inside the generated function, so the prologue is
+ * stripped to keep the result minimal.
+ */
+const USE_STRICT_PROLOGUE = '"use strict";';
+
+/**
+ * Transpiles a TypeScript/JSX source string into plain JavaScript that uses
+ * CommonJS-style `require`/`exports`, ready to run with `evalCode`.
+ *
+ * JSX is emitted with the classic runtime (`React.createElement`), so `React`
+ * must be in scope when the result is evaluated.
+ */
+export function transformCode(code) {
+  const {
+    code: transpiled
+  } = sucraseTransform(code, {
+    transforms: ['jsx', 'typescript', 'imports'],
+    production: true
+  });
+  return transpiled.startsWith(USE_STRICT_PROLOGUE) ? transpiled.slice(USE_STRICT_PROLOGUE.length) : transpiled;
+}
+
+/**
+ * Matches a source that leads (after optional whitespace) with a renderable
+ * expression: a JSX element, a function declaration/expression, a zero-argument
+ * arrow function, or a class. Only the first line is captured so the rest of the
+ * source is preserved untouched.
+ */
+const LEADING_RENDERABLE = /^(\s*)(<[^>]*>|function[\s(]|\(\)\s*=>|class\s)(.*)/;
+
+/**
+ * Promotes a bare leading expression to the module's default export, so a snippet
+ * like `<App />` can be run on its own. Sources that already declare their own
+ * exports — or lead with anything else — are returned unchanged.
+ */
+export function normalizeCode(code) {
+  return code.replace(LEADING_RENDERABLE, '$1export default $2$3');
+}

package/useDemoController/transpileClientSingleton.d.mts

@@ -0,0 +1,10 @@
+import type { Transpile } from "./transpileSource.mjs";
+/**
+ * Returns the page-shared {@link Transpile}, creating the worker (or main-thread
+ * fallback) on first call and reusing it thereafter. Call this from a browser
+ * effect — never at module top level — so the worker is never constructed during
+ * SSR.
+ */
+export declare function getTranspile(): Promise<Transpile>;
+/** Test-only: drop the cached singleton (and terminate any worker it created). */
+export declare function resetTranspileClientForTests(): void;

package/useDemoController/transpileClientSingleton.mjs

@@ -0,0 +1,83 @@
+import { createTranspileWorkerClient } from "./createTranspileWorkerClient.mjs";
+/**
+ * The page-shared transpile, created lazily once and reused across every demo
+ * controller. Transpilation is stateless (sucrase is pure), so — unlike the
+ * per-provider syntax-highlight worker — a single worker serves the whole page:
+ * fewer worker spin-ups, one shared module-graph, and a process-wide compile
+ * cache. It is intentionally never terminated; an idle worker is cheap.
+ */
+let transpilePromise = null;
+let activeClient = null;
+
+/**
+ * Lazily loads the main-thread transpile. The heavy `transpileSource` (sucrase + the
+ * import parser) rides in its own chunk, fetched only when there's no worker — so a
+ * worker-capable environment never downloads it.
+ */
+async function loadMainThreadTranspile() {
+  const {
+    transpileSource
+  } = await import("./transpileSource.mjs");
+  // `async` so a transpile failure rejects (matching the worker client) rather than
+  // throwing synchronously.
+  return async (source, options, signal) => {
+    if (signal?.aborted) {
+      throw signal.reason;
+    }
+    return transpileSource(source, options);
+  };
+}
+async function createTranspile() {
+  // The live transpile implementation — a worker, or the main-thread fallback. Held
+  // in a closure variable so a worker crash can swap it WITHOUT the caller (which
+  // caches the returned function) having to re-fetch.
+  let delegate;
+  const fallBackToMainThread = () => {
+    // The same worker URL would just fail again, so don't rebuild it — load the
+    // main-thread transpile once and route every later call through it. Until it
+    // resolves, calls await the same promise so none are dropped.
+    const mainThread = loadMainThreadTranspile();
+    delegate = (source, options, signal) => mainThread.then(run => run(source, options, signal));
+  };
+
+  // A browser with module-worker support runs transpilation off the UI thread.
+  // `createTranspileWorkerClient()` throws synchronously where module workers are
+  // unsupported (SSR, no `Worker`, older Safari) — caught here to fall back to a
+  // main-thread transpile, still async so the caller has one code path.
+  try {
+    const client = createTranspileWorkerClient(() => {
+      // The shared worker died (a load/init failure). Its in-flight requests were
+      // already rejected by the client (they retry from the next edit); swap to the
+      // main thread so live editing keeps working instead of failing every build.
+      activeClient = null;
+      fallBackToMainThread();
+    });
+    activeClient = client;
+    delegate = client.transpile;
+  } catch {
+    fallBackToMainThread();
+  }
+
+  // A STABLE wrapper: callers cache it, and `delegate` swaps underneath on a crash.
+  return (source, options, signal) => delegate(source, options, signal);
+}
+
+/**
+ * Returns the page-shared {@link Transpile}, creating the worker (or main-thread
+ * fallback) on first call and reusing it thereafter. Call this from a browser
+ * effect — never at module top level — so the worker is never constructed during
+ * SSR.
+ */
+export function getTranspile() {
+  if (!transpilePromise) {
+    transpilePromise = createTranspile();
+  }
+  return transpilePromise;
+}
+
+/** Test-only: drop the cached singleton (and terminate any worker it created). */
+export function resetTranspileClientForTests() {
+  activeClient?.terminate();
+  activeClient = null;
+  transpilePromise = null;
+}

package/useDemoController/transpileSource.d.mts

@@ -0,0 +1,29 @@
+/** How to transform one source before sucrase transpiles it. */
+export interface TranspileSourceOptions {
+  /** The file's path within the demo (e.g. `dir/util.ts`) — resolves relative imports when `nested`. */
+  fileName?: string;
+  /** Rewrite relative imports to absolute scope keys (subdirectory demos). */
+  nested?: boolean;
+  /** Promote a bare leading expression to a default export — used for the entry source. */
+  normalize?: boolean;
+}
+/**
+ * The full source → runnable-JS transform, run for one file: rewrite relative
+ * imports to absolute scope keys (when `nested`), promote a bare leading
+ * expression to a default export (the `normalize` entry case), then transpile
+ * TS/JSX to CommonJS via sucrase.
+ *
+ * Pure `string → string` with no DOM, React, or `new Function`, so it runs
+ * identically on the main thread or inside a Web Worker — it is the unit the
+ * transpile worker offloads off the UI thread. The `new Function`/eval that turns
+ * the result into a module stays on the main thread (see `instantiateModule`).
+ */
+export declare function transpileSource(source: string, options?: TranspileSourceOptions): string;
+/**
+ * Transpiles one source to runnable JS asynchronously — on the main thread, or
+ * (preferably) in a Web Worker off the UI thread. An optional `AbortSignal` drops
+ * a stale request when a newer edit supersedes it. Mirrors {@link transpileSource}
+ * but async, so a worker-backed and a main-thread implementation are
+ * interchangeable.
+ */
+export type Transpile = (source: string, options?: TranspileSourceOptions, signal?: AbortSignal) => Promise<string>;

package/useDemoController/transpileSource.mjs

@@ -0,0 +1,36 @@
+import { absolutizeImports } from "./absolutizeImports.mjs";
+import { normalizeCode, transformCode } from "./transformCode.mjs";
+
+/** How to transform one source before sucrase transpiles it. */
+
+/**
+ * The full source → runnable-JS transform, run for one file: rewrite relative
+ * imports to absolute scope keys (when `nested`), promote a bare leading
+ * expression to a default export (the `normalize` entry case), then transpile
+ * TS/JSX to CommonJS via sucrase.
+ *
+ * Pure `string → string` with no DOM, React, or `new Function`, so it runs
+ * identically on the main thread or inside a Web Worker — it is the unit the
+ * transpile worker offloads off the UI thread. The `new Function`/eval that turns
+ * the result into a module stays on the main thread (see `instantiateModule`).
+ */
+export function transpileSource(source, options = {}) {
+  const {
+    fileName = '',
+    nested = false,
+    normalize = false
+  } = options;
+  let result = nested ? absolutizeImports(source, fileName) : source;
+  if (normalize) {
+    result = normalizeCode(result);
+  }
+  return transformCode(result);
+}
+
+/**
+ * Transpiles one source to runnable JS asynchronously — on the main thread, or
+ * (preferably) in a Web Worker off the UI thread. An optional `AbortSignal` drops
+ * a stale request when a newer edit supersedes it. Mirrors {@link transpileSource}
+ * but async, so a worker-backed and a main-thread implementation are
+ * interchangeable.
+ */

package/useDemoController/transpileWorker.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Worker entry point for off-main-thread transpilation.
+ *
+ * For each request the main thread posts `{ type: 'transpile', id, source,
+ * options }`; the worker runs the same {@link transpileSource} body the main
+ * thread would (so the output is byte-identical) and posts back
+ * `{ type: 'transpile', id, ok, code? | error? }`.
+ *
+ * Stateless and dependency-free of any handshake: sucrase is pure, so — unlike
+ * the syntax-highlight worker — there is no `init`/grammar payload and no request
+ * queue. The heavy `sucrase` (and the import parser) are imported here, inside the
+ * worker chunk, so they stay off the main thread's bundle.
+ */
+export {};

package/useDemoController/transpileWorker.mjs

@@ -0,0 +1,41 @@
+/**
+ * Worker entry point for off-main-thread transpilation.
+ *
+ * For each request the main thread posts `{ type: 'transpile', id, source,
+ * options }`; the worker runs the same {@link transpileSource} body the main
+ * thread would (so the output is byte-identical) and posts back
+ * `{ type: 'transpile', id, ok, code? | error? }`.
+ *
+ * Stateless and dependency-free of any handshake: sucrase is pure, so — unlike
+ * the syntax-highlight worker — there is no `init`/grammar payload and no request
+ * queue. The heavy `sucrase` (and the import parser) are imported here, inside the
+ * worker chunk, so they stay off the main thread's bundle.
+ */
+
+import { transpileSource } from "./transpileSource.mjs";
+// `self` in a dedicated worker exposes `postMessage`/`addEventListener` on the
+// global scope, but the default `tsconfig` `lib` here doesn't include the
+// `webworker` lib so we cast once via a typed alias instead of per-call.
+const workerScope = self;
+workerScope.addEventListener('message', event => {
+  const data = event.data;
+  if (data.type !== 'transpile') {
+    return;
+  }
+  try {
+    const code = transpileSource(data.source, data.options);
+    workerScope.postMessage({
+      type: 'transpile',
+      id: data.id,
+      ok: true,
+      code
+    });
+  } catch (error) {
+    workerScope.postMessage({
+      type: 'transpile',
+      id: data.id,
+      ok: false,
+      error
+    });
+  }
+});

package/useDemoController/types.d.mts

@@ -0,0 +1,30 @@
+/**
+ * The set of identifiers exposed to evaluated source as local variables.
+ *
+ * Every own-enumerable key becomes a binding in the generated function, with two
+ * reserved keys handled specially: `import` is the registry consulted by
+ * (transpiled) `import` statements, and `default` is never bound because it is a
+ * reserved word and cannot name a function parameter.
+ *
+ * A cleanroom reimplementation of the `react-runner` runtime (MIT, © 2019 Neo);
+ * the public surface (`useRunner`, `importCode`, `Runner`, …) mirrors that
+ * library so it can be vendored as a drop-in replacement.
+ */
+export type Scope = Record<string, unknown> & {
+  /** Registry consulted by transpiled `import` statements, keyed by specifier. */
+  import?: Record<string, unknown>;
+};
+/** Inputs shared by every entry point that transpiles and evaluates a source string. */
+export interface RunnerOptions {
+  /** The TypeScript/JSX source to transpile and evaluate. */
+  code: string;
+  /** Identifiers (and an `import` registry) exposed to the evaluated source. */
+  scope?: Scope;
+}
+/**
+ * Evaluates a compiled module against the `import` registry, writing its exports
+ * into the passed `exports` object. The registry registers one of these per
+ * module; it runs on first `require`, so circular imports resolve via the
+ * in-progress `exports` set before the body runs.
+ */
+export type ModuleRun = (imports: Record<string, unknown>, exports: Scope) => void;

package/useDemoController/types.mjs

@@ -0,0 +1 @@
+export {};

package/useDemoController/useDemoController.d.mts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import type { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerContext';
+export interface UseDemoControllerResult {
+  /** The controlled source, keyed by variant. `null` until the first edit. */
+  code: ControlledCode | null;
+  /**
+   * Updates the controlled source (e.g. as a reader edits a variant). Typed as the
+   * context's `setCode` (`Dispatch<SetStateAction>`) so the whole result drops straight
+   * into a `CodeControllerContext.Provider` with no cast.
+   */
+  setCode: NonNullable<CodeControllerContext['setCode']>;
+  /**
+   * One live preview node per variant, keyed by variant — for the variants that
+   * have finished building. `undefined` until at least one is ready, so a host can
+   * keep showing its build-time render in the meantime (an in-flight variant simply
+   * has no entry). Drop straight into `CodeControllerContext` as `components`.
+   *
+   * Each node is the lazy `DemoRunner`, so the host MUST render it under a `Suspense`
+   * boundary; that boundary's fallback should be the build-time render so a freshly
+   * mounted preview (e.g. the first edit after `reset()`) shows the original rather
+   * than an empty frame while the chunk resolves. `CodeHighlighterClient` does this.
+   */
+  components: Record<string, React.ReactNode> | undefined;
+  /** Current error message per variant (or `null` when it renders cleanly). */
+  errors: Record<string, string | null>;
+  /**
+   * Warms the lazy live-editing engine chunks when a block activates for editing.
+   * Drop straight into `CodeControllerContext` as `onActivate`; the host calls it with
+   * which file kinds the demo spans (`js`/`css`).
+   */
+  onActivate: (deps: {
+    js: boolean;
+    css: boolean;
+  }) => void;
+}
+/**
+ * Drives the live previews for a demo controller. Owns the controlled `code` state,
+ * transpiles each variant OFF the main thread (via a shared Web Worker, with a
+ * main-thread fallback) and renders the ready ones through {@link DemoRunner}, and
+ * collects the per-variant `errors` — returning exactly the `{ code, setCode,
+ * components, errors }` shape a `CodeControllerContext` provider expects, so a host
+ * wires it up in one line and reads results back through `useDemo`.
+ *
+ * Because transpilation is async, a variant joins `components` only once its build
+ * resolves; editing never blocks the UI thread, and an in-flight variant shows its
+ * fallback rather than a flash of empty preview. Keeping `code` unset until the
+ * first `setCode` lets the host serve its build-time/server render first.
+ *
+ * By default the controlled code is also mirrored across same-origin tabs of the same
+ * page (via the `crossTabSync` option), so a reader editing a demo in a Chrome split
+ * view sees it update in both panes.
+ */
+export declare function useDemoController(): UseDemoControllerResult;