feat(app): serve Pyodide from origin instead of CDN

Pyodide assets (~14MB across pyodide.js, .asm.js, .asm.wasm,
python_stdlib.zip, pyodide-lock.json) used to be loaded from
cdn.jsdelivr.net on every page load. Two problems:

1. Dev iteration: even with browser cache, cold loads were ~10s.
2. PWA tier: the SW can't cache cross-origin opaque responses
   reliably, so "offline-capable" apps were never truly offline.

New behavior:
- New route /_violetear/pyodide/{filename} serves from a local disk
  cache at ~/.cache/violetear/pyodide-<version>/ (override via
  VIOLETEAR_PYODIDE_CACHE env var).
- Cache is populated lazily on first request from the same CDN —
  no work at App() construction, no impact on tests that don't fetch
  Pyodide files.
- Atomic .partial → final rename so a crashed download leaves no
  half-baked file.
- The injected <script src=...> now points at the local route;
  loadPyodide()'s default indexURL follows automatically.
- PWA Service Worker asset list now includes the Pyodide files so
  tier 4 (pomodoro) can be fully offline after first visit.

Three new smoke tests:
- Local route serves the seeded files; whitelist-only (no path traversal).
- Injected client script uses /_violetear/pyodide/, not the CDN URL.
- SW asset list includes all five Pyodide files.

Tests stub the cache via VIOLETEAR_PYODIDE_CACHE → no real network
fetch in CI. 43 passed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: apiad

tests/test_engine.py

@@ -227,6 +227,81 @@ def home():
     compile(bundle, "<bundle>", "exec")
 
 
+def test_pyodide_route_serves_from_local_cache(tmp_path, monkeypatch):
+    """Pyodide is served from `/_violetear/pyodide/<file>` via a local disk cache.
+
+    We seed the cache with stub files via the VIOLETEAR_PYODIDE_CACHE env override
+    so the test runs without downloading ~14MB from the CDN.
+    """
+    monkeypatch.setenv("VIOLETEAR_PYODIDE_CACHE", str(tmp_path))
+    # Seed all expected files so the route succeeds.
+    from violetear.app import PYODIDE_FILES
+
+    for fname in PYODIDE_FILES:
+        (tmp_path / fname).write_text(f"// stub for {fname}\n")
+
+    app = App(title="Pyodide", version="pyodide1")
+
+    @app.view("/")
+    def home():
+        return Document(title="x")
+
+    client = TestClient(app.api)
+
+    # Each declared file is served and matches what we wrote on disk.
+    for fname in PYODIDE_FILES:
+        r = client.get(f"/_violetear/pyodide/{fname}")
+        assert r.status_code == 200, fname
+        assert f"stub for {fname}" in r.text
+
+    # Unknown filenames are 404 — the route is a whitelist, not a directory walk.
+    r = client.get("/_violetear/pyodide/etc/passwd")
+    assert r.status_code == 404
+    r = client.get("/_violetear/pyodide/random.js")
+    assert r.status_code == 404
+
+
+def test_injected_client_script_points_at_local_pyodide_route():
+    """When the app has client code, the injected <script src=...> uses
+    `/_violetear/pyodide/pyodide.js` (origin), not the CDN URL."""
+    app = App(title="Local Pyodide", version="pyodide2")
+
+    @app.client.callback
+    async def noop(event):
+        pass
+
+    @app.view("/")
+    def home():
+        return Document(title="x")
+
+    client = TestClient(app.api)
+    html = client.get("/").text
+    assert "/_violetear/pyodide/pyodide.js" in html
+    assert "cdn.jsdelivr.net" not in html
+
+
+def test_pwa_service_worker_precaches_pyodide_assets(tmp_path, monkeypatch):
+    """PWA-enabled apps add Pyodide files to the SW asset list so the app
+    loads fully offline after first visit."""
+    monkeypatch.setenv("VIOLETEAR_PYODIDE_CACHE", str(tmp_path))
+
+    app = App(title="PWA Offline", version="pwaoff")
+
+    @app.view("/", pwa=True)
+    def home():
+        return Document(title="x")
+
+    import hashlib
+    from violetear.app import PYODIDE_FILES
+
+    h = hashlib.md5(b"/").hexdigest()[:8]
+    client = TestClient(app.api)
+    sw = client.get(f"/_violetear/pwa/{h}/sw.js").text
+
+    for fname in PYODIDE_FILES:
+        assert f"/_violetear/pyodide/{fname}" in sw, fname
+
+
 def test_reactive_class_binding_via_class_name_alias():
     """`class_name=` (React-style) is honored as an alias for `classes=`.
 

violetear/app.py

@@ -5,9 +5,11 @@
 import inspect
 import hashlib
 import json
+import threading
 from pathlib import Path
 from textwrap import dedent
 from typing import Any, Callable, Dict, List, Set, Union, cast
+from urllib.request import urlretrieve
 import uuid
 
 from .stylesheet import StyleSheet
@@ -16,6 +18,74 @@
 from .state import ReactiveProxy, local
 
 
+# --- Pyodide local hosting ---
+# We serve Pyodide assets from the same origin as the app instead of a CDN, so:
+# (a) the dev iteration loop isn't gated on a ~10MB CDN round-trip every page
+#     load (browser cache helps but isn't always honored mid-iteration);
+# (b) Service Workers can pre-cache Pyodide for fully offline PWA support;
+# (c) air-gapped deployments work after a single download per machine.
+
+PYODIDE_VERSION = "0.29.0"
+PYODIDE_FILES = (
+    "pyodide.js",
+    "pyodide.asm.js",
+    "pyodide.asm.wasm",
+    "python_stdlib.zip",
+    "pyodide-lock.json",
+)
+PYODIDE_CDN_BASE = f"https://cdn.jsdelivr.net/pyodide/v{PYODIDE_VERSION}/full/"
+
+
+def _pyodide_cache_dir() -> Path:
+    """Resolve the local Pyodide cache directory.
+
+    Honors ``VIOLETEAR_PYODIDE_CACHE`` env override; otherwise defaults to
+    ``~/.cache/violetear/pyodide-<version>/``. Version is part of the path so
+    bumping ``PYODIDE_VERSION`` produces a clean new cache (no stale files).
+    """
+    override = os.environ.get("VIOLETEAR_PYODIDE_CACHE")
+    if override:
+        return Path(override)
+    return Path.home() / ".cache" / "violetear" / f"pyodide-{PYODIDE_VERSION}"
+
+
+_pyodide_download_lock = threading.Lock()
+
+
+def _ensure_pyodide_cached() -> Path:
+    """Download missing Pyodide assets to the local cache. Returns the cache path.
+
+    Idempotent: existing files are not re-downloaded. Thread-safe via a module
+    lock so concurrent first-requests coalesce. Uses ``.partial`` rename for
+    atomic completion — a crashed download leaves no half-baked file behind.
+    """
+    cache = _pyodide_cache_dir()
+    cache.mkdir(parents=True, exist_ok=True)
+
+    missing = [f for f in PYODIDE_FILES if not (cache / f).exists()]
+    if not missing:
+        return cache
+
+    with _pyodide_download_lock:
+        # Re-check inside the lock — another thread may have raced ahead.
+        missing = [f for f in PYODIDE_FILES if not (cache / f).exists()]
+        if not missing:
+            return cache
+
+        print(
+            f"[violetear] Downloading Pyodide v{PYODIDE_VERSION} to {cache} "
+            f"(~14MB, one-time per machine)…"
+        )
+        for fname in missing:
+            print(f"[violetear]   {fname}")
+            tmp = cache / f"{fname}.partial"
+            urlretrieve(PYODIDE_CDN_BASE + fname, tmp)
+            tmp.rename(cache / fname)
+        print("[violetear] Pyodide cache ready.")
+
+    return cache
+
+
 # --- Optional Server Dependencies ---
 try:
     from pydantic import create_model
@@ -320,6 +390,22 @@ async def lifespan(api: FastAPI):
         async def get_favicon():
             return FileResponse(self.favicon)
 
+        # Pyodide assets served from origin. Cache is populated lazily on the
+        # first request — no work happens at App() construction time.
+        @self.api.get("/_violetear/pyodide/{filename}")
+        async def get_pyodide_asset(filename: str):
+            if filename not in PYODIDE_FILES:
+                return Response(status_code=404)
+            try:
+                cache = _ensure_pyodide_cached()
+            except Exception as e:
+                return Response(
+                    status_code=503,
+                    content=f"Pyodide download failed: {e}",
+                    media_type="text/plain",
+                )
+            return FileResponse(cache / filename)
+
         # Registry of served styles to prevent duplicate route registration
         self.served_styles: Dict[str, StyleSheet] = {}
 
@@ -714,8 +800,10 @@ def _inject_client_side(self, doc: Document):
             )
             doc.script(content=cloak_script)
 
-        # 2. Load Pyodide (from CDN)
-        doc.script(src="https://cdn.jsdelivr.net/pyodide/v0.29.0/full/pyodide.js")
+        # 2. Load Pyodide from the local origin route. loadPyodide() defaults
+        # its indexURL to the directory where pyodide.js was loaded from, so
+        # all subsequent fetches (wasm, stdlib, lock file) hit our route too.
+        doc.script(src="/_violetear/pyodide/pyodide.js")
 
         # 3. Bootstrap Script
         # We update this to remove the cloak once hydration is complete.
@@ -786,6 +874,13 @@ def _register_pwa(self, path: str, config: Union[bool, Manifest]):
             self._version_url("/favicon.ico"),
         )
 
+        # Pre-cache Pyodide assets so the PWA loads fully offline after first
+        # visit. These URLs are stable across versions (not version-bumped) so
+        # we don't apply self._version_url to them — the Pyodide files
+        # themselves are pinned by PYODIDE_VERSION on the server side.
+        for fname in PYODIDE_FILES:
+            sw.add_assets(f"/_violetear/pyodide/{fname}")
+
         self.pwa_registry[scope_hash] = (manifest, sw)
 
     def _inject_pwa_tags(self, doc: Document, path: str):