---
name: wizget-widgets
description: Build custom desktop widgets for the Wizget app. Use when the user wants a custom Wizget widget — any data source, layout, colours, icons or size. Output one widget/1 JSON spec; the user pastes it into Wizget's widget editor (or it reaches Wizget via MCP when connected).
---

# Wizget widgets

Wizget puts widgets on the desktop. A widget is a single JSON object — the `widget/1` spec below.
You never write code, CSS or HTML. Your whole output is:

1. One line: what the widget does (for the user, not part of the JSON).
2. One fenced ```json block containing the complete spec. Nothing else.

The user pastes your output into Wizget's custom-widget editor, which extracts the JSON, validates
it, and places the widget — so the JSON must be complete and valid on its own. If the user's Wizget
has MCP connected you may instead call its tools (list_widgets, create_widget, validate_spec…);
the rules below are identical either way.

## Rules

- `schema` must be `"widget/1"`. `id` is kebab-case, unique, and becomes `custom:<id>`.
- `size` is one of `1x1`, `2x1`, `2x2`, `3x1`, `3x2` — the base size; users can still resize.
- `tone` is one of `canary`, `green`, `red`, `blue`, `orange`, `violet`, `teal`, `pink`, `gray`.
- Every `{{path}}` in `view` must resolve to `data` output, `sample` fallback, a `sources` field,
  a `{{param.X}}` declared in `needs`, or a credential `{{cred.X}}` — never invent paths.
- Keep the layout inside the card: use `gap`/`wrap`, avoid fixed pixel assumptions, and pick a
  size the content actually fits at.
- Prefer `native` sources (local, instant, no key) over `http` ones. When you need the web, use
  `http` sources and declare `credentials`/`auth` and `hosts`.
- If the widget can't work without user input (a repo, a city, an API key), declare it under
  `needs` (param) or `credentials` — never hardcode personal values.

## When the user asks what widgets to make

If the user asks which widgets would help them, or doesn't know where to start, suggest widgets
made for them, not a generic list. Use what you already know about them: your memory, past
conversations, their work, projects, tools, accounts, routines and goals. Don't make them describe
themselves first.

1. With MCP, call `list_widgets` and `list_custom` first so you don't suggest what they already
   have, and `list_gallery` to reuse a built-in widget where one fits.
2. Suggest 5–8 widgets, most useful first. For each give a short name; one line on why it helps
   *them*, pointing to what you know ("you check Stripe every morning…"); what it shows or lets
   them do; and what it needs (nothing, an API key for a named service, or a value like a city).
   Mix widgets that keep a number up to date with ones they act on (to-dos, timers, counters,
   checklists).
3. Suggest only what this guide can build: built-in sources, or `http` APIs the service really
   offers. Leave out anything that can't be built.
4. Ask which ones to make, then build each one. With MCP, use `create_widget`, look at the
   screenshot it returns and fix the spec until it looks right. Without MCP, reply with one spec
   per widget, each in its own ```json block.

If you know little about them, suggest a starter set from what they've said so far and ask one
short question about their work or day.

The complete authoring reference — every node, source id, field and examples — follows.

---

# Building a Wizget widget

This is the guide an AI reads before it writes a widget. A widget is one JSON file in the
`widget/1` format: where its data comes from, and how the card shows it. You never write code —
only this JSON (the `Html` node's `html`/`css` fields are markup for the card, not app code).
The contract is [`widget.schema.json`](widget.schema.json); every file in [`gallery/`](gallery) is
a working example to start from.

**Stay inside the spec.** You are a client of the app, not its author. Use only the sources,
nodes and fields this guide lists. If the data a widget needs has no source, say so — do not
modify Wizget's code, config or any other files to get it, and do not invent source ids.

## The shape of a widget

```json
{
  "schema": "widget/1",
  "id": "timer",
  "name": "Timer",
  "description": "A countdown that starts in one click.",
  "category": "focus",
  "size": "2x1",
  "tone": "blue",
  "sources": { "timer": { "kind": "native", "id": "focus.timer", "params": { "minutes": 5 } } },
  "sample": { "timer": { "remaining": 272, "progress": 0.1, "running": true, "toggleIcon": "ph:pause" } },
  "active": { "bind": "timer", "path": "running" },
  "view": { "type": "Stack", "children": [ ... ] }
}
```

- **sources:** up to 6, each under a name you pick (`timer` above). The view reads each one by
  that name. A source is `native` (built into Wizget, listed below) or `http` (any web API with a
  key, see [Web APIs](#web-apis-the-http-source)).
- **data** (optional): named results worked out from sources with fixed steps (sum the last 30
  days, one point per day). The view binds to these names like it does to sources.
- **sample:** example data for each source name, in the same shape the source gives. The gallery
  shows it before the widget is on a desktop, and the widget shows it while real data loads.
- **view:** the components, nested. Any value can be a literal or a binding to source data.
- **size:** `1x1`, `2x1`, `2x2`, `3x1` or `3x2` cells. One cell is 160 px with 16 px padding inside the
  card, so a `2x1` has about 288 × 128 px of room.
- **tone:** the widget's colour: `canary`, `green`, `red`, `blue`, `orange`, `violet`, `teal`,
  `pink` or `gray`. Pick a colour that means something: red for focus, green for money and done,
  blue for time, orange for activity.
- **active** (optional): a binding that's `true` while something runs. The card then gets an
  outline in its tone.

## Bindings and text

- `{ "bind": "timer", "path": "remaining", "format": "clock" }` reads `remaining` from the `timer`
  source and formats it.
- A string can hold templates: `"{{todo.open}} left"`, with a format after a bar:
  `"{{month|money}} this month"`, `"{{share|percent}}"`.
- Formats: `number` (1,234), `compact` (12.4k), `percent` (0.42 or 42 → 42%), `duration` (seconds →
  3h 12m), `clock` (seconds → 4:59), `clock:tenths` (0:42.3), `relativeTime`, `time`,
  `time:seconds`, `date:short`, `date:long`, `weekday`, `currency:USD`, and `money` (an amount in the
  currency its data carries, from `{ "value": 4820, "currency": "EUR" }`; USD when it has none).

## Components

| Component | What it shows | Main fields |
|---|---|---|
| `Stack` | Children top to bottom | `children`, `gap` (xs, sm, md, lg), `align` |
| `Row` | Children side by side | `children`, `gap`, `align` (start, center, end, between) |
| `Label` | The widget's name with its icon tile | `text`, `icon` |
| `Text` | A line of text | `text`, `size` (sm, md, lg) |
| `Metric` | One big number, optional change arrow and caption | `value`, `delta`, `caption`, `size` (md, lg, xl) |
| `Progress` | A bar, pinned to the bottom of the card | `value`, `max` |
| `Ring` | A ring with a label in the middle | `value`, `max`, `text` |
| `Dots` | Steps as dots, like Pomodoro rounds | `value`, `max` |
| `Grid` | A dense grid of dots filling up, like the year's days | `value`, `max` |
| `Gauge` | A semicircle with a needle, like a fuel gauge | `value`, `max`, `text` |
| `Sparkline` | A line with a soft fill | `series`, `y` |
| `BarChart` | Bars | `series`, `y` |
| `List` | Rows of `{title, subtitle?, value?}` | `items`, `limit`, `placeholder` |
| `Logo` | A brand mark in a tile | `icon` (`logo:github` …) |
| `Button` | A control that runs a source action | `action`, `icon`, `text`, `variant` (round, soft, ghost), `size` |
| `Input` | A text or number field, or a slider | `action`, `kind` (text, number, slider), `value`, `placeholder` |
| `Notes` | A text area that saves as you type | `value`, `action`, `placeholder` |
| `Checklist` | Rows of `{id, title, done}` with tick boxes | `items`, `action` (toggle), `remove`, `limit`, `placeholder` |
| `Timeline` | A day on one line | `from`, `to` (hours), `activity`, `blocks`, `sun` |
| `AnalogClock` | An analog face with sweeping hands | `value` (bind to `hands`), `tone` |
| `NowPlaying` | A music player that lays itself out by the card's size (art, title, progress, prev/play/next) | `value` (bind to a `media.nowPlaying` source), `action.source` (that source's name), `tone`, `compact` (one line) |
| `FlipClock` | Split-flap digits | `value` ("14:32"), `tone` |
| `SegmentClock` | A seven-segment display | `value` ("14:32:05"), `tone` |
| `WeekStrip` | This week as a strip of cells, today lit | `items` (`{title, value, today}`), `tone` |

Icons are Phosphor names: `"ph:timer"`, `"ph:calendar-dots"`. A `Button`'s icon can be a binding,
so a play button can follow the source: `"icon": { "bind": "timer", "path": "toggleIcon" }`.

**Controls only run actions.** `"action": { "source": "timer", "do": "toggle" }` calls the
`toggle` action of the source named `timer`. Each source lists its actions below; nothing else
can run. An `Input` of kind `text` sends its text on Enter and clears itself. Kind `number`
sends the number on every change; `slider` (0–1 `value`, bound) sends 0–100 on every change.

## Built-in sources

Use `{ "kind": "native", "id": "<id>", "params": { … } }`. Each source gives the fields listed;
bind to them by `path`. A source with **setup** asks the user for those settings on the widget
itself the first time (you can leave them empty). Add `"optional": true` to a source so its setup
can be skipped.

### Time and focus

**`clock`**: the current time as an ISO string. Format it with `time`, `date:long` and so on.

**`countdown`**: days until a date.
Params: `to` (YYYY-MM-DD), `label`.
Fields: `value` (days), `label`, `date`.

**`focus.timer`**: a countdown timer. It keeps running while Wizget is closed.
Params: `minutes` (default 5).
Fields: `remaining` (s), `total` (s), `minutes`, `progress` (0–1), `status` (idle, running, paused,
done), `running`, `toggleIcon`.
Actions: `toggle` (start, pause, resume; restarts when done), `reset`, `add` (arg: minutes, may
be negative).

**`focus.stopwatch`**
Fields: `elapsed` (s, with fractions), `running`, `status`, `lapCount`, `toggleIcon`, `laps` (list,
newest first: `title` "Lap 3", `value` the lap's split, `subtitle` the total).
Actions: `toggle`, `lap`, `reset`.

**`focus.pomodoro`**: focus rounds with breaks. A finished phase moves to the next one and waits
for Start. Finished focus rounds go into the shared focus log.
Params: `focus` (min, default 25), `break` (5), `longBreak` (15), `rounds` (4, a long break after this
many).
Fields: `phase` (focus, break, long), `phaseLabel`, `remaining`, `total`, `progress`, `round`,
`rounds`, `running`, `status`, `doneToday`, `toggleIcon`.
Actions: `toggle`, `skip`, `reset`.

**`focus.log`**: today's finished focus rounds, as a list of `{start, end}` (ms). Use it in a
Timeline's `blocks`, or `{{focus.length}}` for the count.

**`focus.todos`**: a to-do list kept on the computer.
Fields: `items` (`{id, title, done}`, open first), `open`, `done`, `total`, `progress`, `next`
(the first open task's title).
Actions: `add` (arg: text, from a text `Input`), `toggle` (arg: id), `remove` (arg: id), `clearDone`.

**`focus.notes`**: one note kept on the computer.
Fields: `text`, `updatedAt`, `words`.
Actions: `set` (arg: the whole text, from `Notes`).

**`setting`**: a value the user types once on the widget, like a monthly goal. Put the question
in the source's `needs`: `{ "param": "value", "label": "Your monthly goal", "placeholder": "5000" }`.
Field: `value` (a number when it looks like one).

Any native source can take extra `needs`; the answers become its params.

### Calendar, money, the day

**`calendar.ical`**: upcoming events from a calendar's private iCal link (Google, Outlook,
iCloud, Fastmail). Repeating events, skipped dates and moved occurrences are handled.
Setup: `url`. Params: `days` (how far ahead, default 7).
Gives a list: `title`, `subtitle` ("in 25 min", "Tomorrow", with the place), `value` (start time
or "All day"), `start`, `end` (ms), `allDay`. Show it with `List`, or as Timeline `blocks`.

**`money.currency`**: converts an amount at the European Central Bank's daily rate
(Frankfurter, no key).
Setup: `from`, `to` (currency codes). Params: `amount`.
Fields: `pair` ("USD → EUR"), `amount`, `rate`, `result` (formatted in the target currency),
`rateText`, `asOf`.
Actions: `amount` (arg: number, from a number `Input`), `swap`.

**`system.screenTime`**: time in front of the computer today, recorded by Wizget every 5 s while
it runs (the app in front; time away from the keyboard doesn't count). macOS now, Windows soon.
Fields: `value` (s today), `todayText`, `hours` (24 × `{t, v}`, minutes), `dayHours` (minutes per
hour so far today, for `BarChart`), `activity` (24 × seconds, for `Timeline`), `apps` (list:
`title`, `value` like "1h 20m"), `top`, `weekAvg`, `weekAvgText`, `days` (`{t, v}` hours per day).

**`sky.sun`**: sunrise and sunset for a city (Open-Meteo, no key).
Setup: `city` (optional).
Fields: `city`, `sunrise`, `sunset` (ms), `sunriseText`, `sunsetText`, `frac` (where the sun is,
0–1, for `Gauge` or `Progress`), or nothing until a city is set. Use as a Timeline's `sun`.

### The machine itself

A 1 Hz sampler in the app keeps one snapshot of the computer; every `system.*` source reads its
fields out of it (see `app/src-tauri/src/system.rs`).

**`system.cpu`**: processor load.
Fields: `value` (0–1), `top` (the three busiest apps: `{title, value}` like "18%").

**`system.ram`**: memory in use.
Fields: `value` (0–1), `used`, `total` ("5.1 GB"), `top` (three biggest apps: `{title, value}`).

**`system.battery`**: charge level, or nothing on a desktop with no battery.
Fields: `supported`, `note`, `value` (0–1), `state` (Charging, On battery, Full), `charging`,
`cells` (0–12, for `Dots`), `dots` (0–10).

**`system.devices`**: this computer's battery plus every connected Bluetooth device that reports
one — each earbud and its case separately, headphones, keyboards, mice, controllers (macOS now).
Fields: `list` (`{title, kind, level` 0–1`, pct, value` "54%"`, charging, bolt` "on" while
charging`, low` "low" at 20% or less`, icon}`), `count`, `any`. `icon` is a Phosphor class
(`ph-fill ph-laptop`) or, for earbuds, `bud-left`/`bud-right`/`bud-case`, which an `Html` node's
CSS draws. Refreshes every minute.

**`system.network`**: download and upload speed.
Fields: `down`, `up` (B/s), `downText`, `upText` ("3.2 MB/s"), `series`, `upSeries` (the last
30 samples, for `Sparkline`).

**`system.disk`**: free space on the system drive.
Fields: `value` (0–1 used), `freeText`, `used`, `total`.

**`system.temp`**: CPU temperature, where a sensor reports one.
Fields: `supported`, `note`, `value` (°C), `cpu`, `mem` (0–1 each).

**`system.brightness`**: display brightness (Windows and Linux).
Fields: `supported`, `note`, `value` (0–1), `pct`.
Actions: `set` (arg: 0–100, from a `slider` Input).

**`system.theme`**: Windows dark or light mode.
Fields: `supported`, `dark`, `label`, `icon`.
Actions: `toggle`.

**`system.os`**: the desktop shortcuts a taskbar gave you — Windows only, marked so on the widget.
Fields: `supported`, `windows`, `state`, `lang` (the keyboard layout's name), `dark`.
Actions: `open` (arg: `quickSettings`, `notifications`, `showDesktop`, `tray`, `language`,
`keyboard`, `taskManager`, `dnd`).

**`media.nowPlaying`**: whatever is playing, from the OS media controls — every app counts.
Fields: `supported`, `title`, `artist`, `album`, `art` (a `data:` URL, for a `Logo` node's `icon`),
`playing`, `toggleIcon`, `position` (0–1), `elapsedText`, `durationText`.
Actions: `toggle`, `next`, `prev`.

**`audio.volume`**: the current speaker or headphone volume.
Fields: `supported`, `note`, `value` (0–1), `pct`, `muted`, `icon` (follows the level),
`muteLabel`, `muteIcon`.
Actions: `set` (arg: 0–100, from a `slider` Input), `toggle` (mute).

**`audio.mic`**: the microphone's mute state.
Fields: `supported`, `note`, `muted`, `label`, `icon`, `toggleLabel`.
Actions: `toggle`.

**`apps.notifs`**: the toasts in Windows' notification centre, filtered to one app.
Setup: `app` — which app's notifications to count (empty means WhatsApp). Windows only.
Fields: `supported`, `note`, `app`, `count`, `lastTitle`, `lastText`, `list` ([{title, value}]).

**`apps.running`**: the apps with windows open right now (EnumWindows / NSWorkspace).
Fields: `supported`, `state` ("Start" on Windows, "Launchpad" on macOS), `count`,
`apps` ([{title}] for a `List`).
Actions: `start` (opens the platform's app menu — Start or Launchpad).

**`files.recent`**: files you opened recently (%APPDATA%\Recent on Windows, `mdfind` on macOS).
Fields: `files` ([{title, path}] for a `List`).
Actions: `open` (arg: a path).

**`files.bin`**: the recycle bin / trash.
Fields: `count`, `sizeText`, `label`, `emptyLabel`.
Actions: `empty` (empties the bin).

**`files.open`**: open something — a path opens in the file manager, a URL or domain
opens in the browser, anything else is searched on the web.
Actions: `go` (arg: the typed text).

**`files.launch`**: launch an app by name (`start` on Windows, `open -a` on macOS).
Actions: `go` (arg: the app name).

**`files.shot`**: take a screenshot via the OS tool (Win+Shift+S / `screencapture`).
Actions: `go` (arg: `region`, `window`, or `screen`).

**`files.wallpaper`**: a small photo gallery (picsum, no key needed).
Fields: `photos` ([{title, value}] for a `List`).
Actions: `set` (downloads a random pick and sets it as the desktop wallpaper).

**`clock.zone`**: the time in another place.
Setup: `zone` — a city name (geocoded) or an IANA zone like "Asia/Tokyo"; empty means local.
Fields: `name`, `value` ("14:32"), `text` ("14:32:05"), `offset` ("GMT+9"), `h`/`m`/`s`,
`hands` ([fractional hour, minute, second] for `AnalogClock`), `dayText`, `dateText`.

**`time.today`**: today's date in fields, plus this week for `WeekStrip`.
Fields: `day`, `month`, `year`, `weekday`, `date`, `days` (7 × `{title, value, today}`).

**`sky.weather`**: temperature now and the week's highs, from Open-Meteo (no key).
Setup: `city` (optional).
Fields: `city`, `value` (°C), `high`, `low`, `label`, `icon`, `wind` (km/h), `precip` (mm),
`details` (wind/rain/high/low rows for `List`), `days` (7 × `{title, value, today}`),
`forecast` (next 3 days: `{title, value, subtitle}`), `hours` (next 6 h).

**`time.progress`**: how much of today, the month or the year is behind you — pure calendar math.
Params: `of` (`day` default, `month`, `year`).
Fields: `value` (0–1), `name` ("Today", "November", "2026"), `left`, `day`, `totalDays`,
`dots`/`dotsMax` (hours today, days this month, or days this year — for `Dots`/`Grid`).

### AI plan usage

How much of an AI subscription is left, read from the sign-ins the tools already keep on the
PC — `~/.claude/.credentials.json`, `~/.codex/auth.json`, `~/.gemini/oauth_creds.json`,
`~/.grok/auth.json`, the Cursor app's `state.vscdb`, OpenCode's `opencode.db`. Nothing new to
log in to; each call goes to that provider's own API. Every reading is cached, so an expired
sign-in still shows the last good numbers with `stale` set and the widget can say "last seen".

Each source reads one provider and returns the same shape:
Fields: `id`, `name`, `ok`, `note` (what to do when `ok` is false — "run claude once"),
`plan`, `items` (raw windows `[{label, pct, resets, text}]`), `first`/`second` (the first two
windows, each `{label, pct, text, subtitle}`), `list` (List-ready `{title, subtitle, value}`),
`foot` (small print), `stale`, `at`.

- **`ai.claudeCode`** / **`ai.claude`**: Claude's 5-hour and weekly windows from Claude Code's
  OAuth file → api.anthropic.com/api/oauth/usage. Extra usage when the plan has it.
- **`ai.codex`**: ChatGPT's 5h and weekly Codex windows → chatgpt.com/backend-api/wham/usage.
- **`ai.gemini`**: the Gemini CLI's Pro/Flash quota left (its OAuth is refreshed for you).
- **`ai.grok`**: SuperGrok credit use and on-demand spend → cli-chat-proxy.grok.com.
- **`ai.cursor`**: the Cursor plan's requests and on-demand spend → cursor.com/api/usage-summary.
- **`ai.opencode`**: session/today/week tokens summed from OpenCode's local SQLite history
  (local only — no network call).
- **`ai.deepseek`** / **`ai.glm`**: the only two that take a key — they declare `credential` +
  `host` on the source, so setup asks for the key exactly like an http source and the keychain
  binds it to `api.deepseek.com` / `api.z.ai`.

**`ai.limits`**: reads every provider at once and flattens the two with data to show.
Fields: `aName`/`aPlan`/`aPct`/`aText`/`aLabel`/`aResets`/`aOk`, the same `b…` set,
`count`, `any`, `notes` (providers missing a sign-in). Params `a`/`b` pin a provider each
("claude", "chatgpt", …); empty means auto-pick.

## Web APIs: the `http` source

For anything with a web API and a key (payments, analytics, issues, email…), describe one request;
Wizget makes it, pages through the reply, and maps it to rows. Start from the closest example:
[`stripe.json`](gallery/stripe.json) (cursor paging), [`dodo-payments.json`](gallery/dodo-payments.json)
(page numbers, live or test), [`lemon-squeezy.json`](gallery/lemon-squeezy.json) (next links, sums of
fields), [`shopify.json`](gallery/shopify.json) (a key in a header, the user's own store),
[`polar.json`](gallery/polar.json) (an API that already gives one row per day).

```json
"credentials": {
  "cred_stripe": { "label": "Stripe", "help": "In Stripe: Developers, API keys, Create restricted key, with Read on Balance.", "placeholder": "rk_live_…" }
},
"sources": {
  "pay": {
    "kind": "http",
    "request": {
      "url": "https://api.stripe.com/v1/balance_transactions",
      "query": { "limit": 100, "created[gte]": "{{now-60d|unix}}" },
      "auth": { "credential": "cred_stripe", "as": "bearer" }
    },
    "paginate": { "cursor": { "param": "starting_after", "from": "$.data[-1].id" }, "while": "$.has_more", "max": 10 },
    "shape": "series",
    "map": { "items": "$.data", "t": "created", "v": "net|cents", "type": "type", "currency": "currency" }
  }
}
```

**Keys.** Never put a key in a spec. Name it in `credentials` (`cred_` and lowercase), with a
`label` and `help` that says where in the provider's dashboard to make a **read-only** key. The
user pastes it on the widget the first time; it goes to the system keychain and is only ever sent
to the hosts this widget's requests go to. Widgets that name the same key share it. `auth.as` is
`bearer`, `basic`, `header:<Name>` or `query:<name>`.

**Request.** `method` (GET or POST), `url` (https only), `query`, `headers`, `body` (JSON, for POST
and GraphQL). Templates inside them: `{{now}}`, `{{now-30d}}`, `{{now-month}}` (the first of this
month) as `|iso` (default), `|unix` (seconds), `|ms` or `|date` (YYYY-MM-DD); and
`{{param.<name>}}` for an answer from the source's `needs` (a store name, `live` or `test`).

**Setup questions.** `needs` on the source: `{ "param": "mode", "label": "Live or test mode",
"options": ["live", "test"] }` (a choice) or with a `placeholder` (text). `params` gives defaults.
`"optional": true` adds Skip; a skipped source gives no rows (Total revenue's stores).

**Paging.** At most `max` requests (default 5, up to 20), and only while `while` is true:
- `cursor`: pass the value at `from` as the query `param` (`$.data[-1].id` is the last row's id).
- `page`: page numbers in `param` from `start`, until a page comes back short or empty.
- `next`: follow the link at this path (`$.links.next`) until it's missing.

**Map.** `items` is where the rows are. Every other key is a field to keep, read from each row:
a path (`attributes.status`), arithmetic with the usual precedence and number literals
(`total_usd - tax_usd - refunded_amount_usd`, `percent_change / 100`, `close / previous_close - 1`;
missing fields count as 0), and a conversion after a bar: `|cents` (÷ 100), `|number`, `|unix`
(seconds → ms), `|date` (text → ms), `|lower`, `|re:<pattern>` (a regex capture group — for
replies that aren't JSON at all; the raw body is then `$.text`). `=USD` is a fixed value for a field the API
doesn't send. Name the time `t` and the amount `v`: times become ms on their own, and charts and
steps use `t` and `v` unless told otherwise. Keep `currency` when the API sends it.

**Shapes.** `series` and `list` give rows. `metric` and `progress` read one reply: each map key is a
path into the reply (`{ "value": "$.balance.available|cents" }`), no `items`.

### Data steps

Each `data` entry reads `from` a source or an earlier entry (several are merged as rows), then runs
its `ops` in order:

| Step | Does |
|---|---|
| `window` | Keeps rows in the `last` span (`"30d"`) or `since` the start of `today`, `week`, `month`, `year` |
| `filter` | Keeps rows whose `field` is `eq` a value, `ne` a value, or `in` a list |
| `sort`, `topN` | By `field` (`desc`), or the `n` largest |
| `groupBy` | One row per `day`, `week` or `month`, summed; with `last`, empty days are 0 (for charts) |
| `sum`, `avg`, `min`, `max`, `count`, `first`, `last` | One number from the rows (`field`, default `v`); sums keep the currency |
| `streak` | Days in a row with `v` > 0, ending today (or yesterday while today is still empty) |
| `periodChange` | This `period` against the one before, as 0.18 for up 18% (for `Metric`'s `delta`) |
| `pace` | A month-so-far total projected to the whole month |
| `ratio` | This value divided by another entry's (`"of": "goal.value"`) |

```json
"data": {
  "sales": { "from": "pay", "ops": [{ "op": "filter", "field": "type", "in": ["charge", "refund"] }] },
  "total": { "from": "sales", "ops": [{ "op": "window", "last": "30d" }, { "op": "sum" }] },
  "change": { "from": "sales", "ops": [{ "op": "periodChange", "period": "30d" }] },
  "daily": { "from": "sales", "ops": [{ "op": "groupBy", "by": "day", "last": "14d" }] }
}
```

Fetch twice the span you compare (`now-60d` for a 30-day change). Set `refresh` (`"15m"`; at least
a minute). When a request fails, the widget shows the provider's own error message and an Edit
settings button.

## Custom styling (theme + Html)

The default theme covers most widgets. When the owner asks for a specific look — "dark terminal",
"match this design", "use my brand colors" — the spec can restyle everything:

**`theme` (on the spec, optional):** set only what differs.

```json
"theme": {
  "bg": "#0b0e14",            // card background — color or gradient
  "fg": "#e6edf3",            // text color
  "accent": "#a8ff3e",        // overrides tone everywhere it paints
  "font": "JetBrains Mono",   // font family for the whole widget
  "radius": 12,               // corner radius px
  "pad": 14,                  // card padding px
  "css": ".wg-text { letter-spacing: .05em }"   // raw CSS — scope selectors under .wg
}
```

`font` only names the family — to load a webfont, `@import` it inside `theme.css`
(e.g. Google Fonts; remote fonts are allowed).

**`Html` node — the full escape hatch:** raw markup in a shadow root, so your CSS is completely
isolated from the widget kit (and can't break it). Use it when the built-in nodes can't express the
design — custom layouts, tables, avatars, branded cards:

```json
{ "type": "Html",
  "html": "<ul class=\"lb\">{{#each lb.rows}}<li><img src=\"{{avatar}}\"><b>{{name}}</b><i>{{revenue}}</i></li>{{/each}}</ul>",
  "css": "ul.lb{list-style:none;margin:0;padding:0;display:grid;gap:10px} .lb li{display:flex;align-items:center;gap:10px} .lb img{width:28px;height:28px;border-radius:50%}" }
```

- `{{source.field}}` and `{{source.field|format}}` fill live data, same as Text.
- `{{#each source.path}}…{{/each}}` repeats a block per array item; inside it `{{field}}` reads the
  item, `{{idx}}` is the 1-based index.
- Remote images (`<img src="https://…">`) and `@import` stylesheets work.
- It's display-only — put interactive nodes (`Button`, `Input`) outside it.
- Escape `{{` isn't supported; keep JS out — no `<script>`.

Prefer built-in nodes when they fit — they get hover/drag/menu behavior and the native look for
free. Reach for `Html` when the brief is a specific design or the nodes genuinely can't do it.

## Make it look right

A widget lives on someone's desktop — it should look like it belongs there, not like a wireframe.
After `create_widget`/`update_widget` the reply includes a **PNG of the widget as rendered**. Look
at it before you call the job done, and fix what you see:

- **Fill the card.** Dead space at the bottom is the most common defect — it means the size is too
  big for the content or the layout doesn't stretch. Pick a `size` the content fills, and after
  placing, read `contentHeight` from `list_widgets` — if it's much less than the window height,
  `resize_widget` to fit it (leave ~8px of air).
- **Visuals over text.** If the widget has one number that matters, show it as a `Metric`,
  `Ring`, `Gauge` or `Progress` — not another row of `Text`. A leaderboard is a `List`, a trend
  is a `Sparkline`/`BarChart`, a share is a `Ring`. A card that is only `Text` rows is a
  spreadsheet, not a widget.
- **One hero.** The thing the owner checks at a glance is the biggest element on the card; labels
  and captions stay small and muted. If everything is the same size, nothing is.
- **Icon + title row.** Start most widgets with a `Row`: a `Logo`/`Label` with an icon on the left
  and a small secondary value (count, date, status) on the right. Pick an icon that says what the
  widget is (`ph:` names).
- **Pair rows.** "Name left, value right" is `Row` with `align: "between"`. Keep row text the
  same `size` so the column of values lines up.
- **Rhythm.** `gap: "sm"` between sections, `gap: "xs"` inside them. One `tone` per widget — it
  paints the icon tile, bars and primary button.
- **Match the mood.** `red` for alerts/limits, `green` for money/up, `blue`/`violet` for neutral
  info, `gray` only when nothing else fits.

Iterate: change the spec, `update_widget`, look at the new PNG. Repeat until it looks like
something you'd keep on your own desktop — that's the bar.

## Tips

- Start from the closest gallery widget and change it. Keep the sample in step with the view so
  the gallery preview looks right.
- Put the one number that matters first and biggest; labels and captions are small and muted.
- Keep it to what fits: a `2x1` holds a label, one big value and a row of buttons.
- One colour per widget, used for its icon tile, its bars and its main button.
