quantized-lab 0.27.0__tar.gz → 0.28.0__tar.gz

quantized_lab-0.28.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: quantized-lab
+Version: 0.28.0
+Summary: Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines.
+Project-URL: Homepage, https://github.com/pquarterman17/quantized
+Project-URL: Documentation, https://github.com/pquarterman17/quantized/wiki
+Project-URL: Repository, https://github.com/pquarterman17/quantized
+Project-URL: Releases, https://github.com/pquarterman17/quantized/releases
+Project-URL: Issues, https://github.com/pquarterman17/quantized/issues
+Author: Paige Quarterman
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: h5py>=3.10
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: periodictable>=1.7
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: scipy>=1.11
+Requires-Dist: uvicorn[standard]>=0.51.0
+Provides-Extra: bumps
+Requires-Dist: bumps>=1.0; extra == 'bumps'
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5.1; extra == 'desktop'
+Provides-Extra: office
+Requires-Dist: python-docx>=1.1; extra == 'office'
+Requires-Dist: python-pptx>=1.0; extra == 'office'
+Provides-Extra: origin-com
+Requires-Dist: pywin32; (sys_platform == 'win32') and extra == 'origin-com'
+Provides-Extra: stats
+Requires-Dist: lifelines>=0.27; extra == 'stats'
+Requires-Dist: statsmodels>=0.14; extra == 'stats'
+Description-Content-Type: text/markdown
+
+# quantized
+
+<p align="center">
+  <!-- Absolute URL, not a repo-relative path: this README is also the PyPI
+       long_description (pyproject `readme`), and PyPI cannot resolve
+       repo-relative images. -->
+  <img src="https://raw.githubusercontent.com/pquarterman17/quantized/main/assets/branding/quantized-app-icon.png" alt="Quantized logo" width="180">
+</p>
+
+**Plot, analyze, and publish lab data — magnetometry, X-ray/neutron
+diffraction & reflectometry, transport — in one fast, reproducible app.**
+
+A clean-architecture Python (FastAPI) + React application, born as a port
+of the `quantized_matlab` scientific toolbox and grown into a full
+OriginPro-class daily driver. Backend math is **golden-verified** against
+the MATLAB original; the GUI is a ground-up revamp.
+
+> **Install:** `pip install quantized-lab` → run `qz`
+> (the PyPI name is `quantized-lab`; the package you import and the
+> commands you run are plain `quantized` / `qz`)
+
+## What it does
+
+**Import instrument data** — Quantum Design VSM/PPMS/MPMS, Lake Shore VSM,
+PANalytical XRDML (1-D scans *and* 2-D reciprocal-space maps with Q-space),
+Rigaku, NCNR reflectometry/PNR, refl1d, SIMS, generic CSV/Excel — with
+content sniffing for ambiguous extensions, drag-drop, paste, guided import
+wizard, and one-click re-import when the source file changes.
+
+**Read and write OriginPro files** — native, clean-room `.opj`/`.opju`
+readers recover workbooks, figures (with styles, legends, annotations),
+and notes; the `.opj` writer produces projects real Origin loads; plus
+Origin-ASCII + `.ogs` scripts, `.otp` template import, and an optional
+Windows COM "Send to Origin" bridge.
+
+**Explore interactively** — an Origin-style pointer tool (drag, resize,
+and pin plot text; draggable legends), multi-window MDI with linked
+zoom/cursor groups, a ctrl-click panel builder (side-by-side / grid /
+overlay with automatic dual-Y by unit family), linked row selection and
+masking across every view, worksheet with formulas and filters, and
+app-wide **undo/redo**.
+
+**Analyze with domain depth** — 29+ fit models plus a no-eval custom
+equation builder, AICc model scanning, global/batch/ODR fits, an optional
+[bumps](https://github.com/bumps/bumps) engine with DREAM posterior
+sampling; a Peak Analyzer wizard; baselines from ALS to Shirley to
+interactive anchor points; Parratt reflectivity; RSM strain analysis;
+Williamson-Hall, FFT film thickness, and reflectivity-FFT reductions;
+hysteresis, relaxation, and a full statistics suite.
+
+**Publish** — every plot window is a durable **figure document**: save,
+reopen, rename, and duplicate figures without losing errors, secondary
+axes, styles, or annotations. **Publication Preview** edits that same
+document at output size — tweak fonts, ticks, margins, axis breaks, and
+annotations in a live WYSIWYG preview (drag the legend, right-click any
+element), then Apply as one undoable change or Cancel cleanly. Export is
+vector PDF/SVG (server-rendered matplotlib) that matches the screen:
+rich-text labels (µ₀H, Å⁻¹, χ″…), journal size presets
+(APS/Nature/thesis…), per-series styles, fills, color-mapped scatter,
+and a multi-panel figure composer for Fig. 1(a)–(d)-style pages.
+
+**Stay reproducible** — every correction is a replayable pipeline step
+with a recalculation DAG, a macro recorder emits runnable scripts,
+workspaces save to a single `.dwk` file, and everything is scriptable
+through the HTTP API and a plugin system.
+
+**DiraCulator** — the built-in materials calculators (units, X-ray/neutron,
+crystallography, SLD, semiconductors, superconductors, magnetism, optics,
+vacuum, and more) also launch standalone: `diraculator` (or
+`qz --calc`), with its own Start Menu entry in the Windows installer.
+
+## Scope
+
+Magnetometry / XRD / reflectometry / lab-data analysis. Electron-microscopy
+tooling (EELS/EDS, imaging) is **out of scope** and lives in the separate
+`fermiviewer` project.
+
+## Run it
+
+| Method | Command | Notes |
+|--------|---------|-------|
+| pipx (recommended) | `pipx install quantized-lab && qz` | isolated env, `qz` on PATH, no dev tools needed |
+| uv tool | `uv tool install quantized-lab && qz` | same idea, via `uv` |
+| pip | `pip install quantized-lab && qz` | into whatever env is active |
+| Native installer | download from [Releases](https://github.com/pquarterman17/quantized/releases) | Windows `.exe` (NSIS, auto-updates), macOS `.dmg` (Apple silicon only — no Intel/x86-64 build), Linux `.deb` — no Python required |
+| From source | see below | for development |
+
+Once installed, `qz` serves the app at `http://127.0.0.1:8000` and opens a
+browser tab. An empty library shows a **"Drop files here, or use ⊞ to import
+/ ✚ for a demo"** hint — click **✚** for an instant synthetic dataset, so a
+fresh install has something to plot within seconds.
+
+**From source — double-click a launcher** (builds the UI + installs deps on
+first run, then opens the app in your browser):
+
+- **Windows:** double-click `run.cmd`
+- **macOS:** double-click `run.command` (first time: right-click → Open)
+
+**Or one command** (after `uv` + Node.js are installed):
+
+```bash
+# first time only: build the UI bundle the app serves
+cd frontend && npm install && npm run build && cd ..
+
+uv run qz                 # serve on :8000 and open a browser tab
+uv run qz --port 9000     # different port
+uv run qz --no-browser    # headless (don't open a tab; never auto-exits)
+uv run qz --desktop       # native window (needs: pip install quantized-lab[desktop])
+uv run qz --dev           # contributor mode: Vite HMR + reloading backend
+uv run diraculator        # the materials calculators, standalone
+```
+
+The default mode behaves like an app: closing the last browser tab shuts
+the server down (a page refresh doesn't). Set `QZ_AUTO_SHUTDOWN=0` to opt
+out, use `--no-browser` for a persistent/headless server, or stop any mode
+with **Ctrl+C** in its window. A busy port falls back to a free one
+automatically, so the app and a standalone DiraCulator coexist.
+
+Building your own wheel/sdist? Build the frontend **first** —
+`cd frontend && npm ci && npm run build` — before `uv build`, or the wheel
+ships without a UI.
+
+## Documentation
+
+- **[Wiki](https://github.com/pquarterman17/quantized/wiki)** — installation,
+  getting started, feature guides, Origin interop
+- **[Releases](https://github.com/pquarterman17/quantized/releases)** —
+  installers + changelogs
+- [`CHANGELOG.md`](https://github.com/pquarterman17/quantized/blob/main/CHANGELOG.md)
+  — plain-language changes per release, Keep a Changelog format
+- [`RELEASE.md`](https://github.com/pquarterman17/quantized/blob/main/RELEASE.md)
+  — how releases are built and published
+- In-app: **⌘K** command palette, **Help ▸ Keyboard shortcuts**, and
+  **Help ▸ Text formatting** for the rich-text label syntax
+
+## Architecture (for contributors)
+
+Pure `io/` + `calc/` libraries (data in → results out, no web imports),
+thin FastAPI `routes/`, a 500-line per-module ceiling, ~400-line React
+component ceiling, and **golden tests** that freeze MATLAB outputs as the
+parity oracle — enforced by tests, not convention. See
+[`CLAUDE.md`](https://github.com/pquarterman17/quantized/blob/main/CLAUDE.md)
+for the rules and
+[`CONTRIBUTING.md`](https://github.com/pquarterman17/quantized/blob/main/CONTRIBUTING.md)
+for the gate and the flake-fix evidence standard.
+
+```bash
+uv sync --group dev                    # backend deps
+uv run python tools/gate.py            # the whole gate, one command (~8 min)
+
+# what it runs, if you want to run a step by hand:
+uv run pytest -n auto        # backend tests (+ `-m golden` for MATLAB parity)
+uv run ruff check src tests tools && uv run mypy src
+cd frontend && npm test && npm run build
+```
+
+License: Apache-2.0.

quantized_lab-0.28.0/pyproject.toml

@@ -0,0 +1,178 @@
+[project]
+name = "quantized-lab"
+version = "0.28.0"
+description = "Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Paige Quarterman" }]
+dependencies = [
+    "fastapi>=0.139.0",
+    "uvicorn[standard]>=0.51.0",
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "pydantic>=2.7",
+    "openpyxl>=3.1",
+    "h5py>=3.10",
+    "python-multipart>=0.0.32",
+    "matplotlib>=3.11.0",
+    "periodictable>=1.7",
+    "platformdirs>=4.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pquarterman17/quantized"
+Documentation = "https://github.com/pquarterman17/quantized/wiki"
+Repository = "https://github.com/pquarterman17/quantized"
+Releases = "https://github.com/pquarterman17/quantized/releases"
+Issues = "https://github.com/pquarterman17/quantized/issues"
+
+[project.scripts]
+qz = "quantized.cli:main"
+quantized = "quantized.cli:main"
+diraculator = "quantized.cli:main_calc"
+
+[project.optional-dependencies]
+# Word/PowerPoint report export (#37). MIT-licensed, pure-python. Optional so
+# the core install stays lean — io/report_export.py guards these imports and
+# LaTeX/HTML export always work; `pip install quantized[office]` enables .docx/.pptx.
+office = [
+    "python-docx>=1.1",
+    "python-pptx>=1.0",
+]
+# COM "Send to Origin" (item 25) — Windows-only optional, behind QZ_ORIGIN_COM=1
+# (architecture guard #10: never a hard dependency, never a CI requirement).
+# io/origin_com.py imports win32com lazily and guards its absence; the
+# cross-platform fallback (Origin-ASCII / .ogs, always available) is
+# io/origin.py. `pip install quantized[origin-com]` adds the live COM path.
+origin-com = [
+    "pywin32; sys_platform == 'win32'",
+]
+# `qz --desktop` native window (PORT_PLAN #3): pure-Python pywebview shell for
+# dev/daily use; the Tauri shell (src-tauri/) stays the packaged path (W8).
+# BSD-3 licensed. server_launch.py guards the import — without this extra,
+# `qz --desktop` prints an install hint and every other mode works normally.
+desktop = [
+    "pywebview>=5.1",
+]
+# Advanced statistics: GLM, survival analysis, Cox PH (gap #30). BSD-3 / MIT
+# licensed. Optional so core install stays lean — calc/stats_glm.py and
+# calc/stats_survival.py guard these imports; ROC is pure numpy and always
+# available. `pip install quantized[stats]` enables GLM/survival methods.
+stats = [
+    "statsmodels>=0.14",
+    "lifelines>=0.27",
+]
+# Optional bumps fit engine (GOTO #10). BSD-3 licensed. calc/fit_bumps.py
+# guards the import — the MATLAB-parity fitter (calc/fitting.py, golden-locked)
+# stays the default engine everywhere; bumps adds amoeba/lm/de/dream as an
+# ADDITIONAL engine. `pip install quantized[bumps]` enables it.
+bumps = [
+    "bumps>=1.0",
+]
+# quantized.client (scripting/API slice 1) — a network client for an
+# ALREADY-RUNNING `qz` server, distinct from the in-process `quantized.api`.
+# BSD-licensed. client.py guards the import; `pip install quantized[client]`
+# enables `QuantizedClient`. Already a dev dependency (TestClient), so this
+# adds no new package to CI, only a new extras group.
+client = [
+    "httpx>=0.27",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "httpx>=0.27",
+    "ruff>=0.15.21",
+    "mypy>=2.2.0",
+    # exercise the optional office exporters (#37) in CI
+    "python-docx>=1.1",
+    "python-pptx>=1.0",
+    # exercise the optional stats methods (GLM/survival/Cox) in CI
+    "statsmodels>=0.14",
+    "lifelines>=0.27",
+    # exercise the optional bumps fit engine (GOTO #10) in CI
+    "bumps>=1.0",
+    "pytest-xdist>=3.8.0",
+]
+# Desktop packaging only — used by the release workflow to freeze the server
+# into a self-contained sidecar (tools/bundle/qz-server.spec). Never a runtime
+# dependency; CI installs it with `uv sync --group bundle`.
+bundle = [
+    "pyinstaller>=6.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Hatchling's default sdist has no include/exclude list, so it sweeps in the
+# whole repo (frontend/node_modules alone is 5000+ files) — scope it to just
+# what a build needs: the package sources (including src/quantized/web/, the
+# gitignored Vite build output, and src/quantized/samples/, the bundled demo
+# dataset — both walked from disk, not from git, so they're picked up when
+# present) plus top-level metadata. Build the SPA BEFORE `uv build` / `python
+# -m build` (`cd frontend && npm ci && npm run build`) or the wheel ships
+# without a UI (qz still runs — see cli.py's "UI not built" warning).
+[tool.hatch.build.targets.sdist]
+include = ["src/quantized", "README.md", "LICENSE", "NOTICE"]
+# Hatchling force-includes LICENSE*/README*-named files project-wide by
+# default (a footgun here: every vendored npm package under
+# frontend/node_modules ships its own LICENSE + README.md) — exclude wins
+# over that default, so this is required even with the include list above.
+exclude = ["frontend/**"]
+# The Vite SPA output (src/quantized/web/**) is gitignored, so hatchling's
+# VCS-aware sdist drops it even though it's under the `include` path above.
+# `uv build`/`python -m build` build the WHEEL FROM THIS SDIST, so if the SPA
+# is missing here it's missing from the wheel too (the wheel target's own
+# artifacts= can't re-add what the sdist never carried). Force-include it in
+# BOTH targets. (Regression fixed 2026-07-08: v0.5.0's wheel shipped UI-less.)
+artifacts = ["src/quantized/web/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quantized"]
+# `packages` alone only reliably ships src/quantized/web/ when hatchling
+# builds directly against a live git checkout; building the wheel FROM an
+# sdist (what `uv build`/`python -m build` do by default, and what the
+# publish workflow does) drops it, since that step can't see this repo's
+# .git and treats the gitignored build output as excluded. `artifacts` is
+# hatchling's explicit "include this even though it looks ignored" escape
+# hatch — force it so the SPA ships in both the direct-build and
+# build-from-sdist paths.
+artifacts = ["src/quantized/web/**"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# Miller indices are conventionally named h, k, l — `l` is unavoidable and clear
+# in crystallographic context (E741 "ambiguous variable name").
+"src/quantized/calc/crystallography.py" = ["E741"]
+"src/quantized/calc/miller_bravais.py" = ["E741"]
+"src/quantized/calc/plane_spacings.py" = ["E741"]
+"src/quantized/routes/crystallography.py" = ["E741"]
+"tests/test_crystallography.py" = ["E741"]
+"tests/test_calc_planespacings.py" = ["E741"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[[tool.mypy.overrides]]
+# Third-party libs without bundled type stubs — skeleton-safe.
+module = ["scipy.*", "uvicorn.*", "openpyxl.*", "h5py.*", "periodictable.*", "docx.*", "pptx.*", "mpl_toolkits.*", "win32com.*", "statsmodels.*", "lifelines.*", "pandas.*", "webview.*", "bumps.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+markers = [
+    "golden: compares output against frozen quantized_matlab reference values",
+    "realdata: needs the local-only instrument corpus (auto-skips when absent)",
+    "perf: wall-time regression tripwires with generous ceilings (not benchmarks)",
+    "perfguard: R7 bounded large-map regression guard, run in a dedicated non-blocking CI job",
+]

quantized_lab-0.28.0/src/quantized/__init__.py

@@ -0,0 +1,11 @@
+"""quantized — Python backend for the quantized toolbox port.
+
+Layered, enforced architecture (see CLAUDE.md):
+  - ``datastruct`` + ``io`` + ``calc`` are pure libraries (no web imports).
+  - ``routes`` are thin FastAPI adapters.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.28.0"
+__all__ = ["__version__"]

quantized_lab-0.28.0/src/quantized/app.py

@@ -0,0 +1,285 @@
+"""FastAPI application factory for quantized.
+
+Thin transport layer only — business logic lives in ``calc/`` and ``io/``.
+Composes the per-domain routers; each router is a thin adapter.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from collections.abc import Collection
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from quantized import __version__
+from quantized.auth import resolve_token
+from quantized.body_limit import BodyLimitMiddleware
+from quantized.io.workbook_transfer_store import cleanup_transfer_dir
+from quantized.jobs import jobs
+from quantized.plugins import load_plugins
+from quantized.routes import (
+    _datasetcache,
+    aggregate,
+    baseline,
+    books,
+    calc,
+    corrections,
+    crystallography,
+    database,
+    datasets,
+    diffusion,
+    electrical,
+    electrochemistry,
+    export,
+    export_figures,
+    export_figures_aux,
+    export_multivar,
+    export_page,
+    export_statplots,
+    fitting,
+    fitting_bumps,
+    fitting_global,
+    fitting_stats,
+    import_template,
+    import_wizard,
+    jobs_api,
+    magnetic,
+    magnetometry,
+    optics,
+    parsers,
+    peaks,
+    peaks_batch,
+    plot,
+    reductions,
+    reference,
+    reflectivity,
+    reflectivity_graded,
+    report_export,
+    rsm,
+    samples,
+    semiconductor,
+    sims,
+    sld,
+    spectral,
+    statplots,
+    stats,
+    stats_design,
+    stats_outliers,
+    stats_varcomp,
+    structures,
+    substrates,
+    superconductor,
+    thermal,
+    thin_film,
+    transform,
+    vacuum,
+    workbook_transfer,
+    xray,
+)
+from quantized.routes._errors import validation_error_handler
+from quantized.security import dev_origins_from_env, host_allowed
+from quantized.web_guard import authorized, origin_ok, security_guard
+
+__all__ = ["create_app", "app"]
+
+# Built SPA (vite build → src/quantized/web/). A build artifact, gitignored;
+# present in packaged/installed runs, absent in a bare dev checkout.
+#
+# One resolution serves both cases: Path(__file__).parent always points at
+# wherever the ``quantized`` package itself lives, so a PyPI/pipx install
+# (the built wheel bundles ``web/`` alongside app.py — see
+# [tool.hatch.build.targets.wheel] artifacts in pyproject.toml and the
+# "build frontend first" step in README.md) and a dev checkout that has run
+# ``npm run build`` resolve to the same relative path with no branching.
+_WEB_DIR = Path(__file__).parent / "web"
+
+# ── Desktop-style lifecycle (client presence over /api/ws) ──────────────────
+# The SPA holds a WebSocket open; the status bar's connected dot reflects it.
+# Auto-shutdown on last-tab-close is opt-in (env QZ_AUTO_SHUTDOWN=1, for the
+# future `qz --desktop` run model) so dev/tests are never killed.
+_clients = 0
+_ever_connected = False
+_AUTO_SHUTDOWN = os.environ.get("QZ_AUTO_SHUTDOWN") == "1"
+_SHUTDOWN_GRACE_S = 1.5  # tab refresh disconnects + reconnects within ~1 s
+
+
+async def _lifecycle_ws(ws: WebSocket) -> None:
+    """Client-presence socket: count live tabs; (optionally) shut down when the
+    last one drops past a refresh-safe grace window. Module-level to keep
+    create_app simple."""
+    global _clients, _ever_connected
+    # The HTTP middleware doesn't run on the WS upgrade — enforce the same
+    # Host + Origin + API-token checks here (closing before accept()).
+    if not host_allowed(ws.headers.get("host")):
+        await ws.close(code=1008)  # policy violation
+        return
+    if not origin_ok(ws) or not authorized(ws):
+        await ws.close(code=1008)  # policy violation
+        return
+    await ws.accept()
+    _clients += 1
+    _ever_connected = True
+    try:
+        while True:
+            await ws.receive_text()  # idles until disconnect
+    except WebSocketDisconnect:
+        pass
+    finally:
+        _clients -= 1
+        if _AUTO_SHUTDOWN and _clients == 0:
+            asyncio.get_running_loop().create_task(_grace_check())
+
+
+async def _grace_check() -> None:
+    """Exit unless a client reconnected within the grace window."""
+    await asyncio.sleep(_SHUTDOWN_GRACE_S)
+    if _AUTO_SHUTDOWN and _ever_connected and _clients == 0:
+        os._exit(0)
+
+
+@asynccontextmanager
+async def _app_lifespan(app: FastAPI):  # type: ignore[no-untyped-def]
+    """App lifespan: clean up the executor pool + dataset cache on shutdown."""
+    # Startup: sweep expired large-workbook transfer packages (Group F) from
+    # an EXISTING transfer dir -- never creates it, never fails startup.
+    try:
+        cleanup_transfer_dir()
+    except OSError:
+        logging.getLogger(__name__).warning("transfer-package cleanup failed", exc_info=True)
+    yield
+    # Shutdown: terminate the job executor with pending cancellation
+    jobs._pool.shutdown(wait=False, cancel_futures=True)
+    # RSM_CUTS_PLAN item 18: drop every cached dataset (local-server-
+    # hardening -- lifespan hook, never atexit).
+    _datasetcache.clear_cache()
+
+
+def create_app(
+    *, dev_origins: Collection[str] | None = None, api_token: str | None = None
+) -> FastAPI:
+    """Build the FastAPI app and wire the domain routers.
+
+    ``dev_origins`` are the only cross-origin pages (besides the Tauri shell)
+    allowed to call /api. None reads them from the environment, where
+    ``qz --dev`` exports the Vite port (``security.dev_origins_from_env``);
+    every other run mode leaves it unset, so the set is empty there.
+
+    ``api_token`` is the secret every /api route but /api/health needs
+    (``quantized.auth``). None takes ``QZ_API_TOKEN``, which the ``qz``
+    launcher exports, else a fresh random token."""
+    allowed_dev = frozenset(dev_origins_from_env() if dev_origins is None else dev_origins)
+    application = FastAPI(title="quantized", version=__version__, lifespan=_app_lifespan)
+    application.state.dev_origins = allowed_dev
+    application.state.api_token = resolve_token() if api_token is None else api_token
+    application.add_exception_handler(RequestValidationError, validation_error_handler)
+    # CORS read access for the Vite dev origin in --dev only (empty otherwise:
+    # the served SPA and the desktop shells are same-origin and need none).
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=sorted(allowed_dev),
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Body caps while the body streams (413) -- inside the guard, so an
+    # unauthenticated request is refused before its size matters.
+    application.add_middleware(BodyLimitMiddleware)
+    # Host, Origin and API-token checks, the SPA index cookie bootstrap and
+    # the CSP header -- see ``quantized.web_guard``. Registered last, so it is
+    # the outermost layer and refuses before anything reads a body.
+    application.middleware("http")(security_guard)
+
+    @application.get("/api/health")
+    def health() -> dict[str, str]:
+        # "app" is the identity field the launchers key on: the sibling
+        # fermiviewer serves the same {"status": "ok"} shape on the same
+        # default port (8000), and a probe that checks status alone adopts
+        # it — rendering the wrong app's UI in a Quantized window.
+        return {"status": "ok", "app": "quantized", "version": __version__}
+
+    application.include_router(parsers.router)
+    application.include_router(books.router)
+    application.include_router(samples.router)
+    application.include_router(import_wizard.router)
+    application.include_router(import_template.router)
+    application.include_router(plot.router)
+    application.include_router(datasets.router)
+    application.include_router(corrections.router)
+    application.include_router(database.router)
+    application.include_router(fitting.router)
+    application.include_router(fitting_bumps.router)
+    application.include_router(fitting_global.router)
+    application.include_router(fitting_stats.router)
+    application.include_router(jobs_api.router)
+    application.include_router(baseline.router)
+    application.include_router(stats.router)
+    application.include_router(stats_design.router)
+    application.include_router(stats_outliers.router)
+    application.include_router(stats_varcomp.router)
+    application.include_router(statplots.router)
+    application.include_router(reference.router)
+    application.include_router(export.router)
+    application.include_router(export_figures.router)
+    application.include_router(export_figures_aux.router)
+    application.include_router(export_statplots.router)
+    application.include_router(export_multivar.router)
+    application.include_router(export_page.router)
+    application.include_router(report_export.router)
+    application.include_router(magnetometry.router)
+    application.include_router(peaks.router)
+    application.include_router(peaks_batch.router)
+    application.include_router(reductions.router)
+    application.include_router(reflectivity.router)
+    application.include_router(reflectivity_graded.router)
+    application.include_router(rsm.router)
+    application.include_router(xray.router)
+    application.include_router(sld.router)
+    application.include_router(spectral.router)
+    application.include_router(crystallography.router)
+    application.include_router(structures.router)
+    application.include_router(electrical.router)
+    application.include_router(optics.router)
+    application.include_router(vacuum.router)
+    application.include_router(thermal.router)
+    application.include_router(diffusion.router)
+    application.include_router(electrochemistry.router)
+    application.include_router(substrates.router)
+    application.include_router(semiconductor.router)
+    application.include_router(thin_film.router)
+    application.include_router(superconductor.router)
+    application.include_router(magnetic.router)
+    application.include_router(aggregate.router)
+    application.include_router(transform.router)
+    application.include_router(sims.router)
+    application.include_router(calc.router)
+    application.include_router(workbook_transfer.router)
+
+    # Client-presence WebSocket (registered before the SPA mount so the
+    # catch-all StaticFiles route never shadows it).
+    application.websocket("/api/ws")(_lifecycle_ws)
+
+    # Load user/third-party plugins once (gap #8). Registration is isolated
+    # per-plugin and logged; a broken plugin never crashes startup. Cheap when
+    # none are installed (an empty dir scan + entry-point lookup). Fit-model /
+    # parser routes read the shared registries at request time, so plugin
+    # contributions are visible regardless of this call's position.
+    try:
+        load_plugins()
+    except Exception:  # pragma: no cover - load_plugins already isolates per-plugin
+        logging.getLogger("quantized.plugins").exception("plugin loading failed")
+
+    # Serve the built SPA at / when present (production / packaged runs). In a
+    # bare dev checkout the dir is absent and the Vite dev server serves the UI.
+    if _WEB_DIR.is_dir():
+        application.mount("/", StaticFiles(directory=_WEB_DIR, html=True), name="web")
+    return application
+
+
+app = create_app()