feat(playground): engine radio (minipy / real Python), Pyodide warmed on open and cached

An "Engine" radio above the editor swaps between the step-through interpreter
(minipy, default) and real Python (Pyodide in a Web Worker); the choice is
remembered. In real-Python mode edits re-run automatically and the output and
figures take the right column. The runtime starts downloading shortly after a
playground opens; the worker keeps everything fetched from the Pyodide base in
Cache Storage, so later visits start from the cache. Runs are serialized (newest
wins), stopped after 15 s, and the worker restarts from the cache. The service
worker no longer deletes the Pyodide cache. Replaces the separate card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: CharlesZhang2023

docs/log.md

@@ -7,6 +7,12 @@
 
 ## 进展时间线
 
+### 2026-10-08 — 实验台引擎切换：逐步演示（minipy）/ 真实 Python（Pyodide）（按用户要求）
+- **feat**：NumPy、matplotlib、pandas 实验台的编辑器上方新增「运行引擎」单选：逐步演示（minipy，默认）或真实 Python（Pyodide，Web Worker）。选真实 Python 后，代码改动后自动在真实库中运行，输出（含版本与耗时）和 matplotlib 图显示在右栏，逐步可视化暂停；选择记在 `knowcs-py-engine`，全站共享。PyTorch、Keras、TensorFlow 中该选项置灰并说明没有浏览器版本。
+- **feat**：打开实验台约 1.2 秒后在后台下载并启动 Python 运行时（省流量模式下不预载）；各包仍按导入按需下载。worker 把从 Pyodide 地址取到的文件（wasm、标准库、lock、各 wheel）存入 Cache Storage（`knowcs-pyodide:<base>`，换版本时清掉旧缓存），再次打开约 1.3 秒就绪。站点 Service Worker 激活时不再删除该缓存。
+- **feat**：同一时间只运行一段代码，新的请求替换排队中的旧请求；单次运行超过 15 秒自动停止（提示是否死循环），worker 随即从缓存重启；运行中可手动停止。
+- **change**：替换上一版的「用真实 Python 运行」卡片。浏览器检查：预载、缓存条目、自动运行、超时与重启、刷新后从缓存启动、matplotlib 出图、PyTorch 置灰，无控制台错误；390 宽无横向滚动，对比度通过。
+
 ### 2026-10-08 — 实验台加「用真实 Python 运行」（Pyodide，按用户要求）
 - **feat**：NumPy、matplotlib、pandas 实验台（实验场页与笔记旁）在输出下方新增「用真实 Python 运行」卡片：点按钮后才在 Web Worker 里加载 Pyodide 314.0.7（CPython 3.14.2），用 `loadPackagesFromImports` 只下载代码导入的包（NumPy 2.4.6、pandas 3.0.2、matplotlib 3.10.8、scikit-learn 1.8.0、SciPy、OpenCV），seaborn 不在内置包里，导入时用 micropip 安装。每次运行用新的命名空间；显示 print、stderr、最后一个表达式的 repr、Python 3.14 的 traceback 和 matplotlib 图（PNG）；可随时停止（直接终止 worker）。minipy 仍是默认引擎，逐步可视化不变；PyTorch、Keras、TensorFlow 没有 Pyodide 版本，不显示该卡片。
 - **config**：资源地址默认 `https://cdn.jsdelivr.net/pyodide/v314.0.7/full/`，构建时可用 `VITE_PYODIDE_BASE` 改为自托管或 COS + CDN（jsDelivr 在内地不稳定，目前未自托管）。首屏不加载任何 Pyodide 资源；首次运行约 7 MB（仅 Python）到 37 MB（含 scikit-learn），浏览器缓存后再次运行约 60 ms。下载失败时提示所用域名。

src/lib/pyodide/client.ts

@@ -1,33 +1,82 @@
-// The page's side of real Python: one shared worker, started on the first run and terminated by Stop.
+// The page's side of real Python: one shared worker. It boots in the background once a playground opens (warmReal),
+// runs one piece of code at a time (a newer request replaces one still waiting), and Stop or a run that takes too
+// long terminates it; a fresh worker then starts again from the cache.
 import { pyodideBase } from './config'
 import type { FromWorker, RealPhase, RealResult } from './protocol'
 
 export type { RealPhase, RealResult } from './protocol'
 
 /** Python or a package could not be downloaded (offline, CDN blocked …) */
 export class RealLoadError extends Error {}
-/** the run was stopped (Stop, or the worker was replaced) */
+/** the run was stopped (Stop) */
 export class RealStopped extends Error {}
+/** the run took longer than RUN_LIMIT_MS (an endless loop?) */
+export class RealTimeout extends Error {}
+/** a newer run replaced this one before it started */
+export class RealSuperseded extends Error {}
+
+/** the most a run may take once its packages are loaded */
+export const RUN_LIMIT_MS = 15_000
+
+export type EngineState = 'cold' | 'loading' | 'ready' | 'failed'
+
+interface Job {
+  code: string
+  onStatus: (s: RealPhase) => void
+  resolve: (r: RealResult) => void
+  reject: (e: Error) => void
+}
 
 let worker: Worker | null = null
-let warm = false
+let engine: EngineState = 'cold'
+let seenReady = false
+const listeners = new Set<(s: EngineState) => void>()
 let nextId = 0
-const pending = new Map<number, { onStatus: (s: RealPhase) => void; resolve: (r: RealResult) => void; reject: (e: Error) => void }>()
+let current: (Job & { id: number }) | null = null
+let queued: Job | null = null
+let timer: ReturnType<typeof setTimeout> | undefined
+
+const setEngine = (s: EngineState) => {
+  engine = s
+  if (s === 'ready') seenReady = true
+  listeners.forEach((f) => f(s))
+}
+
+export const engineState = () => engine
+/** has Python started in this tab before (a restart after Stop then comes from the cache: no size warning) */
+export const engineSeenReady = () => seenReady
+export const onEngineState = (f: (s: EngineState) => void) => {
+  listeners.add(f)
+  return () => void listeners.delete(f)
+}
+
+const finish = () => {
+  clearTimeout(timer)
+  current = null
+  const next = queued
+  queued = null
+  if (next) start(next)
+}
 
 const spawn = (): Worker => {
   const w = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
   w.onmessage = (e: MessageEvent<FromWorker>) => {
     const m = e.data
-    const p = pending.get(m.id)
-    if (!p) return
-    if (m.type === 'status') return p.onStatus(m.status)
-    pending.delete(m.id)
-    if (m.type === 'done') {
-      warm = true
-      p.resolve(m.result)
-    } else {
+    if (m.type === 'engine') {
+      if (m.state === 'failed') console.warn('[real python]', m.message)
+      return setEngine(m.state)
+    }
+    if (!current || m.id !== current.id) return
+    const job = current
+    if (m.type === 'status') {
+      if (m.status.phase === 'running') timer = setTimeout(() => stopReal(new RealTimeout('timeout')), RUN_LIMIT_MS)
+      return job.onStatus(m.status)
+    }
+    finish()
+    if (m.type === 'done') job.resolve(m.result)
+    else {
       console.warn('[real python]', m.message)
-      p.reject(new RealLoadError(m.message))
+      job.reject(new RealLoadError(m.message))
     }
   }
   w.onerror = (e) => {
@@ -37,24 +86,51 @@ const spawn = (): Worker => {
   return w
 }
 
-/** has Python already been downloaded and started in this tab? */
-export const isRealWarm = () => warm
+const ensureWorker = (): Worker => {
+  if (!worker) {
+    worker = spawn()
+    setEngine('loading')
+  }
+  return worker
+}
+
+function start(job: Job) {
+  const w = ensureWorker()
+  if (engine === 'failed') setEngine('loading') // the worker tries the download again
+  current = { ...job, id: ++nextId }
+  w.postMessage({ id: current.id, base: pyodideBase(), type: 'run', code: job.code })
+}
+
+/** download and start Python in the background (the packages still wait for an import) */
+export function warmReal(): void {
+  if (worker && engine !== 'failed') return
+  if (engine === 'failed') stopWorker()
+  ensureWorker().postMessage({ id: 0, base: pyodideBase(), type: 'boot' })
+}
 
 /** run code with real CPython and the real libraries; onStatus reports downloading and running */
 export function runReal(code: string, onStatus: (s: RealPhase) => void): Promise<RealResult> {
-  worker ??= spawn()
-  const id = ++nextId
   return new Promise<RealResult>((resolve, reject) => {
-    pending.set(id, { onStatus, resolve, reject })
-    worker!.postMessage({ id, base: pyodideBase(), code })
+    const job = { code, onStatus, resolve, reject }
+    if (!current) return start(job)
+    queued?.reject(new RealSuperseded('superseded'))
+    queued = job
   })
 }
 
-/** stop whatever is running: the worker is thrown away, so the next run starts Python again (from the browser cache) */
-export function stopReal(reason: Error = new RealStopped('stopped')): void {
+function stopWorker() {
   worker?.terminate()
   worker = null
-  warm = false
-  for (const p of pending.values()) p.reject(reason)
-  pending.clear()
+  setEngine('cold')
+}
+
+/** stop whatever is running; a new worker boots again at once (from the cache), so the next run is quick */
+export function stopReal(reason: Error = new RealStopped('stopped')): void {
+  clearTimeout(timer)
+  const jobs = [current, queued]
+  current = null
+  queued = null
+  stopWorker()
+  jobs.forEach((j) => j?.reject(reason))
+  if (!(reason instanceof RealLoadError)) warmReal()
 }

src/lib/pyodide/protocol.ts

@@ -23,10 +23,13 @@ export interface RealResult {
 
 export type RealPhase = { phase: 'runtime' } | { phase: 'packages'; names: string[] } | { phase: 'running' }
 
-export type ToWorker = { id: number; base: string; code: string }
+/** run code, or (type 'boot') only download and start Python so a later run is instant */
+export type ToWorker = { id: number; base: string; type: 'run'; code: string } | { id: number; base: string; type: 'boot' }
 
 export type FromWorker =
   | { id: number; type: 'status'; status: RealPhase }
   | { id: number; type: 'done'; result: RealResult }
   /** Python or its packages could not be downloaded */
   | { id: number; type: 'failed'; message: string }
+  /** the runtime itself: started (ready) or could not be downloaded (failed) */
+  | { type: 'engine'; state: 'ready' | 'failed'; message?: string }

src/lib/pyodide/worker.ts

@@ -1,13 +1,14 @@
 /// <reference lib="webworker" />
 // The Pyodide worker: downloads CPython (once) and the packages each run imports, then runs the code with harness.py.
 // It lives off the main thread so a long run never freezes the page, and Stop can simply terminate it.
+// Everything fetched from the Pyodide base (the wasm runtime, the standard library, package wheels) is kept in
+// Cache Storage, so the next visit starts Python without downloading it again.
 import HARNESS from './harness.py?raw'
 import { MICROPIP_IMPORTS, packageOf } from './config'
 import type { FromWorker, ToWorker } from './protocol'
 
 interface PyProxy {
   (...args: unknown[]): unknown
-  toJs(): unknown
   destroy(): void
 }
 interface Pyodide {
@@ -21,15 +22,55 @@ interface Pyodide {
 const post = (m: FromWorker) => self.postMessage(m)
 const quiet = () => {}
 
+const CACHE_PREFIX = 'knowcs-pyodide:'
+
+/** fetch from the Pyodide base through Cache Storage: cache first, store what was downloaded; old versions are dropped */
+const cacheFetches = (base: string) => {
+  if (typeof caches === 'undefined') return // not a secure context: the browser's HTTP cache still helps
+  const name = CACHE_PREFIX + base
+  void caches.keys().then((keys) => Promise.all(keys.filter((k) => k.startsWith(CACHE_PREFIX) && k !== name).map((k) => caches.delete(k)))).catch(quiet)
+  const plain = self.fetch.bind(self)
+  self.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
+    if (!url.startsWith(base) || (init?.method ?? 'GET') !== 'GET') return plain(input, init)
+    let cache: Cache
+    try {
+      cache = await caches.open(name)
+      const hit = await cache.match(url)
+      if (hit) return hit
+    } catch {
+      return plain(input, init)
+    }
+    const res = await plain(input, init)
+    if (res.ok) cache.put(url, res.clone()).catch(quiet) // a full disk only costs the cache
+    return res
+  }
+}
+
 let booting: Promise<Pyodide> | null = null
 
 const boot = async (base: string): Promise<Pyodide> => {
+  cacheFetches(base)
   const mod = (await import(/* @vite-ignore */ `${base}pyodide.mjs`)) as { loadPyodide(o: object): Promise<Pyodide> }
   const py = await mod.loadPyodide({ indexURL: base, stdout: quiet, stderr: quiet })
   py.runPython(HARNESS)
   return py
 }
 
+const start = (base: string): Promise<Pyodide> => {
+  if (!booting) {
+    booting = boot(base)
+    booting.then(
+      () => post({ type: 'engine', state: 'ready' }),
+      (err) => {
+        booting = null
+        post({ type: 'engine', state: 'failed', message: String(err) })
+      },
+    )
+  }
+  return booting
+}
+
 /** the imports that still need downloading (not built in, not loaded yet) */
 const missing = (py: Pyodide, code: string): string[] => {
   const find = py.globals.get('knowcs_missing')
@@ -40,50 +81,49 @@ const missing = (py: Pyodide, code: string): string[] => {
   }
 }
 
-let queue: Promise<unknown> = Promise.resolve()
-
-self.onmessage = (e: MessageEvent<ToWorker>) => {
-  const { id, base, code } = e.data
-  // one run at a time: Python has one global interpreter
-  queue = queue.then(async () => {
-    const started = performance.now()
-    let py: Pyodide
-    try {
-      if (!booting) post({ id, type: 'status', status: { phase: 'runtime' } })
-      booting ??= boot(base)
-      py = await booting
-    } catch (err) {
-      booting = null
-      post({ id, type: 'failed', message: String(err) })
-      return
-    }
-    try {
-      const need = missing(py, code)
-      if (need.length) {
-        post({ id, type: 'status', status: { phase: 'packages', names: need.map(packageOf) } })
-        await py.loadPackagesFromImports(code, { messageCallback: quiet })
-        const extra = need.filter((m) => m in MICROPIP_IMPORTS)
-        if (extra.length) {
-          await py.loadPackage('micropip', { messageCallback: quiet })
-          const micropip = py.pyimport('micropip')
-          for (const m of extra) await micropip.install(MICROPIP_IMPORTS[m])
-        }
+const run = async (id: number, base: string, code: string) => {
+  const started = performance.now()
+  let py: Pyodide
+  try {
+    if (!booting) post({ id, type: 'status', status: { phase: 'runtime' } })
+    py = await start(base)
+  } catch (err) {
+    post({ id, type: 'failed', message: String(err) })
+    return
+  }
+  try {
+    const need = missing(py, code)
+    if (need.length) {
+      post({ id, type: 'status', status: { phase: 'packages', names: need.map(packageOf) } })
+      await py.loadPackagesFromImports(code, { messageCallback: quiet })
+      const extra = need.filter((m) => m in MICROPIP_IMPORTS)
+      if (extra.length) {
+        await py.loadPackage('micropip', { messageCallback: quiet })
+        const micropip = py.pyimport('micropip')
+        for (const m of extra) await micropip.install(MICROPIP_IMPORTS[m])
       }
-    } catch (err) {
-      post({ id, type: 'failed', message: String(err) })
-      return
     }
-    post({ id, type: 'status', status: { phase: 'running' } })
-    const run = py.globals.get('knowcs_run')
-    const versions = py.globals.get('knowcs_versions')
-    try {
-      const out = JSON.parse(run(code, /\bmatplotlib\b|\bseaborn\b/.test(code)) as string)
-      post({ id, type: 'done', result: { ...out, versions: JSON.parse(versions() as string), ms: Math.round(performance.now() - started) } })
-    } catch (err) {
-      post({ id, type: 'failed', message: String(err) })
-    } finally {
-      run.destroy()
-      versions.destroy()
-    }
-  })
+  } catch (err) {
+    post({ id, type: 'failed', message: String(err) })
+    return
+  }
+  post({ id, type: 'status', status: { phase: 'running' } })
+  const exec = py.globals.get('knowcs_run')
+  const versions = py.globals.get('knowcs_versions')
+  try {
+    const out = JSON.parse(exec(code, /\bmatplotlib\b|\bseaborn\b/.test(code)) as string)
+    post({ id, type: 'done', result: { ...out, versions: JSON.parse(versions() as string), ms: Math.round(performance.now() - started) } })
+  } catch (err) {
+    post({ id, type: 'failed', message: String(err) })
+  } finally {
+    exec.destroy()
+    versions.destroy()
+  }
+}
+
+// the page sends one run at a time (client.ts queues them), so runs never overlap here
+self.onmessage = (e: MessageEvent<ToWorker>) => {
+  const m = e.data
+  if (m.type === 'boot') void start(m.base).catch(quiet)
+  else void run(m.id, m.base, m.code)
 }

src/locales/en.json

@@ -3936,21 +3936,30 @@
       "prev": "Previous step",
       "next": "Next step",
       "real": {
-        "title": "Run in real Python",
-        "engine": "Pyodide · CPython running in your browser",
-        "what": "The step-by-step views come from KnowCS's own interpreter. This runs the same code with the real NumPy, pandas and matplotlib (scikit-learn, SciPy and OpenCV work too), so you can check the output.",
         "size": "The first run downloads Python and the libraries your code imports: about 7 MB for Python alone, 10 MB with NumPy, 20 MB with pandas and matplotlib, 37 MB with scikit-learn. Your browser keeps them for next time.",
-        "run": "Run in real Python",
-        "rerun": "Run again",
         "stop": "Stop",
         "phase_runtime": "Downloading Python…",
         "phase_packages": "Downloading {{names}}…",
         "phase_running": "Running…",
         "took": "{{ms}} ms",
-        "stale": "The code has changed since this run.",
         "failed": "Couldn't download Python from {{host}}. Check your connection, then try again.",
         "stopped": "Stopped.",
-        "figure": "Figure {{n}}, drawn by real matplotlib"
+        "figure": "Figure {{n}}, drawn by real matplotlib",
+        "output": "Output · real Python",
+        "timeout": "Stopped after {{s}} s. Is there an endless loop?",
+        "see_figures": "No printed output; the figures are below."
+      },
+      "engine": {
+        "label": "Engine",
+        "mini": "Step-through",
+        "mini_sub": "minipy · draws every step",
+        "real": "Real Python",
+        "real_cold": "Pyodide · loads when chosen",
+        "real_loading": "Pyodide · loading…",
+        "real_ready": "Pyodide · ready",
+        "real_failed": "Pyodide · couldn't download",
+        "unavailable": "No browser build of {{name}}",
+        "steps_off": "Step-by-step views need the Step-through engine. Real Python runs the code as is and shows its output and figures."
       }
     },
     "view": {