fix(playground): defer loading of large emitters until selected (#11508)

Fixes #11506

## Problem

`typespec.io/playground` hangs forever on iOS. The standalone playground
(`cadlplayground.z22.web.core.windows.net`) works fine.

The difference:
`website/src/components/playground-component/import-map.ts` adds
`@typespec/http-client-python` and `@typespec/http-client-csharp` to the
website's import map, and `browser-host.ts` eagerly `import()`s
**every** library in the map at startup — before the user has picked an
emitter.

`@typespec/http-client-python` boots a full Pyodide (CPython/WASM)
runtime as a module-level side effect, which alone pulls ~23 MB of extra
payload and ~270 MB of resident memory.

Measured with Playwright WebKit under iPhone 15 emulation (`ps` RSS of
the `WebKit.WebContent` process):

| Page | RSS |
| --- | --- |
| typespec.io home | 195 MB |
| standalone playground (works on real iPhone) | 547 MB |
| typespec.io/playground?version=1.13.x (no extra emitters — **works on
real iPhone**) | 463 MB |
| typespec.io/playground (as shipped — **hangs on real iPhone**) | 741
MB |

## Fix

Add a `deferredEmitters` option. Libraries named there are registered as
placeholder entries at startup (so they still show up in the emitter
dropdown) and are only imported when a compilation actually needs them —
i.e. when they're the selected emitter or listed under `emit` in the
tspconfig.

The website passes the two heavy client emitters. Nothing is downloaded
or evaluated for them until you select one.

Caveat, documented on the option: a deferred library can't be referenced
by an `import` statement in TypeSpec source. That's fine for these two —
they're pure emitters with no decorators or `.tsp` surface.

## Relation to #11507

#11507 makes the Pyodide boot
lazy inside the Python emitter. That's the right fix at the source, but
the website resolves emitter bundles at **runtime** from blob storage
(`typespec.blob.core.windows.net/pkgs/<name>/latest.json`), uploaded by
a separate ADO stage. So it can't take effect — or be validated in a PR
preview — until the emitter is republished. This PR fixes the site
independently of that, and also cuts startup cost for the C# emitter.

## Tests

- `packages/playground/test/browser-host-deferred.test.ts` — deferral,
exclusion from the virtual `package.json` dependencies, load-once
memoization, retry after a failed load, no-op for non-deferred libs.
- `packages/playground/test/deferred-emitter-compile.test.ts` —
end-to-end against the **real** compiler: compiling with a deferred
emitter fails to resolve it, then succeeds and writes its output after
`loadLibrary()`.

Full playground suite: 55/55 green. `tsc --noEmit` clean for
`packages/playground` and `website/src`.

## Not fixed here

Monaco web workers fail to start on typespec.io on desktop *and* mobile
(`Could not create web worker(s). Falling back to loading web worker
code in main thread`) — `MonacoEnvironment.getWorker` isn't defined.
Pre-existing and unrelated to the hang, but worth a follow-up:
everything currently runs on the main thread.

## Why this is an opt-in list rather than "defer every emitter"

`isEmitter` comes from `$lib.emitter`, which only exists once the bundle
has been evaluated. Neither the blob index (`latest.json` is just
`{version, imports}`) nor `package.json` carries an emitter marker, so
there is no way to populate the emitter dropdown without importing every
candidate. Deferring everything would leave the dropdown empty.

Deferring *all* emitters would also break the ones that ship TypeSpec
surface — `@typespec/openapi3` (`lib/decorators.tsp`),
`@typespec/json-schema`, `@typespec/protobuf` — since an `import
"@typespec/json-schema";` in the editor would fail to resolve before the
emitter is ever selected. `http-client-python` and `http-client-csharp`
are the only two in the map that are pure emitters with no `.tsp`.

The payoff is also concentrated in those two: with pyodide blocked the
page sits at 474 MB vs 463 MB for `?version=1.13.x` (which loads no
additional packages at all), so everything else the website pulls in
eagerly — including the ~7 Azure libraries that `http-client-python`'s
import map drags along — is only ~11 MB combined.

Possible follow-up, not done here: the host's `readFile`/`stat` are
async, so a miss under `node_modules/<deferred-lib>/` could trigger the
load mid-resolution. That would remove the "cannot be referenced by an
`import` statement" restriction and make the list safe to expand without
auditing each library.

Author: timotheeguerin

.chronus/changes/defer-playground-emitter-loading-2026-7-31-10-30-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/playground"
+---
+
+Add support for deferring the loading of emitter libraries until they are selected. Configure with the new `deferredEmitters` option to avoid downloading and evaluating large emitters on startup.

packages/playground/src/browser-host.ts

@@ -12,6 +12,12 @@ export function resolveVirtualPath(path: string, ...paths: string[]) {
 export interface BrowserHostCreateOptions {
   readonly compiler: typeof import("@typespec/compiler");
   readonly libraries: Record<string, PlaygroundTspLibrary & { _TypeSpecLibrary_: any }>;
+
+  /**
+   * Libraries that are known to the playground but have not been imported yet, keyed by name.
+   * Each entry imports the library when called. See {@link BrowserHost.loadLibrary}.
+   */
+  readonly deferredLibraries?: Record<string, () => Promise<LoadedPlaygroundTspLibrary>>;
 }
 
 /**
@@ -21,10 +27,24 @@ export function createBrowserHostInternal(options: BrowserHostCreateOptions): Br
   const virtualFs = new Map<string, string>();
   const jsImports = new Map<string, Promise<any>>();
 
-  const libraries: Record<string, PlaygroundTspLibrary & { _TypeSpecLibrary_: any }> = {
+  const libraries: Record<string, PlaygroundTspLibrary & { _TypeSpecLibrary_?: any }> = {
     ...options.libraries,
   };
 
+  const deferredLoaders = new Map(Object.entries(options.deferredLibraries ?? {}));
+  const pendingLoads = new Map<string, Promise<void>>();
+
+  for (const name of deferredLoaders.keys()) {
+    // A placeholder keeps the emitter visible in the UI (dropdown, settings) without paying the
+    // cost of importing it. It is replaced by the real library on the first `loadLibrary` call.
+    libraries[name] = {
+      name,
+      isEmitter: true,
+      deferred: true,
+      packageJson: { name, version: "" } as any,
+    };
+  }
+
   function registerLibraryFiles(
     libName: string,
     lib: PlaygroundTspLibrary & { _TypeSpecLibrary_: any },
@@ -43,13 +63,42 @@ export function createBrowserHostInternal(options: BrowserHostCreateOptions): Br
       JSON.stringify({
         name: "playground-pkg",
         dependencies: Object.fromEntries(
-          Object.values(libraries).map((x) => [x.name, x.packageJson.version]),
+          // Deferred libraries have no files registered yet, so listing them would make the
+          // compiler resolve a dependency it cannot read.
+          Object.values(libraries)
+            .filter((x) => !x.deferred)
+            .map((x) => [x.name, x.packageJson.version]),
         ),
       }),
     );
   }
 
-  for (const [libName, lib] of Object.entries(libraries)) {
+  function loadLibrary(name: string): Promise<void> {
+    const loader = deferredLoaders.get(name);
+    if (loader === undefined) {
+      return Promise.resolve();
+    }
+    let pending = pendingLoads.get(name);
+    if (pending === undefined) {
+      pending = loader().then(
+        (lib) => {
+          libraries[name] = lib;
+          registerLibraryFiles(name, lib);
+          updatePackageJson();
+          deferredLoaders.delete(name);
+        },
+        (error) => {
+          // Drop the cached promise so a later compilation can retry after a transient failure.
+          pendingLoads.delete(name);
+          throw error;
+        },
+      );
+      pendingLoads.set(name, pending);
+    }
+    return pending;
+  }
+
+  for (const [libName, lib] of Object.entries(options.libraries)) {
     registerLibraryFiles(libName, lib);
   }
   updatePackageJson();
@@ -61,6 +110,7 @@ export function createBrowserHostInternal(options: BrowserHostCreateOptions): Br
   return {
     compiler: options.compiler,
     libraries,
+    loadLibrary,
     async readUrl(url: string) {
       const contents = virtualFs.get(url);
       if (contents === undefined) {
@@ -183,6 +233,28 @@ export function createBrowserHostInternal(options: BrowserHostCreateOptions): Br
   };
 }
 
+/**
+ * A library that has been imported, along with the raw bundle payload used to populate the
+ * in-memory file system.
+ * @internal
+ */
+export type LoadedPlaygroundTspLibrary = PlaygroundTspLibrary & { _TypeSpecLibrary_: any };
+
+async function importPlaygroundLibrary(
+  libName: string,
+  importOptions: LibraryImportOptions,
+): Promise<LoadedPlaygroundTspLibrary> {
+  const { _TypeSpecLibrary_, $lib, $linter } = (await importLibrary(libName, importOptions)) as any;
+  return {
+    name: libName,
+    isEmitter: $lib?.emitter,
+    definition: $lib,
+    packageJson: JSON.parse(_TypeSpecLibrary_.typespecSourceFiles["package.json"]),
+    linter: $linter,
+    _TypeSpecLibrary_,
+  };
+}
+
 /**
  * Load libraries in parallel from the given list.
  * @param libsToLoad List of library names. Must be available in the webpage importmap.
@@ -191,43 +263,73 @@ export function createBrowserHostInternal(options: BrowserHostCreateOptions): Br
 export async function loadLibraries(
   libsToLoad: readonly string[],
   importOptions: LibraryImportOptions = {},
-): Promise<Record<string, PlaygroundTspLibrary & { _TypeSpecLibrary_: any }>> {
+): Promise<Record<string, LoadedPlaygroundTspLibrary>> {
   const entries = await Promise.all(
     libsToLoad.map(async (libName) => {
-      const { _TypeSpecLibrary_, $lib, $linter } = (await importLibrary(
-        libName,
-        importOptions,
-      )) as any;
-      const lib: PlaygroundTspLibrary & { _TypeSpecLibrary_: any } = {
-        name: libName,
-        isEmitter: $lib?.emitter,
-        definition: $lib,
-        packageJson: JSON.parse(_TypeSpecLibrary_.typespecSourceFiles["package.json"]),
-        linter: $linter,
-        _TypeSpecLibrary_,
-      };
-      return [libName, lib] as const;
+      return [libName, await importPlaygroundLibrary(libName, importOptions)] as const;
     }),
   );
   return Object.fromEntries(entries);
 }
 
+/**
+ * Options for creating the browser host.
+ */
+export interface BrowserHostOptions {
+  /**
+   * Emitters that should not be imported until they are used.
+   *
+   * Importing a library evaluates its module, which for some emitters means downloading a large
+   * runtime up front. Names listed here are shown in the emitter list right away but are only
+   * imported once selected, which keeps the initial load cheap.
+   *
+   * Only use this for pure emitters: a deferred library cannot be referenced by an `import`
+   * statement in the TypeSpec source, since its files are not registered until it is loaded.
+   */
+  readonly deferredEmitters?: readonly string[];
+}
+
+/**
+ * Split the libraries to load into the ones to import now and the ones to import on demand.
+ * @internal
+ */
+export function splitDeferredLibraries(
+  libsToLoad: readonly string[],
+  deferredEmitters: readonly string[] = [],
+): { eager: string[]; deferred: string[] } {
+  const deferredSet = new Set(deferredEmitters);
+  return {
+    eager: libsToLoad.filter((x) => !deferredSet.has(x)),
+    deferred: libsToLoad.filter((x) => deferredSet.has(x)),
+  };
+}
+
 /**
  * Create the browser host from the list of libraries.
  * @param libsToLoad List of libraries to load. Those must be set in the webpage importmap.
  * @param importOptions Import configuration.
+ * @param options Additional host options.
  * @returns
  */
 export async function createBrowserHost(
   libsToLoad: readonly string[],
   importOptions: LibraryImportOptions = {},
+  options: BrowserHostOptions = {},
 ): Promise<BrowserHost> {
+  const { eager, deferred } = splitDeferredLibraries(libsToLoad, options.deferredEmitters);
+
   const [libraries, compiler] = await Promise.all([
-    loadLibraries(libsToLoad, importOptions),
+    loadLibraries(eager, importOptions),
     importTypeSpecCompiler(importOptions),
   ]);
+
+  const deferredLibraries = Object.fromEntries(
+    deferred.map((name) => [name, () => importPlaygroundLibrary(name, importOptions)] as const),
+  );
+
   return createBrowserHostInternal({
     compiler,
     libraries,
+    deferredLibraries,
   });
 }

packages/playground/src/index.ts

@@ -1,4 +1,4 @@
-export { createBrowserHost } from "./browser-host.js";
+export { createBrowserHost, type BrowserHostOptions } from "./browser-host.js";
 export { registerMonacoDefaultWorkersForVite } from "./monaco-worker.js";
 export { registerMonacoLanguage } from "./services.js";
 export { createUrlStateStorage, type StateStorage, type UrlStateStorage } from "./state-storage.js";

packages/playground/src/react/compilation/compile.ts

@@ -18,13 +18,21 @@ export async function compile(
   try {
     const typespecCompiler = host.compiler;
 
+    // Deferred emitters are only imported once they are actually used.
+    if (selectedEmitter) {
+      await host.loadLibrary(selectedEmitter);
+    }
+
     // Resolve the compiler options natively from the tspconfig.yaml so the playground
     // honors the full config (emit, options, linter, imports, warn-as-error, ...).
     const [resolvedOptions] = await typespecCompiler.resolveCompilerOptions(host, {
       cwd: resolveVirtualPath("."),
       entrypoint: resolveVirtualPath("main.tsp"),
     });
 
+    // The tspconfig.yaml can request emitters other than the selected one.
+    await Promise.all((resolvedOptions.emit ?? []).map((name) => host.loadLibrary(name)));
+
     const options: CompilerOptions = {
       ...resolvedOptions,
       options: {

packages/playground/src/react/standalone.tsx

@@ -36,6 +36,12 @@ import {
 export interface ReactPlaygroundConfig extends Partial<PlaygroundProps> {
   readonly libraries: readonly string[];
   readonly importConfig?: LibraryImportOptions;
+  /**
+   * Emitters from {@link libraries} that should only be imported once selected, rather than when
+   * the playground starts. Only valid for pure emitters, which are never referenced by an `import`
+   * statement in the TypeSpec source.
+   */
+  readonly deferredEmitters?: readonly string[];
   /** Content to show while the playground data is loading(Libraries) */
   readonly fallback?: ReactNode;
 }
@@ -51,15 +57,17 @@ function useStandalonePlaygroundContext(
   const [context, setContext] = useState<StandalonePlaygroundContext | undefined>();
   useEffect(() => {
     const load = async () => {
-      const host = await createBrowserHost(config.libraries, config.importConfig);
+      const host = await createBrowserHost(config.libraries, config.importConfig, {
+        deferredEmitters: config.deferredEmitters,
+      });
       await registerMonacoLanguage(host);
 
       const stateStorage = createStandalonePlaygroundStateStorage();
       const initialState = stateStorage.load();
       setContext({ host, initialState, stateStorage });
     };
     void load();
-  }, [config.importConfig, config.libraries]);
+  }, [config.importConfig, config.libraries, config.deferredEmitters]);
   return context;
 }
 

packages/playground/src/types.ts

@@ -33,9 +33,23 @@ export interface PlaygroundTspLibrary {
   isEmitter: boolean;
   definition?: TypeSpecLibrary<any>;
   linter?: LinterDefinition;
+
+  /**
+   * Whether the library module has been declared but not imported yet.
+   *
+   * Deferred emitters are only imported the first time they are used, so their `definition`,
+   * `linter` and `packageJson` are placeholders until then.
+   */
+  deferred?: boolean;
 }
 
 export interface BrowserHost extends CompilerHost {
   compiler: typeof import("@typespec/compiler");
   libraries: Record<string, PlaygroundTspLibrary>;
+
+  /**
+   * Import a library that was registered as a deferred emitter and make its files available to the
+   * compiler. Resolves immediately for libraries that are already loaded.
+   */
+  loadLibrary(name: string): Promise<void>;
 }