webapp-shell 0.1__tar.gz

webapp_shell-0.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+node_modules/
+!examples/*/frontend/dist/

webapp_shell-0.1/CHANGE_LOG.md

@@ -0,0 +1,28 @@
+# 0.1
+
+The first version (not yet published). What it holds:
+
+- **The shell as a library:** `run(config)` gives a program its command line; the backend is started, watched and restarted by the shell (`BackendProcess`, `BackendWatchdog`), with a splash and a first-run library check.
+- **Config objects:** `AppIdentity`, `BackendSpec`, `WireProtocol`, `CliFlag` and `ShellConfig`; no program's name is built into the library.
+- **Two windows:** pywebview (built in) and Qt (the `qt` extra).
+- **The backend contract** (`webapp_shell.contract`): launch token, origin policy, launch arguments, and a Starlette `TokenGuard` (the `backend` extra).
+- **WebSocket guard:** `WebSocketGuard` (Starlette) applies the same token and origin rules to a socket as `TokenGuard` does to a request, closing a refused one with code 4401.
+- **Typed everywhere:** `pyright` strict passes on the whole library (`py.typed` ships); everything that crosses between the page and Python is a `JsonValue`.
+- **Typed native arguments:** a function declares its arguments as a dataclass (`NativeFunction(name, Arguments, handler)`); the page's values are checked against the field types before the handler runs and nothing is converted silently.
+- **Native functions:** the standard set (choose a file or folder, save as, show in the file manager, open a link, zoom, boot colours) and your own through `NativeFunction`, one envelope on both toolkits.
+- **The page-side bridge:** `webapp-shell-bridge.js` with its `.d.ts`, copied into a frontend with `python -m webapp_shell bridge --out DIR`.
+- **Documentation site:** twenty-two pages with live demonstrations and Frontend/Backend/Shell code tabs, a page for frontend developers and a security page whose claims are checked by tests.
+- **Examples:** `examples/minimal` and the documentation site `examples/site`.
+- `ShellMessages` / `MessageKey`: the shell's own sentences as one catalogue a project can translate (`ShellConfig.messages`); `python -m webapp_shell messages` prints it as JSON for a frontend; `docs/TRANSLATING.md`.
+- `docs/API.md`, generated from the source by `tools/api_listing.py` (a test keeps it current), lists only the public API: the names in the `__all__` of `webapp_shell`, `webapp_shell.contract` and `webapp_shell.contract.guard`. `Installation`, `FileFilter`, `standard_functions` and `build_parser` are exported for freezing and tuning; the guide samples and the examples are tested to import nothing else.
+- **Freezing:** `webapp_shell.freezing` (`FreezePlan`, `DataFolder`) and `python -m webapp_shell freeze PLAN [qt] [webview]` freeze a program with PyInstaller (`webapp-shell[freeze]`): the library writes the entry file and the spec, leaves the other shell's libraries out, and checks the folder (required files, nothing of the other shell, the frozen program's own `--check-libraries`). `examples/minimal/freeze_plan.py` is a plan; the frozen Qt build was run headless (`--smoke`) and the frozen `--run-backend` path answered with the token guard on. The zoom limits moved to `native/zoom_range.py` so a Qt-only build does not reach pywebview.
+- **Site:** a page for the splash and the start-up checks (it reads the shell's sentences from the library through the site's backend), the six guides of `docs/` as pages (the same Markdown files, rendered with their code highlighted and copyable; links between guides stay in the site), and tests that keep the guides, their links and the committed build in step.
+- Badges in the README (CI, PyPI, Python, licence, docs) and `CONTRIBUTING.md`.
+- Guides: contract, configuration, native functions, freezing, troubleshooting (their Python samples are checked by a test).
+- Pyright strict also covers the examples; CI (3 systems, Python 3.13), a Pages workflow and a trusted-publishing release workflow (TestPyPI, then PyPI on a tag).
+- Package metadata (classifiers, URLs, keywords); the wheel and sdist pass `twine check`.
+- Name checked free on PyPI on 1 November 2026. Checked: Starlette 0.40 and 1.10, pywebview 6.2 and 6.2.1; a clean install of the built wheel runs the example.
+- Plainer start-up errors: a backend that stops while starting reports its exit code; one that never answers names the health path and the seconds waited.
+- On Windows, a missing WebView2 runtime is found before any window opens and reported in a message box with the download page (`webapp_shell.webview2`).
+- The example site colours every code block (Python, TypeScript, shell) with highlight.js; the README links to the documentation site.
+- Example site: every code card has a Copy button; in a plain browser the demos use the browser's own features (file, folder and save pickers, zoom, theme colour, new-tab links), with a note that a browser never gives a path on the disk. Only "Show in the file manager" needs the shell.

webapp_shell-0.1/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+Thank you for helping. The library is small and typed on purpose; these are the rules that keep it so.
+
+## Set up
+
+Python 3.13 or newer, and Node (only for the documentation site and the Markdown checks).
+
+```sh
+git clone https://github.com/prmpsmart/webapp_shell.git
+cd webapp_shell
+python -m venv .venv && . .venv/bin/activate   # on Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]" pyright
+```
+
+## The checks
+
+CI runs all of these on Ubuntu, macOS and Windows; run them before you push, with the newest `ruff`.
+
+```sh
+python -m ruff check .
+python -m ruff format --check .
+npx --yes prettier --check "**/*.md"
+npx --yes markdownlint-cli "**/*.md" --ignore "**/node_modules/**"
+python -m pyright
+python -m pytest
+python -m pytest -m freeze     # freezes the minimal example with PyInstaller (slow)
+```
+
+## How the code is written
+
+- **Typed.** `pyright` is strict on `src/` and the examples. Use dataclasses and `StrEnum`s, not dictionaries and loose
+  strings; everything that crosses between the page and Python is a `JsonValue`.
+- **One job per class.** A window toolkit (`webview`, `PySide6`) is imported only by the modules of its own shell, never
+  by a shared one, so a Qt-only build never reaches pywebview (a test checks it). `PyInstaller` is imported by
+  `freezing/spec.py` alone.
+- **The public API is what is exported.** A name is public when it is in the `__all__` of `webapp_shell`,
+  `webapp_shell.contract`, `webapp_shell.contract.guard` or `webapp_shell.freezing`. Adding one is a decision: it needs a
+  test and a line in `CHANGE_LOG.md`. Regenerate `docs/API.md` with `python tools/api_listing.py` (a test fails when it
+  is out of date). The examples and the guides import only public names.
+- **Tests.** Every behaviour has one. A fake backend lives in `tests/fake_backend`; tests are not type-checked because
+  their fakes are not the real types.
+- **Docs.** `CHANGE_LOG.md` holds the version in progress (`change_logs/` the past ones); `docs/REMAINING.md` lists only
+  what is still open. Markdown is formatted by `prettier` and checked by `markdownlint`.
+
+## The documentation site
+
+`examples/site` is a React and TypeScript site that the library's own shell opens. Its compiled `frontend/dist` is
+committed (a test checks that it contains the code it shows), so after changing the site:
+
+```sh
+cd examples/site
+npm ci
+npm run build
+```
+
+The guides in `docs/` are shown as pages of the site; editing one means rebuilding it.
+
+## A change
+
+Open an issue first for anything that changes the public API. A pull request needs the checks above to pass, a test for
+the change, and a line in `CHANGE_LOG.md` when behaviour changes.

webapp_shell-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miracle Apata (prmpsmart)
+
+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.

webapp_shell-0.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: webapp-shell
+Version: 0.1
+Summary: A desktop window for a web app made of a Python backend and a compiled frontend.
+Project-URL: Homepage, https://github.com/prmpsmart/webapp_shell
+Project-URL: Documentation, https://prmpsmart.github.io/webapp_shell
+Project-URL: Source, https://github.com/prmpsmart/webapp_shell
+Project-URL: Issues, https://github.com/prmpsmart/webapp_shell/issues
+Project-URL: Changelog, https://github.com/prmpsmart/webapp_shell/blob/main/CHANGE_LOG.md
+Author-email: Miracle Apata <prmpsmart@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backend,desktop,frontend,native,python,pywebview,shell,webview
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28
+Requires-Dist: pywebview>=6.2
+Provides-Extra: backend
+Requires-Dist: starlette>=0.40; extra == 'backend'
+Provides-Extra: dev
+Requires-Dist: pyinstaller>=6; extra == 'dev'
+Requires-Dist: pyside6>=6.9; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: starlette>=0.40; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Provides-Extra: freeze
+Requires-Dist: pyinstaller>=6; extra == 'freeze'
+Provides-Extra: qt
+Requires-Dist: pyside6>=6.9; extra == 'qt'
+Description-Content-Type: text/markdown
+
+# webapp-shell
+
+[![CI](https://github.com/prmpsmart/webapp_shell/actions/workflows/ci.yml/badge.svg)](https://github.com/prmpsmart/webapp_shell/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/webapp-shell)](https://pypi.org/project/webapp-shell/)
+[![Python](https://img.shields.io/pypi/pyversions/webapp-shell)](https://pypi.org/project/webapp-shell/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-site-3556d6)](https://prmpsmart.github.io/webapp_shell)
+
+A desktop window for a web app made of a **Python backend** and a **compiled frontend**. Your project describes itself
+in one config object; the library starts the backend, waits until it is healthy, opens the frontend in a native window
+(pywebview, or Qt on request) and gives the page a small set of native functions (file and folder dialogs, reveal in the
+file manager, open a link, zoom).
+
+> Documentation: <https://prmpsmart.github.io/webapp_shell>. The same site is what `examples/site` opens in the
+> library's own window, where each feature's demonstration button does the real thing.
+>
+> By Miracle Apata ([@prmpsmart](https://github.com/prmpsmart)). MIT licence.
+
+```python
+from pathlib import Path
+
+from webapp_shell import AppIdentity, BackendSpec, BootColors, ShellConfig, WireProtocol, run
+
+ROOT = Path(__file__).resolve().parent
+
+config = ShellConfig(
+    identity=AppIdentity(
+        name="Acme Notes",
+        slug="acme",
+        storage_dir=Path.home() / ".acme",
+        boot_colors=BootColors(base="#102030", glow_a="#204060", glow_b="#4060a0"),
+    ),
+    backend=BackendSpec(module="acme_backend", wire=WireProtocol.for_slug("acme"), package_dirs=(ROOT / "backend",)),
+    source_root=ROOT,  # holds frontend/dist, the compiled frontend
+)
+
+if __name__ == "__main__":
+    raise SystemExit(run(config))
+```
+
+The backend reads the same contract with the library's helpers (Starlette or FastAPI):
+
+```python
+parser = argparse.ArgumentParser()
+add_launch_arguments(parser, config.backend)  # --port, --frontend, --preferences-file, --token
+launch = read_launch_arguments(parser, parser.parse_args(), config.backend.wire)
+app.add_middleware(TokenGuard, validator=TokenValidator(launch.token, wire), wire=wire)
+```
+
+Native functions: the standard set (file and folder dialogs, save as, reveal, open a link, zoom, boot colours) is always
+there; a project adds its own and the page calls them by name.
+
+```python
+from dataclasses import dataclass
+from webapp_shell import JsonValue, NativeContext, NativeFunction
+
+
+@dataclass(frozen=True)
+class Greeting:  # the page's arguments, in order; each is type-checked before your code runs
+    who: str
+
+
+def greet(context: NativeContext, arguments: Greeting) -> JsonValue:  # context.window, .preferences, .actions
+    return f"hello {arguments.who}"
+
+
+config = ShellConfig(..., native_functions=(NativeFunction("greet", Greeting, greet),))
+```
+
+```js
+// copy the bridge into the frontend once: python -m webapp_shell bridge --out src/
+import { getBridge } from "./webapp-shell-bridge.js";
+
+const bridge = await getBridge({ nativeGlobal: "acmeNative" });
+const path = await bridge.pickFile([{ name: "Excel", extensions: ["xlsx"] }]);
+const hello = await bridge.call("greet", "Ada");
+```
+
+Install: `pip install webapp-shell` (pywebview is included); `pip install "webapp-shell[qt]"` adds Qt, and
+`pip install "webapp-shell[backend]"` adds Starlette for the token guard.
+
+On Windows the pywebview window needs the WebView2 runtime (present on Windows 11); `pythonnet` is installed by pywebview.
+
+A runnable minimal program is in `examples/minimal/`, and `examples/site/` is the documentation website, opened by the
+library's own shell, with a live demonstration of every feature.
+
+Guides (`docs/`): [the contract](docs/CONTRACT.md), [configuration](docs/CONFIGURATION.md),
+[native functions](docs/NATIVE_FUNCTIONS.md), [freezing with PyInstaller](docs/FREEZING.md),
+[translating](docs/TRANSLATING.md), [troubleshooting](docs/TROUBLESHOOTING.md), and the generated
+[API listing](docs/API.md) (the public API: nothing that is not listed there is promised). The same guides are pages of
+the documentation site. To work on the library, read [CONTRIBUTING.md](CONTRIBUTING.md).

webapp_shell-0.1/README.md

@@ -0,0 +1,91 @@
+# webapp-shell
+
+[![CI](https://github.com/prmpsmart/webapp_shell/actions/workflows/ci.yml/badge.svg)](https://github.com/prmpsmart/webapp_shell/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/webapp-shell)](https://pypi.org/project/webapp-shell/)
+[![Python](https://img.shields.io/pypi/pyversions/webapp-shell)](https://pypi.org/project/webapp-shell/)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-site-3556d6)](https://prmpsmart.github.io/webapp_shell)
+
+A desktop window for a web app made of a **Python backend** and a **compiled frontend**. Your project describes itself
+in one config object; the library starts the backend, waits until it is healthy, opens the frontend in a native window
+(pywebview, or Qt on request) and gives the page a small set of native functions (file and folder dialogs, reveal in the
+file manager, open a link, zoom).
+
+> Documentation: <https://prmpsmart.github.io/webapp_shell>. The same site is what `examples/site` opens in the
+> library's own window, where each feature's demonstration button does the real thing.
+>
+> By Miracle Apata ([@prmpsmart](https://github.com/prmpsmart)). MIT licence.
+
+```python
+from pathlib import Path
+
+from webapp_shell import AppIdentity, BackendSpec, BootColors, ShellConfig, WireProtocol, run
+
+ROOT = Path(__file__).resolve().parent
+
+config = ShellConfig(
+    identity=AppIdentity(
+        name="Acme Notes",
+        slug="acme",
+        storage_dir=Path.home() / ".acme",
+        boot_colors=BootColors(base="#102030", glow_a="#204060", glow_b="#4060a0"),
+    ),
+    backend=BackendSpec(module="acme_backend", wire=WireProtocol.for_slug("acme"), package_dirs=(ROOT / "backend",)),
+    source_root=ROOT,  # holds frontend/dist, the compiled frontend
+)
+
+if __name__ == "__main__":
+    raise SystemExit(run(config))
+```
+
+The backend reads the same contract with the library's helpers (Starlette or FastAPI):
+
+```python
+parser = argparse.ArgumentParser()
+add_launch_arguments(parser, config.backend)  # --port, --frontend, --preferences-file, --token
+launch = read_launch_arguments(parser, parser.parse_args(), config.backend.wire)
+app.add_middleware(TokenGuard, validator=TokenValidator(launch.token, wire), wire=wire)
+```
+
+Native functions: the standard set (file and folder dialogs, save as, reveal, open a link, zoom, boot colours) is always
+there; a project adds its own and the page calls them by name.
+
+```python
+from dataclasses import dataclass
+from webapp_shell import JsonValue, NativeContext, NativeFunction
+
+
+@dataclass(frozen=True)
+class Greeting:  # the page's arguments, in order; each is type-checked before your code runs
+    who: str
+
+
+def greet(context: NativeContext, arguments: Greeting) -> JsonValue:  # context.window, .preferences, .actions
+    return f"hello {arguments.who}"
+
+
+config = ShellConfig(..., native_functions=(NativeFunction("greet", Greeting, greet),))
+```
+
+```js
+// copy the bridge into the frontend once: python -m webapp_shell bridge --out src/
+import { getBridge } from "./webapp-shell-bridge.js";
+
+const bridge = await getBridge({ nativeGlobal: "acmeNative" });
+const path = await bridge.pickFile([{ name: "Excel", extensions: ["xlsx"] }]);
+const hello = await bridge.call("greet", "Ada");
+```
+
+Install: `pip install webapp-shell` (pywebview is included); `pip install "webapp-shell[qt]"` adds Qt, and
+`pip install "webapp-shell[backend]"` adds Starlette for the token guard.
+
+On Windows the pywebview window needs the WebView2 runtime (present on Windows 11); `pythonnet` is installed by pywebview.
+
+A runnable minimal program is in `examples/minimal/`, and `examples/site/` is the documentation website, opened by the
+library's own shell, with a live demonstration of every feature.
+
+Guides (`docs/`): [the contract](docs/CONTRACT.md), [configuration](docs/CONFIGURATION.md),
+[native functions](docs/NATIVE_FUNCTIONS.md), [freezing with PyInstaller](docs/FREEZING.md),
+[translating](docs/TRANSLATING.md), [troubleshooting](docs/TROUBLESHOOTING.md), and the generated
+[API listing](docs/API.md) (the public API: nothing that is not listed there is promised). The same guides are pages of
+the documentation site. To work on the library, read [CONTRIBUTING.md](CONTRIBUTING.md).

webapp_shell-0.1/change_logs/README.md

@@ -0,0 +1,5 @@
+# Change logs of past versions
+
+One file per released version, named `<version>.md` (`0.1.md`, `0.2.md`, …), saying what changed compared with the version before it.
+
+The version being worked on is `CHANGE_LOG.md` in the root of the repository. When a new version starts, the root `CHANGE_LOG.md` is moved here as `<its version>.md` and a new `CHANGE_LOG.md` is begun for the new version (`tests/test_change_log.py` checks that its title is the version in `pyproject.toml`).

webapp_shell-0.1/docs/API.md

@@ -0,0 +1,273 @@
+# API listing
+
+Generated by `python tools/api_listing.py` from the source; do not edit by hand (a test fails when it is out of date).
+
+This is the whole public API: what a project imports (`webapp_shell`, `webapp_shell.contract`) and what it can use to
+tune the shell (`webapp_shell.contract.guard`, `standard_functions`, `build_parser`, `Installation`, `ShellMessages`).
+Nothing else is promised: a module or name that is not listed here can change in any release, even though it can be
+imported.
+
+Public names: 34.
+
+## `webapp_shell.backend`
+
+How a project's backend is started: a Python module run as `python -m <module>` (or, in a frozen program, by the program running itself).
+
+- `class CliFlag` — A command-line switch the project adds to its program (`--sandbox`). When given, the backend gets `passes`.
+  - `name: str`
+  - `help: str`
+  - `passes: tuple[str, ...]`
+- `class BackendSpec`
+  - `module: str`
+  - `wire: WireProtocol`
+  - `frontend_dist: Path`
+  - `frontend_argument: str`
+  - `port_argument: str`
+  - `preferences_argument: str | None`
+  - `arguments: tuple[str, ...]`
+  - `source_only_arguments: tuple[str, ...]`
+  - `flags: tuple[CliFlag, ...]`
+  - `package_dirs: tuple[Path, ...]`
+
+## `webapp_shell.cli`
+
+The command line every project gets: `<program> [webview|qt] [--smoke] [--splash-seconds N] [project switches]`.
+
+- `def build_parser(config: ShellConfig) -> argparse.ArgumentParser`
+- `def run(config: ShellConfig, argv: list[str] | None=None, installation: Installation | None=None) -> int` — The entry point of a project's program: its launcher builds a `ShellConfig` and calls this.
+
+## `webapp_shell.config`
+
+The one object a project gives the library.
+
+- `class ShellConfig`
+  - `identity: AppIdentity`
+  - `backend: BackendSpec`
+  - `source_root: Path`
+  - `host: str`
+  - `startup_timeout: float`
+  - `splash_seconds: float`
+  - `native_functions: tuple[NativeCallable, ...]`
+  - `required_libraries: tuple[str, ...]`
+  - `library_checks: tuple[Callable[[], list[LibraryProblem]], ...]`
+  - `messages: ShellMessages`
+
+## `webapp_shell.contract.guard`
+
+Access control for a Starlette or FastAPI backend: the launch token, from a header or a cookie.
+
+- `class GuardResponses` — What a refused request gets back. A project with its own error format replaces them.
+  - `unauthorized: dict[str, str]`
+  - `foreign_origin: dict[str, str]`
+- `class TokenGuard(BaseHTTPMiddleware)` — Protects the API with the launch token.
+  - `def __init__(self, app: ASGIApp, validator: TokenValidator, wire: WireProtocol, origins: OriginPolicy | None=None, responses: GuardResponses | None=None)`
+  - `async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response`
+- `class WebSocketGuard` — The same rules for a socket as `TokenGuard` has for a request: the token (header, cookie or query string) and the origin. A refused socket is closed with `wire.ws_close_unauthorized` before it is accepted.
+  - `def __init__(self, validator: TokenValidator, wire: WireProtocol, origins: OriginPolicy | None=None)`
+  - `def allows(self, socket: WebSocket) -> bool`
+  - `async def accept(self, socket: WebSocket) -> bool`
+
+## `webapp_shell.contract.launch`
+
+The command line the shell starts a backend with, read by the backend: the port, the compiled frontend, the preferences file and the token. The argument names come from the same `BackendSpec` the shell builds the command from, so the two cannot drift.
+
+- `class LaunchArguments`
+  - `port: int`
+  - `token: str`
+  - `frontend: Path | None`
+  - `preferences_file: Path | None`
+  - `host: str`
+- `def add_launch_arguments(parser: argparse.ArgumentParser, backend: BackendSpec) -> None` — Adds the standard arguments to a backend's parser. Read them back with `LaunchArguments.of(args, ...)`.
+- `def read_launch_arguments(parser: argparse.ArgumentParser, args: argparse.Namespace, wire: WireProtocol) -> LaunchArguments` — Checks the token is there (the parser reports the error) and gathers the standard arguments.
+
+## `webapp_shell.contract.tokens`
+
+Decides whether a candidate is the launch token, and whether a request comes from the app's own page. No HTTP framework code here.
+
+- `class TokenValidator`
+  - `def __init__(self, token: str, wire: WireProtocol)`
+  - `property token(self) -> str`
+  - `def is_valid(self, candidate: str | None) -> bool`
+  - `def is_valid_connection(self, headers: Mapping[str, str], cookies: Mapping[str, str], query: Mapping[str, str]) -> bool`
+- `class OriginPolicy` — A browser tells which page made a request in `Origin`. Cookies are shared by every port of a host, so another program's page on 127.0.0.1 would otherwise be allowed to call this one: only the app's own page is.
+  - `def allows(self, origin: str | None, host: str | None) -> bool`
+
+## `webapp_shell.enums`
+
+- `class ShellKind(StrEnum)` — The desktop shells. The value is what the command line and the run scripts use.
+  - `QT`
+  - `WEBVIEW`
+- `class NativeMethod(StrEnum)` — The native functions a page may call (02-architecture.md). The value is the name on the wire, in both shells.
+  - `PICK_FOLDER`
+  - `PICK_FILE`
+  - `SAVE_AS`
+  - `REVEAL`
+  - `OPEN_URL`
+  - `SET_BOOT_COLORS`
+  - `SET_ZOOM`
+
+## `webapp_shell.freezing.plan`
+
+What a project says about its frozen build. The rest (the entry file, what each shell leaves out, the checks of the finished folder) belongs to the library.
+
+- `class DataFolder` — A folder of the project that goes into the build as data (the compiled frontend, files the backend reads).
+  - `source: Path`
+  - `target: str`
+- `class FreezePlan`
+  - `product: str`
+  - `config: str`
+  - `packages: tuple[str, ...]`
+  - `data_folders: tuple[DataFolder, ...]`
+  - `required: tuple[str, ...]`
+  - `collect_all: tuple[str, ...]`
+  - `runtime_hooks: tuple[Path, ...]`
+  - `excludes: tuple[str, ...]`
+  - `icon: Path | None`
+  - `def load(cls, reference: str) -> 'FreezePlan'`
+
+## `webapp_shell.identity`
+
+Who the program is: the one place a project says its name, where it keeps things and how its opening looks.
+
+- `class AppIdentity` — What the shell shows and stores for one program. Nothing else in the library names the program.
+  - `name: str`
+  - `slug: str`
+  - `storage_dir: Path`
+  - `boot_colors: BootColors`
+  - `icon_png: Path | None`
+  - `icon_ico: Path | None`
+  - `window_size: tuple[int, int]`
+  - `property native_global(self) -> str`
+  - `property native_ready_event(self) -> str`
+  - `property shell_preferences_path(self) -> Path`
+  - `property app_preferences_path(self) -> Path`
+
+## `webapp_shell.installation`
+
+Where the program lives and how its backend is started: from the source tree, or frozen into one folder.
+
+- `class Installation` — A frozen program (PyInstaller) has one executable and no `python -m`: it starts its own backend by running itself with `RUN_BACKEND`. From the source tree the backend is `python -m <module>`, as always.
+  - `RUN_BACKEND`
+  - `CHECK_LIBRARIES`
+  - `COMMANDS`
+  - `def __init__(self, source_root: Path, frozen: bool | None=None, bundle: Path | None=None)`
+  - `property root(self) -> Path`
+  - `def package_dirs(self, backend: BackendSpec) -> tuple[Path, ...]`
+  - `def backend_command(self, backend: BackendSpec) -> list[str]`
+
+## `webapp_shell.json_types`
+
+What JSON can carry. Everything that crosses between the page and Python is one of these, never a bare `dict`.
+
+- `type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None`
+- `type JsonObject = dict[str, JsonValue]`
+
+## `webapp_shell.library_check`
+
+Imports every third-party library a project lists. Heavy libraries load lazily, so a frozen program that lacks one would only fail when the person reaches the feature; this finds it when the program is built.
+
+- `class LibraryProblem`
+  - `name: str`
+  - `detail: str`
+
+## `webapp_shell.messages`
+
+The few sentences the shell shows itself (in the splash page's error, and in what it prints), as one catalogue.
+
+- `class MessageKey(StrEnum)` — The name of each sentence. The member name, lower-cased, is the field of `ShellMessages`; the value is the key in the JSON catalogue.
+  - `FRONTEND_MISSING`
+  - `BACKEND_NOT_STARTED`
+  - `BACKEND_EXITED`
+  - `VERSION_NOT_OBJECT`
+  - `BACKEND_GAVE_UP`
+  - `LIBRARIES_PRESENT`
+  - `WEBVIEW2_MISSING`
+- `class ShellMessages` — Every sentence, with its English default. `{name}` and `{path}` are filled in when the sentence is shown.
+  - `frontend_missing: str`
+  - `backend_not_started: str`
+  - `backend_exited: str`
+  - `version_not_object: str`
+  - `backend_gave_up: str`
+  - `libraries_present: str`
+  - `webview2_missing: str`
+  - `def text(self, key: MessageKey, **values: str) -> str`
+  - `def sentences(self) -> dict[MessageKey, str]`
+  - `def catalogue(self) -> JsonObject`
+
+## `webapp_shell.native.errors`
+
+The error a native function raises to refuse a call in words the page may show.
+
+- `class NativeError(Exception)` — Raised by a handler to refuse a call in words the page may show.
+
+## `webapp_shell.native.filters`
+
+File-type filters in the one shape the frontend sends, converted for each toolkit.
+
+- `class FileFilter` — `{name: 'Excel', extensions: ['xlsx', 'xls']}` from the page. An extension may be written `xlsx` or `*.xlsx`.
+  - `name: str`
+  - `extensions: tuple[str, ...]`
+  - `property is_usable(self) -> bool`
+  - `def to_qt(self) -> str`
+  - `def to_webview(self) -> str`
+
+## `webapp_shell.native.registry`
+
+The native functions a page may call: a name, typed arguments, a handler, and one place that runs them for both toolkits.
+
+- `class NoArguments` — The arguments of a function that takes none.
+- `class NativeCallable(Protocol)` — What the registry stores: any `NativeFunction`, whatever its arguments are.
+  - `property name(self) -> str`
+  - `def run(self, context: NativeContext, values: list[JsonValue]) -> JsonValue`
+- `class NativeFunction` — A function the page can call by `name`. `arguments` is a dataclass (see `native.arguments`); the handler is called as `handler(context, arguments)` and returns anything JSON can carry.
+  - `def __init__(self, name: str, arguments: type[A], handler: Callable[[NativeContext, A], JsonValue])`
+  - `property name(self) -> str`
+  - `def run(self, context: NativeContext, values: list[JsonValue]) -> JsonValue`
+
+## `webapp_shell.native.standard`
+
+The native functions every project gets. Written once, against `NativeContext`; the page sees them under the names of `NativeMethod`. Each declares its arguments as a dataclass.
+
+- `def standard_functions() -> tuple[NativeCallable, ...]`
+
+## `webapp_shell.native.window`
+
+What a native function can use: the window it opens dialogs on, the shell's preferences and the OS actions. Each toolkit implements `NativeWindow`; the functions are written once, against it.
+
+- `class NativeWindow(ABC)` — The window of one toolkit. A dialog returns the chosen path, or None when the person cancelled.
+  - `def pick_folder(self, start: str) -> str | None`
+  - `def pick_file(self, filters: list[FileFilter], start: str) -> str | None`
+  - `def save_as(self, name: str, start: str) -> str | None`
+  - `def set_zoom(self, factor: float) -> bool`
+- `class NativeContext` — Handed to every native function as its first argument.
+  - `window: NativeWindow`
+  - `preferences: ShellPreferences`
+  - `actions: OsActions`
+
+## `webapp_shell.preferences`
+
+What the shell itself remembers between launches: the colours of the app's opening screen, so the window and the splash start in the colours of the theme the user chose (the shell cannot read the web page's storage before the page loads).
+
+- `class BootColors` — The three colours of the navy gradient (frontend tokens `--nav`, `--hero-a`, `--hero-b`).
+  - `base: str`
+  - `glow_a: str`
+  - `glow_b: str`
+  - `def from_values(cls, base: JsonValue, glow_a: JsonValue, glow_b: JsonValue) -> 'BootColors | None'`
+  - `property is_valid(self) -> bool`
+  - `def normalised(self) -> 'BootColors'`
+
+## `webapp_shell.protocol`
+
+The names the shell and a backend must agree on. The backend reads the same names; the library never invents them silently: `for_slug` gives a consistent default set and a project may write its own.
+
+- `class WireProtocol`
+  - `token_header: str`
+  - `token_cookie: str`
+  - `token_query: str`
+  - `token_env: str`
+  - `api_prefix: str`
+  - `health_path: str`
+  - `version_path: str | None`
+  - `ws_close_unauthorized: int`
+  - `def for_slug(cls, slug: str) -> 'WireProtocol'`
+  - `def token_from_environment(self, environ: Mapping[str, str] | None=None) -> str | None`