figpress-apps 2026.10.28__tar.gz

figpress_apps-2026.10.28/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+site/
+node_modules/
+.DS_Store
+js-tests/fixtures/
+build/
+.pytest_cache/

figpress_apps-2026.10.28/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+Releases are dated: `YYYY.MM.DD`, and `YYYY.MM.DD.N` for a bug-fix release of it (0.1.0 and 0.2.0
+predate this). The version does not say whether a release breaks things; the migration notes do.
+
+Every release has a section. Every breaking change has a migration note with three parts, so the
+`figpress-apps-upgrade` skill can apply it:
+
+- **What changed**: one sentence.
+- **Find**: how to locate affected code, e.g. `grep -rn "compute:" webapps/`.
+- **Edit**: the exact change to make.
+
+A release with a breaking change that has no migration note is not tagged.
+
+## 2026.10.28 — 2026-10-28
+
+figkit is now **figpress-apps**, a member of the [figpress](https://nstarkman.space/figpress/) family,
+published on PyPI. Nothing else changes: same modules, same behaviour, same data format. Each rename
+below has its migration note; the `figpress-apps-upgrade` skill applies them in order.
+
+### Changed — migration
+
+- **What changed**: the Python distribution, its import and its command: `figkit` →
+  `figpress-apps` (PyPI), `import figkit` → `import figpress_apps`, the command `figkit` →
+  `figpress-apps`, the widget `figkit.anywidget.Widget` → `figpress_apps.anywidget.Widget`.
+  **Find**: `grep -rnE "figkit( @|\\.|$| build| serve| test)|import figkit|from figkit" .`
+  **Edit**: pin `figpress-apps==2026.10.28` instead of `figkit @ git+…`; replace `import figkit` with
+  `import figpress_apps` and `figkit.` with `figpress_apps.`; run `figpress-apps build|serve|test`.
+- **What changed**: browser module specifiers: `figkit/<module>.js` → `figpress-apps/<module>.js`,
+  and the entry module and stylesheet `figkit/figkit.js` → `figpress-apps/index.js`,
+  `figkit/figkit.css` → `figpress-apps/index.css`.
+  **Find**: `grep -rn "figkit/" webapps/`
+  **Edit**: replace `figkit/figkit.js` with `figpress-apps/index.js`, `figkit/figkit.css` with
+  `figpress-apps/index.css`, then every remaining `figkit/` with `figpress-apps/`.
+- **What changed**: built pages: `<meta name="figkit-version">` → `<meta name="figpress-apps-version">`,
+  `vendor/figkit-<v>/` → `vendor/figpress-apps-<v>/`, `globalThis.FIGKIT_DATA` →
+  `globalThis.FIGPRESS_APPS_DATA`, the app element's `data-figkit-app` → `data-figpress-app`.
+  **Find**: `grep -rnE "figkit-version|vendor/figkit-|FIGKIT_DATA|figkitApp|data-figkit-app" .`
+  **Edit**: rebuild (`figpress-apps build`); in app code, replace `dataset.figkitApp` with
+  `dataset.figpressApp`. Commit the new `vendor/` folder if built output is tracked.
+- **What changed**: datasets are written with `figpress_apps_data` / `figpress_apps` instead of
+  `figkit_data` / `figkit`. Datasets written by figkit still load.
+  **Find**: `grep -rn "figkit_data" .` (code that reads manifests itself)
+  **Edit**: none for datasets; in code that reads a manifest directly, read `figpress_apps_data`
+  (falling back to `figkit_data` for old data). JS `FigkitDataError` is now `DataError`.
+- **What changed**: the skills `figkit` and `figkit-upgrade` are `figpress-apps` and
+  `figpress-apps-upgrade`; the repository is `nstarman/figpress-apps` (GitHub redirects the old
+  address) and the gallery `https://nstarkman.space/figpress-apps/`.
+  **Find**: `grep -rn "nstarman/figkit\|skills/figkit\|nstarkman.space/figkit" .`
+  **Edit**: use the new names and addresses.
+
+Unchanged: the `.fk-*` CSS classes and `--fk-*` custom properties, the data format (1), and the
+figkit releases `v0.1.0` / `v0.2.0` (still installable from their tags; fixes for them stay
+`0.1.N` / `0.2.N`).
+
+### Added
+
+- Releases are published to PyPI from their tag (`release.yml`, trusted publishing).
+
+### Changed
+
+- Versioning: releases are dated (`vYYYY.MM.DD`, bug fixes `vYYYY.MM.DD.N`), and every bug fix is
+  backported to every released version that has it (constitution 2.0.0, AGENTS.md "Releasing").
+  No code changes; pins to `v0.1.0`/`v0.2.0` keep working, and the next release sorts after them.
+
+## 0.2.0 — 2026-10-21
+
+No breaking changes: no migration needed from 0.1.
+
+### Added
+
+- Responsive layout classes in `figkit.css`, driven by container queries (the app's own width,
+  so they also adapt in narrow notebook cells): `.fk-split` (two columns, stacked below 760 px)
+  and `.fk-grid-2` (a 2 × 2-style grid, one column below 320 px).
+- `cssVar(el, name, fallback)`, `rgb(color)` (a frozen `[r, g, b]`) and `context2d(canvas)` (a clear error
+  instead of a null context) in `figkit/stage.js`, re-exported by `figkit.js`.
+- `shade(camera, texture, size, out, base)`: optional background `[r, g, b]` (0–255) to composite over.
+
+### Fixed
+
+- Dark mode: the globe's disc, axes and labels and the panels' origin mark follow the theme
+  instead of staying white or near-black; canvases redraw when the system theme changes.
+- Panel headers wrap on narrow screens: titles may wrap, readouts stay on one line.
+- The globe example stacks the globe above its panels on phones.
+- Gallery: each example page links back to the gallery (served and single file).
+- All text files are read and written as UTF-8 (`figkit build`, `export`, the notebook widget):
+  non-ASCII characters in figkit's JS, CSS and generated READMEs broke on non-UTF-8 locales
+  (e.g. Windows cp1252). A test guards it.
+
+### Development
+
+- Pull requests get a live gallery preview on Cloudflare Pages and a single **CI Pass** gate.
+- The `versions/vX.Y.x` release process (AGENTS.md).
+
+## 0.1.0 — 2026-10-21
+
+First release. Specified in `specs/001-figkit-v0-1/`.
+
+### Added
+
+- Data contract: `figkit.export` / `figkit.load` — a manifest plus plain `.npy` files, dtype rules,
+  checked opt-in float64 → float32 narrowing (data format 1).
+- Browser library: `model`, `npy`, `data`, `geom`, `stage`, `globe`, `skypanel` and `figkit.css`.
+- `figkit build` (served site with vendored library and import map; single self-contained HTML that
+  opens from `file://`), `figkit serve`, `figkit test`.
+- `figkit.anywidget.Widget` (extra `notebook`): the same app in JupyterLab and marimo.
+- The globe example (`examples/globe/`) and its gallery page.
+- Skills: `figkit` (building a webapp) and `figkit-upgrade` (moving one to a newer tag).

figpress_apps-2026.10.28/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathaniel Starkman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

figpress_apps-2026.10.28/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: figpress-apps
+Version: 2026.10.28
+Summary: Toolbox for webapps that are the interactive counterparts of scientific papers
+Author: Nathaniel Starkman
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Provides-Extra: notebook
+Requires-Dist: anywidget<0.12,>=0.11; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# figpress-apps
+
+*Formerly **figkit** (renamed in 2026.10.28; the [changelog](CHANGELOG.md) says how to move an app).
+Part of the [figpress](https://nstarkman.space/figpress/) family.*
+
+A toolbox for webapps that are the interactive counterparts of scientific papers: data, plots and
+movies that readers can explore next to the static PDF, built to keep working for years.
+
+- **Python** exports a paper's arrays as plain `.npy` files with a manifest (readers can `np.load`
+  them without figpress-apps), builds sites, serves previews and runs the app's JS tests.
+- **Browser** code is plain ES modules and CSS — no build step, no framework, no CDN. Each site
+  vendors the exact figpress-apps version it was built with.
+- **Two outputs** from one source: a site for GitHub Pages, and a single HTML file that opens from
+  disk, offline, for archives.
+- **Same app in notebooks** (Jupyter, marimo) through anywidget, with state synced back to Python.
+
+Gallery: <https://nstarkman.space/figpress-apps/> (published from releases).
+
+## Install
+
+Pin a release from [PyPI](https://pypi.org/project/figpress-apps/):
+
+```bash
+uv add "figpress-apps==2026.10.28"
+uv add "figpress-apps[notebook]==2026.10.28"   # notebooks
+```
+
+figkit's releases (`v0.1.0`, `v0.2.0`) stay installable from their git tags.
+
+## Use
+
+```python
+import figpress_apps
+figpress_apps.export("build/data", "points", {"xyz": xyz}, meta={"title": "…"})
+```
+
+```bash
+uv run figpress-apps build webapps/points --data build/data/points --out build/site/points --single-file build/points.html
+uv run figpress-apps serve build/site
+uv run figpress-apps test webapps/points
+```
+
+```python
+from figpress_apps.anywidget import Widget
+Widget(app="webapps/points/widget.js", data="build/data/points")
+```
+
+An app is an `index.html`, a `widget.js` (an anywidget module composing figpress-apps components) and a
+DOM-free `science.js`. See [`examples/globe/`](examples/globe/) and the agent skills in
+[`skills/`](skills/): `figpress-apps` (building a webapp) and `figpress-apps-upgrade` (moving one to a newer tag).
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest                                   # Python
+uv run python tests/make_fixtures.py && node --test js-tests/*.test.js   # JS
+uv run playwright install chromium webkit && uv run pytest -m smoke --browser chromium --browser webkit
+```
+
+Design and requirements: [`specs/001-figkit-v0-1/`](specs/001-figkit-v0-1/) (written as figkit). Rules:
+[`.specify/memory/constitution.md`](.specify/memory/constitution.md).
+
+License: MIT. The globe example's data: see [`examples/globe/SOURCE.md`](examples/globe/SOURCE.md).

figpress_apps-2026.10.28/README.md

@@ -0,0 +1,64 @@
+# figpress-apps
+
+*Formerly **figkit** (renamed in 2026.10.28; the [changelog](CHANGELOG.md) says how to move an app).
+Part of the [figpress](https://nstarkman.space/figpress/) family.*
+
+A toolbox for webapps that are the interactive counterparts of scientific papers: data, plots and
+movies that readers can explore next to the static PDF, built to keep working for years.
+
+- **Python** exports a paper's arrays as plain `.npy` files with a manifest (readers can `np.load`
+  them without figpress-apps), builds sites, serves previews and runs the app's JS tests.
+- **Browser** code is plain ES modules and CSS — no build step, no framework, no CDN. Each site
+  vendors the exact figpress-apps version it was built with.
+- **Two outputs** from one source: a site for GitHub Pages, and a single HTML file that opens from
+  disk, offline, for archives.
+- **Same app in notebooks** (Jupyter, marimo) through anywidget, with state synced back to Python.
+
+Gallery: <https://nstarkman.space/figpress-apps/> (published from releases).
+
+## Install
+
+Pin a release from [PyPI](https://pypi.org/project/figpress-apps/):
+
+```bash
+uv add "figpress-apps==2026.10.28"
+uv add "figpress-apps[notebook]==2026.10.28"   # notebooks
+```
+
+figkit's releases (`v0.1.0`, `v0.2.0`) stay installable from their git tags.
+
+## Use
+
+```python
+import figpress_apps
+figpress_apps.export("build/data", "points", {"xyz": xyz}, meta={"title": "…"})
+```
+
+```bash
+uv run figpress-apps build webapps/points --data build/data/points --out build/site/points --single-file build/points.html
+uv run figpress-apps serve build/site
+uv run figpress-apps test webapps/points
+```
+
+```python
+from figpress_apps.anywidget import Widget
+Widget(app="webapps/points/widget.js", data="build/data/points")
+```
+
+An app is an `index.html`, a `widget.js` (an anywidget module composing figpress-apps components) and a
+DOM-free `science.js`. See [`examples/globe/`](examples/globe/) and the agent skills in
+[`skills/`](skills/): `figpress-apps` (building a webapp) and `figpress-apps-upgrade` (moving one to a newer tag).
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest                                   # Python
+uv run python tests/make_fixtures.py && node --test js-tests/*.test.js   # JS
+uv run playwright install chromium webkit && uv run pytest -m smoke --browser chromium --browser webkit
+```
+
+Design and requirements: [`specs/001-figkit-v0-1/`](specs/001-figkit-v0-1/) (written as figkit). Rules:
+[`.specify/memory/constitution.md`](.specify/memory/constitution.md).
+
+License: MIT. The globe example's data: see [`examples/globe/SOURCE.md`](examples/globe/SOURCE.md).

figpress_apps-2026.10.28/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "figpress-apps"
+dynamic = ["version"]
+description = "Toolbox for webapps that are the interactive counterparts of scientific papers"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Nathaniel Starkman" }]
+requires-python = ">=3.11"
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+notebook = ["anywidget>=0.11,<0.12"]
+
+[project.scripts]
+figpress-apps = "figpress_apps.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-playwright>=0.10"]
+
+[tool.hatch.version]
+path = "src/figpress_apps/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/figpress_apps"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"CHANGELOG.md" = "figpress_apps/CHANGELOG.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/figpress_apps", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["smoke: browser smoke tests (need Playwright browsers)"]
+addopts = "-m 'not smoke'"

figpress_apps-2026.10.28/src/figpress_apps/__init__.py

@@ -0,0 +1,9 @@
+"""figpress-apps: webapps that are the interactive counterparts of scientific papers."""
+
+__version__ = "2026.10.28"
+
+from figpress_apps.build import BuildError, BuildResult, build, inline_modules  # noqa: E402
+from figpress_apps.data import DataError, Dataset, export, load  # noqa: E402
+
+__all__ = ["BuildError", "BuildResult", "DataError", "Dataset", "__version__", "build", "export",
+           "inline_modules", "load"]

figpress_apps-2026.10.28/src/figpress_apps/anywidget.py

@@ -0,0 +1,41 @@
+"""Run a figpress-apps app in Jupyter or marimo (extra: ``figpress-apps[notebook]``).
+
+The app module is the same file the web page runs; its imports are inlined into nested ``data:``
+URLs (anywidget loads modules without an import map). The dataset travels as synced traits:
+``manifest``, ``arrays`` (entry name → the ``.npy`` file's bytes) and ``json``.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+
+import anywidget
+import traitlets
+
+from figpress_apps.build import JS_DIR, inline_modules
+from figpress_apps.data import load
+
+
+class Widget(anywidget.AnyWidget):
+    """A figpress-apps app as a notebook widget; ``camera`` and ``views`` sync back to Python."""
+
+    camera = traitlets.List(traitlets.Float()).tag(sync=True)
+    views = traitlets.Dict().tag(sync=True)
+    manifest = traitlets.Dict().tag(sync=True)
+    arrays = traitlets.Dict().tag(sync=True)
+    json = traitlets.Dict().tag(sync=True)
+
+    def __init__(self, app: str | Path, data: str | Path, **kwargs):
+        app, data = Path(app), Path(data)
+        ds = load(data)  # verifies the dataset (format version, checksums)
+        entries = ds.manifest["entries"]
+        # anywidget turns these attributes into synced traits during __init__
+        self._esm = inline_modules(f"app/{app.name}", roots={"figpress-apps/": JS_DIR, "app/": app.parent})
+        self._css = (JS_DIR / "index.css").read_text(encoding="utf-8")
+        super().__init__(
+            manifest=ds.manifest,
+            arrays={k: (data / e["file"]).read_bytes() for k, e in entries.items() if e["kind"] == "array"},
+            json={k: _json.loads((data / e["file"]).read_text(encoding="utf-8")) for k, e in entries.items() if e["kind"] == "json"},
+            **kwargs,
+        )

figpress_apps-2026.10.28/src/figpress_apps/build.py

@@ -0,0 +1,230 @@
+"""Build a webapp into a served site and/or a single self-contained HTML file.
+
+Modules import each other only by bare specifiers: ``figpress-apps/…`` (the vendored library) and
+``app/…`` (the app's own files). The served site resolves them with an import map; the single
+file and the notebook wrapper rewrite them into nested ``data:`` URLs (research R1).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+import shutil
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from figpress_apps.data import FORMAT, DataError, read_manifest
+
+JS_DIR = Path(__file__).parent / "js"
+WEB_SUFFIXES = {".html", ".js", ".css", ".json", ".png", ".jpg", ".jpeg", ".svg", ".webp", ".mp4", ".webm"}
+
+_STATIC = re.compile(r"""\bimport\s*(?:[\w*{}\s,$]+?\s*from\s*)?(['"])([^'"\n]+)\1""")
+_EXPORT_FROM = re.compile(r"""\bexport\s*(?:\*\s*(?:as\s+[\w$]+\s*)?|\{[^}]*\})\s*from\s*(['"])([^'"\n]+)\1""")
+_DYNAMIC = re.compile(r"""\bimport\s*\(\s*([^)]*?)\s*\)""")
+_META_URL = re.compile(r"\bimport\.meta\.url\b")
+_MODULE_SCRIPT = re.compile(r"""(<script\b[^>]*\btype=["']module["'][^>]*>)(.*?)(</script>)""", re.S | re.I)
+_ASSET_ATTR = re.compile(r"""\b(href|src)=(["'])figpress-apps/""")
+_STYLESHEET = re.compile(r"""<link\b[^>]*\brel=["']stylesheet["'][^>]*>""", re.I)
+
+
+class BuildError(ValueError):
+    """The app or its data cannot be built; the message names the file and line."""
+
+
+@dataclass
+class BuildResult:
+    out: Path | None = None
+    single_file: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class _Import:
+    start: int  # offset of the specifier's text (inside the quotes)
+    end: int
+    spec: str
+    line: int
+
+
+def _imports(source: str, file: str, offset_line: int = 0) -> list[_Import]:
+    """Find every module specifier; reject what the single file and notebooks cannot resolve."""
+    line = lambda pos: offset_line + source.count("\n", 0, pos) + 1  # noqa: E731
+    if m := _META_URL.search(source):
+        raise BuildError(f"{file}:{line(m.start())}: import.meta.url is not allowed (modules may be inlined)")
+    found: list[_Import] = []
+    for rx in (_STATIC, _EXPORT_FROM):
+        found += [_Import(m.start(2), m.end(2), m.group(2), line(m.start())) for m in rx.finditer(source)]
+    for m in _DYNAMIC.finditer(source):
+        arg = m.group(1)
+        lit = re.fullmatch(r"""(['"])([^'"\n]+)\1""", arg)
+        if not lit:
+            raise BuildError(f"{file}:{line(m.start())}: non-literal dynamic import({arg}); use a string literal")
+        found.append(_Import(m.start(1) + 1, m.end(1) - 1, lit.group(2), line(m.start())))
+    for imp in found:
+        if imp.spec.startswith(("./", "../", "/")):
+            raise BuildError(f"{file}:{imp.line}: relative import {imp.spec!r}; use a bare specifier "
+                             f"(figpress-apps/… or app/…)")
+        if re.match(r"^[a-z][a-z0-9+.-]*:|^//", imp.spec):
+            raise BuildError(f"{file}:{imp.line}: third-party URL {imp.spec!r}; vendor it instead "
+                             f"(no relative or remote imports)")
+    return sorted(found, key=lambda i: i.start)
+
+
+def _resolve(spec: str, roots: Mapping[str, Path], file: str, line: int) -> Path:
+    for prefix, root in roots.items():
+        if spec.startswith(prefix):
+            path = Path(root) / spec[len(prefix):]
+            if path.is_file():
+                return path
+    raise BuildError(f"{file}:{line}: cannot resolve {spec!r} (known prefixes: {', '.join(roots)})")
+
+
+def _check_tree(sources: Iterable[tuple[str, str, int]], roots: Mapping[str, Path]) -> None:
+    """Check every module reachable from the given (source, file, line offset) entries."""
+    seen: set[Path] = set()
+    stack = list(sources)
+    while stack:
+        source, file, off = stack.pop()
+        for imp in _imports(source, file, off):
+            path = _resolve(imp.spec, roots, file, imp.line)
+            if path not in seen:
+                seen.add(path)
+                stack.append((path.read_text(encoding="utf-8"), path.name, 0))
+
+
+def _data_url(text: str | bytes, mime: str) -> str:
+    raw = text.encode() if isinstance(text, str) else text
+    return f"data:{mime};base64,{base64.b64encode(raw).decode()}"
+
+
+def _rewrite(source: str, file: str, roots: Mapping[str, Path], memo: dict, stack: tuple, off: int = 0) -> str:
+    out, last = [], 0
+    for imp in _imports(source, file, off):
+        path = _resolve(imp.spec, roots, file, imp.line)
+        out += [source[last:imp.start], _inline_path(path, roots, memo, stack)]
+        last = imp.end
+    return "".join(out) + source[last:]
+
+
+def _inline_path(path: Path, roots: Mapping[str, Path], memo: dict, stack: tuple) -> str:
+    if path in stack:
+        chain = " → ".join(p.name for p in (*stack, path))
+        raise BuildError(f"{path.name}: import cycle {chain}")
+    if path not in memo:
+        memo[path] = _data_url(_rewrite(path.read_text(encoding="utf-8"), path.name, roots, memo, (*stack, path)),
+                               "text/javascript")
+    return memo[path]
+
+
+def inline_modules(entry: str, *, roots: Mapping[str, Path]) -> str:
+    """Return the entry module's source with every import rewritten to nested ``data:`` URLs.
+
+    ``entry`` is a bare specifier (e.g. ``"app/widget.js"``); ``roots`` maps prefixes to folders,
+    e.g. ``{"figpress-apps/": apps_js_dir, "app/": app_dir}``. Identical modules become identical URLs,
+    so each module is instantiated once.
+    """
+    path = _resolve(entry, roots, entry, 0)
+    return _rewrite(path.read_text(encoding="utf-8"), path.name, roots, {}, (path,))
+
+
+def _insert_head(html: str, snippet: str) -> str:
+    m = re.search(r"<head\b[^>]*>", html, re.I)
+    if m:
+        return html[:m.end()] + "\n" + snippet + html[m.end():]
+    return snippet + "\n" + html
+
+
+def _version_meta() -> str:
+    from figpress_apps import __version__
+
+    return f'<meta name="figpress-apps-version" content="{__version__}">'
+
+
+def _check_data(data: Iterable[str | Path]) -> list[Path]:
+    paths = [Path(d) for d in data]
+    for d in paths:
+        try:
+            read_manifest(d)
+        except DataError as e:
+            raise BuildError(f"{e} (this figpress-apps reads figpress_apps_data {FORMAT})") from None
+    return paths
+
+
+def build(
+    app_dir: str | Path,
+    *,
+    data: Iterable[str | Path] = (),
+    out: str | Path | None = None,
+    single_file: str | Path | None = None,
+    size_warning_mb: float = 50.0,
+) -> BuildResult:
+    """Build ``app_dir`` (an ``index.html`` plus app modules) into a served site and/or one file."""
+    from figpress_apps import __version__
+
+    if out is None and single_file is None:
+        raise BuildError("nothing to build: give out and/or single_file")
+    app = Path(app_dir)
+    index = app / "index.html"
+    if not index.is_file():
+        raise BuildError(f"{index} not found")
+    roots = {"figpress-apps/": JS_DIR, "app/": app}
+    html = index.read_text(encoding="utf-8")
+    scripts = [(m.group(2), "index.html", html.count("\n", 0, m.start(2))) for m in _MODULE_SCRIPT.finditer(html)]
+    app_js = [(p.read_text(encoding="utf-8"), p.name, 0) for p in sorted(app.glob("*.js")) if not p.name.endswith(".test.js")]
+    lib_js = [(p.read_text(encoding="utf-8"), f"figpress-apps/{p.name}", 0) for p in sorted(JS_DIR.glob("*.js"))]
+    _check_tree([*scripts, *app_js, *lib_js], roots)
+    datasets = _check_data(data)
+    result = BuildResult()
+
+    if out is not None:
+        site = Path(out)
+        if site.exists():
+            shutil.rmtree(site)
+        site.mkdir(parents=True)
+        for f in app.iterdir():
+            if f.is_file() and f.suffix in WEB_SUFFIXES and not f.name.endswith(".test.js"):
+                shutil.copy2(f, site / f.name)
+        vendor = f"vendor/figpress-apps-{__version__}"
+        shutil.copytree(JS_DIR, site / vendor)
+        imap = json.dumps({"imports": {"figpress-apps/": f"./{vendor}/", "app/": "./"}})
+        page = _ASSET_ATTR.sub(lambda m: f"{m.group(1)}={m.group(2)}./{vendor}/", html)
+        page = _insert_head(page, f'{_version_meta()}\n<script type="importmap">{imap}</script>')
+        (site / "index.html").write_text(page, encoding="utf-8")
+        for d in datasets:
+            shutil.copytree(d, site / "data" / d.name)
+        result.out = site
+
+    if single_file is not None:
+        memo: dict = {}
+        page = _MODULE_SCRIPT.sub(
+            lambda m: m.group(1) + _rewrite(m.group(2), "index.html", roots, memo, (),
+                                            html.count("\n", 0, m.start(2))) + m.group(3),
+            html,
+        )
+
+        def inline_css(m: re.Match) -> str:
+            href = re.search(r"""\bhref=["']([^"']+)["']""", m.group(0)).group(1)
+            path = JS_DIR / href[len("figpress-apps/"):] if href.startswith("figpress-apps/") else app / href
+            if not path.is_file():
+                raise BuildError(f"index.html: stylesheet {href!r} not found")
+            css = path.read_text(encoding="utf-8")
+            return f"<style>\n{css}</style>"
+
+        page = _STYLESHEET.sub(inline_css, page)
+        registry = {
+            d.name: {"name": d.name, "urls": {f.name: _data_url(f.read_bytes(), "application/octet-stream")
+                                               for f in sorted(d.iterdir()) if f.is_file()}}
+            for d in datasets
+        }
+        page = _insert_head(page, f"{_version_meta()}\n<script>globalThis.FIGPRESS_APPS_DATA = {json.dumps(registry)};</script>")
+        target = Path(single_file)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(page, encoding="utf-8")
+        size_mb = target.stat().st_size / 1e6
+        if size_mb > size_warning_mb:
+            result.warnings.append(f"{target} is {size_mb:.1f} MB (above {size_warning_mb:g} MB); "
+                                   f"consider the served build or smaller data")
+        result.single_file = target
+    return result