chrome/README.md
Michał Kopeć 039b6f3711 Error bodies carry both keys, and /healthz can stand down
Both found by adopting the shell in scribe, which is older than chrome and
had conventions of its own.

chrome answered an API error with {"error": ...}. FastAPI's convention is
{"detail": ...}, and scribe's client reads exactly that:

    msg = (await r.json()).detail || msg

A missing key there does not fail - it falls back to r.statusText, so every
error message in the UI quietly becomes "Bad Request" and the real reason
is lost. That is the worst shape for a regression: no exception, no failing
request, just worse text. Both keys are sent now. marketplace and
agent-bridge read `error` and are unaffected.

chrome also registers /healthz, and being registered first it won over
scribe's - which reports whether whisper, piper and xtts are reachable,
the thing actually worth knowing when scribe is unwell. `health=False`
lets a service keep its own, the same way language_switcher=False already
lets it keep its own language control.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-04 20:54:24 +02:00

130 lines
4.3 KiB
Markdown

# chrome
The shared shell for the internal services: one page frame, one palette, one
set of components, one implementation of the handful of things every service
needs (config readers, proxy auth, `/healthz`, i18n, cache-busted assets).
It exists because the same stylesheet had been copied into four repositories
and had started to drift — along with `theme.js`, the `asset()` helper and
the error pages. A token change should be one commit here and a version bump
there, not four hand-edits with one forgotten.
## What's in it
| Module | Replaces |
|---|---|
| `chrome.app.Chrome` | per-service app factory boilerplate, error pages, static mounts |
| `chrome.config` | three near-identical `_bool`/`_int`/`_list` env readers |
| `chrome.auth` | agent-bridge's `Remote-User` + proxy-key check |
| `chrome.health` | four copies of `/healthz` |
| `chrome.i18n` | homepage's pl/en machinery, which nothing else could reuse |
| `chrome.assets` | two different cache-busting strategies, one of them broken in containers |
| `templates/base.html` | four page shells |
| `static/tokens.css` | four copies of the design tokens |
## UI components
[Web Awesome](https://webawesome.com) (MIT, Fonticons) is vendored under
`chrome/static/wa/`. The autoloader registers each `<wa-*>` element the first
time it appears, so there is no per-component import list.
Components are styled inside a shadow root, which means a page rule **cannot**
reach into one. That is the point: "this input is the wrong width" stops being
a thing that can happen. Customise through `--wa-*` tokens and `::part()`.
Note that Combobox, Date Picker, File Input and the chart components are
Web Awesome **Pro**, and are not vendored here. Use a native control or a
different component.
### Upgrading Web Awesome
```sh
./vendor-webawesome.sh 3.15.0 # then commit the diff
```
Plain `curl` and `tar` against the npm registry — no `npm install`, no
`node_modules`, no lockfile, nothing for CI or a Containerfile to run.
The script prunes type definitions and IDE metadata (~13M down to ~3.4M)
and keeps only the `en` and `pl` translations.
## Using it
```python
from fastapi import FastAPI
from chrome.app import Chrome
app = FastAPI()
ui = Chrome(
app,
service="marketplace",
version="0.2.0",
title="Skills Marketplace",
templates_dir=HERE / "templates",
static_dir=HERE / "static",
locales_dir=HERE / "locales",
)
@app.get("/")
def index(request: Request):
return ui.render(request, "index.html", things=[...])
```
Templates `{% extends "base.html" %}` and fill `content`. Service templates
and chrome's are both on the loader path, service first.
## Depending on it
Pin a tag, not a branch:
```toml
dependencies = [
"chrome @ git+https://git.wierzbowa.cloud/michal/chrome@v0.6.0",
]
```
For the edit loop, install it editable alongside the service:
`pip install -e ../chrome`.
## Theme convention
Pages use `data-theme="light|dark|system"` on `<html>`, which is what the
services have always used. Web Awesome drives light/dark from a `wa-light` /
`wa-dark` class instead; `base.html` and `theme.js` own that mapping, so no
service or stylesheet needs to know about it.
## Mounting under a prefix
A service whose reverse proxy forwards only certain path prefixes can move
both static trees underneath one of them:
```python
Chrome(app, ..., mount_prefix="/ui")
```
chrome's assets then live at `/ui/chrome/...` and the service's at
`/ui/static/...`, Web Awesome's versioned path included. agent-bridge needs
this: its design (D-0008) puts everything behind exactly two proxied
prefixes, `/ui` and `/api`, so a third top-level path would be unreachable
behind Caddy.
## Per-request page context
Flask's context processors, with the app object taken out:
```python
ui.page_context = lambda request: {"user": current_user(request)}
```
It runs on every render, because what it returns usually depends on who is
asking. An explicit value passed at the render site wins over it.
## Standing down the language switcher
```python
Chrome(app, ..., language_switcher=False)
```
For a service that stores the choice per **user** rather than per browser.
scribe keeps it in its database, so the language follows you to another
machine; chrome's cookie does not. Two switchers disagreeing about one
setting is worse than either alone.