# 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 `` 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 ``, 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.