site: one shared compiler+Python runtime across pages, warmed in the background (#2)

The runnable-block worker is now a SharedWorker where supported (dedicated
per-page worker as fallback, with in-flight replay if shared mode errors),
so open tabs and the playground share a single live compiler and Pyodide
instance; runs serialize inside the worker since pages share one
interpreter. A SharedWorker still dies with its last page, so a same-tab
navigation restarts it: for visitors who have used Run before (a
localStorage flag), every page now warms the worker in the background at
load, and the runtime is ready by the time they click. The docs widget also
compiles inside the worker now, so lesson pages load no WASM on the main
thread at all. Measured on lesson pages: first-ever run ~6.6s with the
honest progress message; after a same-tab navigation ~1.0s (was ~6.3s);
second tab ~0.6s; same-page rerun ~0.8s.

Author: simontreanor

docs/theme/docs-run.js

@@ -20,17 +20,24 @@
   }
   var playgroundBase = new URL(root + "playground/", location.href).href;
 
-  var compilerPromise = null;
+  // Everything heavy (the compiler WASM and the Python runtime) lives in the worker
+  // behind createRunner: a SharedWorker where supported, so open tabs share one
+  // runtime. A same-tab navigation still restarts it (a SharedWorker dies with its
+  // last page), so for visitors who have used Run before, plumbing() is called at
+  // page load below and the runtime boots in the background while they read.
+  var runnerPromise = null;
   var runner = null;
+  var mod = null;
 
   function plumbing() {
-    if (!compilerPromise) {
-      compilerPromise = import(playgroundBase + "pyfun-run.js").then(function (mod) {
-        runner = mod.createRunner(playgroundBase);
-        return mod.loadCompiler(playgroundBase);
+    if (!runnerPromise) {
+      runnerPromise = import(playgroundBase + "pyfun-run.js").then(function (m) {
+        mod = m;
+        runner = m.createRunner(playgroundBase);
+        return runner;
       });
     }
-    return compilerPromise;
+    return runnerPromise;
   }
 
   function attach(code) {
@@ -71,20 +78,22 @@
       out.className = "pyfun-run-out";
       out.textContent = runner && runner.loaded()
         ? "running…"
-        : "loading the compiler and Python runtime… (first run on a page downloads ~10 MB, then it is cached)";
+        : "starting the compiler and Python runtime… (the first run on the site downloads ~10 MB; every page then shares the same live runtime)";
       btn.disabled = true;
       plumbing()
-        .then(function (compile) {
-          var result = compile(code.textContent);
-          if (!result.ok) {
-            var msgs = result.diagnostics.map(function (d) {
-              return d.severity + ": " + d.message;
-            });
-            out.className = "pyfun-run-out pyfun-run-err";
-            out.textContent = msgs.length ? msgs.join("\n") : "(nothing to compile)";
-            return null;
-          }
-          return runner.run(result.python);
+        .then(function (r) {
+          mod.markRunnerUsed();
+          return r.compile(code.textContent).then(function (result) {
+            if (!result.ok) {
+              var msgs = result.diagnostics.map(function (d) {
+                return d.severity + ": " + d.message;
+              });
+              out.className = "pyfun-run-out pyfun-run-err";
+              out.textContent = msgs.length ? msgs.join("\n") : "(nothing to compile)";
+              return null;
+            }
+            return r.run(result.python);
+          });
         })
         .then(function (res) {
           if (!res) return;
@@ -105,5 +114,22 @@
     });
   }
 
-  document.querySelectorAll("code.language-pyfun").forEach(attach);
+  var blocks = document.querySelectorAll("code.language-pyfun");
+  blocks.forEach(attach);
+
+  // Background warm-up for returning users: if this visitor has clicked Run before,
+  // start the worker now so the runtime is ready by the time they click it here.
+  if (blocks.length > 0) {
+    import(playgroundBase + "pyfun-run.js")
+      .then(function (m) {
+        if (m.runnerWasUsed()) {
+          plumbing().then(function (r) {
+            r.warm();
+          });
+        }
+      })
+      .catch(function () {
+        // No worker, no warm-up; the click path reports real errors.
+      });
+  }
 })();

playground/README.md

@@ -64,10 +64,13 @@ The playground is a normal web page, so record it natively on any OS — no `tty
   resilient `analyze`), as you type.
 - **Runs it.** The **Run** button executes the emitted Python in **CPython itself**,
   compiled to WebAssembly ([Pyodide](https://pyodide.org)), and shows stdout. Pyodide runs
-  in a **Web Worker** (`pyodide-worker.js`), off the main thread, so loading the ~10 MB
-  runtime (lazy, on first Run, then cached) and executing code never freeze the UI. Each run
-  uses a fresh namespace and captures stdout/stderr via a `StringIO` redirect; a Python
-  exception shows its traceback. Programs that only touch the stdlib (`json`, `sqlite3`,
+  in a worker (`pyodide-worker.js`), off the main thread, so loading the ~10 MB runtime
+  (lazy, on first Run) and executing code never freeze the UI. The worker is a
+  **SharedWorker** where supported: one compiler + Python runtime serves this page AND
+  every runnable code block on the docs site, so nothing reloads per page (browsers
+  without module SharedWorkers fall back to a per-page worker; runs are serialized inside
+  the worker since pages share one interpreter). Each run uses a fresh namespace and
+  captures stdout/stderr via a `StringIO` redirect; a Python exception shows its traceback. Programs that only touch the stdlib (`json`, `sqlite3`,
   `math`, `statistics`, `dataclasses`, …) run as-is; an `extern` for a third-party package
   (`numpy`, `requests`) would need `micropip` (not wired up) and network calls don't work in
   the sandbox.

playground/web/app.js

@@ -2,7 +2,7 @@
 // edit, render the emitted Python + diagnostics, and — on demand — run that Python in
 // CPython-via-WebAssembly (Pyodide). The compile/run plumbing lives in pyfun-run.js,
 // shared with the docs site's runnable code blocks.
-import { loadCompiler, createRunner } from "./pyfun-run.js";
+import { loadCompiler, createRunner, markRunnerUsed, runnerWasUsed } from "./pyfun-run.js";
 
 // Assigned in main() once the WASM loads: source -> { ok, python, diagnostics }.
 let compileFn = null;
@@ -269,12 +269,13 @@ const runner = createRunner(import.meta.url);
 
 runBtn.addEventListener("click", async () => {
   if (lastPython === null) return;
+  markRunnerUsed();
   const code = lastPython;
   runOutput.hidden = false;
   runOutput.classList.remove("run-error");
   runOutput.textContent = runner.loaded()
     ? "running…"
-    : "loading Python runtime… (first run downloads ~10 MB, then it's cached)";
+    : "starting Python runtime… (the first run on the site downloads ~10 MB; after that the docs and this page share one live runtime)";
   runBtn.disabled = true;
   try {
     const { out, err } = await runner.run(code);
@@ -303,6 +304,10 @@ window.addEventListener("hashchange", () => {
 });
 
 async function main() {
+  // Returning users get the Python runtime booted in the background so Run is warm.
+  if (runnerWasUsed()) {
+    runner.warm();
+  }
   compileFn = await loadCompiler(import.meta.url);
   editor.value = sourceFromHash() ?? EXAMPLES[0].source;
   render();

playground/web/pyfun-run.js

@@ -14,43 +14,103 @@ export async function loadCompiler(base) {
   return (source) => JSON.parse(mod.compile(source));
 }
 
-// A lazy Pyodide runner. The worker (and Pyodide's ~10 MB runtime) loads on the
-// first run() and is reused after; run() resolves with { out, err }.
+// A lazy runner over pyodide-worker.js. Preferred channel: a SharedWorker, so ONE
+// compiler + Python runtime serves every page on the site (the first run anywhere
+// pays the load; every later page connects to the live instance). Browsers without
+// module SharedWorkers (e.g. Firefox) fall back to a per-page dedicated worker.
+//
+// run(code)      -> Promise<{ out, err }>       execute emitted Python
+// compile(src)   -> Promise<{ ok, python, diagnostics }>   compile Pyfun in the worker
 export function createRunner(base) {
-  let worker = null;
   let seq = 0;
-  const pending = new Map();
-
-  function ensureWorker() {
-    if (!worker) {
-      worker = new Worker(new URL("./pyodide-worker.js", base), { type: "module" });
-      worker.onmessage = (event) => {
-        const { id, out, err } = event.data;
-        const resolve = pending.get(id);
-        if (resolve) {
-          pending.delete(id);
-          resolve({ out, err });
-        }
-      };
-      worker.onerror = (e) => {
-        for (const resolve of pending.values()) {
-          resolve({ out: "", err: "worker failed to start: " + (e.message || e) });
-        }
-        pending.clear();
-      };
+  let post = null;
+  const pending = new Map(); // id -> resolve
+  const inflight = new Map(); // id -> message (replayed if shared mode fails)
+
+  function onMessage(event) {
+    const resolve = pending.get(event.data.id);
+    if (resolve) {
+      pending.delete(event.data.id);
+      inflight.delete(event.data.id);
+      resolve(event.data);
+    }
+  }
+
+  function useDedicated(url) {
+    const w = new Worker(url, { type: "module" });
+    w.onmessage = onMessage;
+    w.onerror = (e) => {
+      for (const resolve of pending.values()) {
+        resolve({ out: "", err: "worker failed to start: " + (e.message || e) });
+      }
+      pending.clear();
+      inflight.clear();
+    };
+    post = (m) => w.postMessage(m);
+  }
+
+  function ensureChannel() {
+    if (post) return;
+    const url = new URL("./pyodide-worker.js", base);
+    if (typeof SharedWorker !== "undefined") {
+      try {
+        const sw = new SharedWorker(url, { type: "module", name: "pyfun-runner" });
+        sw.port.onmessage = onMessage;
+        sw.onerror = () => {
+          // The script failed in shared mode (typically: module SharedWorkers
+          // unsupported). Rebuild as a per-page worker and replay what was queued.
+          useDedicated(url);
+          for (const msg of inflight.values()) post(msg);
+        };
+        sw.port.start();
+        post = (m) => sw.port.postMessage(m);
+        return;
+      } catch {
+        // Constructor refused outright; use the dedicated path below.
+      }
     }
-    return worker;
+    useDedicated(url);
+  }
+
+  function send(msg) {
+    ensureChannel();
+    inflight.set(msg.id, msg);
+    return new Promise((resolve) => {
+      pending.set(msg.id, resolve);
+      post(msg);
+    });
   }
 
   return {
-    loaded: () => worker !== null,
-    run(code) {
-      const w = ensureWorker();
-      const id = ++seq;
-      return new Promise((resolve) => {
-        pending.set(id, resolve);
-        w.postMessage({ id, code });
-      });
-    },
+    loaded: () => post !== null,
+    run: (code) => send({ id: ++seq, code }).then(({ out, err }) => ({ out, err })),
+    compile: (source) =>
+      send({ id: ++seq, source }).then(({ compiled, err }) => {
+        if (!compiled) throw new Error(err || "compiler failed to load");
+        return compiled;
+      }),
+    // Boot the compiler and Python runtime without running anything, so a page can
+    // warm the worker in the background before the user clicks Run.
+    warm: () => send({ id: ++seq, warm: true }),
   };
 }
+
+// The localStorage flag marking that this visitor has used Run before; pages check it
+// to decide whether background-warming the runtime is worth the download/CPU.
+export const WARM_FLAG = "pyfun-runner-used";
+
+export function markRunnerUsed() {
+  try {
+    localStorage.setItem(WARM_FLAG, "1");
+  } catch {
+    // Storage can be unavailable (privacy modes); warming is just an optimization.
+  }
+}
+
+export function runnerWasUsed() {
+  try {
+    return localStorage.getItem(WARM_FLAG) === "1";
+  } catch {
+    return false;
+  }
+}