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>
4.3 KiB
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 (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
./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
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:
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:
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:
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
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.