- {title}
+{title}
++ {s.links.map((l) => ( + + {l.label} + + ))} +
+ )} +{title}
+
- 
- 
- 
-
-
- 
- Dark theme
+Light theme
+
+ 
+ 
+ 
+ ` and `
` intact. No other tag renders.
+- Translate a whole message. Word order, articles and punctuation move when the language changes.
+- Leave proper nouns and technical tokens as they are: Unsplash, Docker, URLs, environment variable names, HTTP header names.
+
+### Terms with a fixed meaning
+
+| Term | Meaning |
+| --- | --- |
+| tile | One item on the dashboard grid. |
+| badge | The small status readout drawn on a tile. |
+| folder | A tile that opens to hold other tiles. |
+| widget | A tile that runs its own page in a frame. |
+| Dock | The fixed row of tiles at the foot of the dashboard. |
+| upstream | The service a tile points at, not Stackyard. |
+| stale | The last reading is old. The service was not reached this time. |
+| unavailable | The service answered, and it is not working. |
+
+Some languages have words that must or must not be used. `ui/test/i18n-coverage.test.mjs` holds that list and fails on a forbidden word.
+
+## Fallback
+
+Fallback is per key, not per locale. A key missing from the selected language falls back to English on its own, and the rest of the page stays translated.
+
+A key missing from English too renders as the key itself. The reachability test fails the build before that reaches a reader.
+
+## Counted messages
+
+A message with a count is stored once per plural category. The language's own rules choose the category:
+
+```json
+"loaded_one": "Loaded {count} option",
+"loaded_other": "Loaded {count} options"
+```
+
+Call it with a numeric `count`:
+
+```js
+t('widgetCfg.loaded', { count: opts.length });
+```
+
+Never choose the form in code. `count === 1` is an English rule. French and Persian put zero in `one`, Chinese has one form for every count, and other languages have `few` and `many`.
+
+Read the categories a language uses from the runtime:
+
+```sh
+node -e "console.log(new Intl.PluralRules('fr').resolvedOptions().pluralCategories)"
+```
+
+Every category listed must exist in that catalog, and no others.
+
+## Add a key
+
+1. Add it to `ui/i18n/en.json`, under the section it belongs to.
+2. Add the same key to the other five catalogs.
+3. Reference it by its full dotted name, such as `t('general.logLevel')` or `data-i18n="general.logLevel"`, so the reachability test can see it.
+
+A key nothing references fails the test suite. So does a reference to a missing key, and English written straight into the source, which `ui/test/hardcoded-strings.test.mjs` catches.
+
+In static markup, name the key on the element:
+
+| Attribute | Sets |
+| --- | --- |
+| `data-i18n` | text content |
+| `data-i18n-html` | text content, with the allowed markup tags |
+| `data-i18n-ph` | `placeholder` |
+| `data-i18n-al` | `aria-label` |
+| `data-i18n-title` | `title` |
+
+## Add a language
+
+1. Add it to `LANGUAGES` in `ui/js/i18n.js`:
+
+ ```js
+ { code: 'it', name: 'Italiano', english: 'Italian', dir: 'ltr', status: 'machine' },
+ ```
+
+2. Copy `en.json` to `ui/i18n/it.json` and translate the values.
+3. Copy `en.json` to `ui/widgets//i18n/it.json` for every widget and translate those too.
+4. Split each counted message into the categories the language uses.
+5. Update the language table on this page.
+
+The language then appears under Settings, General, Language.
+
+## Development locales
+
+Two locales exist for testing and are never offered in the selector. Add `?lang=` to the dashboard or admin URL:
+
+```
+http://localhost:8080/?lang=en-XA
+http://localhost:8080/admin/?lang=cimode
+```
+
+- **`en-XA`** accents every letter, pads the text by about 40% and brackets each message. Clipped text, bad wrapping and joined fragments show up while still readable.
+- **`cimode`** loads no catalog, so every string renders as its key. Text that bypasses the translation system stands out.
+
+Neither is saved. `e2e/localisation.spec.js` loads the dashboard and Settings in `en-XA` and fails on any control whose text overflows without an ellipsis, at desktop and at 390px wide.
+
+## Validation
+
+```sh
+cd ui/test && node --test i18n.test.mjs i18n-reachability.test.mjs i18n-coverage.test.mjs widget-i18n.test.mjs i18n-markup.test.mjs
+```
+
+These run offline and contact no translation service.
+
+## Widget strings
+
+A widget frame never loads the dashboard i18n module. The selected code arrives on the frame URL as `lang`.
+
+Everything a widget shows, in its settings form and in the widget itself, comes from its own folder:
+
+```
+ui/widgets//
+ widget.json
+ i18n/
+ en.json the source
+ fa.json one file per language
+```
+
+In `widget.json`, write the key where the text would go:
+
+```json
+{ "key": "dnsUrl", "type": "text", "label": "dnsUrl.label", "hint": "dnsUrl.hint" }
+```
+
+`label`, `placeholder`, `hint`, `rowLabel` and `fetchLabel` are resolved this way. The API substitutes the selected language when it serves the manifest.
+
+In the widget page, ask the toolbox:
+
+```js
+import { loadStrings, wt } from '/js/widget-toolbox.js?v=1';
+await loadStrings();
+wt('ui.queriesBlocked', 'Queries Blocked');
+```
+
+Resolution is the selected language, then the widget `en.json`, then the text passed in. The toolbox has no counted-message form. A widget that needs one selects the category itself with `Intl.PluralRules`.
+
+See [Build your first widget](/docs/create-a-widget/).
diff --git a/src/content/docs/docs/create-a-widget/checklist.md b/src/content/docs/docs/create-a-widget/checklist.md
new file mode 100644
index 0000000..41144d3
--- /dev/null
+++ b/src/content/docs/docs/create-a-widget/checklist.md
@@ -0,0 +1,29 @@
+---
+title: Widget checklist
+description: What to check before opening a pull request for a new Stackyard widget.
+---
+
+CI validates every manifest. Run the same check locally with `cd api && node --test`.
+
+## Files
+
+- `widget.json` with `name` matching the folder, `label`, `sizes` and `fields`.
+- `data.js`, unless the widget runs entirely in the browser.
+- `index.html`.
+- `i18n/en.json`, plus one catalog per shipped language.
+- `demo.js`, optional.
+
+## Behaviour
+
+- Upstream calls go through `ctx.fetchJSON`.
+- Failures use `ctx.fail`, never a returned error.
+- Empty and failed look different.
+- The page calls no other host.
+- Spacing next to text uses logical properties.
+
+## Look
+
+- Transparent background, system font, palette colours.
+- Readable at every size it offers.
+
+A refused manifest is logged at startup and nowhere else. Check `docker logs `.
diff --git a/src/content/docs/docs/create-a-widget/data.md b/src/content/docs/docs/create-a-widget/data.md
new file mode 100644
index 0000000..9223aca
--- /dev/null
+++ b/src/content/docs/docs/create-a-widget/data.md
@@ -0,0 +1,104 @@
+---
+title: Widget data reference
+description: The data.js contract for a Stackyard widget. The ctx object, fetching upstream, option endpoints, reporting failures and demo mode.
+---
+
+`data.js` runs on the server, in Node, as CommonJS. It exports one async function that takes `ctx`. The saved config is on `ctx.config`.
+
+```js
+module.exports = async function (ctx) {
+ const { url, apiKey } = ctx.config;
+ const r = await ctx.fetchJSON(`${url}/api/items`, {
+ headers: { 'X-Api-Key': apiKey },
+ timeout: 8000,
+ });
+ return { items: r.data.slice(0, 10) };
+};
+```
+
+The return value is served as-is at `/api/widget-data/`.
+
+A widget that renders entirely in the browser, like [Clock](/docs/widgets/clock/) or [Dashboard switch](/docs/widgets/dashboard-switch/), ships no `data.js`.
+
+## ctx
+
+| Property | What it is |
+| --- | --- |
+| `ctx.config` | The saved widget config, secrets included. Server-side only. |
+| `ctx.settings` | A frozen copy of the dashboard settings shared with widgets. An allowlist, currently `stats` only. Everything else is withheld. To share another key, add it to `SHARED_KEYS` in `api/src/widget-settings.js`. |
+| `ctx.endpoint` | The endpoint name, set for an `optionsFrom` fetch or a multi-view widget. |
+| `ctx.row` | For an `optionsFrom` fetch from a field in a `group`, that row's values. Otherwise `null`. |
+| `ctx.params` | Extra query parameters, as `URLSearchParams`. |
+| `ctx.fetchJSON(url, opts)` | Fetches a URL and parses the body. Returns `{ status, data }` or throws. JSON is returned as-is. Prometheus text and XML are parsed. Pass `{ raw: true }` for the untouched text. |
+| `ctx.parsePrometheus(text)` | Parses a Prometheus metrics body. Non-string input gives an empty object. |
+| `ctx.normalizeBase(raw)` | Tidies a user-entered base URL: adds a scheme, drops a trailing slash. |
+| `ctx.metrics` | Host metrics: `cpuSample`, `ramPercent`, `cpuTemp`, `diskStats`, `procCount`, `uptimeSeconds`. Each is a function. `cpuSample()` is async and returns `{ cpu, iowait }`. They read `/proc` and `/sys`, so they report the host, not the container limits. |
+| `ctx.dispatchProvider(handlers, opts)` | Runs the handler for the provider the user picked. `opts.field` holds the key, `provider` by default. `opts.default` is the fallback key. |
+| `ctx.fail(message, opts)` | Reports a failure. Throws. `opts.kind` is one of `ctx.KIND`, `UPSTREAM` by default. |
+| `ctx.KIND` | `AUTH`, `INVALID`, `UPSTREAM`, `NETWORK`, `TIMEOUT`, `BLOCKED`, `INTERNAL`. See [API errors](/docs/contributing/api-errors/). |
+| `ctx.log` | The structured logger. |
+
+Keep every upstream call behind `ctx.fetchJSON`. It applies the SSRF guard, IP pinning, the size limit and the TLS setting.
+
+### Metrics and XML bodies
+
+Metrics are recognised from `application/openmetrics-text`, `text/plain; version=0.0.4`, or a bare `text/plain` containing a `# TYPE` comment. Other plain text comes back as a string.
+
+XML `data` is keyed by the root tag. Attributes and child elements become keys, a repeated tag becomes an array, and a text-only element becomes its text. Numbers convert only when they round-trip exactly, so `007` stays a string.
+
+Parsed XML and Prometheus objects have a null prototype. Use `Object.hasOwn(o, k)`, not `o.hasOwnProperty(k)`. A feed field called `__proto__` or `constructor` then stays an ordinary key.
+
+## Option endpoints
+
+A `select` with `optionsFrom` calls the same function with `ctx.endpoint` set:
+
+```js
+module.exports = async function (ctx) {
+ if (ctx.endpoint === 'lists') {
+ const r = await ctx.fetchJSON(`${ctx.config.url}/api/lists`, { /* ... */ });
+ return { options: r.data.map(l => ({ value: l.id, label: l.name })) };
+ }
+ return { items: [] };
+};
+```
+
+See [Options from the service](/docs/create-a-widget/manifest/#options-from-the-service).
+
+## Reporting a failure
+
+Throw. Never return an error as data.
+
+```js
+if (!config.apiKey) ctx.fail('API key not configured', { kind: ctx.KIND.INVALID });
+if (r.status === 401) ctx.fail('Auth failed, check the API key', { kind: ctx.KIND.AUTH });
+if (r.status >= 400) ctx.fail('Service HTTP ' + r.status);
+```
+
+A thrown failure becomes a 502. The frontend `poll()` counts it toward `staleAfter`, keeps the last good render, and reports how long ago the data was fresh. A returned `{ error: ... }` arrives as HTTP 200, and `poll()` records it as a success.
+
+Do not catch what `ctx.fetchJSON` throws. Letting it propagate classifies it: a refused connection as a network failure, a deadline as a timeout, the guard as blocked.
+
+Use `ctx.fail`, not `throw new Error`. A thrown message is replaced with a generic one before it reaches the browser, because it may carry a hostname, a path or an upstream body. Never build a `ctx.fail` message from an upstream response or a caught error. A status code is fine.
+
+An error field inside a successful result is a different thing, and correct. A widget reporting several services marks the one that failed and returns the rest:
+
+```js
+return { services: [{ name: 'VPN', error: 'Auth required' }, { name: 'Proxy', connected: true }] };
+```
+
+## Demo mode
+
+The public demo has no reachable services. A widget can ship `demo.js` beside `data.js`, returning an invented body. It runs only with `DEMO_MODE=true`.
+
+```js
+module.exports = function (ctx) {
+ const { wave, round } = ctx.demo;
+ return { items: [{ name: 'Example' }], total: Math.round(wave(600, 8, 20)) };
+};
+```
+
+It receives the same `ctx`, plus `ctx.demo` with `wave` and `round`. `wave(periodSec, min, max, phase)` is a clock-driven oscillation, so values drift between polls and every widget on the demo moves together. Build structural data, such as a calendar grid, once and cache it in a module-level variable.
+
+A widget with no `demo.js` runs its real `data.js` on the demo. [System summary](/docs/widgets/system-summary/) has none, because `ctx.metrics` already returns invented figures there.
+
+Only polling gets a demo body. An `optionsFrom` fetch always runs the real code.
diff --git a/src/content/docs/docs/create-a-widget/index.mdx b/src/content/docs/docs/create-a-widget/index.mdx
new file mode 100644
index 0000000..d055cb5
--- /dev/null
+++ b/src/content/docs/docs/create-a-widget/index.mdx
@@ -0,0 +1,83 @@
+---
+title: Build a custom Stackyard widget
+description: Build a Stackyard dashboard widget step by step, from the manifest to the data handler and the page that draws it.
+---
+
+import WidgetGroup from '../../../../components/WidgetGroup.astro';
+
+A widget is one folder in `ui/widgets/`. This page builds one from the template in the repository.
+
+`. The template returns `{ error }` when the URL is missing. Use `ctx.fail` as shown, so the widget shows its failure state. See [Data](/docs/create-a-widget/data/).
+
+## 4. Page
+
+```html title="index.html"
+
+```
+
+`poll()` fetches the data and handles loading, empty, stale and failed states. The template adds the markup and styles. See [Widget page](/docs/create-a-widget/widget-page/).
+
+## 5. Try it
+
+Restart Stackyard, then in Settings, **Dashboard**, press Add and pick **My Widget**. If it is missing, the container log says why.
+
+Before a pull request, go through the [checklist](/docs/create-a-widget/checklist/).
diff --git a/src/content/docs/docs/create-a-widget/manifest.md b/src/content/docs/docs/create-a-widget/manifest.md
new file mode 100644
index 0000000..0d42697
--- /dev/null
+++ b/src/content/docs/docs/create-a-widget/manifest.md
@@ -0,0 +1,191 @@
+---
+title: Widget manifest reference
+description: Every widget.json option for a Stackyard widget. Views, sizes, list icons, card backgrounds, field types and option pickers.
+---
+
+`widget.json` describes a widget: its `label`, the card `sizes` it offers, the settings form, and for a multi-view widget, its views.
+
+```json
+{
+ "name": "mywidget",
+ "label": "My Widget",
+ "sizes": ["small", "medium"],
+ "fields": [
+ { "key": "url", "type": "text", "label": "Service URL", "placeholder": "http://host:port" }
+ ]
+}
+```
+
+- **`name`** must match the folder name.
+- **`label`** is the name in the admin list and the type picker, and the default widget name when the user saves without one.
+- **`sizes`** is the set of card sizes offered: `small`, `medium`, `large`, `xlarge`.
+
+An invalid manifest is skipped at startup with a logged reason. Only that widget is disabled.
+
+## Views
+
+A widget can ship more than one page and let the user pick, like the [GitHub](/docs/widgets/github/) and [Clock](/docs/widgets/clock/) widgets. Declare each view and its file, the field that holds the choice, and the default:
+
+```json
+{
+ "viewField": "clockStyle",
+ "defaultView": "digital",
+ "views": {
+ "digital": { "label": "Digital", "src": "digital.html" },
+ "analog": { "label": "Analog", "src": "analog.html" }
+ }
+}
+```
+
+`viewField` names a field the user sets, usually a `select`. Its value is matched against the `views` keys. With no `views` block, the page is `index.html`. A single-view widget whose file is not `index.html` declares it as one view, with no `viewField`.
+
+`viewField` must name a declared field. If that field lists `options`, its values and the `views` keys must be the same set. A manifest that breaks either rule is rejected, because both failures are otherwise silent. A field using `optionsFrom` is not checked, since its choices are fetched at runtime.
+
+### Sizes per view
+
+A view can narrow the widget sizes, for a layout that works at one size only. The [Connections](/docs/widgets/connections/) map is Medium only:
+
+```json
+"views": {
+ "map": { "label": "Map", "src": "connections-map.html", "sizes": ["medium"] },
+ "vpn": { "label": "VPN", "src": "connections-vpn.html" }
+}
+```
+
+Each list must be a subset of the top-level `sizes`. A view without `sizes` offers all of them.
+
+## List icon
+
+Settings lists every item with an icon. A widget that names a `glyph` shows it. One that names none shows its card size.
+
+| `glyph` | What it depicts |
+| --- | --- |
+| `clock` | A dial and hands |
+| `weather` | A sun behind a cloud |
+| `gauge` | A dial with a needle, for a measured figure |
+| `shield` | A shield with record lines, for a name server |
+| `drive` | A drive with a trace across it |
+| `archive` | A store with an arrow into it |
+| `shelf` | Book spines |
+| `play` | A play mark in a frame |
+| `network` | Three linked nodes |
+| `merge` | Two branches joining one |
+| `panels` | Two panels, one handing over to the other |
+
+Two widgets may not name the same glyph. A test refuses it. A name not on this list is rejected at startup.
+
+## Card background
+
+The card behind a widget is glass by default: dark, semi-transparent and blurred, so the wallpaper reads through. A widget can name another:
+
+| `card` | What it looks like |
+| --- | --- |
+| `dark` | Solid dark, `#1c1c1e`. |
+| `light` | Solid white. |
+| `translucent` | Darker than the default but more transparent, with a stronger blur. |
+
+A `card` inside a `views` entry overrides the widget-level one for that view.
+
+Keep the default glass when the widget paints its own interior. The [Weather](/docs/widgets/weather/) widget does this, white by day and dark by night.
+
+Under the increased-contrast setting, `translucent` becomes as dense as the default card. An unknown name is rejected.
+
+## Field types
+
+| Type | What the user sees |
+| --- | --- |
+| `text` | An inline-edit row. |
+| `number` | An inline-edit row that stores a number. |
+| `secret` | An inline-edit row for a masked value. Shows `Configured` once set. The value stays on the server. Leaving it blank keeps the stored value. |
+| `toggle` | An on and off switch, stored as a boolean. |
+| `color` | The swatch and colour control used elsewhere in the admin. Saves `#rrggbb`. |
+| `select` | A dropdown. `"variant": "pills"` renders a radio group. With `optionsFrom` it adds a Fetch button. |
+| `multiselect` | A checklist dropdown. The value is an array. |
+| `group` | A repeatable set of sub-fields in a nested `fields` array, each entry its own card with Add and Remove. Groups cannot nest. |
+| `picklist` | A fixed number of dropdowns filled from one fetch. Saves an array, `null` where unset. Needs `count` or `countBySize`, plus `options` or `optionsFrom`. |
+| `object` | One nested set of sub-fields in a `fields` array, saved one level deep. Objects cannot nest. |
+
+## Field options
+
+| Key | Meaning |
+| --- | --- |
+| `label` | Shown to the user. Required. |
+| `placeholder` | The hint in an empty `text`, `number` or `secret` row. |
+| `default` | The value used when none is saved. |
+| `hint` | Short help under the field. On a `group`, it shows at the bottom of the section. |
+| `optional` | When `true`, the field is not required to save. A required `secret` counts as missing only when nothing is stored. |
+| `transient` | When `true`, the field is sent to an `optionsFrom` fetch but not saved. Use it for a search box. Top-level fields only. |
+| `carries` | For a `select` with `optionsFrom`: extra config keys this picker writes, from the chosen option's `set` block. |
+| `showIf` | Shows the field only when a sibling matches: `{ "field": "provider", "equals": "adguard" }`, or `{ "field": "provider", "in": ["adguard", "pihole"] }`. Anything else is rejected. |
+| `optionsFrom` | For a `select`: the data endpoint that returns the options at config time. |
+| `variant` | For a `select`: `"pills"` renders a radio group. |
+| `min`, `max` | For a `group`: the fewest and most entries. |
+| `maxBySize` | For a `group`: a cap per size, such as `{ "small": 2, "medium": 5 }`. Extra entries are trimmed on a smaller size. |
+| `countBySize` | For a `group`: a fixed row count per size, such as `{ "small": 1, "medium": 3 }`, with no Add or Remove. |
+
+## One key, asked for differently
+
+Two sibling fields may share a `key`, so the same value is asked for differently depending on another field. Give each one a `showIf`:
+
+```json
+{ "key": "url", "type": "text", "label": "Metrics URL", "placeholder": "conduit:9090",
+ "showIf": { "field": "type", "equals": "conduit" } },
+{ "key": "url", "type": "text", "label": "Management API URL", "placeholder": "netbird:33073",
+ "showIf": { "field": "type", "equals": "netbird" } }
+```
+
+Hidden fields are skipped when values are read back, so only the visible one saves. A repeated key without a `showIf` on every declaration is rejected. The validator does not check that the conditions exclude each other.
+
+## A fixed list of picks
+
+A `picklist` stores a plain array of ids, one per physical slot, filled from one call. [Disk health](/docs/widgets/disk-health/) uses it for bays:
+
+```json
+{ "key": "bays", "type": "picklist", "label": "Bays", "rowLabel": "Bay",
+ "optionsFrom": "devices", "countBySize": { "small": 4, "medium": 10 } }
+```
+
+One Fetch button loads the options once for every row. The saved value is always `count` entries long, such as `["sda-abc", null, ...]`.
+
+A `group` whose `min` equals its `max` is fixed-length too.
+
+## Nested settings
+
+Use `object` for config stored one level deep:
+
+```json
+{ "key": "vpn", "type": "object", "label": "Connection", "fields": [
+ { "key": "url", "type": "text", "label": "Control server URL" },
+ { "key": "apiKey", "type": "secret", "label": "API key", "optional": true }
+] }
+```
+
+That saves `{ "vpn": { "url": "...", "apiKey": "..." } }`. A sub-field `showIf` names a sibling inside the same object. Its secrets are scrubbed and kept like top-level ones.
+
+## Options from the service
+
+When a `select` can only be filled after the user enters a URL and key, give it `"optionsFrom": ""`. The form shows a **Fetch** button, which calls `data.js` with `ctx.endpoint` set to that name. Return `{ options: [{ value, label }, ...] }`.
+
+The fetch receives the current form values, `transient` fields included.
+
+An option can write other keys too. List them in `carries` and return them in the option's `set`. [Weather](/docs/widgets/weather/) stores coordinates this way:
+
+```json
+{ "key": "city", "type": "select", "optionsFrom": "geocode", "carries": ["lat", "lon"] }
+```
+
+```js
+return { options: [{ value: 'Ottawa, Ontario, Canada', label: 'Ottawa, Ontario, Canada', set: { lat: 45.42, lon: -75.7 } }] };
+```
+
+Saved values under carried keys are kept when the widget is edited without touching the picker.
+
+A `select` inside a `group` can use `optionsFrom`. Each row fetches on its own, and `ctx.row` holds that row's values:
+
+```js
+if (ctx.endpoint === 'jobs') {
+ const slot = ctx.row || {};
+ const r = await ctx.fetchJSON(`${ctx.normalizeBase(slot.url)}/api/jobs`, { /* ... */ });
+ return { options: r.data.map(j => ({ value: j.id, label: j.name })) };
+}
+```
diff --git a/src/content/docs/docs/create-a-widget/widget-page.md b/src/content/docs/docs/create-a-widget/widget-page.md
new file mode 100644
index 0000000..5afbef3
--- /dev/null
+++ b/src/content/docs/docs/create-a-widget/widget-page.md
@@ -0,0 +1,145 @@
+---
+title: Widget page reference
+description: The index.html side of a Stackyard widget. Frame parameters, the content policy, canvas sizes, text direction and the widget toolbox.
+---
+
+A widget page runs in a frame, scaled uniformly from a fixed design size to its card. It reads its `id` from the query string, fetches its own data, and draws it.
+
+- Keep styles and scripts inline or same-origin. There is no shared widget stylesheet.
+- Never call an external host. Reach a service through `data.js`.
+- The saved config, without secrets, is at `/api/widget-config/`.
+
+## Frame parameters
+
+| Parameter | What it is |
+| --- | --- |
+| `id` | The dashboard item id. Pass it to `/api/widget-data/` and `/api/widget-config/`. |
+| `size` | The size the user placed this widget at, one of the manifest `sizes`. |
+| `mobile` | `1` on the mobile layout, absent otherwise. |
+| `lang` | The selected language code. See [Translations](/docs/contributing/translations/#widget-strings). |
+| `v` | The cache version, stamped at release. Nothing to read. |
+
+## Canvas sizes
+
+| Size | Canvas |
+| --- | --- |
+| small | 170 × 170 |
+| medium | 360 × 170 |
+| large | 360 × 360 |
+| xlarge | 360 × 540 |
+
+Match the existing look: a transparent background, the system font stack, the dark palette. See [Design system](/docs/contributing/design-system/).
+
+## What a page may load
+
+The widget frame has a stricter Content-Security-Policy than the dashboard. Scripts and styles must be inline or same-origin. `connect-src` is `'self'`, so the only host a widget can call is Stackyard. Images may come from the icon CDN or a `data:` URI.
+
+## Text direction
+
+The dashboard sets the frame direction and language when it mounts the widget. A widget must not set `dir` on its own ``. In Persian the frame becomes right to left, and text, flex rows and grid columns reverse with it.
+
+Write spacing next to text with logical properties, so it reverses too:
+
+```css
+.flag { margin-inline-end: 5px }
+.meta { padding-inline-start: 13px }
+.left { border-inline-end: 1px solid rgba(255, 255, 255, 0.1) }
+```
+
+`left: 0; right: 0` is symmetric and needs no change. `left: 50%` with a translate is centring. Artwork is artwork, and mirroring it is usually wrong. `ui/test/rtl-logical-properties.test.mjs` enforces the rule for properties that carry text.
+
+Content that reads the same in every language, such as an IP address, a log tail or a chart axis, pins its own direction on the element:
+
+```html
+10.0.0.1
+```
+
+Never on the document. The test refuses `dir` on `` or ``, and `direction` on `html`, `body` or `:root`.
+
+## Mobile active state
+
+A widget with an interior state a tap turns on, such as a selected row, takes part in this protocol. Without it, two widgets end up active at once.
+
+```js
+parent.postMessage({ type: 'widget-active' }, window.location.origin);
+
+window.__clearActive = () => { /* drop the active state, hide any tooltip */ };
+```
+
+The dashboard resets every other widget when it receives the message, and calls `__clearActive` when a tap lands outside any widget. The frames are same-origin, so a widget needs no `message` listener. If you add one, check `e.origin` against `window.location.origin` first.
+
+## Off-screen pages
+
+Every dashboard page is mounted at once. The dashboard slows the polling of widgets on other pages through `window.__setPollRate`, which the toolbox defines. A widget that uses `poll()` needs nothing. A widget with its own timer must read the same hook.
+
+Returning to a page refreshes a widget at once when its data is older than one normal interval.
+
+## Cache busting
+
+Nothing to do by hand. The release build hashes each widget entry file and stamps the version into the manifest.
+
+## Toolbox
+
+Optional, and it bundles the pieces widgets keep needing. Import from `/js/widget-toolbox.js` and keep the `?v=1`:
+
+```js
+import { poll, fetchData, sparkline } from '/js/widget-toolbox.js?v=1';
+```
+
+### Data
+
+- `widgetId()` returns this widget id from the frame URL.
+- `fetchData(endpoint?)` fetches `/api/widget-data/` and returns the parsed JSON. Throws on a non-OK response.
+- `getConfig()` fetches this widget config, without secrets.
+
+### Polling
+
+`poll(opts)` runs the fetch and render loop and handles the loading, empty, stale and error states. A single failed poll never blanks a working widget.
+
+```js
+poll({
+ render: data => { root.textContent = `${data.items.length} items`; },
+ isEmpty: data => data.items.length === 0,
+ interval: 30000,
+});
+```
+
+A failure keeps the last good render. After `staleAfter` consecutive failures, 2 by default, it shows the failure and how long ago the last success was. `sinceLabel(ts)` gives that label on its own.
+
+The first fetch runs at once. Each repeat is spread by up to 15%, so widgets on one dashboard do not fetch on the same tick.
+
+### Failure and empty states
+
+Empty and failed are different claims and must look different. `isEmpty(data)` decides which applies. Without a custom handler, `poll()` draws both. With `onError`, add `onEmpty` too.
+
+`errorState(opts)` draws a failure state:
+
+```js
+const state = errorState({ root, content: chartEl, caption: metaLineEl });
+
+poll({
+ render: d => { state.ok(); draw(d); },
+ isEmpty: d => d.items.length === 0,
+ onEmpty: () => state.empty(wt('ui.noItems', 'Nothing here')),
+ onError: ({ error, everOk, stale, since }) => {
+ if (!everOk || stale) state.fail(error, { since, inert: everOk });
+ },
+});
+```
+
+- `content` is what goes inert. Without it, every child of `root` except the caption does.
+- `caption` is the widget metadata slot. Without one, a line is placed at the foot of `root`, or over its centre with `place: 'center'`.
+- `fail(err, { since, inert })` returns the line it drew. Pass `inert: false` when the widget never had data.
+- Set `--wt-cap-color` on a widget with a light card.
+
+The wording comes from the failure kind, not the upstream message. `errorLine(err)` returns the same wording for a widget with its own designed state.
+
+### Links, markup and visuals
+
+- `openUrl(href)` opens a link in a new tab. Use it instead of `window.open`, which the sandbox can block.
+- `esc(value)` HTML-escapes a value for `innerHTML`. Use it for anything from config or upstream.
+- `sparkline(values, opts?)` returns an `