From 2a660d38403e684f818b1568f586af5129cb9a3d Mon Sep 17 00:00:00 2001
From: Timothee Guerin <tiguerin@microsoft.com>
Date: Fri, 31 Jul 2026 09:29:13 -0400
Subject: [PATCH] fix(http-client-python): boot pyodide lazily in the browser

The browser bootstrap ran as a module-level side effect, so simply importing
the emitter downloaded a full CPython WebAssembly runtime and micropip-installed
its wheels from PyPI.

Hosts like the TypeSpec playground import every library in the import map up
front, so this happened on every page load. Measured on typespec.io/playground
(WebKit, iPhone emulation) it added ~290MB of resident memory (463MB -> 752MB)
and ~8MB of downloads, pushing the tab past the per-tab memory budget on mobile
browsers and preventing the playground from loading.

Boot pyodide on the first emit instead, and drop the cached promise when the
bootstrap fails so a later emit can retry.

Fixes microsoft/typespec#11506
---
 .../lazy-browser-pyodide-2026-7-31-9-30-0.md  |  7 +++++
 .../http-client-python/emitter/src/emitter.ts | 27 ++++++++++++++++---
 .../emitter/test/browser-pyodide.test.ts      | 25 +++++++++++++++++
 3 files changed, 56 insertions(+), 3 deletions(-)
 create mode 100644 .chronus/changes/lazy-browser-pyodide-2026-7-31-9-30-0.md
 create mode 100644 packages/http-client-python/emitter/test/browser-pyodide.test.ts

diff --git a/.chronus/changes/lazy-browser-pyodide-2026-7-31-9-30-0.md b/.chronus/changes/lazy-browser-pyodide-2026-7-31-9-30-0.md
new file mode 100644
index 00000000000..93aab4abd24
--- /dev/null
+++ b/.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.
diff --git a/packages/http-client-python/emitter/src/emitter.ts b/packages/http-client-python/emitter/src/emitter.ts
index 9e0489ee2e3..0609c70054f 100644
--- a/packages/http-client-python/emitter/src/emitter.ts
+++ b/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(
diff --git a/packages/http-client-python/emitter/test/browser-pyodide.test.ts b/packages/http-client-python/emitter/test/browser-pyodide.test.ts
new file mode 100644
index 00000000000..09bad2b8471
--- /dev/null
+++ b/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);
+  });
+});