Pyodide Phase 1: run the real clarifying loop in the playground (#8)

Add a "Run real Python" toggle to the playground for the clarifying-question
scenario. When enabled, the page lazily boots Pyodide, unpacks the pir bundle,
and runs the unmodified examples/embodied_ai/35_clarifying_question.py loop
headless (numpy only, matplotlib blocked). The real Trace is serialized into the
exact config the existing JS renderer consumes, so the browser draws real Python
output instead of the JS reimplementation.

The JS preview stays the default first paint — Pyodide loads only on toggle — so
the instant experience is preserved. Deleting the JS clarifying dynamics is
deliberately deferred until the real path is the verified default (noted in the
design memo).

- pir/viz/playground_trace.py: pure-Python, JSON-friendly Trace -> playground
  serializer (no numpy/matplotlib), runnable in CPython and Pyodide alike.
- tests/test_playground_trace.py: pins the trace->render JSON contract (every
  field the renderer reads, plain-JSON, real ask->look->pick outcome).
- build_pyodide_bundle.py: bundle 35_clarifying_question.py too; rebuilt zip.
- Verified the exact browser driver's Python path in CPython (unpack-into-cwd
  sim): answer=red yields the real ambiguous_goal->resolved->pick at [32,56].

Browser check still pending (boot Pyodide + redraw from the real trace).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rsasaki0109

docs/playground.css

@@ -138,6 +138,17 @@ button:disabled {
   min-height: 1.25rem;
 }
 
+.real-status {
+  color: var(--ink-soft, #5a6b67);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.82rem;
+  min-height: 1.1rem;
+}
+
+.real-status.real-error {
+  color: #b5482f;
+}
+
 .status-strip {
   display: grid;
   gap: 10px;

docs/playground.html

@@ -65,6 +65,10 @@ <h1 id="playground-title">Playground</h1>
               <span>Compare</span>
               <input id="compareToggle" type="checkbox">
             </label>
+            <label class="toggle-label">
+              <span>Run real Python</span>
+              <input id="realPythonToggle" type="checkbox">
+            </label>
             <div class="button-row">
               <button id="resetButton" type="button">Reset</button>
               <button id="stepButton" type="button">Step</button>
@@ -74,6 +78,7 @@ <h1 id="playground-title">Playground</h1>
             </div>
           </div>
           <div id="copyStatus" class="copy-status" aria-live="polite"></div>
+          <div id="realStatus" class="real-status" aria-live="polite"></div>
 
           <div class="status-strip" aria-label="Current simulation state">
             <div>
@@ -129,6 +134,7 @@ <h2 id="trace-title">Trace</h2>
       </section>
     </main>
 
+    <script src="https://cdn.jsdelivr.net/pyodide/v0.27.2/full/pyodide.js"></script>
     <script src="playground.js"></script>
   </body>
 </html>

docs/playground.js

@@ -45,6 +45,8 @@
     answer: document.getElementById("answerSelect"),
     failureFilter: document.getElementById("failureFilter"),
     compare: document.getElementById("compareToggle"),
+    realPython: document.getElementById("realPythonToggle"),
+    realStatus: document.getElementById("realStatus"),
     reset: document.getElementById("resetButton"),
     step: document.getElementById("stepButton"),
     run: document.getElementById("runButton"),
@@ -72,16 +74,13 @@
   let copyStatusTimer = null;
 
   elements.scenario.addEventListener("change", () => {
-    stopRun();
-    state = buildState();
-    updateLocation(false);
-    render();
+    if (elements.scenario.value !== "clarifying") {
+      elements.realPython.checked = false;
+    }
+    rebuild();
   });
   elements.answer.addEventListener("change", () => {
-    stopRun();
-    state = buildState();
-    updateLocation(false);
-    render();
+    rebuild();
   });
   elements.failureFilter.addEventListener("change", () => {
     updateLocation(false);
@@ -91,15 +90,15 @@
     updateLocation(false);
     render();
   });
+  elements.realPython.addEventListener("change", () => {
+    rebuild();
+  });
   elements.replay.addEventListener("input", () => {
     state.replayIndex = clampReplayIndex(elements.replay.value);
     render();
   });
   elements.reset.addEventListener("click", () => {
-    stopRun();
-    state = buildState();
-    updateLocation(false);
-    render();
+    rebuild();
   });
   elements.step.addEventListener("click", () => {
     stepOnce();
@@ -123,23 +122,127 @@
     window.setTimeout(startRun, 180);
   }
 
-  function buildState() {
+  function buildState(realConfig) {
     const scenario = elements.scenario.value;
     const answer = elements.answer.value;
-    const config =
-      scenario === "household"
-        ? buildHouseholdScenario(answer)
-        : buildClarifyingScenario(answer);
+    let config;
+    let source;
+    if (realConfig) {
+      config = realConfig;
+      source = "python";
+    } else {
+      config =
+        scenario === "household"
+          ? buildHouseholdScenario(answer)
+          : buildClarifyingScenario(answer);
+      source = "js";
+    }
     return {
       scenario,
       answer,
       config,
+      source,
       index: 0,
       trace: [],
       replayIndex: null,
     };
   }
 
+  // Rebuild the playground state, honoring the "Run real Python" toggle. When the
+  // toggle is on (clarifying only), we lazily boot Pyodide and run the actual
+  // examples/embodied_ai/35_clarifying_question.py loop, then draw its real trace.
+  // Otherwise we use the instant JS preview so first paint never waits on Pyodide.
+  async function rebuild() {
+    stopRun();
+    const useReal =
+      elements.realPython.checked && elements.scenario.value === "clarifying";
+    if (useReal) {
+      setRealStatus("booting Pyodide + running real Python…");
+      try {
+        const config = await fetchRealClarifyingConfig(elements.answer.value);
+        state = buildState(config);
+        setRealStatus(
+          "running real Python: examples/embodied_ai/35_clarifying_question.py"
+        );
+      } catch (error) {
+        elements.realPython.checked = false;
+        state = buildState();
+        setRealStatus("Pyodide failed (" + error + ") — showing JS preview", true);
+      }
+    } else {
+      state = buildState();
+      setRealStatus("");
+    }
+    updateLocation(false);
+    render();
+  }
+
+  function setRealStatus(message, isError) {
+    if (!elements.realStatus) {
+      return;
+    }
+    elements.realStatus.textContent = message || "";
+    elements.realStatus.classList.toggle("real-error", Boolean(isError));
+  }
+
+  // --- Real Python in the browser (Pyodide), lazy-loaded on first use ---------
+  let pyodideReadyPromise = null;
+  const realConfigCache = {};
+
+  async function ensurePyodide() {
+    if (pyodideReadyPromise) {
+      return pyodideReadyPromise;
+    }
+    pyodideReadyPromise = (async () => {
+      // eslint-disable-next-line no-undef
+      const pyodide = await loadPyodide({
+        indexURL: "https://cdn.jsdelivr.net/pyodide/v0.27.2/full/",
+      });
+      await pyodide.loadPackage("numpy");
+      const buffer = await (await fetch("./pyodide/pir_bundle.zip")).arrayBuffer();
+      await pyodide.unpackArchive(buffer, "zip");
+      return pyodide;
+    })();
+    return pyodideReadyPromise;
+  }
+
+  // Runs the unmodified example headless and serializes its Trace with the same
+  // pir.viz.playground_trace helper that tests/test_playground_trace.py pins.
+  // ANSWER is replaced with a JSON string literal before execution.
+  const CLARIFYING_DRIVER = [
+    "import json, os, sys, importlib.util",
+    "cwd = os.getcwd()",
+    "if cwd not in sys.path:",
+    "    sys.path.insert(0, cwd)",
+    "class _NoMatplotlib:",
+    "    def find_spec(self, name, path=None, target=None):",
+    "        if name == 'matplotlib' or name.startswith('matplotlib.'):",
+    "            raise ImportError('matplotlib is intentionally unavailable on the headless browser path')",
+    "        return None",
+    "sys.meta_path.insert(0, _NoMatplotlib())",
+    "path = os.path.join(cwd, 'examples', 'embodied_ai', '35_clarifying_question.py')",
+    "spec = importlib.util.spec_from_file_location('clarifying_question', path)",
+    "mod = importlib.util.module_from_spec(spec)",
+    "spec.loader.exec_module(mod)",
+    "from pir.viz.playground_trace import clarifying_trace_to_playground",
+    "answer = ANSWER",
+    "trace = mod.run(command='pick the block', answer=answer, render=False)",
+    "json.dumps(clarifying_trace_to_playground(trace, command='pick the block', answer=answer))",
+  ].join("\n");
+
+  async function fetchRealClarifyingConfig(answer) {
+    const cacheKey = "clarifying:" + answer;
+    if (realConfigCache[cacheKey]) {
+      return realConfigCache[cacheKey];
+    }
+    const pyodide = await ensurePyodide();
+    const code = CLARIFYING_DRIVER.replace("ANSWER", JSON.stringify(answer));
+    const json = await pyodide.runPythonAsync(code);
+    const config = JSON.parse(json);
+    realConfigCache[cacheKey] = config;
+    return config;
+  }
+
   function stepOnce() {
     if (state.index >= state.config.steps.length) {
       render();
@@ -626,6 +729,7 @@
     elements.run.disabled = state.index >= state.config.steps.length && !timer;
     elements.copyTrace.disabled = state.trace.length === 0;
     elements.compare.disabled = state.scenario !== "household";
+    elements.realPython.disabled = state.scenario !== "clarifying";
 
     renderReplay(replayIndex);
     renderCompare();

docs/pyodide/pir_bundle.zip

@@ -101,10 +101,33 @@ that `loadPyodide`/`unpackArchive`/`fetch` behave as expected. Open
 `docs/pyodide/poc.html` via a local server (e.g. `python3 -m http.server` from
 `docs/`) or on GitHub Pages and click “Run the real loop”.
 
-**Phase 1 — one real loop on the page (1–2 days).** Add a "Run real Python"
-toggle to the existing playground for `clarifying_question` (its renderer already
-exists). Python produces the trace; JS draws it; delete the JS dynamics for that
-scenario. This is the first honest "real Python in your browser" claim.
+**Phase 1 — one real loop on the page. ✅ built (Python path verified; needs a
+browser check).** The playground ([`docs/playground.html`](playground.html))
+has a **"Run real Python"** toggle for `clarifying_question`. When on, it lazily
+boots Pyodide, unpacks the bundle, and runs the **unmodified**
+`examples/embodied_ai/35_clarifying_question.py` `run(...)` headless; the real
+`Trace` is serialized by [`pir/viz/playground_trace.py`](../pir/viz/playground_trace.py)
+into the exact config the existing JS renderer consumes, and the page draws that.
+The JS preview stays the default first paint (Pyodide is loaded only on toggle),
+so the instant experience is preserved.
+
+The trace→render JSON is now a **pinned contract**:
+[`tests/test_playground_trace.py`](../tests/test_playground_trace.py) runs the
+real loop, serializes it, and asserts every field the renderer reads is present
+and plain-JSON (no numpy leaks) — exactly the drift guard the risk list calls for.
+
+Verified locally (CPython simulating Pyodide's unpack-into-cwd, the exact driver
+from `playground.js`): for `answer=red` the serializer returns the real
+`ask → look → pick` trace (`ambiguous_goal` then resolved belief, pick at
+`[32, 56]`), identical to the CLI loop. **Still to confirm in a real browser:**
+toggling "Run real Python" boots Pyodide, runs the loop, and the scene/belief/
+timeline redraw from the real trace.
+
+Deliberately **deferred** (not yet done): deleting the JS `buildClarifyingScenario`
+dynamics. It is kept as the no-Pyodide instant fallback so first paint never waits
+on a multi-MB download. Full deletion waits until the real path is the verified
+default — at which point the JS mock can be dropped and the contract test becomes
+the single source of truth.
 
 **Phase 2 — tabletop renderer + hero loop (1–2 days).** Add the continuous
 tabletop renderer and wire `pick_and_retry`. Now the README hero GIF has a