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

package/useDemoController/compileCssWithPostcss.mjs

@@ -0,0 +1,89 @@
+import postcss from 'postcss';
+import autoprefixer from 'autoprefixer';
+import modulesValues from 'postcss-modules-values';
+import localByDefault from 'postcss-modules-local-by-default';
+import extractImports from 'postcss-modules-extract-imports';
+import scope from 'postcss-modules-scope';
+import relativeColorSyntax from '@csstools/postcss-relative-color-syntax';
+import lightDarkFunction from '@csstools/postcss-light-dark-function';
+import steppedValueFunctions from '@csstools/postcss-stepped-value-functions';
+import { extractICSS } from 'icss-utils';
+import { hashString } from "./hashString.mjs";
+import { currentBrowserTarget } from "./currentBrowserTarget.mjs";
+/**
+ * Shared autoprefixer plugin, created once when this lazy chunk first loads. It
+ * targets the EXACT browser the preview is running in (see
+ * {@link currentBrowserTarget}) rather than a broad range — a demo's CSS only has to
+ * work in the visitor's own browser, so a current browser gets no prefixes at all.
+ * `ignoreUnknownVersions` makes a browser newer than the bundled caniuse-lite resolve
+ * to no prefixes (correct) instead of throwing.
+ */
+const autoprefix = autoprefixer({
+  overrideBrowserslist: currentBrowserTarget(),
+  ignoreUnknownVersions: true
+});
+
+/**
+ * Lowers the handful of modern CSS features that aren't yet Baseline Widely Available
+ * — relative color syntax (`rgb(from …)`), `light-dark()`, and the stepped-value math
+ * (`round()`/`mod()`/`rem()`) — so a demo using them still renders while live-editing
+ * on a browser older than the feature, matching what Lightning CSS does at build time.
+ * `preserve: true` keeps the modern syntax alongside the fallback, so a current browser
+ * uses it natively and the fallback is harmless dead weight. Everything else on
+ * Lightning CSS's lowering list (nesting, `color-mix()`, lab/lch, media-query ranges,
+ * `:is()`/`:not()`, …) is already widely available and needs no transform.
+ */
+const lowerModernCss = [relativeColorSyntax({
+  preserve: true
+}), lightDarkFunction({
+  preserve: true
+}), steppedValueFunctions({
+  preserve: true
+})];
+
+/**
+ * The PostCSS implementation behind {@link import('./compileCssModule').compileCssModule}.
+ *
+ * This module statically imports the WHOLE CSS toolchain (postcss + autoprefixer +
+ * the ICSS Modules plugins), so it is loaded behind ONE dynamic `import()` from the
+ * light `compileCssModule` shell — the bundler then emits a single `compileCss`
+ * chunk instead of a separate chunk per npm package. None of this enters the main
+ * bundle; it is paid for only when a demo first compiles CSS.
+ *
+ * Runs the same ICSS plugin chain css-loader uses (values → local-by-default →
+ * extract-imports → scope) followed by {@link lowerModernCss} and autoprefixer, then
+ * `extractICSS` for the exports. See the shell's docs for the full semantics.
+ */
+export async function compileCssModuleWithPostcss(source, options = {}) {
+  const suffix = hashString(options.hashSeed ?? source).padStart(5, '0');
+  const result = await postcss([modulesValues, localByDefault({
+    mode: 'local'
+  }), extractImports(), scope({
+    generateScopedName: name => `${name}-${suffix}`,
+    exportGlobals: false
+  }), ...lowerModernCss, autoprefix
+  // `from` is the file name, so a `CssSyntaxError` reads `name.module.css:L:C: …`.
+  ]).process(source, {
+    from: options.fileName
+  });
+
+  // `extractICSS` mutates the root (removing the `:export`/`:import` rules), so
+  // re-stringify from the root afterwards rather than reading the stale `css`.
+  const {
+    icssImports,
+    icssExports
+  } = extractICSS(result.root, true);
+  return {
+    css: result.root.toString(),
+    exports: icssExports,
+    imports: icssImports
+  };
+}
+
+/** The PostCSS implementation behind `prefixCss` — {@link lowerModernCss} + autoprefix, no scoping. */
+export async function prefixCssWithPostcss(source, fileName) {
+  const result = await postcss([...lowerModernCss, autoprefix]).process(source, {
+    from: fileName
+  });
+  return result.css;
+}

package/useDemoController/compileModule.d.mts

@@ -0,0 +1,14 @@
+import type { ModuleRun } from "./types.mjs";
+/**
+ * Transpiles a module's source and returns a runner that evaluates it against a
+ * `require` registry, writing into a caller-provided `exports`. A synchronous
+ * convenience that pairs the two halves — `transformCode` (the heavy sucrase
+ * transpile) and {@link instantiateModule} (`new Function` + run) — for callers
+ * that transpile on the main thread. The async/worker path splits them: it
+ * transpiles off-thread and calls `instantiateModule` directly with the result.
+ *
+ * The returned runner injects `React` and a `require` shim backed by the passed
+ * `imports`, mirroring the `{ import }` scope that {@link importCode} evaluates
+ * against.
+ */
+export declare function compileModule(code: string): ModuleRun;

package/useDemoController/compileModule.mjs

@@ -0,0 +1,17 @@
+import { instantiateModule } from "./instantiateModule.mjs";
+import { transformCode } from "./transformCode.mjs";
+/**
+ * Transpiles a module's source and returns a runner that evaluates it against a
+ * `require` registry, writing into a caller-provided `exports`. A synchronous
+ * convenience that pairs the two halves — `transformCode` (the heavy sucrase
+ * transpile) and {@link instantiateModule} (`new Function` + run) — for callers
+ * that transpile on the main thread. The async/worker path splits them: it
+ * transpiles off-thread and calls `instantiateModule` directly with the result.
+ *
+ * The returned runner injects `React` and a `require` shim backed by the passed
+ * `imports`, mirroring the `{ import }` scope that {@link importCode} evaluates
+ * against.
+ */
+export function compileModule(code) {
+  return instantiateModule(transformCode(code));
+}

package/useDemoController/constants.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Specifier prefix under which an extra file's exports are registered in the
+ * runner scope. Relative imports between extra files (and from the main source)
+ * are rewritten to `<prefix><path-from-demo-root>`, so the runner's exact-key
+ * `require` resolves them no matter where the importing file sits.
+ *
+ * Kept in this tiny module — not in `absolutizeImports` — so the static-graph
+ * `collectSources`, which only needs this constant, doesn't pull the heavy
+ * `absolutizeImports` (sucrase-adjacent: the import parser + rewriter) into the
+ * main bundle. That function then folds into the lazy `transpileSource` chunk
+ * instead of hoisting out as its own.
+ */
+export declare const SCOPE_IMPORT_PREFIX = "@mui/internal-docs-infra/useDemoController/imports/";

package/useDemoController/constants.mjs

@@ -0,0 +1,13 @@
+/**
+ * Specifier prefix under which an extra file's exports are registered in the
+ * runner scope. Relative imports between extra files (and from the main source)
+ * are rewritten to `<prefix><path-from-demo-root>`, so the runner's exact-key
+ * `require` resolves them no matter where the importing file sits.
+ *
+ * Kept in this tiny module — not in `absolutizeImports` — so the static-graph
+ * `collectSources`, which only needs this constant, doesn't pull the heavy
+ * `absolutizeImports` (sucrase-adjacent: the import parser + rewriter) into the
+ * main bundle. That function then folds into the lazy `transpileSource` chunk
+ * instead of hoisting out as its own.
+ */
+export const SCOPE_IMPORT_PREFIX = '@mui/internal-docs-infra/useDemoController/imports/';

package/useDemoController/createRequire.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Builds the `require` shim handed to transpiled `import` statements. There is no
+ * real module system at runtime, so specifiers are resolved by exact lookup in
+ * the provided registry; anything missing throws.
+ *
+ * Lookup uses `Object.prototype.hasOwnProperty` so inherited members (e.g.
+ * `toString`) are never mistaken for registered modules, and a registry created
+ * with `Object.create(null)` still works.
+ */
+export declare function createRequire(modules?: Record<string, unknown>): (specifier: string) => unknown;

package/useDemoController/createRequire.mjs

@@ -0,0 +1,17 @@
+/**
+ * Builds the `require` shim handed to transpiled `import` statements. There is no
+ * real module system at runtime, so specifiers are resolved by exact lookup in
+ * the provided registry; anything missing throws.
+ *
+ * Lookup uses `Object.prototype.hasOwnProperty` so inherited members (e.g.
+ * `toString`) are never mistaken for registered modules, and a registry created
+ * with `Object.create(null)` still works.
+ */
+export function createRequire(modules = {}) {
+  return specifier => {
+    if (!Object.prototype.hasOwnProperty.call(modules, specifier)) {
+      throw new Error(`Module not found: '${specifier}'`);
+    }
+    return modules[specifier];
+  };
+}

package/useDemoController/createTranspileWorkerClient.d.mts

@@ -0,0 +1,27 @@
+import type { Transpile } from "./transpileSource.mjs";
+export interface TranspileWorkerClient {
+  /**
+   * Transpiles one source inside the worker. Returns the same string the
+   * synchronous `transpileSource` would. If `signal` aborts before the worker
+   * responds, the in-flight request is dropped and the promise rejects with
+   * `signal.reason`.
+   */
+  transpile: Transpile;
+  terminate(): void;
+}
+/**
+ * Creates a worker-backed {@link Transpile}. The caller owns the lifecycle and
+ * must call `terminate()` when done. Each client owns exactly one `Worker`;
+ * concurrent in-flight requests are demuxed by a monotonically increasing `id`.
+ *
+ * If the worker dies unexpectedly (a load/parse failure, or a message that fails
+ * to deserialize), every in-flight request is rejected and `onFatal` fires — so a
+ * crash surfaces as a rejected build rather than a request that hangs forever. The
+ * client then latches `dead`: later `transpile` calls reject immediately instead of
+ * posting to a worker that will never reply. The owner (`transpileClientSingleton`)
+ * uses `onFatal` to swap in the main-thread transpile so editing keeps working.
+ *
+ * Mirrors `CodeProvider/createParseSourceWorkerClient` — minus the grammar
+ * init/register handshake, since transpilation is stateless.
+ */
+export declare function createTranspileWorkerClient(onFatal?: (error: Error) => void): TranspileWorkerClient;

package/useDemoController/createTranspileWorkerClient.mjs

@@ -0,0 +1,139 @@
+/**
+ * Creates a worker-backed {@link Transpile}. The caller owns the lifecycle and
+ * must call `terminate()` when done. Each client owns exactly one `Worker`;
+ * concurrent in-flight requests are demuxed by a monotonically increasing `id`.
+ *
+ * If the worker dies unexpectedly (a load/parse failure, or a message that fails
+ * to deserialize), every in-flight request is rejected and `onFatal` fires — so a
+ * crash surfaces as a rejected build rather than a request that hangs forever. The
+ * client then latches `dead`: later `transpile` calls reject immediately instead of
+ * posting to a worker that will never reply. The owner (`transpileClientSingleton`)
+ * uses `onFatal` to swap in the main-thread transpile so editing keeps working.
+ *
+ * Mirrors `CodeProvider/createParseSourceWorkerClient` — minus the grammar
+ * init/register handshake, since transpilation is stateless.
+ */
+export function createTranspileWorkerClient(onFatal) {
+  // Module workers are required (the worker uses `import` statements). On browsers
+  // that expose `Worker` but reject `{ type: 'module' }` (older Safari, some
+  // embedded webviews) the constructor throws synchronously. Surface that as a
+  // tagged error so callers can fall back cleanly to the main-thread transpile.
+  let worker;
+  try {
+    worker = new Worker(new URL('./transpileWorker', import.meta.url), {
+      type: 'module'
+    });
+  } catch (cause) {
+    throw new Error('Module workers are not supported in this environment', {
+      cause
+    });
+  }
+  const pending = new Map();
+  let nextId = 1;
+  // Latched once the worker dies or is terminated, so later `transpile` calls reject
+  // immediately rather than hanging on a worker that will never respond.
+  let dead = false;
+
+  // Reject + forget every in-flight request with `reason`, detaching their abort
+  // listeners first. Shared by `terminate()` (intentional) and the fatal-error path.
+  const rejectAllPending = reason => {
+    for (const entry of pending.values()) {
+      if (entry.signal && entry.onAbort) {
+        entry.signal.removeEventListener('abort', entry.onAbort);
+      }
+      entry.reject(reason);
+    }
+    pending.clear();
+  };
+
+  // The worker died unexpectedly — a load/parse failure, or a message that could not
+  // be deserialized. (A transpile that merely throws is caught inside the worker and
+  // reported as an `ok: false` response, so it never reaches here.) Reject everything
+  // in flight, latch `dead`, terminate the husk, and let the owner recover via
+  // `onFatal`. Idempotent: a second fatal event (or a later `terminate`) is a no-op.
+  const handleFatal = error => {
+    if (dead) {
+      return;
+    }
+    dead = true;
+    rejectAllPending(error);
+    worker.terminate();
+    onFatal?.(error);
+  };
+  worker.addEventListener('message', event => {
+    const data = event.data;
+    if (data.type !== 'transpile') {
+      return;
+    }
+    const entry = pending.get(data.id);
+    if (!entry) {
+      // Aborted before the response arrived — drop silently.
+      return;
+    }
+    pending.delete(data.id);
+    if (entry.signal && entry.onAbort) {
+      entry.signal.removeEventListener('abort', entry.onAbort);
+    }
+    if (data.ok) {
+      entry.resolve(data.code);
+    } else {
+      entry.reject(data.error);
+    }
+  });
+  worker.addEventListener('error', event => {
+    handleFatal(new Error(event.message || 'Transpile worker errored'));
+  });
+  worker.addEventListener('messageerror', () => {
+    handleFatal(new Error('Transpile worker received an undeserializable message'));
+  });
+  const transpile = (source, options, signal) => {
+    if (dead) {
+      return Promise.reject(new Error('Transpile worker is no longer available'));
+    }
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason);
+    }
+    const id = nextId;
+    nextId += 1;
+    return new Promise((resolve, reject) => {
+      const onAbort = signal ? () => {
+        const entry = pending.get(id);
+        if (!entry) {
+          return;
+        }
+        pending.delete(id);
+        if (entry.signal && entry.onAbort) {
+          entry.signal.removeEventListener('abort', entry.onAbort);
+        }
+        reject(signal.reason);
+      } : undefined;
+      pending.set(id, {
+        resolve,
+        reject,
+        signal,
+        onAbort
+      });
+      if (signal && onAbort) {
+        signal.addEventListener('abort', onAbort, {
+          once: true
+        });
+      }
+      const message = {
+        type: 'transpile',
+        id,
+        source,
+        options
+      };
+      worker.postMessage(message);
+    });
+  };
+  function terminate() {
+    dead = true;
+    worker.terminate();
+    rejectAllPending(new Error('Worker terminated'));
+  }
+  return {
+    transpile,
+    terminate
+  };
+}

package/useDemoController/cssModules.d.mts

@@ -0,0 +1,47 @@
+// Ambient declarations for the ICSS plugin trio + helpers that power CSS Modules
+// scoping. These are the exact packages css-loader composes internally; none ship
+// their own types, and all are pure PostCSS AST transforms (no fs/path), so they
+// run identically in the browser and Node. Typed minimally to what the compiler
+// here uses — see `compileCssModule.ts`.
+
+declare module 'postcss-modules-values' {
+  import type { Plugin } from 'postcss';
+
+  // Resolves `@value` definitions/usages. Used directly as a plugin (no options).
+  const plugin: Plugin;
+  export default plugin;
+}
+declare module 'postcss-modules-local-by-default' {
+  import type { Plugin } from 'postcss';
+  const plugin: (options?: {
+    mode?: 'local' | 'global' | 'pure';
+  }) => Plugin;
+  export default plugin;
+}
+declare module 'postcss-modules-extract-imports' {
+  import type { Plugin } from 'postcss';
+  const plugin: (options?: {
+    failOnWrongOrder?: boolean;
+  }) => Plugin;
+  export default plugin;
+}
+declare module 'postcss-modules-scope' {
+  import type { Plugin } from 'postcss';
+  const plugin: (options?: {
+    generateScopedName?: (name: string, path: string, css: string) => string;
+    generateExportEntry?: unknown;
+    exportGlobals?: boolean;
+  }) => Plugin;
+  export default plugin;
+}
+declare module 'icss-utils' {
+  import type { Root } from 'postcss';
+
+  /** Pulls the `:import`/`:export` ICSS rules out of a processed root. */
+  export function extractICSS(css: Root, removeRules?: boolean): {
+    icssImports: Record<string, Record<string, string>>;
+    icssExports: Record<string, string>;
+  };
+  export function replaceValueSymbols(css: Root, replacements: Record<string, string>): void;
+  export function replaceSymbols(css: Root, replacements: Record<string, string>): void;
+}

package/useDemoController/currentBrowserTarget.d.mts

@@ -0,0 +1,16 @@
+/**
+ * The autoprefixer/browserslist target for the live-demo CSS compiler: the EXACT
+ * browser + version the preview is running in.
+ *
+ * A demo's compiled CSS only has to work in the visitor's own browser, so prefixing
+ * for that single engine adds exactly what it needs — usually nothing on a current
+ * browser — instead of the whole "baseline" range. Off the main thread (SSR/Node) or
+ * in an unrecognized engine it falls back to `baseline widely available`, a
+ * broad-but-safe default. On iOS every browser is WebKit, so the `safari` branch
+ * (matched for any `Version/x Safari` UA) is the correct target there too.
+ *
+ * Pair with autoprefixer's `ignoreUnknownVersions`, so a browser newer than the
+ * bundled caniuse-lite resolves to no prefixes (correct — current browsers need none)
+ * rather than throwing.
+ */
+export declare function currentBrowserTarget(): string[];

package/useDemoController/currentBrowserTarget.mjs

@@ -0,0 +1,36 @@
+/**
+ * The autoprefixer/browserslist target for the live-demo CSS compiler: the EXACT
+ * browser + version the preview is running in.
+ *
+ * A demo's compiled CSS only has to work in the visitor's own browser, so prefixing
+ * for that single engine adds exactly what it needs — usually nothing on a current
+ * browser — instead of the whole "baseline" range. Off the main thread (SSR/Node) or
+ * in an unrecognized engine it falls back to `baseline widely available`, a
+ * broad-but-safe default. On iOS every browser is WebKit, so the `safari` branch
+ * (matched for any `Version/x Safari` UA) is the correct target there too.
+ *
+ * Pair with autoprefixer's `ignoreUnknownVersions`, so a browser newer than the
+ * bundled caniuse-lite resolves to no prefixes (correct — current browsers need none)
+ * rather than throwing.
+ */
+export function currentBrowserTarget() {
+  const userAgent = typeof navigator === 'undefined' ? '' : navigator.userAgent;
+  const edge = userAgent.match(/Edg\/(\d+)/);
+  if (edge) {
+    return [`edge ${edge[1]}`];
+  }
+  const firefox = userAgent.match(/Firefox\/(\d+)/);
+  if (firefox) {
+    return [`firefox ${firefox[1]}`];
+  }
+  // Edge is matched above, so a remaining `Chrome/` is Chromium proper.
+  const chrome = userAgent.match(/Chrome\/(\d+)/);
+  if (chrome) {
+    return [`chrome ${chrome[1]}`];
+  }
+  const safari = userAgent.match(/Version\/(\d+\.\d+) Safari/);
+  if (safari) {
+    return [`safari ${safari[1]}`];
+  }
+  return ['baseline widely available'];
+}

package/useDemoController/evalCode.d.mts

@@ -0,0 +1,12 @@
+import type { Scope } from "./types.mjs";
+/**
+ * Evaluates already-transpiled CommonJS-style code with `scope` bound as local
+ * variables. `React` and a `require` shim (backed by `scope.import`) are always
+ * injected. The `import` key is consumed by the shim rather than bound, and
+ * `default` is skipped because it is a reserved word and cannot name a function
+ * parameter.
+ *
+ * Returns the evaluated function's return value; callers that need a module's
+ * exports pass an `exports` object in `scope` and read it back after the call.
+ */
+export declare function evalCode(code: string, scope: Scope): unknown;

package/useDemoController/evalCode.mjs

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { createRequire } from "./createRequire.mjs";
+/**
+ * Evaluates already-transpiled CommonJS-style code with `scope` bound as local
+ * variables. `React` and a `require` shim (backed by `scope.import`) are always
+ * injected. The `import` key is consumed by the shim rather than bound, and
+ * `default` is skipped because it is a reserved word and cannot name a function
+ * parameter.
+ *
+ * Returns the evaluated function's return value; callers that need a module's
+ * exports pass an `exports` object in `scope` and read it back after the call.
+ */
+export function evalCode(code, scope) {
+  const boundScope = {};
+  for (const key of Object.keys(scope)) {
+    if (key !== 'import' && key !== 'default') {
+      boundScope[key] = scope[key];
+    }
+  }
+
+  // Inject AFTER copying scope so the always-injected bindings WIN over any
+  // same-named scope entry: JSX in the evaluated code compiles to `React.*`, and
+  // its transpiled `import`s call this `require` shim — a scope `React`/`require`
+  // must not shadow either.
+  boundScope.React = React;
+  boundScope.require = createRequire(scope.import);
+  const names = Object.keys(boundScope);
+  const values = names.map(name => boundScope[name]);
+
+  // Evaluating transpiled demo source is the whole purpose of the runner;
+  // `new Function` runs it without leaking the surrounding lexical scope.
+  // eslint-disable-next-line no-new-func
+  const evaluate = new Function(...names, code);
+  return evaluate(...values);
+}

package/useDemoController/generateCssModuleSource.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Serializes a CSS module's class-name exports into ESM source text — the
+ * optional companion to `compileCssModule` for when a literal JS string is
+ * needed (to display in a source viewer, or to run a `.module.css` file through
+ * the same `importCode` path as `.ts`/`.js` files).
+ *
+ * Emits a named export for every identifier-safe class name and a default export
+ * object containing all of them (so hyphenated names like `my-button` remain
+ * reachable via `styles['my-button']`).
+ */
+export declare function generateCssModuleSource(exports: Record<string, string>): string;

package/useDemoController/generateCssModuleSource.mjs

@@ -0,0 +1,55 @@
+/**
+ * Reserved words that cannot be bound by `export const <name>` in a module
+ * (modules are always strict mode). Such class names are still reachable through
+ * the default-export object, just not as a named export.
+ */
+const RESERVED_WORDS = new Set(['break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'implements', 'interface', 'let', 'package', 'private', 'protected', 'public', 'static', 'yield', 'await', 'eval', 'arguments']);
+
+/** Whether `name` is a (conservative, ASCII) JavaScript identifier. */
+function isJsIdentifier(name) {
+  if (name.length === 0) {
+    return false;
+  }
+  for (let index = 0; index < name.length; index += 1) {
+    const code = name.charCodeAt(index);
+    const isLetter = code >= 97 && code <= 122 || code >= 65 && code <= 90;
+    const isUnderscoreOrDollar = code === 95 || code === 36;
+    const isDigit = code >= 48 && code <= 57;
+    if (!(isLetter || isUnderscoreOrDollar || index > 0 && isDigit)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Wraps a value in a single-quoted JS string literal, escaping it safely. */
+function quote(value) {
+  const escaped = value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n').replaceAll('\r', '\\r')
+  // U+2028/U+2029 are line terminators that were illegal in pre-ES2019 string
+  // literals; escape them so the generated source stays valid for any input.
+  .replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029');
+  return `'${escaped}'`;
+}
+
+/**
+ * Serializes a CSS module's class-name exports into ESM source text — the
+ * optional companion to `compileCssModule` for when a literal JS string is
+ * needed (to display in a source viewer, or to run a `.module.css` file through
+ * the same `importCode` path as `.ts`/`.js` files).
+ *
+ * Emits a named export for every identifier-safe class name and a default export
+ * object containing all of them (so hyphenated names like `my-button` remain
+ * reachable via `styles['my-button']`).
+ */
+export function generateCssModuleSource(exports) {
+  const entries = Object.entries(exports);
+  const lines = [];
+  for (const [local, scoped] of entries) {
+    if (isJsIdentifier(local) && !RESERVED_WORDS.has(local)) {
+      lines.push(`export const ${local} = ${quote(scoped)};`);
+    }
+  }
+  const objectBody = entries.map(([local, scoped]) => `${quote(local)}: ${quote(scoped)}`).join(', ');
+  lines.push(`export default {${objectBody ? ` ${objectBody} ` : ''}};`);
+  return `${lines.join('\n')}\n`;
+}

package/useDemoController/generateElement.d.mts

@@ -0,0 +1,21 @@
+import type * as React from 'react';
+import { ENTRY_EXPORTS_KEY } from "./instantiateElement.mjs";
+import type { RunnerOptions } from "./types.mjs";
+export { ENTRY_EXPORTS_KEY };
+/**
+ * Transpiles and evaluates a source string, returning the React node it exports
+ * as its default. A synchronous convenience that pairs the two halves —
+ * `normalizeCode` + `transformCode` (the heavy sucrase transpile) and
+ * {@link instantiateElement} (`evalCode` + node coercion) — for callers that
+ * transpile on the main thread. The async/worker path splits them: it transpiles
+ * off-thread and calls `instantiateElement` directly with the result.
+ *
+ * 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 (see `normalizeCode`). An empty source yields
+ * `null`.
+ */
+export declare function generateElement({
+  code,
+  scope
+}: RunnerOptions): React.ReactNode;

package/useDemoController/generateElement.mjs

@@ -0,0 +1,26 @@
+import { instantiateElement, ENTRY_EXPORTS_KEY } from "./instantiateElement.mjs";
+import { normalizeCode, transformCode } from "./transformCode.mjs";
+export { ENTRY_EXPORTS_KEY };
+
+/**
+ * Transpiles and evaluates a source string, returning the React node it exports
+ * as its default. A synchronous convenience that pairs the two halves —
+ * `normalizeCode` + `transformCode` (the heavy sucrase transpile) and
+ * {@link instantiateElement} (`evalCode` + node coercion) — for callers that
+ * transpile on the main thread. The async/worker path splits them: it transpiles
+ * off-thread and calls `instantiateElement` directly with the result.
+ *
+ * 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 (see `normalizeCode`). An empty source yields
+ * `null`.
+ */
+export function generateElement({
+  code,
+  scope
+}) {
+  if (!code.trim()) {
+    return null;
+  }
+  return instantiateElement(transformCode(normalizeCode(code)), scope);
+}

package/useDemoController/hashString.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Computes a short, deterministic base36 hash of a string.
+ *
+ * Deterministic and dependency-free: the same input always yields the same
+ * output, which matters when the result must agree across server render and
+ * client hydration. Uses a polynomial rolling hash modulo a Mersenne prime
+ * (2^31 - 1) — only arithmetic (no bitwise ops), staying within `Number`'s
+ * exact-integer range. Not cryptographic; meant for cheap, stable identifiers
+ * such as scoped CSS class suffixes.
+ */
+export declare function hashString(input: string): string;

package/useDemoController/hashString.mjs

@@ -0,0 +1,20 @@
+/**
+ * Computes a short, deterministic base36 hash of a string.
+ *
+ * Deterministic and dependency-free: the same input always yields the same
+ * output, which matters when the result must agree across server render and
+ * client hydration. Uses a polynomial rolling hash modulo a Mersenne prime
+ * (2^31 - 1) — only arithmetic (no bitwise ops), staying within `Number`'s
+ * exact-integer range. Not cryptographic; meant for cheap, stable identifiers
+ * such as scoped CSS class suffixes.
+ */
+export function hashString(input) {
+  const MODULUS = 2147483647; // 2^31 - 1
+  let hash = 0;
+  for (let index = 0; index < input.length; index += 1) {
+    // `hash < MODULUS` and the multiplier keep the product well under 2^53, so
+    // every step is exact.
+    hash = (hash * 131 + input.charCodeAt(index)) % MODULUS;
+  }
+  return hash.toString(36);
+}