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>
130 lines
4.3 KiB
Markdown
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.
|