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

package/useDemoController/absolutizeImports.mjs

@@ -0,0 +1,73 @@
+import { parseImportsAndComments } from "../pipeline/loaderUtils/parseImportsAndComments.mjs";
+import { rewriteImports } from "../pipeline/loaderUtils/rewriteImports.mjs";
+
+/**
+ * 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 function absolutizeImports(source, fileName,
+// Defaults to `SCOPE_IMPORT_PREFIX` (`./constants`) but INLINED as a literal rather
+// than imported: this module lands in the lazy `transpileSource` worker chunk, and
+// importing the eager `collectSources`'s `constants` would hoist that one-line module
+// into its own shared chunk. The match is guarded by this file's tests, which call
+// with the default and assert `SCOPE_IMPORT_PREFIX`-prefixed output.
+prefix = '@mui/internal-docs-infra/useDemoController/imports/') {
+  const lastSlash = fileName.lastIndexOf('/');
+  const fromDir = lastSlash === -1 ? '' : fileName.slice(0, lastSlash);
+
+  // Reuse the loader's single-pass import scanner (it correctly skips specifiers
+  // inside strings, comments, and template literals) to find each relative
+  // specifier and the positions where it appears. The parse URL is a fixed JS
+  // name, NOT the real `fileName`: the extra files routed here are always JS/TS,
+  // and a `.mdx` name would otherwise switch the scanner into MDX mode (where
+  // quotes no longer delimit strings). The directory is tracked separately above,
+  // so the made-up URL doesn't affect resolution.
+  const {
+    relative
+  } = parseImportsAndComments(source, 'file:///source.tsx');
+  const mapping = new Map();
+  for (const specifier of Object.keys(relative)) {
+    mapping.set(specifier, `${prefix}${resolveFromDir(fromDir, specifier)}`);
+  }
+  return rewriteImports(source, mapping, relative);
+}
+
+/**
+ * Resolves a relative `specifier` against `fromDir` into a normalized path (no
+ * leading `./`, `..` collapsed against real segments). A `..` that points ABOVE
+ * the demo root is PRESERVED, not dropped: a demo can import a shared file outside
+ * its own folder (`../shared/Button`), which a canonical `storeAt` mode keys by
+ * that same `../`-prefixed path — so the resolved specifier must keep the `..` to
+ * line up with the key. Pure string work — no Node `path` — so it runs unchanged
+ * in the browser.
+ */
+function resolveFromDir(fromDir, specifier) {
+  const segments = fromDir ? fromDir.split('/') : [];
+  segments.push(...specifier.split('/'));
+  const stack = [];
+  for (const segment of segments) {
+    if (segment === '' || segment === '.') {
+      continue;
+    }
+    if (segment === '..') {
+      // Collapse against a real preceding segment; otherwise keep the `..` (the
+      // path climbs above the root to a parent-directory file).
+      if (stack.length > 0 && stack[stack.length - 1] !== '..') {
+        stack.pop();
+      } else {
+        stack.push('..');
+      }
+      continue;
+    }
+    stack.push(segment);
+  }
+  return stack.join('/');
+}

package/useDemoController/buildScope.d.mts

@@ -0,0 +1,48 @@
+import type { ControlledVariantExtraFiles } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import type { Transpile } from "./transpileSource.mjs";
+export interface BuildScopeOptions {
+  /** Sibling files the sources can import, keyed by file name. */
+  extraFiles?: ControlledVariantExtraFiles;
+  /** Identifiers (e.g. `react`) seeded into the registry before the demo's files. */
+  externals: Record<string, unknown>;
+  /** The variant's main source — registered so an extra can import the entry, and returned (transpiled) as `runnerCode`. */
+  mainCode?: string;
+  /** Transpiles one source off the main thread (worker) or on it (fallback). */
+  transpile: Transpile;
+  /** Aborts in-flight transpiles when a newer edit supersedes this build. */
+  signal?: AbortSignal;
+  /** Overrides the name the main source is registered + resolved under. */
+  mainName?: string;
+}
+export interface BuiltScope {
+  /** The runner's module registry — the `import` map handed to the runner. */
+  imports: Record<string, unknown>;
+  /** The concatenated stylesheet text collected from CSS extra files. */
+  css: string;
+  /** Whether any extra file lives in a subdirectory (see {@link collectSources}). */
+  nested: boolean;
+  /** The transpiled main source for the runner to render. `undefined` when none was provided. */
+  runnerCode?: string;
+}
+/**
+ * Builds the runner scope from a variant's extra files (and optionally the main
+ * source). {@link collectSources} plans the registry keys (pure); each JS/TS file
+ * is then transpiled — relative imports rewritten + sucrase — by `transpile`, which
+ * runs off the main thread in a Web Worker (with a main-thread async fallback); CSS
+ * is scoped + autoprefixed by PostCSS (dynamically imported, off the main bundle).
+ * The compiled files are assembled into a lazy, circular-safe `import` registry,
+ * with cross-file `composes ... from` resolved across the variant's CSS modules.
+ *
+ * Per-file transpilation is cached by object identity, so editing one file only
+ * re-transpiles that file; a broken but UNUSED file is harmless (its error is thrown
+ * only if required). The main source (when provided) is returned transpiled as
+ * `runnerCode` for the runner to evaluate.
+ */
+export declare function buildScope({
+  extraFiles,
+  externals,
+  mainCode,
+  transpile,
+  signal,
+  mainName
+}: BuildScopeOptions): Promise<BuiltScope>;

package/useDemoController/buildScope.mjs

@@ -0,0 +1,270 @@
+import { compileCssModule, prefixCss } from "./compileCssModule.mjs";
+import { instantiateModule } from "./instantiateModule.mjs";
+import { ENTRY_EXPORTS_KEY } from "./instantiateElement.mjs";
+import { collectSources } from "./collectSources.mjs";
+import { resolveCssImports } from "./resolveCssImports.mjs";
+
+/**
+ * A compiled extra file, cached by the file's object identity (see `compiledFiles`).
+ * A JS module keeps a reusable `run`; a module whose transpile FAILED keeps the
+ * error, thrown only if the module is actually required (so a broken but unused
+ * file stays harmless); CSS results are fully materialized.
+ */
+
+/**
+ * Compiled-form cache keyed by the extra-file OBJECT. An edit replaces only the
+ * changed file's object (the controlled code is updated immutably), so unchanged
+ * files keep their reference and stay cache hits — skipping the costly re-transpile
+ * (and its worker round-trip) on every keystroke. Module-level so it survives
+ * re-renders; `WeakMap` so entries are reclaimed once a demo drops its files.
+ */
+const compiledFiles = new WeakMap();
+
+/**
+ * Transpiles one JS/TS module (off the main thread) and caches the result, unless
+ * an up-to-date entry already exists. The cache is gated on `nested`: absolutization
+ * differs by mode, so the transpiled output does too. A transpile FAILURE is cached
+ * as `moduleError` and re-thrown only when the module is required — so a broken but
+ * unused extra file never breaks the demo. An abort propagates (and is not cached).
+ */
+async function transpileModule(module, nested, transpile, signal) {
+  const cached = compiledFiles.get(module.file);
+  if (cached && (cached.kind === 'module' || cached.kind === 'moduleError') && cached.nested === nested) {
+    return;
+  }
+  try {
+    const transpiled = await transpile(module.source, {
+      fileName: module.fileName,
+      nested
+    }, signal);
+    compiledFiles.set(module.file, {
+      kind: 'module',
+      nested,
+      run: instantiateModule(transpiled)
+    });
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error; // a superseded build — let it reject so the caller drops it (don't cache)
+    }
+    compiledFiles.set(module.file, {
+      kind: 'moduleError',
+      nested,
+      // `toString()` (not `.message`) keeps the error name (e.g. `SyntaxError:`) in the
+      // surfaced message — the transpile paths reject with a live, named error.
+      error: error instanceof Error ? error.toString() : String(error)
+    });
+  }
+}
+
+/**
+ * Compiles one CSS extra file and caches the result, unless an up-to-date entry
+ * exists. A `*.module.css` is scoped + autoprefixed by {@link compileCssModule}
+ * (its cross-file `composes ... from` left as `imports` for the assembly pass to
+ * resolve); a plain `*.css` is autoprefixed by {@link prefixCss}. Both are async
+ * (PostCSS is dynamically imported) but mode-independent, so the result is cached
+ * by file identity and reused as-is.
+ *
+ * Malformed CSS rejects inside PostCSS with a `CssSyntaxError` (labelled
+ * `name.module.css:L:C` via the `fileName`), which propagates so the whole build
+ * rejects and the caller surfaces it as the variant's error (keeping the last good
+ * preview) — a broken stylesheet is a real error, not something to silently pass
+ * through as raw, unscoped CSS. An abort drops the result quietly instead of
+ * surfacing (the build was superseded).
+ */
+async function compileStyleExtra(style, signal) {
+  const cached = compiledFiles.get(style.file);
+  if (cached && cached.kind !== 'module' && cached.kind !== 'moduleError') {
+    return;
+  }
+  try {
+    if (style.isModule) {
+      const {
+        css,
+        exports,
+        imports
+      } = await compileCssModule(style.source, {
+        fileName: style.fileName
+      });
+      if (signal?.aborted) {
+        return;
+      }
+      compiledFiles.set(style.file, {
+        kind: 'cssModule',
+        exports,
+        css,
+        imports
+      });
+    } else {
+      const css = await prefixCss(style.source, style.fileName);
+      if (signal?.aborted) {
+        return;
+      }
+      compiledFiles.set(style.file, {
+        kind: 'css',
+        css
+      });
+    }
+  } catch (error) {
+    if (signal?.aborted) {
+      return; // superseded build — drop without surfacing
+    }
+    throw error; // a real `CssSyntaxError`, already naming the file — surface it
+  }
+}
+
+/** A style's compiled form: a scoped CSS module (with exports) or a plain sheet. */
+
+/** The cached compiled form for a style — defensively raw if it was never built. */
+function cssExtraFor(style) {
+  const cached = compiledFiles.get(style.file);
+  if (cached && (cached.kind === 'cssModule' || cached.kind === 'css')) {
+    return cached;
+  }
+  return {
+    kind: 'css',
+    css: style.source
+  };
+}
+
+/**
+ * Registers a module as a LAZILY-evaluated entry. It runs on first `require`, not
+ * eagerly, so registration order doesn't matter: a file can import a sibling (or
+ * the main source) registered later, and circular imports resolve via the
+ * in-progress `exports` (set before the body runs). `makeRun` is invoked once, on
+ * first access.
+ *
+ * `alwaysKeys` are claimed unconditionally; `ifFreeKeys` only when not already
+ * taken — so a concrete file wins over a weaker claimant on the same key (Node
+ * semantics: `foo.ts` beats `foo/index.ts`'s directory key, and an explicit extra
+ * beats the main entry).
+ */
+function defineLazyModule(imports, alwaysKeys, ifFreeKeys, makeRun) {
+  let exports = null;
+  const get = () => {
+    if (exports === null) {
+      // Set before running so a circular re-entry sees the in-progress exports.
+      exports = {};
+      makeRun()(imports, exports);
+    }
+    return exports;
+  };
+  const define = key => Object.defineProperty(imports, key, {
+    get,
+    enumerable: true,
+    configurable: true
+  });
+  alwaysKeys.forEach(define);
+  for (const key of ifFreeKeys) {
+    if (!Object.prototype.hasOwnProperty.call(imports, key)) {
+      define(key);
+    }
+  }
+}
+
+/** The run a module's registry getter uses: its cached `run`, or a deferred throw. */
+function moduleRunFor(module) {
+  const cached = compiledFiles.get(module.file);
+  if (cached?.kind === 'module') {
+    return cached.run;
+  }
+  // Transpile failed (or, defensively, was never run): surface it only here, when
+  // the module is actually required, so an unused broken file stays harmless.
+  const message = cached?.kind === 'moduleError' ? cached.error : `Module was not transpiled: ${module.fileName}`;
+  return () => {
+    throw new Error(message);
+  };
+}
+
+/**
+ * Assembles the runner registry SYNCHRONOUSLY from already-compiled files (the
+ * cache populated by {@link transpileModule} + {@link compileStyleExtra}). Kept
+ * synchronous so circular imports stay safe: every getter sets its in-progress
+ * `exports` before the body runs, and nothing here awaits.
+ */
+function assembleScope(collected, runnerCode, externals) {
+  const imports = {
+    ...externals
+  };
+  const styleSheets = [];
+
+  // Gather each style's compiled sheet (order-preserving); a plain CSS file exports
+  // an empty module, while a CSS module's exports wait for the cross-file pass below.
+  const cssModules = [];
+  for (const style of collected.styles) {
+    const compiled = cssExtraFor(style);
+    styleSheets.push(compiled.css);
+    if (compiled.kind === 'cssModule') {
+      cssModules.push({
+        key: style.key,
+        fileName: style.fileName,
+        exports: compiled.exports,
+        imports: compiled.imports
+      });
+    } else {
+      imports[style.key] = {};
+    }
+  }
+  // Resolve cross-file `composes ... from` against the CURRENT siblings. Done here,
+  // not in the per-file cache: a module's resolved names depend on sibling exports,
+  // which change when a sibling is edited even though this file's source did not.
+  const resolvedCssExports = resolveCssImports(cssModules);
+  for (const cssModule of cssModules) {
+    imports[cssModule.key] = resolvedCssExports.get(cssModule.key) ?? cssModule.exports;
+  }
+  for (const module of collected.modules) {
+    defineLazyModule(imports, module.primaryKeys, module.directoryKey ? [module.directoryKey] : [], () => moduleRunFor(module));
+  }
+  if (collected.entry) {
+    // The entry's keys and the hidden ENTRY_EXPORTS_KEY point at ONE exports object
+    // (claimed only where no extra took the key), so the rendered entry and any
+    // extra that imports it share a single evaluation.
+    const mainExports = {};
+    imports[ENTRY_EXPORTS_KEY] = mainExports;
+    for (const key of collected.entry.primaryKeys) {
+      if (!Object.prototype.hasOwnProperty.call(imports, key)) {
+        imports[key] = mainExports;
+      }
+    }
+  }
+  return {
+    imports,
+    css: styleSheets.join('\n'),
+    nested: collected.nested,
+    runnerCode
+  };
+}
+
+/**
+ * Builds the runner scope from a variant's extra files (and optionally the main
+ * source). {@link collectSources} plans the registry keys (pure); each JS/TS file
+ * is then transpiled — relative imports rewritten + sucrase — by `transpile`, which
+ * runs off the main thread in a Web Worker (with a main-thread async fallback); CSS
+ * is scoped + autoprefixed by PostCSS (dynamically imported, off the main bundle).
+ * The compiled files are assembled into a lazy, circular-safe `import` registry,
+ * with cross-file `composes ... from` resolved across the variant's CSS modules.
+ *
+ * Per-file transpilation is cached by object identity, so editing one file only
+ * re-transpiles that file; a broken but UNUSED file is harmless (its error is thrown
+ * only if required). The main source (when provided) is returned transpiled as
+ * `runnerCode` for the runner to evaluate.
+ */
+export async function buildScope({
+  extraFiles,
+  externals,
+  mainCode,
+  transpile,
+  signal,
+  mainName
+}) {
+  const collected = collectSources(extraFiles, mainCode, mainName);
+
+  // Transpile the entry and every module concurrently, off the main thread. The
+  // entry's transpile error rejects this build (there's nothing to render); module
+  // errors are deferred inside `transpileModule` (thrown only if required).
+  const [runnerCode] = await Promise.all([collected.entry ? transpile(collected.entry.source, {
+    fileName: collected.entry.fileName,
+    nested: collected.nested,
+    normalize: true
+  }, signal) : Promise.resolve(undefined), Promise.all(collected.modules.map(module => transpileModule(module, collected.nested, transpile, signal))), Promise.all(collected.styles.map(style => compileStyleExtra(style, signal)))]);
+  return assembleScope(collected, runnerCode, externals);
+}

package/useDemoController/collectSources.d.mts

@@ -0,0 +1,67 @@
+import type { ControlledVariantExtraFiles } from '@mui/internal-docs-infra/CodeHighlighter/types';
+/** Name the main source is registered + resolved under (it lives at the demo root). */
+export declare const MAIN_SOURCE_NAME = "index.tsx";
+/** A JS/TS extra file to register, with the specifiers it answers to. */
+export interface CollectedModule {
+  /** The extra-file object — used as the per-file transpile-cache key (identity). */
+  file: object;
+  /** Path within the demo (e.g. `dir/util.ts`) — drives absolutize + cache gating. */
+  fileName: string;
+  /** The raw source — absolutized later (in the transpile worker) when `nested`. */
+  source: string;
+  /** Specifiers this module always answers to (its own path). */
+  primaryKeys: string[];
+  /** Directory specifier an `index` file also answers to — claimed only if free. */
+  directoryKey?: string;
+}
+/** A CSS extra file to register + collect. */
+export interface CollectedStyle {
+  /** The extra-file object — used as the per-file compile-cache key (identity). */
+  file: object;
+  fileName: string;
+  source: string;
+  /** Registry key the class map (or empty module) is registered under. */
+  key: string;
+  /** `*.module.css` (scoped, exports a class map) vs a plain global `*.css`. */
+  isModule: boolean;
+}
+/** The main source to render, with the specifiers it answers to. */
+export interface CollectedEntry {
+  /** The raw main source — absolutized + normalized later (in the transpile worker). */
+  source: string;
+  /** The entry's path (the demo root) — used to resolve its relative imports. */
+  fileName: string;
+  /** Specifiers the entry answers to — claimed only if no extra already took them. */
+  primaryKeys: string[];
+}
+export interface CollectedSources {
+  /**
+   * Whether any extra file lives in a subdirectory (its key contains `/`). When
+   * `true`, keys are absolute `<SCOPE_IMPORT_PREFIX><path>` specifiers and every
+   * JS/TS source — including the main one — has its relative imports rewritten
+   * (during transpilation) so they resolve by absolute key.
+   */
+  nested: boolean;
+  modules: CollectedModule[];
+  styles: CollectedStyle[];
+  entry?: CollectedEntry;
+}
+/**
+ * Plans the runner scope from a variant's extra files (and optionally the main
+ * source): the pure, transpile-free half of `buildScope`. It decides each file's
+ * registry keys and detects whether the demo is `nested`, but compiles nothing and
+ * — unlike before — does not rewrite imports: the raw source is carried through so
+ * the absolutize + sucrase transpile can run together off the main thread (see
+ * `transpileSource`). The result is a descriptor list the caller transpiles and
+ * assembles into a registry.
+ *
+ * Keys carry the `storeAt`-mode's leading `./` stripped, so a bare path
+ * (`dir/file.ts`) and an import specifier (`./dir/file.ts`) collapse to the same
+ * key — and a flat `./file.ts` is not mistaken for nested.
+ *
+ * Files are routed by extension: `*.css` become {@link CollectedStyle}s
+ * (`*.module.css` scoped, others global); everything else a {@link CollectedModule}
+ * keyed by its extension-less specifier, its full name, and — for an `index` file —
+ * its directory. Files with a non-string `source` (e.g. `null`) are skipped.
+ */
+export declare function collectSources(extraFiles: ControlledVariantExtraFiles | undefined, mainCode?: string, mainName?: string): CollectedSources;

package/useDemoController/collectSources.mjs

@@ -0,0 +1,92 @@
+import { SCOPE_IMPORT_PREFIX } from "./constants.mjs";
+
+/** Name the main source is registered + resolved under (it lives at the demo root). */
+export const MAIN_SOURCE_NAME = 'index.tsx';
+
+/** A JS/TS extra file to register, with the specifiers it answers to. */
+
+/** A CSS extra file to register + collect. */
+
+/** The main source to render, with the specifiers it answers to. */
+
+/**
+ * The specifiers a JS/TS module answers to: its extension-less path (`dir/util`),
+ * its full name (`dir/util.ts`), and — for an `index` file — its containing
+ * directory (`dir/index.ts` also answers `import './dir'`), each under `prefix`.
+ */
+function moduleKeys(fileName, prefix) {
+  const pathWithoutExtension = fileName.replace(/\.[^.]+$/, '');
+  const primary = [...new Set([`${prefix}${pathWithoutExtension}`, `${prefix}${fileName}`])];
+  if (pathWithoutExtension.endsWith('/index')) {
+    return {
+      primary,
+      directory: `${prefix}${pathWithoutExtension.slice(0, -'/index'.length)}`
+    };
+  }
+  return {
+    primary
+  };
+}
+
+/**
+ * Plans the runner scope from a variant's extra files (and optionally the main
+ * source): the pure, transpile-free half of `buildScope`. It decides each file's
+ * registry keys and detects whether the demo is `nested`, but compiles nothing and
+ * — unlike before — does not rewrite imports: the raw source is carried through so
+ * the absolutize + sucrase transpile can run together off the main thread (see
+ * `transpileSource`). The result is a descriptor list the caller transpiles and
+ * assembles into a registry.
+ *
+ * Keys carry the `storeAt`-mode's leading `./` stripped, so a bare path
+ * (`dir/file.ts`) and an import specifier (`./dir/file.ts`) collapse to the same
+ * key — and a flat `./file.ts` is not mistaken for nested.
+ *
+ * Files are routed by extension: `*.css` become {@link CollectedStyle}s
+ * (`*.module.css` scoped, others global); everything else a {@link CollectedModule}
+ * keyed by its extension-less specifier, its full name, and — for an `index` file —
+ * its directory. Files with a non-string `source` (e.g. `null`) are skipped.
+ */
+export function collectSources(extraFiles, mainCode, mainName = MAIN_SOURCE_NAME) {
+  const entries = Object.entries(extraFiles ?? {}).map(([fileName, file]) => [fileName.replace(/^\.\//, ''), file]);
+  const nested = entries.some(([fileName]) => fileName.includes('/'));
+  const prefix = nested ? SCOPE_IMPORT_PREFIX : './';
+  const modules = [];
+  const styles = [];
+  for (const [fileName, file] of entries) {
+    if (!file || typeof file.source !== 'string') {
+      continue;
+    }
+    if (fileName.endsWith('.css')) {
+      styles.push({
+        file,
+        fileName,
+        source: file.source,
+        key: `${prefix}${fileName}`,
+        isModule: fileName.endsWith('.module.css')
+      });
+      continue;
+    }
+    const keys = moduleKeys(fileName, prefix);
+    modules.push({
+      file,
+      fileName,
+      source: file.source,
+      primaryKeys: keys.primary,
+      directoryKey: keys.directory
+    });
+  }
+  let entry;
+  if (mainCode !== undefined) {
+    entry = {
+      source: mainCode,
+      fileName: mainName,
+      primaryKeys: moduleKeys(mainName, prefix).primary
+    };
+  }
+  return {
+    nested,
+    modules,
+    styles,
+    entry
+  };
+}

package/useDemoController/compileCssModule.d.mts

@@ -0,0 +1,64 @@
+export interface CssModuleOptions {
+  /**
+   * Seed for the generated class-name hash. Defaults to the source itself, so
+   * identical sources hash identically — keeping scoped names stable across
+   * server render, client hydration, and live-edit recompiles.
+   */
+  hashSeed?: string;
+  /**
+   * The file's name, used only to label a `CssSyntaxError` (`name.module.css:L:C`)
+   * so a multi-file demo points at the offending stylesheet.
+   */
+  fileName?: string;
+}
+export interface CompiledCssModule {
+  /** The transformed CSS: class/id/keyframe names scoped, declarations autoprefixed. */
+  css: string;
+  /**
+   * Map of original local name to its scoped name — the module's exports. A
+   * `composes` target is merged in (space-separated). Register it in a runner
+   * scope's `import` map so demo code can resolve
+   * `import styles from './styles.module.css'` to `styles.button` etc.
+   *
+   * A cross-file `composes ... from` leaves an opaque placeholder token in the
+   * value (see {@link imports}); the caller resolves it against the sibling.
+   */
+  exports: Record<string, string>;
+  /**
+   * Cross-file `composes ... from "./other"` requests this single-file compile
+   * cannot resolve: `{ './other': { '<placeholder>': 'originalName' } }`. The
+   * placeholder also appears in {@link exports}; resolving it (swapping the token
+   * for the sibling's scoped name) is left to the caller, which has the sibling
+   * modules. Empty for the common, self-contained case.
+   */
+  imports: Record<string, Record<string, string>>;
+}
+/**
+ * Compiles a CSS Modules source string into scoped CSS plus its name exports,
+ * using PostCSS with the same ICSS plugin chain css-loader runs (values →
+ * local-by-default → extract-imports → scope) followed by autoprefixer.
+ *
+ * Each local `.button`/`#id`/`@keyframes`/`@value`/animation name becomes
+ * `name-<hash>` in the CSS and `{ button: 'button-<hash>' }` in
+ * {@link CompiledCssModule.exports}. Full CSS Modules semantics are supported:
+ * `:global()`/`:local()`, same-file `composes`, `@keyframes` + `animation` name
+ * scoping, and `@value`. Cross-file `composes ... from` is surfaced as an
+ * {@link CompiledCssModule.imports} entry for the caller to resolve. Declaration
+ * values, comments, and string contents are preserved; autoprefixer then adds the
+ * vendor prefixes the Baseline Widely Available range still needs.
+ *
+ * The whole PostCSS toolchain is loaded behind a SINGLE dynamic import, so it
+ * ships as one lazy `compileCss` chunk (never in the main bundle) — paid for only
+ * when a demo first compiles CSS. Rejects with a PostCSS `CssSyntaxError` on
+ * malformed input — callers that recompile on every keystroke should catch it and
+ * keep the last good output.
+ */
+export declare function compileCssModule(source: string, options?: CssModuleOptions): Promise<CompiledCssModule>;
+/**
+ * Autoprefixes a plain (non-module) stylesheet for the visitor's browser, without
+ * scoping any selectors — the global-CSS counterpart to {@link compileCssModule}.
+ * Class names pass through verbatim; only the vendor prefixes that browser needs are
+ * added. Shares the same lazy `compileCss` chunk. Rejects on malformed CSS, labelling
+ * the error with `fileName` when given.
+ */
+export declare function prefixCss(source: string, fileName?: string): Promise<string>;

package/useDemoController/compileCssModule.mjs

@@ -0,0 +1,40 @@
+/**
+ * Compiles a CSS Modules source string into scoped CSS plus its name exports,
+ * using PostCSS with the same ICSS plugin chain css-loader runs (values →
+ * local-by-default → extract-imports → scope) followed by autoprefixer.
+ *
+ * Each local `.button`/`#id`/`@keyframes`/`@value`/animation name becomes
+ * `name-<hash>` in the CSS and `{ button: 'button-<hash>' }` in
+ * {@link CompiledCssModule.exports}. Full CSS Modules semantics are supported:
+ * `:global()`/`:local()`, same-file `composes`, `@keyframes` + `animation` name
+ * scoping, and `@value`. Cross-file `composes ... from` is surfaced as an
+ * {@link CompiledCssModule.imports} entry for the caller to resolve. Declaration
+ * values, comments, and string contents are preserved; autoprefixer then adds the
+ * vendor prefixes the Baseline Widely Available range still needs.
+ *
+ * The whole PostCSS toolchain is loaded behind a SINGLE dynamic import, so it
+ * ships as one lazy `compileCss` chunk (never in the main bundle) — paid for only
+ * when a demo first compiles CSS. Rejects with a PostCSS `CssSyntaxError` on
+ * malformed input — callers that recompile on every keystroke should catch it and
+ * keep the last good output.
+ */
+export async function compileCssModule(source, options = {}) {
+  const {
+    compileCssModuleWithPostcss
+  } = await import(/* webpackChunkName: "compileCss" */"./compileCssWithPostcss.mjs");
+  return compileCssModuleWithPostcss(source, options);
+}
+
+/**
+ * Autoprefixes a plain (non-module) stylesheet for the visitor's browser, without
+ * scoping any selectors — the global-CSS counterpart to {@link compileCssModule}.
+ * Class names pass through verbatim; only the vendor prefixes that browser needs are
+ * added. Shares the same lazy `compileCss` chunk. Rejects on malformed CSS, labelling
+ * the error with `fileName` when given.
+ */
+export async function prefixCss(source, fileName) {
+  const {
+    prefixCssWithPostcss
+  } = await import(/* webpackChunkName: "compileCss" */"./compileCssWithPostcss.mjs");
+  return prefixCssWithPostcss(source, fileName);
+}

package/useDemoController/compileCssWithPostcss.d.mts

@@ -0,0 +1,17 @@
+import type { CompiledCssModule, CssModuleOptions } from "./compileCssModule.mjs";
+/**
+ * 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 declare function compileCssModuleWithPostcss(source: string, options?: CssModuleOptions): Promise<CompiledCssModule>;
+/** The PostCSS implementation behind `prefixCss` — {@link lowerModernCss} + autoprefix, no scoping. */
+export declare function prefixCssWithPostcss(source: string, fileName?: string): Promise<string>;