Docs: a live browser demo and a How it works explainer

[alxmrs]

This adds two pages to the docs site: a live browser demo and a "How it works" explainer.

Run in the browser (docs/browser.md, docs/demo/)

The demo queries NOAA GFS forecasts from dynamical.org's Zarr store with xarray-sql and DuckDB running in Pyodide, in a web worker. There is no server: each query downloads only the chunks that survive xarray-sql's chunk pruning, and maps are drawn with deck.gl over a MapLibre basemap. A loading animation shows the boot steps (Pyodide and packages, xarray-sql, the forecast store).

JSPI can't suspend while DuckDB or pyarrow calls back into Python, so chunks can't be fetched in the middle of a scan. ChunkCache works around this. It records the chunks a query misses and scans fill values in their place, then fetches the missing chunks concurrently with Dataset.load_async and re-runs the query until a run has no misses. That final run used only real data, so its result is exact. A run that fails on the fill values (e.g. a CAST to INTEGER over NaN) is retried the same way, and a query that needs more chunks than the cache holds raises MemoryError instead of thrashing.

The guide also shows plain Pyodide usage without dask: open a remote Zarr through a small fetch-based store, load_async a slice, query it, and turn the result back into a Dataset with to_dataset.

The embedded demo works only after a release ships the Pyodide wheel. It installs xarray-sql from PyPI, and 0.5.0 requires DataFusion, which has no Pyodide wheel, so until the next release micropip fails to install it. The release workflow already uploads the wasm wheel (PEP 783). For local testing, ?wheel=./<wheel> loads a local build (see the guide).

How it works (docs/how-it-works.md, docs/explainer/)

An interactive, static walkthrough of the three steps, using a tiny real slice of ARCO-ERA5 2 m temperature (8 days × 6 latitudes × 8 longitudes, saved as era5.json by make_snapshot.py):

1. A Dataset is a table: a heatmap with chunk boundaries linked to the 384-row table and its partitions.
2. SQL reads only the chunks it needs: five example queries, with a partition cube showing which partitions are read or pruned.
3. Results come back as a Dataset: the to_dataset repr and a map or line chart of the result.

It needs no Python, so it works as soon as the docs deploy.

Testing

• smoke.mjs runs every demo example in Node Pyodide against the live store; all pass with a wheel built by the wasm CI recipe. The review's failure cases (integer casts, decimal sums, all-NaN results, duplicate points, NaN in lists) also pass there.
• Headless Chromium at desktop and phone widths, light and dark: the demo standalone and inside the built docs site, and every explainer step.

Startup

About 15 s cold and 13 s warm on my connection. About 40 MB is downloaded, about 85% of it Pyodide, pyarrow, DuckDB, pandas and numpy. Even with a warm cache, unpacking and compiling the wasm packages takes ~7 s and Python imports plus dataset setup ~6 s. The worker fetches Pyodide's packages in parallel while the runtime boots. The next lever is a Pyodide memory snapshot.

Other changes

• flake.nix: wasm-shell gains the shared libraries Playwright's Chromium needs.
• .gitignore: wheels copied into docs/demo/ for local testing.
• zensical.toml: "How it works" after Getting started; "Run in the browser" under Concepts.

Known limits (see the guide): lead_time filters don't prune because DuckDB doesn't push down INTERVAL predicates, and dimension-only scans build the full grid.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyN7idACeDMh94qrnFMu6h

[alxmrs]

Feedback for the app.

[alxmrs]

Feedback, overall looks great.

[alxmrs]

New idea.