fix(http-client-python): boot pyodide lazily in the browser

.chronus/changes/lazy-browser-pyodide-2026-7-31-9-30-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Only boot the Pyodide runtime in the browser on the first emit instead of when the emitter module is imported. Hosts such as the TypeSpec playground import every available emitter up front, so the eager bootstrap downloaded a full CPython WebAssembly runtime and its wheels on every page load, which prevented the page from loading on mobile browsers.

packages/http-client-python/emitter/src/emitter.ts

@@ -223,7 +223,7 @@ async function onEmitMain(context: EmitContext<PythonEmitterOptions>) {
 
   if (typeof window !== "undefined") {
     // Running in browser with Pyodide - fileURLToPath and other filesystem operations are browser-incompatible
-    const pyodide = await browserPyodidePromise;
+    const pyodide = await getBrowserPyodide();
 
     if (!pyodide) {
       reportDiagnostic(program, {
@@ -253,8 +253,29 @@ async function onEmitMain(context: EmitContext<PythonEmitterOptions>) {
   }
 }
 
-const browserPyodidePromise: Promise<PyodideInterface> | null =
-  typeof window !== "undefined" ? setupPyodideCallBrowser() : null;
+let browserPyodidePromise: Promise<PyodideInterface> | undefined;
+
+/**
+ * Boot the Pyodide runtime lazily, on the first browser emit.
+ *
+ * This must not happen when the module is imported: hosts like the TypeSpec playground import every
+ * available emitter up front, and booting Pyodide downloads a full CPython WebAssembly runtime plus
+ * its wheels (~10MB, ~290MB of resident memory). Doing that eagerly pushed the playground past the
+ * per-tab memory budget on mobile browsers, which made the page fail to load.
+ */
+function getBrowserPyodide(): Promise<PyodideInterface> | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  if (browserPyodidePromise === undefined) {
+    browserPyodidePromise = setupPyodideCallBrowser().catch((error) => {
+      // Clear the cached promise so a later emit can retry after a transient failure.
+      browserPyodidePromise = undefined;
+      throw error;
+    });
+  }
+  return browserPyodidePromise;
+}
 
 function clearMemfsDirectory(pyodide: PyodideInterface, dir: string): void {
   const entries: string[] = pyodide.FS.readdir(dir).filter(

packages/http-client-python/emitter/test/browser-pyodide.test.ts

@@ -0,0 +1,25 @@
+import { strictEqual } from "assert";
+import { afterEach, describe, it, vi } from "vitest";
+
+const loadPyodide = vi.hoisted(() => vi.fn());
+
+vi.mock("../src/pyodide-loader.js", () => ({ loadPyodide }));
+
+describe("typespec-python: browser pyodide bootstrap", () => {
+  afterEach(() => {
+    delete (globalThis as any).window;
+    loadPyodide.mockReset();
+    vi.resetModules();
+  });
+
+  // Hosts like the TypeSpec playground import every available emitter up front. Booting Pyodide at
+  // module scope downloaded a full CPython WebAssembly runtime on every page load, which pushed the
+  // page past the per-tab memory budget on mobile browsers and prevented it from loading.
+  it("does not boot pyodide when the emitter is imported in a browser", async () => {
+    (globalThis as any).window = globalThis;
+
+    await import("../src/emitter.js");
+
+    strictEqual(loadPyodide.mock.calls.length, 0);
+  });
+});