# Lumen

## Packages

One repo holds the Lumen family. Each folder `packages/<name>` is published as `@columenlabs/lumen-<name>`, and every package ships at the same version from one release, so an app pins one number for all of them.

| Folder | Package | What it holds | Status |
|---|---|---|---|
| [`packages/ui`](https://github.com/columenlabs/lumen/blob/main/packages/ui) | [`@columenlabs/lumen-ui`](https://www.npmjs.com/package/@columenlabs/lumen-ui) | The components, the shadcn parts under `ui/*`, and `theme.css` | Published |
| [`packages/ui-types`](https://github.com/columenlabs/lumen/blob/main/packages/ui-types) | [`@columenlabs/lumen-ui-types`](https://www.npmjs.com/package/@columenlabs/lumen-ui-types) | The view model: view config, formulas, domains and joins, the data catalog, frames, chart formulas. No React | Published |
| [`packages/ship`](https://github.com/columenlabs/lumen/blob/main/packages/ship) | [`@columenlabs/lumen-ship`](https://www.npmjs.com/package/@columenlabs/lumen-ship) | Release notes written by Claude, the changelog What's new reads, lint guards | Published |
| [`packages/auth`](https://github.com/columenlabs/lumen/blob/main/packages/auth) | [`@columenlabs/lumen-auth`](https://www.npmjs.com/package/@columenlabs/lumen-auth) | Sign-in checks: Cloudflare Access tokens and service tokens, verified in the Worker | Published |
| [`packages/ops`](https://github.com/columenlabs/lumen/blob/main/packages/ops) | [`@columenlabs/lumen-ops`](https://www.npmjs.com/package/@columenlabs/lumen-ops) | Ops meters to Analytics Engine (every data query by its shape, every tool call with its latency and code hash) and signed webhooks out; later page errors and email | Published |
| [`packages/ai`](https://github.com/columenlabs/lumen/blob/main/packages/ai) | [`@columenlabs/lumen-ai`](https://www.npmjs.com/package/@columenlabs/lumen-ai) | Serving an MCP server from a Worker, read-only tool sets and metered tool calls; later a product-neutral assistant | Published |
| [`packages/tasks`](https://github.com/columenlabs/lumen/blob/main/packages/tasks) | [`@columenlabs/lumen-tasks`](https://www.npmjs.com/package/@columenlabs/lumen-tasks) | Background jobs: a ledger of the work a person started (state, progress, result), cooperative cancel, a reaper, and the routes the header Tasks list calls | Published |
| [`packages/person`](https://github.com/columenlabs/lumen/blob/main/packages/person) | [`@columenlabs/lumen-person`](https://www.npmjs.com/package/@columenlabs/lumen-person) | One store per person: a Durable Object holding every app's tables for that person, migrations that fail per app, one shared alarm, and backup, restore and delete per app or whole | Published |
| [`packages/vault`](https://github.com/columenlabs/lumen/blob/main/packages/vault) | `@columenlabs/lumen-vault` | Per-person sealing: an envelope codec and a regional codec, both byte for byte with what apps store today, and unlock events (the per-person Durable Object is `lumen-person`) | Published only after the owner approves each release (see its README) |

A planned package has no folder until its first code moves in. Each package's own README says what it exports and how to use it.

### What may join

A part becomes a Lumen package only when all four hold:

1. Two or more apps run it.
2. It names no product (the kit is neutral: apps pass their names and data in through `configureLumen` and `registerDomains`).
3. It moves from working code in an app, never written fresh here.
4. It owns no app's data: it gives the shapes and the machinery, the app keeps its rows.

## For coding agents

- [`llms.txt`](https://lumen.columenlabs.com/llms.txt): what Lumen is, each package, and links to the rest.
- [`llms-full.txt`](https://lumen.columenlabs.com/llms-full.txt): every README plus every component's props and an example, in one file.
- [Component manifest](https://lumen.columenlabs.com/docs/manifests/components.json) (JSON). `bun run --filter=lumen-docs dev` also serves Storybook's MCP at `http://localhost:6006/mcp`.

## The UI kit at a glance

| | Part | What it does |
|---|---|---|
| 🪟 | **App shell** | `LumenShell`: sidebar (icons-only collapse, a drawer on phone), header, status bar, Settings, profile menu and ⌘K Find |
| 🧱 | **Blocks** | `LumenLayout` and `LumenGrid` (a page of cards you can rearrange), `LumenWidget` (a card with its header, link square and controls), sign-in and Security, Settings sections, tabs |
| 📊 | **Views and charts** | `LumenView` and `LumenTable` (filter, group, pivot, totals), `LumenCalendar`, `LumenBoard`, `LumenCard`, `LumenChart`, `LumenEChart`, price and growth charts |
| 🎛️ | **Pickers and panels** | `LumenSelector`, `LumenDrawer`, `LumenConfirm`, `LumenForm`, `LumenDateInput`, `LumenTabs`, `LumenPlayer` |
| 🧩 | **Primitives** | The shadcn/ui parts under `ui/*` and `theme.css` |

Install and use: [packages/ui/README.md](https://github.com/columenlabs/lumen/blob/main/packages/ui/README.md).

### Pages people can rearrange

Give `LumenLayout` an `onConfigChange` and every page can be changed by the person using it: **Edit layout** moves and sizes the widgets on a 6-column grid, and each widget's **Edit widget** changes its type, fields and controls. Both write back into the view config.


Try both live on the docs' [Edit layout](https://lumen.columenlabs.com/docs/?path=/docs/blocks-edit-layout--docs) and [Edit widget](https://lumen.columenlabs.com/docs/?path=/docs/blocks-edit-widget--docs) pages.

> **Status: 0.x.** Any minor version may break things until 1.0.

## Develop

```bash
bun install
bun run lint && bun run type-check && bun run build   # build writes out/<package> and docs/dist
bun run --filter=lumen-docs dev                       # the docs at http://localhost:6006
```

The docs site (`docs/`) is Storybook over the kit's source plus the files agents read. `docs/wrangler.jsonc` serves `docs/dist` at lumen.columenlabs.com:

| Path | What |
|---|---|
| `/docs/` | Storybook: every component on sample data, with Controls and Show code |
| `/llms.txt` | The index for agents ([llmstxt.org](https://llmstxt.org) format) |
| `/llms-full.txt` | Every README and every component's props in one file |
| `/<package>.md` | Each package's README (`/ui.md`, `/ui-types.md`, `/ship.md`, `/auth.md`, `/ops.md`, `/ai.md`) |

All of it is built from the READMEs and the stories (`docs/scripts/llms.ts`), so nothing is written twice. Add or change a story in `docs/stories/` with the part, and keep each package's README current with its exports.

To try a change inside an app before it is published, use `bun link` in `out/<package>` and `bun link @columenlabs/lumen-ui` in the app.

## Releases

Every merge to `main` publishes every package at the next patch version and tags it ([publish.yml](https://github.com/columenlabs/lumen/blob/main/.github/workflows/publish.yml)), with notes on what changed in each release: see the [releases](https://github.com/columenlabs/lumen/releases). A new minor is cut only by hand (Run workflow with bump = minor).

## License

MIT, see [LICENSE](https://github.com/columenlabs/lumen/blob/main/LICENSE). Third-party notices are in [NOTICE](https://github.com/columenlabs/lumen/blob/main/NOTICE).

# How to use: Lumen parts: how to use them

One page per part an app builds screens from. Read the page before you add or change one of these in an app; a code reviewer checks the screen against it. The patterns behind them are in [`DESIGN.md`](https://github.com/columenlabs/lumen/blob/main/DESIGN.md), the blocking list in [`REVIEW.md`](https://github.com/columenlabs/lumen/blob/main/REVIEW.md).

Each page has the same four headings:

- **Use it for**: what the part is for, and what to reach for instead.
- **Anatomy**: what the part draws, top to bottom. The app passes data into these slots and draws nothing around them.
- **Do / Don't**: ✓ and ✗ code, the mistakes agents make most.
- **Checked by**: the `lumen-ship check` rule that fails CI when the page is broken, where one exists.

| Part | Page | Use it for |
|---|---|---|
| `LumenDrawer` + `DrawerSection` | [drawer.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/drawer.md) | The details or editor of one row, beside the list |
| `LumenForm`, `SaveButton`, `FormIssue` | [form.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/form.md) | Fields that save together |
| `LumenSettings`, `LumenExpandList` | [settings.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/settings.md) | An app's Settings page |
| `LumenShell bar`, `useStatus` | [status-bar.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/status-bar.md) | What is true right now, nobody has to act on |
| `LumenSelector` | [selector.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/selector.md) | Every picker |
| `LumenView`, `LumenLayout` | [table.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/table.md) | Every list of rows |
| `LumenFilterPanel` | [filter-panel.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/filter-panel.md) | Browsing a big list by its fields' values, beside it |
| `LumenCalendar` | [calendar.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/calendar.md) | Things on days: month, week and agenda |
| `LumenBoard` | [board.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/board.md) | Items by stage, in columns |
| `LumenPlayer` | [player.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/player.md) | A video, an audio file, or slides over audio |
| `LumenShell tabs` | [tab-bar.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/tab-bar.md) | The main pages at the bottom of a phone screen |

## Three rules every page shares

1. **Icon first.** An action is an `IconButton`: the icon, its name in a tooltip and its `aria-label`, no text on the button. Save is `SaveButton`, Run, Test, Refresh, Copy, Edit and Delete are `IconButton`s. ([DESIGN.md, Actions: icon first](https://github.com/columenlabs/lumen/blob/main/DESIGN.md#actions-icon-first))
2. **Details on demand.** No grey hint line under a field, a section title or a page title. Most labels need nothing; the few that do get an `InfoTip`. ([DESIGN.md, Details on demand](https://github.com/columenlabs/lumen/blob/main/DESIGN.md#details-on-demand-infotip))
3. **Only the kit's overlays.** An app never imports `ui/sheet`, `ui/dialog`, `ui/select`, `ui/command` or `ui/combobox`: drawers are `LumenDrawer`, confirms `LumenConfirm`, pickers `LumenSelector`. ([DESIGN.md, Popups](https://github.com/columenlabs/lumen/blob/main/DESIGN.md#popups-always-a-way-out))

## Checked by

`lumen-ship check parts <app folders>` counts each rule's breaks per folder against a baseline that may only fall (`scripts/parts.baseline`, one `<folder> <rule> <count>` a line). Rules:

| Rule | Fails on |
|---|---|
| `hint-text` | `<p className="… text-xs … text-muted-foreground …">`: a grey line under a field or title |
| `text-action` | a `<Button>` whose text starts with an action (Save, Run, Test, Send, Sync, Refresh, Copy, Edit, Delete, Remove, Retry, Reset) |
| `raw-overlay` | an import of `@columenlabs/lumen-ui/ui/{sheet,dialog,select,command,combobox}` |
| `tags-text` | tags or labels joined into comma text (`r.tags.join(', ')`) on a line with no `tags: true`: a `tags` field or `TagChips` |
| `settings-page` | a route, link or nav item (`path`, `to`, `href`) to a page named `settings`: an app's settings are sections of the one Settings dialog |

`lumen-ship check parts --write-baseline <folders>` writes today's counts (only for a first run; lower a count by hand in the change that removes a break).

# How to use: Board: `LumenBoard`

## Use it for

Items by stage, side by side: a plan's checkpoints and their tasks, a pipeline's steps, a hiring loop. Columns and items come in as data; the app opens an item in its own drawer.

- A long list to sort, filter or total: `LumenView` (see [table.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/table.md)), grouped by stage.
- Items on days: `LumenCalendar` (see [calendar.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/calendar.md)).

## Anatomy

```
┌ Checkpoint 1     12 ┐ ┌ Checkpoint 2      9 ┐   header: label (truncates), count
│ ☐ Task title… Oct 3 ⇄│ │ ☐ Task title  Review│   card: tick slot, title, meta, badges, Move to (hover)
│ ☑ Task title        │ │                     │   each column scrolls on its own (maxHeight)
│        …            │ │    Nothing here     │   an empty column's line
└─────────────────────┘ └─────────────────────┘   the board scrolls sideways in its own box
```

- `columns`: `{ id, label, count? }`; `count` defaults to the number of items in it.
- `items`: `{ id, column, title, meta?, badges? }`. `renderCard(item)` draws the card's body instead; keep it to one line.
- `tick(item)`: a slot before the title, such as a done `Checkbox`.
- `onOpen(item)` opens the app's drawer. `onMove(item, toColumn)` adds a Move to menu on each card: shown on hover or focus, always on a touch screen, and fully usable by keyboard. No drag library.
- On a box under 640px wide the columns become a snap scroller, one column a screen, with a `LumenSelector` above to jump to one; it follows the swipe.

## Do / Don't

```tsx
// ✓ data in, the drawer out, moves through the menu
<LumenBoard columns={checkpoints} items={tasks}
  tick={(t) => <Checkbox checked={t.done} onCheckedChange={(v) => setDone(t.id, v === true)} />}
  onOpen={(t) => setOpen(t.id)} onMove={(t, to) => move.mutate({ id: t.id, to })} />

// ✗ a card on two lines, a text button, the page scrolling sideways
<div className="flex">{cols.map((c) => <div className="w-80">…<p>{t.title}<br />{t.notes}</p>
  <Button>Move</Button></div>)}</div>
```

- ✗ Notes or a description on the card. ✓ One line; the rest is in the drawer.
- ✗ A drag-and-drop library for moves. ✓ `onMove`; the Move to menu works by keyboard and touch.
- ✗ Columns that stretch the page wider than the screen. ✓ The board scrolls inside itself.

## Checked by

Review and the app's interaction smoke (AGENTS.md, UI gate 1 and 3: reach and lines).

# How to use: Calendar: `LumenCalendar`

## Use it for

Things that happen on days: a program's sessions, a plan's tasks by due date, a schedule. Month, Week (with a time axis) and Agenda, over plain data the app passes in.

- Rows to sort, filter and total: `LumenView` (see [table.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/table.md)), with a date column.
- One date to pick in a form: `LumenDateInput`.
- Things by stage rather than by day: `LumenBoard` (see [board.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/board.md)).

## Anatomy

```
▦ Month  ▤ Week  ☰ Agenda                 ✓  ‹  ›   LumenTabs; Today, previous, next as IconButtons
October 2026   [Talks] [Workshops] [Deadlines]       the period (one line), category chips (ColorChip toggles)
Sun  Mon  Tue  Wed  Thu  Fri  Sat                    weekdays from weekStartsOn
 4    5 ● 9:00 Kickoff…   …                          a cell: day, up to 3 one-line events, "+N more"
Wed, Oct 7  Today                                    the picked day's list (always on a narrow box)
 9:00 AM  ● Kickoff and goals         Talks          one line: time, dot, title (truncates), category
```

- `events`: `{ id, title, start, end?, allDay?, category?, color? }`. `start` and `end` are instants (`Date` or ISO string), or a plain `YYYY-MM-DD` for a whole day; a plain end is inclusive.
- `categories`: `{ id, label, color }`. Their chips filter; an event takes its category's colour unless it has its own.
- `onSelect(event)` opens the app's drawer; `onRangeChange({ start, end, view })` fires with the instants on screen, so the app reads only those days.
- `timeZone` (an IANA zone, the browser's by default) is the zone every day and time is shown in.
- View and date are uncontrolled (`defaultView`, `defaultDate`) or controlled (`view` + `onViewChange`, `date` + `onDateChange`).
- On a box under 640px wide (a phone, a narrow drawer) Month shows dots with the picked day's list under the grid, and Agenda is the default view. Week's axis scrolls inside its own box and opens at the first event or 7 AM.

## Do / Don't

```tsx
// ✓ plain data in, the app's drawer out; fetch by the range on screen
<LumenCalendar events={events} categories={categories} timeZone={prefs.timeZone}
  onSelect={(e) => setOpen(e.id)} onRangeChange={({ start, end }) => setRange([start, end])} />

// ✗ a hand-made month grid, text buttons, times built from local Date methods
<div className="grid grid-cols-7">{days.map((d) => <div>{d.getDate()}…</div>)}</div>
<Button onClick={next}>Next month</Button>
```

- ✗ Wrapping an event's title onto a second line. ✓ It truncates; the full title is its hover.
- ✗ Loading every event the app has. ✓ Read by `onRangeChange` and pass that range's events.
- ✗ A second category filter of the app's own above it. ✓ `categories`; the chips are the filter.
- ✗ `h-full` on the calendar's card. ✓ It is as tall as its content; Week scrolls inside itself.

## Checked by

Review and the app's interaction smoke (AGENTS.md, UI gate 1 and 3: reach and lines).

# How to use: Drawer: `LumenDrawer` + `DrawerSection`

## Use it for

The details or the editor of one row, opened from a list, a card or a link. A right-side panel on desktop whose width drags (320px to 60%), a bottom sheet on a phone.

- A list whose rows each open it: pass `dock="<name>"`, so it sits beside the page and the next row swaps it in place.
- A yes or no before something destructive: `LumenConfirm`, not a drawer.
- A whole new screen of its own: a page (a route with a `LumenLayout`), not a drawer.

## Anatomy

```
┌───────────────────────────────┐
│ Title                       × │  title (one line, truncates before the ×)
│ description                   │  one muted line, optional: what this is ("Active · Oct 16")
├───────────────────────────────┤
│ ▸ ⚙ Section   3          None │  DrawerSection: chevron, icon, title, count, short note
│   summary while closed        │  summary: what it is set to, only while closed
│ ▾ ⚙ Section                   │
│   fields / FactList / table   │  body: the section's own parts
├───────────────────────────────┤
│ 12 runs          🗑  ▶  ✓     │  footerStart · actions (data, drawn as icons) · footer: SaveButton
└───────────────────────────────┘
```

- Every body is `DrawerSection`s. No heading, card or divider of the app's own between them.
- Sections start folded; `defaultOpen` the one the person came for.
- Label and value pairs are `FactList`. Fields are the kit's inputs with an `InfoTip` where one is truly needed.
- The footer holds the drawer's actions, right-aligned: `actions` as data (`{ icon, label, onClick, busy, destructive }`), which the drawer draws as icon buttons in order, destructive first, then `SaveButton` in `footer`. With neither there is no footer; the × closes it.

## Do / Don't

```tsx
// ✓ data in the kit's slots; actions are icons
<LumenDrawer open={open} onClose={close} title={job.name} description={job.when} dock="jobs"
  footerStart={`${runs.length} runs`}
  actions={[
    { icon: TrashIcon, label: 'Delete', destructive: true, onClick: () => remove.mutate() },
    { icon: PlayIcon, label: 'Run now', busy: run.isPending, onClick: () => run.mutate() },
  ]}
  footer={<SaveButton issues={issues} busy={save.isPending} disabled={!dirty} onSave={() => save.mutate()} />}>
  <DrawerSection icon={GlobeIcon} title="Page" summary={job.url} defaultOpen>…</DrawerSection>
  <DrawerSection icon={BellIcon} title="Alerts" count={alerts.length}>…</DrawerSection>
</LumenDrawer>

// ✗ text buttons, a hand-made header, a grey hint line
<LumenDrawer …>
  <h3 className="font-semibold">Page</h3>
  <p className="text-xs text-muted-foreground">The address read on each run.</p>
  <Button onClick={run}>Run now</Button>
  <Button disabled={!valid} onClick={save}>Save</Button>
</LumenDrawer>
```

- ✗ A `Sheet` or `Dialog` from `ui/*` for a side panel. ✓ `LumenDrawer`.
- ✗ Tabs at the top of a drawer to split its sections. ✓ `DrawerSection`s that fold; `LumenTabs` only when the drawer shows two different things (a job and its runs).
- ✗ `h-full` on a card inside it: the drawer scrolls, a card is as tall as its content.

## Checked by

`hint-text`, `text-action`, `raw-overlay` (see [README](https://github.com/columenlabs/lumen/blob/main/docs/parts/README.md#checked-by)).

# How to use: Filter panel: `LumenFilterPanel`

## Use it for

A list big enough that people browse it by facets (company, tag, place, level, date): each field becomes a section of values with counts, ticked in place, beside the list. It is the filter box laid out as a panel. Both read and write one `useLumenFilter` state, so a tick is a chip in the box and a chip's × unticks it in the panel.

- A short list, or one or two fields: the filter box alone (`LumenTokenizedFilter`).
- A choice that switches the whole page (All, Review, Pending): `LumenTabs`.

## Anatomy

```
desktop                                   phone
┌ Filters 3        ↺  ⇤ ┐  [≡3] [chips…]  [▽ 3] [chips…]    (filter icon, count)
│ Company (i)        ⊘  │                 ┌──── ▬ ───────────┐
│ ☑ Cloudflare     41   │                 │ Filters        × │  bottom sheet,
│ ☐ Apple         212   │                 │ 3 on           ↺ │  same body
│   61 more             │                 │ Company (i)      │
│ Fit (number)          │                 │ ☑ Cloudflare  41 │
│ [From] – [To]         │                 └──────────────────┘
└───────────────────────┘
```

- **Counts** come from `useFacetCounts`, the box's own: a field counts the rows the other fields keep, so picking one value never hides its siblings. Over one page of a server's rows, pass the server's counts as `facets` (from the same find query that returns the page). The kit never counts a page as if it were every row.
- **Uncounted**: when a server cannot count a field without reading every row (a word search over a big set), it sends that field's values with `counted: false`. The panel and the box list the values to tick and show no numbers. Never send a full scan's counts on a request to fill them in.
- **Callbacks** (`onTokens`, `paging.onSort`, `groups.onGroup`) are heard when the value changes, never because the function is new, so an inline callback cannot loop (`useTell`).
- **Hide** (⇤) folds the panel to the filter icon in the filter row. Whether it is open is kept per device, per page `id`. A phone starts closed and opens the sheet from that icon.
- **⊘** on a field leaves its ticked values out instead of keeping them, like Exclude on a chip.
- A field with more than six values shows the most common first, with "N more" (and a search past ten). "No <field>" sits on top when some rows have no value.

## Do / Don't

```tsx
// ✓ on a page: the layout draws the panel, the icon and the sheet
<LumenLayout
  domain={domain}
  config={config}
  rows={page.rows}
  paging={paging}
  onTokens={setTokens}           // the server reads the chips
  facets={page.facets}           // and counts each field over every row
  filterPanel={{ id: 'roles', tips: { fit: 'Sage scores roles you open or save.' } }}
/>

// ✓ outside a layout: one state, both views
const filter = useLumenFilter(rows, fields);
const panel = useFilterPanel('stores');
<LumenFilterPanel filter={filter} {...panel} />
<LumenFilterPanelButton filter={filter} {...panel} />
<LumenTokenizedFilter filter={filter} />

// ✗ a second filter state for the panel, or checkbox lists of the app's own
const [picked, setPicked] = useState<string[]>([]);
```

- ✗ Counting a server's page in the browser. ✓ `facets` from the server's find query.
- ✗ A count over every row on each request. ✓ Kept counts, a bounded read, or `counted: false`.
- ✗ A grey hint line under a section. ✓ `tips` puts it in an InfoTip.
- ✗ Text buttons (Clear all, Apply). ✓ Ticks apply at once; Clear and Hide are icons.

## Checked by

`raw-overlay`, `hint-text` and `text-action` (see [README](https://github.com/columenlabs/lumen/blob/main/docs/parts/README.md#checked-by)).

# How to use: Form: `LumenForm`, `SaveButton`, `FormIssue`

## Use it for

Fields that save together: an editor in a drawer, a settings section, a new-thing form.

- A flat list of fields: `LumenForm` with `fields` (data, one object per field) and `onSave`.
- A form the app lays out itself (sections, a preview beside it): the kit's inputs, and `SaveButton` with the form's `FormIssue`s.
- One value changed in place (a name, a cell): `EditInputCell` or `RenameField`, no form and no Save.

## Anatomy

```
Name                      [ Lisbon store        ]   label: one line, no hint under it
API key (i)               [ ••••3f9a            ]   an InfoTip only where a reader would guess wrong
Route                     [ Public internet   ▾ ]   select / multi: LumenSelector
                                     ⚠ 2 to fix  ✓   SaveButton: issues chip, then the icon
```

- Every rule a value must meet is a `check` on its field (`LumenForm`) or a `FormIssue` (your own layout). The person sees them only through `SaveButton`: the chip counts them, Save takes them to the first one.
- `disabled` on `SaveButton` means only "nothing changed"; never use it to block a save that has problems.
- A test of the settings (Test it, Send test) is an `IconButton` beside Save. Its result shows on screen, never in a tip.

## Do / Don't

```tsx
// ✓ fields as data; the kit draws labels, inputs and Save
<LumenForm
  fields={[
    { id: 'name', label: 'Name', required: true },
    { id: 'url', label: 'Address', check: (v) => String(v).startsWith('https://') || 'Must start with https://' },
    { id: 'key', label: 'API key', kind: 'secret', saved: '••••3f9a', info: 'Read only. Made in the provider’s console.' },
  ]}
  initial={job}
  onSave={(v) => save.mutate(v)}
  busy={save.isPending}
/>

// ✓ own layout: issues to SaveButton, field ids to jump to
const issues: FormIssue[] = url.startsWith('https://') ? [] : [{ where: 'Address', message: 'Must start with https://', target: 'job-url' }];
<SaveButton issues={issues} disabled={!dirty} busy={save.isPending} onSave={() => save.mutate()} />

// ✗ a silent disabled Save, a text button, a hint under the field
<Button disabled={!url.startsWith('https://')} onClick={save}>Save</Button>
<p className="text-xs text-muted-foreground">Must start with https://</p>
```

- ✗ `hint` on a `LumenFormField` (deprecated; it now draws as an (i) too). ✓ Leave it out, or `info`, which the form draws as an `InfoTip` beside the label.
- ✗ An error message under a field before the person tries to save. ✓ The `SaveButton` chip.
- ✗ Cancel as a text button. ✓ `onCancel` on `LumenForm` draws an × icon labelled Cancel; in a drawer leave it out, the drawer's × and Esc close it.

## Checked by

`hint-text`, `text-action` (see [README](https://github.com/columenlabs/lumen/blob/main/docs/parts/README.md#checked-by)).

# How to use: Player: `LumenPlayer`

## Use it for

A recording to watch or listen to in a drawer or a page: a video, an audio file, or slides in step with audio. The browser's own `<video>`/`<audio>` plays it (served with byte ranges); the kit draws the controls.

- A short clip that loops with no controls: a plain `<video>` in the app.
- A link out to another site's player: an `IconButton` with `href`.

## Anatomy

```
┌────────────────────────────────────┐
│          video / slide image       │   click or space plays; a spinner while it waits
└────────────────────────────────────┘
━━━━━━━━━━━●───────────────────────────   seek bar (Slider)
▶  ↺  ↻  1:02 / 45:10        ⏲ 1×  CC ⛶   play, back 15 s, forward 15 s, time · speed, captions, full screen
Chapters                                   one line each: time, title; the current one lit
 0:00  The page
Transcript                                 its own scroll box; the line being said lit and kept in view
 0:03  Host: Edit layout opens the grid…   a tap plays from that line
```

- `src` (a URL) and `kind` (`video` or `audio`, read from the extension by default), or `source: { kind: 'slides', slides: [{ at, image, alt? }], audio }`.
- `tracks` (WebVTT captions, video), `chapters: [{ at, title }]`, `transcript: [{ start, end?, text, who? }]`, `poster`, `title`.
- `start` (seconds) resumes where the person left off. `onProgress(seconds, { duration, ended })` fires about every 10 s while playing, on pause, at the end and when the player goes away; nothing fires for a recording opened and left unplayed. Save it there.
- `onEnded` (play the next one), `autoPlay` (start as soon as it can; the browser may refuse without a tap).
- Keys while the player has focus: space or k play and pause, j and l skip 15 s, ← and → 5 s, f full screen, c captions. A field or menu inside keeps its own keys.
- A failed load shows one line and a Try again icon; the controls never spin forever.

## Do / Don't

```tsx
// ✓ the saved place in, the place out
<LumenPlayer src={fileUrl(item.file)} title={item.title} start={item.position}
  chapters={item.chapters} transcript={item.lines}
  onProgress={(s, { ended }) => save.mutate({ position: s, watched: ended })}
  onEnded={openNext} />

// ✓ slides over audio
<LumenPlayer source={{ kind: 'slides', slides: lesson.slides, audio: lesson.audio }} />

// ✗ native controls plus the app's own buttons; saving on every timeupdate
<video controls src={src} onTimeUpdate={(e) => save(e.currentTarget.currentTime)} />
<Button onClick={() => (v.currentTime -= 15)}>Back 15s</Button>
```

- ✗ A transcript that scrolls the whole page as it follows. ✓ The player's transcript scrolls inside its own box, and stops following for a few seconds after the person scrolls it.
- ✗ Global key handlers for play and seek. ✓ The player takes its keys only while focused.

## Checked by

Review and the app's interaction smoke (AGENTS.md, UI gate 2 and 5: popups and access).

# How to use: Picker: `LumenSelector`

## Use it for

Every choice from a list: a field's select or multi-select, a filter chip, an icon menu, a picker with search or create. It opens above its trigger when the room below is short, its list scrolls, and its search, header and footer (Done) stay in view.

- A choice of two or three that should all show at once: `LumenChoice` (or a toggle group), not a picker.
- A destructive confirm: `LumenConfirm`.

## Anatomy

```
[ Public internet  ▾ ]      trigger: 'field' (default) · 'chip' · 'icon'
┌────────────────────┐
│ 🔍 Search          │      search: 'auto' shows past a handful of options
│ Group              │      groups / option.group
│   ✓ Option   detail│      option: label, detail, icon, description (in its tip)
│   + Add "acme"     │      create: a new value typed in the search
│              Done  │      footer, multiple only
└────────────────────┘
```

## Do / Don't

```tsx
// ✓ options as data
<LumenSelector
  options={[{ value: 'tunnel', label: 'Tunnel' }, { value: 'public', label: 'Public internet' }]}
  value={route}
  onChange={setRoute}
/>

// ✗ shadcn's Select or a Command list in an app
import { Select, SelectContent } from '@columenlabs/lumen-ui/ui/select';
```

- ✗ A `DropdownMenu` of one or two actions behind ⋯. ✓ The actions as `IconButton`s on the row.
- ✓ A long `detail` is fine: the name keeps up to two thirds of the row and the detail truncates first, its full text on hover. ✗ Shortening a detail to save the name.
- ✓ A row that can't be picked says why: `disabled: 'Added'` dims it and shows a ✓ chip with the words in place of its detail; arrows and Tab skip it. ✗ A disabled row with no reason, or hiding a row the person already picked.
- ✗ Capping the list's height without its footer. ✓ Leave sizing to the kit.

## Checked by

`raw-overlay` (see [README](https://github.com/columenlabs/lumen/blob/main/docs/parts/README.md#checked-by)).

# How to use: Settings: `LumenSettings`, `LumenExpandList`

## Use it for

An app's Settings page: one dialog on every host, General first, then a group per app. Each section is one `SettingsSectionDef`.

- A list of things in a section (providers, channels, accounts, phones): `LumenExpandList` of `LumenExpandRow`s.
- A few fields that save together: a `LumenForm` (see [form.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/form.md)) in the section's `content`, its Save in `footer`.
- Shared sections the kit already has: `SchedulesSection`, `NotificationsSettings`, `McpSettings`, `IntegrationRow`, `TimeZoneSelect`. Use them; never rebuild one.
- Alerts split from delivery: `NotificationsSettings parts="channels"` in one section (where messages go: email, ntfy, webhooks, set up once) and `parts="events"` in another (what goes where: one line per event, a column per channel). Events with a `group` sit under its label ("Limits", "Watchdog").

## Three slots (every thing in a section)

A thing you connect or turn on (a provider, a channel, a key, an account) is one `LumenExpandRow` with three slots, built on shadcn's `Field` and `InputGroup`:

```
[icon] Plaid  Production · keys ••91        ● Works  [on]  ›     header: status pill, on/off for the whole thing
       Environment   [Production|Sandbox]                          SettingField rows: one setting each
       Keys          [••••91            ✎]                          a value's own buttons sit inside it
       Webhook       [https://money…    ⧉]                [on]      a switch for one setting at the row's end
       ✓ Tested 8:41 AM                          ↻ Test  🗑          SettingActions: last result, Test, Remove
```

```tsx
<LumenExpandRow
  id="plaid" icon={<LinkIcon />} name="Plaid" meta="Production · keys ••91"
  status={<SettingStatus health={settingHealth(on, test)} title={`Tested ${when}`} />}
  toggle={{ checked: on, onCheckedChange: setOn, label: 'Plaid on' }}
  actions={<SettingActions test={test} onTest={runTest} remove={{ label: 'Remove keys', run: removeKeys }} />}
>
  <SettingField label="Environment"><ToggleGroup … /></SettingField>
  <SettingField label="Keys"><SettingValue label="Keys" value="••••91" mono onReplace={edit} /></SettingField>
  <SettingField label="Webhook" stack end={<Switch aria-label="Live updates" … />}>
    <SettingValue label="Webhook URL" value={url} mono copy />
  </SettingField>
</LumenExpandRow>
```

Rules:

1. **A row is a setting.** Never a lone button with a label in front ("Last test", "Remove Plaid keys").
2. **A label names the setting, not the thing**: "Keys" inside Plaid, never "Plaid keys".
3. **On/off for the whole thing is `toggle`** in the header; on/off for one setting is that row's `end`. Never a "Turn on" button or a trash icon for "off".
4. **Actions on the whole thing are in `SettingActions`**: Test, then Remove (trash, confirms) at the far right; anything else (Sync now, Sign in again) as an icon before them. Actions on one value sit inside its `SettingValue` (Copy, Replace).
5. **Status is the header pill only** (`SettingStatus`: Works, Failed, Not tested, Off, or a count). The action bar adds just the time or the error.
6. **Several controls on one row are one group** and never wrap. A long value takes `stack`: on a phone its label goes above it.
7. **A section's pill** is `health` on its `SettingsSectionDef`: `sectionHealth(items)`, the worst thing wins. The Settings list shows it as a dot.
8. **A row with only an `end`** (a switch or a status pill, no control) gives its label the whole row, so a short name never cuts off on a phone. A row with a control keeps the fixed label column (8rem, 6rem on a phone).
9. **A form that saves together** keeps label beside field (`SettingField`), and its Test result sits in its footer, not a row of its own.

### Built on the slots
- `LumenConnection` (a key, a sign-in, a relay): one row per way to connect, its value with Replace or Sign in again inside. One way: its last test, Test and Remove sit in the action bar. Several ways: a Use row picks the one that runs, and each way's row ends in its own status, Test and Remove (on a phone the label and those sit above the value).
- `NotificationsSettings`: email and ntfy turn on and off with the header switch, and each webhook is one row.
- `McpSettings`: each server's address is a row with Copy, then From picks the app whose steps show.
- `SchedulesSection`'s editor: each setting is a row (On and Notify end in their switch).

## Anatomy

```
⚙ Email                            one-line description (≤ 64 chars)
  ▸ Relay A       tunnel                 Works      LumenExpandRow: name · meta · badge
  ▾ Relay B       public internet        Failed
      fields of this row …                           opens in place, one row at a time
──────────────────────────────────────────────────
  Passed                                       ↺  ✓  footer: a word or two, then icons
```

- `description` is one plain line of 64 characters or less; nothing else under the title.
- Every row starts collapsed and shows its name, its one-line `meta` beside it, and its `status`. Opening one closes the others.
- The footer's status is a word or two ("Passed", "Test to save"). Actions are icons.

## Do / Don't

```tsx
// ✓
const section: SettingsSectionDef = {
  id: 'email', title: 'Email', icon: MailIcon, description: 'How the app sends mail',
  content: (
    <LumenExpandList>
      {relays.map((r) => (
        <LumenExpandRow key={r.id} id={r.id} name={r.name} meta={r.route} badge={<Badge>{r.state}</Badge>}>
          <RelayForm relay={r} />
        </LumenExpandRow>
      ))}
    </LumenExpandList>
  ),
};

// ✗ a paragraph of help, every row open, cards per row
description: 'Pick a relay. Mail goes out through the relay you choose; a localhost address is reached over the tunnel…',
<Card className="h-full">…</Card>
```

- ✗ `h-full` on a card in a section: Settings scrolls, the card clips at one screen.
- ✗ A grey line under a row's fields. ✓ An `InfoTip` on the one label that needs it; `SettingRow`'s `description` draws one.
- ✗ A Settings page of the app's own (a `/settings` route or nav item). ✓ A section in the app's group of the one dialog, opened from anywhere with `?settings=<section>`.

## Checked by

`lumen-ship check settings-copy` (the 64-character description) and `hint-text`, `text-action`, `settings-page` (see [README](https://github.com/columenlabs/lumen/blob/main/docs/parts/README.md#checked-by)).

# How to use: Status bar: `LumenShell bar`, `useStatus`

## Use it for

What is true right now that nobody has to act on: how fresh the data is, what is running, a warning that blocks nothing, one or two facts. Pick the surface by what the reader must do:

| Must act | Just did it | One row or card | Ambient | What this page is |
|---|---|---|---|---|
| Banner | Toast (`lumenToast`, with Undo) | Badge | **Status bar** | Header `meta` |

## Anatomy

```
● Updated 3m ago │ ⟳ Syncing 40 of 112 │ ⚠ Job boards offline ×3 +2 │ Next run in 12m │ ♥ What's new PT
  1 Sync           2 Work                 3 Message                    4 Facts (≤ 2)     5 End (kit)
```

On a phone the most urgent item shows (error, warning, work, sync) with a chip that opens the rest in a sheet. The bar never scrolls sideways.

## Signals

Warnings and errors are `signals`, not `messages`: data the kit draws as a chip in slot 3 (counts by level, the top signal) that opens the Signals panel. See DESIGN.md, Signals.

```tsx
<LumenShell
  bar={{
    signals: events.map((e) => ({
      key: `${e.kind}:${e.account}:${e.meter}:${e.resource}`,
      level: e.level,            // 'act' | 'look' | 'fyi'
      kind: 'Burning fast', what: 'KV reads', where: 'worker-a', group: 'Prod',
      pace: '11% in 15m', used: 0.34, runsOut: '2h',
      at: e.at, href: `/meters/${e.meter}`,
    })),
    signalOptions: { onMute: saveMuteRule, settings: 'alerts', groupLabel: 'Account' },
  }}
/>
```

- ✗ `messages: [{ text: 'Spike: … 16× its normal hour (2,057 vs 125) · 2% of today\'s allowance used …', tone: 'warning' }]`
- ✓ `signals: [{ kind: 'Unusual', what: 'D1 rows written', where: 'worker-b', pace: '16× peak', used: .02, lands: .10, level: 'fyi' }]`

## Do / Don't

```tsx
// ✓ data, not JSX; the page's main read is its sync
const jobs = useQuery(jobsQuery);
useStatus({ sync: querySync(jobs), facts: [{ label: 'Next run', at: nextRunAt }] });

// ✓ app-wide on the shell
<LumenShell bar={{ sync: { state: 'ok', label: 'Bank feed', at: syncedAt } }} … />

// ✗ JSX status items, a row count the pager shows, a spinner that waits
<LumenShell status={<StatusItem>42 rows</StatusItem>} … />
```

- ✗ "Updated". ✓ "Updated 3m ago": every item says what and when.
- ✗ A fetch made just for the bar. ✓ Read what the page already holds.
- ✗ An error the person must fix. ✓ A banner on the page.

## Checked by

Review only (REVIEW.md); the deprecated `status` prop shows on desktop only.

# How to use: Phone tab bar (`LumenShell tabs`)

## Use it for

An app whose people move between a few main pages on a phone all day (a dashboard, a plan, a course list). It puts up to four of them at the bottom of the screen, one tap away, with More opening the sidebar for every other page. Leave it out and the phone keeps the sidebar alone, as today.

## Anatomy

- Four tabs, each the page's icon over its name, taken from the first four `NavItem`s passed. The tab whose page you are on is in the accent colour (the closest match wins, as in the sidebar).
- More, last: opens the sidebar sheet. It is lit when none of the four is the page you are on.
- Phone only. The status bar rides just above it; it pads the phone's safe area at the bottom.

## Do / Don't

```tsx
// ✓ The same NavItems the sidebar uses, the main ones first.
<LumenShell nav={<NavGroup items={nav} />} tabs={nav.slice(0, 4)} … />

// ✗ A bar of the app's own fixed to the bottom of the page.
<div className="fixed bottom-0 …">…</div>
```

## Checked by

No lint rule. The app's interaction smoke checks reach and tap targets on a phone.

# How to use: Table: `LumenView`, `LumenLayout`

## Use it for

Every list of rows: a page's main table, a card's table, a drawer's runs. A page is a `LumenLayout` over a saved view config; the table is a `LumenView` card in it.

- A handful of label and value pairs: `FactList`.
- Rows that each expand to their own settings: `LumenExpandList` (see [settings.md](https://github.com/columenlabs/lumen/blob/main/docs/parts/settings.md)).
- Header numbers: `TileRow fill` of `Tile`s, not a table.

## Anatomy

```
[ filter tokens…                 ]  ⚙         LumenTokenizedFilter, Columns
Name                      Status      Spend    first column stops at --lead-col-max
Lisbon store              ● Live    $1,204    one line per row, always; numbers right-aligned
▸ Group (3)                          $3,410    roll-up rows carry data-rollup
Total                                $9,882    Total via cardAgg / rollRender
                         ‹ 1 2 3 ›             pager holds its page while rows change in place
```

On a phone each row is a one-line card: the name and one value; the rest waits in the row's drawer.

## Tags

A field whose rows carry several free-form labels (a company's `ai`, `cybersecurity`, `favorite`) sets `tags: true` with `values`: each cell draws `TagChips`, every tag a chip in its colour with an icon first, on one line (past three, a `+N` chip whose hover names them all).

- The colour comes from the tag's name (`tagColor`, the chart palette), so a tag is the same colour on every row, page and app with nothing stored. The icon comes from the tag's words (`tagIcon`: `security` a shield, `ai` sparkles, `data` a database, `favorite` a star); no icon where no word fits.
- `color` and `iconOf` on the field override both (labels the person coloured).
- With `edit.many` the cell is the same chips plus the ✎ picker; the picker's rows carry the same colours and icons.
- Grouped by the field, a single tag's heading takes its colour and icon.
- Outside a table (a drawer, a card) draw the same `TagChips tags={…}`, never `Badge`s or comma text.

```tsx
{ key: 'tags', label: 'Tags', icon: Tags, value: (r) => r.tags.join(', ') || null, values: (r) => r.tags, tags: true, format: 'text', filterable: true }
```

## Resizable columns

Off by default. `configureLumen({ resizableColumns: true })` turns it on for every table in the app; one `LumenView` (or `LumenTable`) overrides with `resizable`. Each header gets a grip on its right edge (desktop only; a phone's rows are cards and a `fit` table wraps instead):

- Drag sets the column's width; a dragged width caps its cells, so a long name ends in an ellipsis with the full text on hover.
- ← and → on the focused grip move it 16px; double-click, Enter or Delete gives the column back its own width.
- Widths are kept on the device per table (`localStorage`, key `lumen:col-widths:<domain id>:<cardId>`); storage off, they last the visit.
- Every column still shows: a wider column makes the table scroll sideways, never drops another.

## Export

The header's Export (`download` control) downloads or copies the table as CSV: the rows shown, or with a filter on, Filtered or All. A table a server pages (`paging`) shows one page, so give `paging.all`, which fetches every row for the filter (the server may cap it), and Export saves those instead of the page.

- ✗ An app's own Download button beside a paged table. ✓ `paging.all`.

## Do / Don't

```tsx
// ✓ a domain, a saved config and rows; a row opens the docked drawer
<LumenView domain={jobsDomain} config={view.config} rows={jobs} onDetails={(r) => setOpen(r.id)} />

// ✗ shadcn Table, two lines in a cell, a unit as text
<Table>…<TableCell>{name}<br /><span className="text-xs">{url}</span></TableCell>…</Table>
<TableCell>{gb + ' GB'}</TableCell>
```

- ✗ A second line in a cell. ✓ One value; more in a hover tooltip or the drawer.
- ✗ `value + unit` text. ✓ `UnitValue`.
- ✗ An app's own pager beside a table. ✓ The view's `pagination` (`size` 10, 25, 50, 100 or 250; 25 by default), drawn by `LumenView`.
- ✗ Resetting the page on a new `rows` array. ✓ Only a new filter, sort, grouping or page size goes back to page 1.
- ✗ Another row of tabs to filter. ✓ A `LumenTokenizedFilter` field.
- ✗ Hiding columns to fit a narrow box (sidebar open, docked drawer). ✓ Every column shows; the table scrolls sideways and the name stays at `--lead-col-max`.
- ✗ Tags as comma text (`r.tags.join(', ')`) or a row of `Badge`s. ✓ `tags: true` on the field, `TagChips` elsewhere.
- ✗ An app's own column-drag code or saved widths. ✓ `configureLumen({ resizableColumns: true })` (every table) or `resizable` on one `LumenView`.

## Checked by

`lumen-ship check parts` rule `tags-text` (tags joined into comma text on a line with no `tags: true`). Review and the app's interaction smoke (AGENTS.md, UI gate 3: lines; Every column always shows: no hidden column at 1024, 1280 or 1440 wide, sidebar open or closed).

# Package: @columenlabs/lumen-ai

Assistant and agent parts for apps on Cloudflare Workers. Serving an MCP server from a Worker, keeping only the read tools for a read-only caller, metering every tool call, and the server side of a chat assistant (`@columenlabs/lumen-ai/assistant`).

## Install

```sh
bun add @columenlabs/lumen-ai @columenlabs/lumen-ops @modelcontextprotocol/sdk
```

Pin every `@columenlabs/lumen-*` package to the same exact version. `@modelcontextprotocol/sdk` is a peer: the app's own copy builds the server.

## Serve an MCP server

Build one server per request for the caller you have already checked, then hand it the request. Each request stands alone (stateless Streamable HTTP, JSON responses), since a Worker keeps nothing between requests.

```ts
import { jsonResult, keepReadTools, meterTools, serveMcp } from '@columenlabs/lumen-ai';
import { setToolSink } from '@columenlabs/lumen-ops/tools';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

setToolSink(env.TOOL_CALLS); // once per isolate; tool calls are metered only when it is set

function build(person: string) {
  const mcp = new McpServer({ name: 'my-app', version: '1.0.0' });
  mcp.registerTool(
    'account_list',
    { description: 'Accounts and balances', annotations: { readOnlyHint: true } },
    async () => jsonResult(await accounts(person)),
  );
  return mcp;
}

app.all('/mcp', async (c) => {
  const server = meterTools(build(c.get('person')), { app: 'my-app' });
  if (c.get('viewOnly')) keepReadTools(server);
  return serveMcp(server, c.req.raw, { onRequest: ({ tool }) => c.set('tool', tool) });
});
```

## Exports

| Export | What it does |
|---|---|
| `serveMcp(server, request, opts?)` | Answers one MCP request and closes the server; `onRequest` hears the method and tool first |
| `jsonResult(value)` | A tool result holding one JSON value as text |
| `keepReadTools(server, isRead?)` | Removes every tool that writes; by default a tool is read-only when its `readOnlyHint` is set |
| `meterTools(server, opts)` | Wraps every registered tool so each call is one tool-call point: wall time, outcome, rows of a JSON list, input and output size |
| `registeredTools(server)` | Every tool on a server, by name |
| `mcpCallOf(body)` | The method and tool a JSON-RPC body asks for |

`meterTools` writes through `@columenlabs/lumen-ops/tools`; see its README for the columns.

## Versions

Every merge to `main` publishes the next patch of every Lumen package at once.

## A chat assistant

`@columenlabs/lumen-ai/assistant` is the server behind a chat side panel: Claude or OpenAI models on the app's own tiers, the app's tools from any MCP server, the web, drafts the person saves, hand off to a higher tier, advice, and a monthly spend cap per person. The panel and Settings sections are `@columenlabs/lumen-ui`'s; the shared types are `@columenlabs/lumen-ui-types/assistant`.

```ts
import {
  assistantRoutes,
  createAssistant,
  doSql,
  mcpServerTools,
  sqlAssistantStore,
} from '@columenlabs/lumen-ai/assistant';

const assistant = createAssistant({
  name: 'Helper',
  system: 'You help people with their notes. Use the notes tools for facts.',
  // Smallest first. The app names them; a person picks each tier's model and effort.
  tiers: [
    { id: 'fast', label: 'Fast', about: 'Quick lookups', model: 'claude-haiku-5-5' },
    { id: 'steady', label: 'Steady', about: 'Most work', model: 'claude-sonnet-5-5' },
    { id: 'deep', label: 'Deep', about: 'Hard judgement', model: 'claude-opus-5-5' },
  ],
  groups: [
    { id: 'notes', label: 'Notes', about: 'Read and edit notes', tools: (caller) => mcpServerTools(() => notesServer(caller.id)) },
  ],
  web: { fetch: { blockHosts: ['app.example.com'] }, scrapeql: { url: 'https://scrapeql.example.com/mcp' } },
  store: sqlAssistantStore(doSql(ctx.storage.sql)), // or d1Sql(env.DB); { table } names another table
  sealer, // the app's own sealing: keys and chats are stored sealed
  // A provider's key when none is set in Settings.
  appKey: async (provider) => (provider === 'openai' ? env.OPENAI_API_KEY : env.ANTHROPIC_API_KEY),
});

const routes = assistantRoutes(assistant, {
  base: '/api/assistant',
  caller: (req) => ({ id: personId(req), admin: isAdmin(req) }),
});
app.all('/api/assistant/*', (c) => routes(c.req.raw));
```

- **Providers.** A tier runs any model in `models` (Claude's and OpenAI's by default, `CLAUDE_MODELS`, `OPENAI_MODELS`): Claude through Anthropic's Messages API, OpenAI through the Responses API, with the same tools, drafts, Stop and caps. xAI's Grok models (`XAI_MODELS`) are opt in: an app that lists them gets an xAI row in Model providers (an API key, `xai-…`); they run on the same Responses client at `XAI_BASE_URL` (`https://api.x.ai/v1`). xAI has no public sign-in for other apps, so Grok takes a key only. A hand-off may cross providers. The advisor and prompt caching marks are Claude's only.
- **Keys.** Each provider has its own keys (`?provider=anthropic|openai|xai` on the key routes). An admin pastes the shared key everyone uses (`PUT /key`); it is tested with one free call before it is kept, then sealed, and no route returns it. A person may add their own (`PUT /my-key`), with one monthly cap on their own keys (`PUT /my-key/cap`).
- **ChatGPT sign-in.** In place of their own OpenAI key a person may sign in with their ChatGPT plan (`POST /my-signin`, then `POST /my-signin/finish {url}`): the sign-in opens in a new tab and ends on `http://127.0.0.1:1455/auth/callback`, a page that does not load, whose address the person pastes back. The tokens are sealed as their own key and refreshed before they run out; answers on the plan count tokens and no dollars.
- **Who pays.** The person's pick (the shared keys by default) while it has a key for the tier's provider and money left this month under its cap (an admin sets the shared keys' cap per person, `PUT /app`), else the other; with neither the panel says why.
- **Tools.** Each group is Off, Read, Read + draft or Read + write per person. A tool is a read when its MCP `readOnlyHint` is set. On Read + draft a write only drafts a card, and runs as the person when they press Save, after access is checked again. A group with `readOnly: true` (read tools only) is offered Off or Read alone. Read + write is offered only for a group with `writes: true`: its writes run at once, and with `undo` set each one's line in the chat has Undo, which calls `undo(caller, { tool, args, result })`; the model is told what was undone. Cards drafted one after another show as one stack with Save all. Use `mcpServerTools` (an SDK `McpServer`), `mcpFetchTools` (a server served as a fetch handler, any SDK), `remoteMcpTools` or `plainTools`.
- **Web.** `fetch` is a plain GET from the Worker (10 s, 2 MB, never the app's own hosts or private addresses). ScrapeQL's own tools join over its MCP API once an admin pastes a Cloudflare Access service token (`PUT /web/scrapeql`). A Worker on ScrapeQL's own Cloudflare account passes its service binding instead, `scrapeql: { url: 'https://scrapeql/mcp', fetch: env.SCRAPEQL.fetch.bind(env.SCRAPEQL) }`: no token is stored, the tools are always on and Settings shows the link with a Test. Each web step carries `web` (`StepWeb`: a search's `query` and `results`, or the page it `read`), so the panel folds a search's results under its line and numbers each page read under the answer as Sources chips; the model marks facts with those numbers ([1]).
- **Hand off and advice.** The `escalate` tool hands one task to a higher tier (the person sets next, any or only when asked); Anthropic's advisor tool lets a higher tier send a plan, at most two an answer.
- **Chats** run on the agent (`./agent`, `LumenAgent`, below): the app routes `POST /chat` and each chat's reads, cards and Undo to its own agent, and `assistantRoutes` answers `POST /chat` with 410 `moved`. Chats saved by the old turn loop stay readable (`GET /chats`, `GET|DELETE /chats/:id`) until `assistant.purge()` drops them 30 days after their last message.
- **Screen moves**: while the person's Settings ▸ Screen is Move (the default), the panel sends its page map (`AssistantMessage.screen`: routes, nav pages, Settings sections, cards on screen, rows to open) and `LumenAgent` gives the model a `screen` tool (`./agent` `screen.ts`). Each call's moves (go, settings, chart, open, point) are checked against the map, kept in the chat and streamed as a `screen` event; the panel runs them through `AssistantScreenProvider` (mounted by `LumenShell`) with an Undo chip, and their outcomes go back with the next message (`outcomes`). Nothing is saved by a move.
- **Background work** an app runs for a person (a score, a summary) is `assistant.complete(caller, { task, system, prompt, images?, maxTokens })`: one answer on the task's tier (`tasks`, so the person picks its model in Settings ▸ Models), no chat and no tools (`images`, base64 with their media type, are read with the prompt: a scanned page, a screenshot), billed to their payer and counted in their spend and allowance like a chat turn. `maxTokens` (default 1,000) goes up to `COMPLETE_MAX_TOKENS` (32,000, thinking included); the answer is streamed, so a long one keeps its connection, and `cut: true` says it stopped at the cap before it ended (the app can ask again, shorter, or continue). It throws `AssistantError` `not_connected`, `app_cap` or `own_cap` when nobody can pay, so the caller waits and tries later. It returns the answer's `usd`, `model` and `usage` (tokens in, cache reads, out, per model). `run: { id, title }` makes the calls that share an `id` one line of the person's usage history (every round of one rebuild); without it a task's calls that day share a line.
- **Usage history.** Each chat (`agentTurn` with `chat`) and each run of background work is one line of the person's month (`usage:YYYY-MM`, the newest 300): its title, first and last use, tokens, cost and its parts per tier and model. `GET /usage?month=YYYY-MM` returns it beside that month's spend and the months that have any; `LumenAssistant`'s footer shows this month's total and opens it (`UsageHistoryView`).

### Commands, `@` and `#`

The panel's composer lists what can follow three keys as they are typed. The kit's own entries are on for every app; an app only adds its own.

- **`/` commands.** Built in: `/compact` (summarise the chat), `/clear` (a new chat), `/model <tier>` (answer on another tier from now on) and `/escalate <task>` (hand one task to the next tier up). An app adds its own on the server with `commands`: the chat shows what the person typed and the model gets `prompt`, with `{args}` replaced by the words after the name (or what the function returns). An app's command wins a built-in's name.

  ```ts
  createAssistant({
    // ...
    commands: [
      { name: 'story', about: 'Find stories for a question', args: '<question>',
        prompt: 'Search my stories for: {args}. List the best three with why each fits.' },
      { name: 'prep', about: 'Prep for an interview', args: '<company>',
        prompt: async (company, caller) => prepPrompt(caller.id, company) },
    ],
  });
  ```

  A command that acts in the browser (opens a page, sets a filter) goes on the panel instead: `LumenAssistant` (or `useLumenAssistantDock`) takes `commands`, each `{ name, about, args?, options?, run }`; `run` returns text to send, or nothing when it acted itself, and `options` lists choices for its words as they are typed.
- **`#` a tier.** `#` lists the app's tiers; the pick is a chip and goes with that message only (`tier`). A higher tier takes it as a task in its own section of the chat; the same or a lower one answers it.
- **`@` a thing.** `@` lists what the person can point at, a group per source; each pick is a chip and goes with the message as a ref (`kind`, `label` and whatever finds it), which the model reads before the message. Standing sources go on the panel (`sources`); a page adds its own while it is shown:

  ```tsx
  import { useAssistantSource } from '@columenlabs/lumen-ui/assistant';

  useAssistantSource({
    id: 'page',
    label: 'On this page',
    items: (q) =>
      rows
        .filter((r) => r.title.toLowerCase().includes(q.toLowerCase()))
        .map((r) => ({ id: r.id, label: r.title, target: `card:${r.id}`, ref: { kind: 'story', label: r.title, id: r.id } })),
  });
  ```

  `target` lights the thing on screen while its row is hovered. A page's source replaces a standing one with the same `id`.

  Text the person highlights on the page is offered first under `@` (Selected text), with where it sits from the nearest `data-assistant-where` attribute. To hand a highlight over from the page, an Ask button calls `composeAssistant({ refs: [selectionRef({ text, where })], text: '' })` (or any refs and text): the panel opens with the chips in the composer, focused for the person to finish.

### Bearings

Each message the model gets starts with a few lines of bearings: the time now in the person's zone (the panel sends the browser's), UTC, how long since the chat's last message and the app's name. They go in the message, not the system prompt, so the prompt cache holds. An app adds its own lines with `bearings`; each call gets 300 ms, and when it is late or throws its lines are left out.

```ts
createAssistant({
  // ...
  app: 'Notes',
  timeZone: 'America/Los_Angeles', // when the browser sends none
  bearings: ({ now, at, span }) => `Next backup: ${at(nextBackup(now))} (in ${span(nextBackup(now) - now)})`,
});
```

An app with its own assistant loop builds the same block with `bearings({ timeZone, lastAt, app, extras })` and puts it before the message.

### Find: one question, one query

The standard way to search an app's records (Columen's canonical setup, 2026-10-28): every app that shows the assistant a collection gives it a find tool, never a list plus one-record reads. One call turns the question into one query that runs where the rows live (D1 or a Durable Object's SQLite). The model gets back only the matching rows and the fields it asked for, and makes the final call itself.

- **Filters** (tags, number and date ranges) are exact SQL.
- **Words** are matched by an FTS5 index (`porter unicode61`, so "egg" finds "eggs"): `any`, `all`, `none` (leave out: "no milk"), and `in` to say which fields to look in.
- **Meaning** comes from Vectorize, opt in per app: `like` ("something light for a hot day") asks the index for the nearest rows, and the same filters and words trim them.
- **Worked-out fields**: a number, date or tag field may be the app's own SQL over the row (`sql: 'json_array_length(t.steps)'`) instead of a column.
- **Counts**: the result carries `count` (all matches), `returned` and `same_name` (different rows that share a name), so the model says the right number. A search by meaning carries `nearest: true` and no `count`: its rows are the nearest few, not every row that fits, so the model never quotes them as a number of matches.

```ts
import { d1Sql, defineFind, findSql, findTool } from '@columenlabs/lumen-ai/assistant';

export const notesFind = defineFind({
  name: 'notes', label: 'note', table: 'notes', key: 'id',
  where: 'deleted = 0',          // the app's own SQL, always applied
  order: 'updated_at DESC',      // with no words to rank by
  fields: {
    title: { kind: 'text' },
    body: { kind: 'text', show: false },     // searchable, returned only when asked
    tags: { kind: 'text', json: true },      // a JSON column, returned parsed
    folder: { kind: 'tag' },                 // exact filter; its values are listed to the model
    updated_at: { kind: 'date' },            // updated_at_from, updated_at_to
  },
});

// In a group's tool source, per answer (a Durable Object passes doSql(ctx.storage.sql)):
plainTools([await findTool(notesFind, d1Sql(env.DB))]);
```

- `findTool` makes `<name>_find` with a flat input schema (every provider takes it) and reads each tag field's values once to list them. The assistant tells the model to put a whole question in one find call.
- `runFind(def, sql, query)` is the same query without the tool: bound parameters only, never model-written SQL. It gives up after 3 s.
- `findSql(def)` gives the index's SQL. `create` is an external-content FTS5 table plus triggers that keep it in step on every insert, update and delete, whoever writes. `fill` indexes the rows already there, and `drop` takes it all out. Put `create` and `fill` in a migration (D1) or a budgeted background step (a Durable Object), never on a request. Until the index exists, words fall back to a plain text match and the result says so, so code can ship before its migration.

Meaning, for the apps whose people ask loosely (a recipe book, a career log; not for exact records like card benefits):

```ts
import { meaningStep, vectorMeaning, workersEmbed } from '@columenlabs/lumen-ai/assistant';

// On the definition: what a row means, and the column every write moves.
meaning: { fields: ['title', 'body', 'tags'], changed: 'updated_at' },

const embed = workersEmbed(env.AI);              // bge-base-en-v1.5: a 768-dimension cosine index
await findTool(notesFind, d1Sql(env.DB), { meaning: vectorMeaning({ embed, index: env.NOTES_INDEX }) });

// Off the request path (waitUntil after a write and when the tool opens, an alarm, a queue):
ctx.waitUntil(meaningStep({ def: notesFind, sql: d1Sql(env.DB), embed, index: env.NOTES_INDEX, mark }));
```

- `meaningStep` embeds only the rows whose `changed` column moved past its bookmark (`mark`: get and put, kept by the app), at most 50 a step in one embedding call and one upsert, and takes rows the find hides (its `where`) out of the index. It resumes where it stopped and runs safely twice at once; `done` is false while rows are left.
- A person's own rows get a `namespace` each (`vectorMeaning` and `meaningStep` take one), so one index serves one app.
- When the index cannot answer in 3 s, `like` is left out, the rest of the find runs and the result says so.

## An agent on Cloudflare Think

`@columenlabs/lumen-ai/agent` runs one chat as a Cloudflare Think agent (`@cloudflare/think`, experimental) on the app's tiers, keys and tool groups. Think keeps the loop, the messages, streaming, resume and compaction; the kit adds the model on the payer's key, the tools at the person's access, the spend cap and the usage. It will replace `./assistant`'s own loop.

| Export | What it does |
|---|---|
| `LumenAgent` | An abstract Think agent. The app answers `plan(turn)` (model, key, effort, instructions, tool sources, money left) and hears `settle(end)` (outcome, usage parts, context size, time) when the turn ends |
| `aiModel(model, key, opts?)` | The AI SDK model for a tier on an API key, or on a ChatGPT plan sign-in (`key.plan`, through `planFetch`) |
| `planFetch(fetch?, name?)` | Rewrites Responses calls to a plan sign-in's rules: tools in one namespace, no output cap, a forced call as the only tool |
| `planFallback(primary, fallback, onSwitch)` | A plan's model that hands the call, and the rest of the turn, to `fallback` when the plan reaches its usage limit (a 429 or a usage code, before any output) |
| `turnSettings(model, opts)` | Output cap and effort as the provider takes them |
| `openAiTools(sources, opts)` | The app's tool groups as AI SDK tools: reads always, drafts and writes by access, results cut at 16k characters |
| `UsageMeter`, `tokenUsage(u)` | Prices each step's tokens (cache reads and writes, reasoning) into one usage part |

A ChatGPT plan sign-in is free to the app (`priced` with `free`). When the plan is used up for now, a turn with `fallback` (`agentTurn` sets the app's first Claude on the same payer's Anthropic key) answers on Claude instead of ending in the limit's error, its use its own part. Nothing here holds a key or a token: the app passes them per turn.

An app with an `Assistant` gets the whole plan from it: `assistant.agentTurn(caller, { message, tier?, context?, refs?, time_zone? })` returns `{ plan, settle }` with the person's tier and model on whoever pays, the tool groups at their access, the kit's rules, the bearings and the page before the message, `escalate` to a higher tier (its own usage part, inside the same cap) and Claude's advisor. `settle` adds the spend to the payer's month and reports the turn through `onStep`. It throws `AssistantError` when nobody can pay.

Drafts and writes are cards in the chat's own storage (`lumen_cards` in the agent's SQLite). A write the person's access only drafts makes an open card and changes nothing. `saveCard(id)` runs it through the app's `applyDraft`, and `dismissCard(id)` drops it. A write made at once is kept for `undoCard(id)` through the app's `undoWrite`. `cards()` lists the cards. The next answer is told how each card ended and what was undone. With an `Assistant`, `applyDraft` is `assistant.runDraft(caller, card)` and `undoWrite` is `assistant.undoChange(caller, card)`. Think compacts the chat past `COMPACT_AT` (150k tokens) on the last answer's model and key, and that spend is added to the next answer.

**Connectors.** A person adds an MCP server to their chat with `addConnector(name, url)`. The address must be https. The server signs in with its own OAuth through Think's MCP client, and the answer carries `authUrl` while it asks. `connectors()` lists them and `removeConnector(id)` drops one. Think never merges their tools on its own (`includeMcpTools` is false). A turn opens the ones `plan.connectors` lists, at the access the app gives each, as group `mcp_<id>`. Read keeps the tools the server marks read-only. Read + draft makes the rest cards, which `saveCard` runs on the server itself. Read + write runs them at once with no Undo. A connector's text is untrusted data.

**Lazy tools.** Past `LAZY_AT` (30) tools, a turn sends the model its core tools and `tool_search`, with one catalog line per group in the instructions. By default the core tools are the apps' finds, the hand off and the advisor. `plan.lazy` sets `{ at, core }`. A search matches the words in a tool's name and description and turns on up to 8 tools from the next step on.

**Images.** `AskInput.images` (base64 PNG, JPEG, WebP or GIF; at most `ASSISTANT_IMAGES_MAX` (4) and `ASSISTANT_IMAGE_CHARS` together) go into the user message as file parts (`imageParts`), so the model sees them and the chat shows them again. `LumenAssistant images` lets the person paste (Cmd+V) or drop images on the box; the composer scales each to 1568 px on its long edge. An app's `POST /chat` passes `images` on in its `AskInput`.

**The panel.** `LumenAssistant` reads a Think chat with no change. `ask(input, sink)` runs one answer and sends the panel's own events (`AssistantEvent`: the chat, the text, each tool line, cards, hand-off sections, advice, the use) to `sink`. The app's `POST /chat` returns `askResponse((sink) => chat.ask(input, sink), { signal, stop: () => chat.stop() })`, the same server-sent events `assistantRoutes` sends. `view()` gives a stored chat as the panel's items, and `usage()` gives the chat's use so far. A card's id is its tool call's, so the panel's Save, Dismiss and Undo go to `saveCard`, `dismissCard` and `undoCard`. The app keeps the list of chats, and each chat is its own agent, such as a facet of the person's store. `chunkEvents` and `itemsOf` are the mapping, for an app that streams some other way.

**Steps.** One answer makes at most `plan.maxSteps` model calls (`MAX_STEPS`, 8). The last one runs with no tools and `LAST_STEP_NOTE`, so an answer always ends in words: what it found, and what is left when the task did not fit.

**Steer and queue.** While an answer runs, the panel's box stays open: Enter steers the message into the answer (`steer(message)` on the agent; the app routes `POST /chats/:id/steer` `{ message }` to it and answers `{ steered }`), Alt+Enter queues it for after. A steer joins at the answer's next step, after the tool it is on, with `STEER_NOTE` before it for the model; the panel shows it there marked Steered (event `steered`), and `view()` keeps it in place (`SteerNote`, under the message the answer is to). A steer the answer ends before reading comes back as `unsteered` and goes first in the queue. `plan.steer: false` turns it off for a model; an app without the route (404) shows Queue only. Queued messages each go as their own message when the answer before them ends; each has Steer now, Edit and Remove.

**Retry.** A turn that ended in an error shows a Retry icon (⟳) beside Copy, always visible, while no answer runs and someone can pay (`status.wait` unset; hidden otherwise, never disabled). It sends the turn's words, `@` parts, `#` tier and images again as a new message (`chat.retry(at, user, extra)` in `useAssistantChat`), marked Retry above the bubble; the old error turns grey (`retried` on the error item) and stops offering Retry. Nothing changes on the server: the retried message is an ordinary message.

```ts
class Chat extends LumenAgent<Env> {
  #settle?: (end: AgentTurnEnd) => Promise<void>;
  async plan(turn: TurnContext) {
    // this.input: what the person sent (message, page, refs, tier, time zone).
    // chat: this chat's id, so its use is one line of the person's usage history.
    const { plan, settle } = await assistant.agentTurn(caller, { ...(this.input ?? { message: '' }), chat: this.name });
    this.#settle = settle;
    return plan;
  }
  settle(end: AgentTurnEnd) { return this.#settle?.(end) ?? Promise.resolve(); }
  protected applyDraft(card: AgentCard) { return assistant.runDraft(caller, card); }
  protected undoWrite(card: AgentCard) { return assistant.undoChange(caller, card); }
}
```

## Workspaces: tabs over recipes, run again on demand

`@columenlabs/lumen-ai/workspaces` is the server the kit's `WorkspacesSection` and `WorkspacePage` call. A workspace is a person's page of tabs; each tab is a table over a **frame**: the rows one **recipe** pulled, the recipe itself and the person's hand edits. A recipe is one call to one of the product's read tools (`{kind: 'call', fn: 'jobs.list', args}`), so running it again needs no model. Nothing runs on a timer: ↻ on a tab runs its recipe, ↻ in the header runs every tab one after another, each within 15 s (`RUN_MS`); a failed run keeps the last rows and says why.

```ts
import { createWorkspaces, doSql, workspaceMigrations, workspaceRoutes } from '@columenlabs/lumen-ai/workspaces';

// In the store that holds the person's data (a Durable Object's SQLite, or D1 with d1Sql):
for (const q of workspaceMigrations({ spaces: 'app_ws_spaces', frames: 'app_ws_frames' })) sql.exec(q);
const store = createWorkspaces({
  db: doSql(sql),
  tables: { spaces: 'app_ws_spaces', frames: 'app_ws_frames' },
  run: (recipe, { owner, signal }) => callReadTool(owner, recipe, signal), // the product's own tools, as the person
});

// In the Worker, at the assistant's api:
const routes = workspaceRoutes({ base: '/api/assistant', owner: callerOf, store: () => store });
```

Budget: one frame is one row (at most 1.5 MB of rows, 10,000 rows, 50 columns), so a run writes one row; every read has a LIMIT (30 workspaces, 12 tabs each, 100 frames). Columns are typed from their values (number, date, text); a list of words, or short text from a small set, becomes a tags column (chips). The kit's `WorkspacesProvider` takes `recipes` to offer + New tab from a recipe in the tab bar.

### Web data and pushed datasets (no server code runs)

Three more ways rows reach a tab, all on a free Workers plan (no Dynamic Workers):

- **Fetch recipe** (`{kind: 'fetch', requests: [{url, method?, key?}], each?: {values}, rows?, pick?}`): declarative web reads the product runs on its server. `{field}` holes in a URL fill from each value of `each` (text fills `{value}`); `fetchCalls` expands them (at most `FETCH_CALLS`, 50 a run) and `fetchedRows` turns the answers into rows, the `each` value's fields first, then `pick`'s dotted paths (`current.temperature_2m`). A data key is named (`key`), never sent: the product adds it server side.
- **Browser script** (`{kind: 'script', runtime: 'browser', code, requests?}`): JavaScript that runs in the person's page. The kit's `runBrowserFrame` loads `<base>/sandbox` (this package's `SANDBOX_HTML`, served with `SANDBOX_CSP`: `connect-src 'none'`) in an iframe with `sandbox="allow-scripts"`, runs the code in a Web Worker there (stopped at `BROWSER_RUN_MS`, 30 s), and saves what it returns with `PUT /frames/:id/rows` (one write, the frame's caps checked). The code is the body of `async (fetched, hub) => rows`: `fetched` holds the answers to its `requests`, `hub.fetch(url, {key})` makes one more read through the product's proxy (`fetch` in `workspaceRoutes`, `POST <base>/fetch`). The server never runs it: `refresh` refuses it (409, open the tab), and `refreshAll` lists such tabs as `browser`.
- **Pushed dataset** (`store.pushFrame(owner, {name, rows, mode, by, key?})`): rows an outside agent wrangled (a CSV parsed by `parseCsv`, at most `CSV_BYTES` a call, the rest as `append` parts; with `key`, an appended row replaces the one with its key). Origin `harness`, no recipe; `by` names the agent and the tab's status bar reads "Pushed by Claude Code · 4 min ago". `frameTab(owner, workspace, {name, frame})` shows one in a tab (no run); `removeFrame` deletes one with its tabs.

`workspaceRoutes` lets `call`, `fetch` and browser `script` recipes through to the product's `allow`; server `sql` and `script` are refused.

# Package: @columenlabs/lumen-auth

Lumen's sign-in checks for Workers behind Cloudflare Access: verify the token Access signs on every request, in the Worker, so a route stays closed even when the Access application is misconfigured or a request reached the Worker another way. No dependencies: Web Crypto and `fetch`, so it runs in a Worker, Bun or Node.

- Docs: https://lumen.columenlabs.com/docs/
- For agents: https://lumen.columenlabs.com/llms.txt
- Source: https://github.com/columenlabs/lumen (`packages/auth`). MIT.

## Install

```bash
bun add @columenlabs/lumen-auth
```

Pin it to the same exact version as the other Lumen packages.

## Verify an Access token

```ts
import { AccessVerifier, accessToken } from '@columenlabs/lumen-auth';

// One per isolate: the team's signing keys are fetched once and kept an hour.
const access = new AccessVerifier({
  teamDomain: 'myteam.cloudflareaccess.com',
  aud: [env.ACCESS_AUD],            // one application's AUD tag, or several (one Worker, several hosts)
});

const who = await access.verify(accessToken(request));
if (!who) return new Response('Not found', { status: 404 });
who.email;         // the person, when a person signed in
who.serviceToken;  // the service token's client ID, when a service token signed in
who.sub;           // Access's subject id
```

`verify` returns `null` for a missing, malformed, expired or wrongly signed token, a token for another application (`aud`) or another team (`iss`). Only RS256 is accepted. A key id it has not seen fetches the keys again.

| Export | |
|---|---|
| `AccessVerifier(config, fetch?, now?)` | `verify(token)` → `AccessIdentity` or `null`. `fetch` and `now` are for tests |
| `AccessConfig` | `{ teamDomain, aud }` |
| `AccessIdentity` | `{ sub, email?, serviceToken? }` |
| `accessToken(request)` | The request's `Cf-Access-Jwt-Assertion`, if any |
| `ACCESS_HEADER` | `'cf-access-jwt-assertion'` |

Who Access lets in stays Access's policy; what each person may do stays the app's own. This package only proves the request came through Access.

## Versions

0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

# Package: @columenlabs/lumen-ops

Lumen's ops parts for Cloudflare Workers: every request your app answers, every event and every data query becomes one Analytics Engine point, so you can find errors, mismatches and slow or heavy queries and fix them. The meter wraps your bindings once, so new code is metered without opting in. It writes only each query's shape, never a value. It also meters tool calls (`/tools`) and sends signed webhooks (`/webhooks`).

- Docs: https://lumen.columenlabs.com/docs/
- For agents: https://lumen.columenlabs.com/llms.txt
- Source: https://github.com/columenlabs/lumen (`packages/ops`). MIT.

## Install

```bash
bun add @columenlabs/lumen-ops
```

Pin it to the same exact version as your other Lumen packages. It uses `AsyncLocalStorage`, so the Worker needs the `nodejs_compat` flag.

## Set up

Bind an Analytics Engine dataset in `wrangler.jsonc`:

```jsonc
"analytics_engine_datasets": [{ "binding": "QUERIES", "dataset": "myapp_queries" }]
```

Wrap the bindings once at start, and hand the wrapped ones to your app:

```ts
import { foldRoute, meteredClickHouse, meteredD1, setQueryCallerOf, setQuerySink } from '@columenlabs/lumen-ops';

setQuerySink(env.QUERIES);
// Name the request in scope: the app (or part of it), the route, and the tool when an MCP call runs.
setQueryCallerOf(() => {
  const req = currentRequest(); // your own request scope
  return req && { app: 'myapp', kind: 'fetch', route: foldRoute(new URL(req.url).pathname) };
});
const db = meteredD1(env.DB);
const clickhouse = meteredClickHouse(env.CLICKHOUSE); // any ClickHouse HTTP service binding
```

In a Durable Object, meter its SQLite:

```ts
import { meteredSql } from '@columenlabs/lumen-ops';

const sql = meteredSql(state.storage.sql, { app: 'myapp', kind: 'do', route: 'Person' });
```

A cron run, queue batch or alarm names itself, so its queries are charged to it:

```ts
import { withQueryCaller } from '@columenlabs/lumen-ops';

await withQueryCaller({ app: 'myapp', kind: 'cron', route: 'nightly-rollup' }, () => rollup(env));
```

Another engine (R2 SQL, an HTTP database) calls `meterQuery({ engine, sql, method, ok, ms, ... })` from its one client.

## What a point holds

One point per kind of statement per turn: the same statement run many times in one go (a loop of inserts) is one point whose numbers are totals, with `statements` saying how many ran. Divide by it for a mean. The column order is the contract for reading the dataset back:

| Column | Holds |
|---|---|
| `index1` | Engine: `d1`, `clickhouse`, `do_sqlite`, `r2_sql` or your own |
| `blob1` … `blob5` | Engine, app, kind (`fetch`, `cron`, `queue`, `alarm`, `do`), route (ids folded to `:id`), tool |
| `blob6` … `blob8` | Op (`select`, `insert`, `update`, `delete`, `ddl`, `pragma`, `other`), fingerprint, the query's shape (up to 1 KB) |
| `blob9`, `blob10` | `ok` or `error`, method (`all`, `first`, `run`, `raw`, `batch`, `query`, `insert`, `exec`) |
| `double1` … `double10` | Wall ms, the engine's own ms, rows read, bytes read, rows returned, rows written, response bytes (each a total), HTTP status, statements, slowest ms |

The shape has every string and number literal as `?`, `IN` lists folded to `(?...)`, comments and ClickHouse's `FORMAT` dropped, and an insert's rows cut off. The fingerprint is a hash of the shape, one per kind of query.

Read it back with the Analytics Engine SQL API, for example the slowest shapes of the last day:

```sql
SELECT blob7 AS fingerprint, any(blob8) AS shape,
       sum(IF(double9 > 0, double9, 1) * _sample_interval) AS calls,
       sum(double1 * _sample_interval) / sum(IF(double9 > 0, double9, 1) * _sample_interval) AS mean_ms,
       max(double10) AS slowest_ms
FROM myapp_queries
WHERE timestamp > NOW() - INTERVAL '1' DAY
GROUP BY fingerprint ORDER BY mean_ms DESC LIMIT 20
```

## Exports

| Export | What it does |
|---|---|
| `setQuerySink(binding)` | The dataset every point goes to; nothing is written until it is set |
| `setQueryCallerOf(fn)` | Names the request in scope when no job is |
| `withQueryCaller(caller, fn)` | Charges every query inside `fn` to `caller` |
| `meteredD1(db)` | D1, metered: `prepare` and `batch`, with D1's own rows read and written and duration |
| `meteredClickHouse(binding)` | A ClickHouse HTTP service binding, metered when the answer has been read: wall time to the last byte, ClickHouse's own statistics |
| `meteredSql(sql, caller?)` | A Durable Object's `storage.sql`, metered; its cursor keeps `toArray`, `one`, `raw`, `next`, iteration and `columnNames` |
| `meterQuery(point)` | One point by hand, for any other engine |
| `queryShape(sql)` | The shape, fingerprint and op of a query |
| `foldRoute(path)` | A path with id-like segments as `:id` |
| `setQueryRowCap(n)` | The most rows one statement should return; one that returns more is marked `capped` in `blob11` |

## Requests

`@columenlabs/lumen-ops/hono` meters every request a Hono app answers: mount it once, first, and every route the app has or adds later writes one point with its route template, status, outcome code and time. It names the request in scope, so events and queries inside carry its id.

```ts
import { requestId } from 'hono/request-id';
import { requestMeter } from '@columenlabs/lumen-ops/hono';
import { setRequestSink } from '@columenlabs/lumen-ops/requests';

app.use('*', async (c, next) => {
  setRequestSink(c.env.REQUESTS, { log: true }); // also one JSON line per point in Workers Logs
  await next();
});
app.use('*', requestId());
app.use('*', requestMeter({
  app: 'myapp',
  env: (c) => c.env.DEPLOY_ENV,
  describe: (c) => ({ surface: 'api', subject: c.get('accountId'), callerKind: 'key' }),
}));
```

| Column | Holds |
|---|---|
| `index1` | Subject: an opaque id the app makes for who called, or `anon` |
| `blob1` … `blob7` | App, surface, method, route template, outcome (`ok`, an `error` code from a JSON answer, `exception`, `http_<status>`), caller kind, caller id |
| `blob8` … `blob13` | Region, env, version, colo, country, request id |
| `double1` … `double6` | Status, ms, bytes in, bytes out, upstream ms, subrequests |

A path no route matched is written as `*`, so a scanner's junk never lands. Without Hono, wrap the handler in `withRequest(scope, route, fn)` and call `meterRequest(point)` yourself.

## Bindings and outbound calls

Wrap the env once at the entry and patch `fetch` once, and every Durable Object RPC method, Workers AI, Vectorize, KV, R2, service or VPC call and every outbound `fetch` is timed and charged to the request in scope:

```ts
import { meterFetch, meteredBindings } from '@columenlabs/lumen-ops';
import { requestMeter } from '@columenlabs/lumen-ops/hono';

meterFetch();
app.use('*', requestMeter({ app: 'myapp', serverTiming: true }));
export default { fetch: (req, env, ctx) => app.fetch(req, meteredBindings(env, { kinds: { AI: 'ai', INDEX: 'vectorize' }, skip: ['METRICS'] }), ctx) };
```

A call is named by its binding and method (`DIRECTORY.seen`, `AI.run`, `fetch.api.example.com`), never its arguments. The request point's `upstream ms` and `subrequests` add them up; `serverTiming: true` sends the split back as `Server-Timing` (`do`, `ai`, `fetch`, ..., `app`, `total`), and when the request ends each call code is one `call` event (`code` the call, `ref` its kind, `ms` the total, counts: calls, failed). Outside a request (an alarm) each call is its own event. `app` may be a function and `route` names the route when one Worker hands requests on to other apps by path.

## Events

`@columenlabs/lumen-ops/events` writes what an app does that isn't a request it answers: a call to another service, a webhook in or out, a sync's start and end, a sign-in. With the request points they show whether what came in was acted on.

```ts
import { meterEvent, setEventSink } from '@columenlabs/lumen-ops/events';

setEventSink(env.EVENTS);
meterEvent({ event: 'bank.call', code: '/accounts/get', ok: res.ok, ms, status: res.status, upstream: true });
meterEvent({ event: 'sync.done', ok: true, subject: accountId, ref: connectionId, counts: [added, modified, removed] });
```

| Column | Holds |
|---|---|
| `index1` | Subject, or `anon` |
| `blob1` … `blob10` | App, event, code, outcome, ref, trigger, request id, upstream id, env, version |
| `double1` … `double6` | ms, status, count1, count2, count3, attempt |

`upstream: true` adds the call's time to the request's `upstream ms`. In a Durable Object no request is in scope: give `setEventSink(binding, { app, env, version })` the defaults, and pass a `requestId` the caller sent if you have one.

## Browser telemetry

`useLumenTelemetry` in `@columenlabs/lumen-ui` sends screens opened, uncaught errors (class and a hash of the stack, never the message), failed requests and Web Vitals in batches to `/api/t`. The Worker checks and writes them:

```ts
import { meterClientBatch, setClientSink } from '@columenlabs/lumen-ops/client';

setClientSink(env.CLIENT);
app.post('/api/t', async (c) => {
  meterClientBatch(await c.req.json().catch(() => null), { app: 'console', subject: c.get('accountId') });
  return c.body(null, 204);
});
```

| Column | Holds |
|---|---|
| `index1` | Subject, or `anon` |
| `blob1` … `blob9` | App, kind (`view`, `error`, `fetch_fail`, `vital`), route template, name, stack fingerprint, request id, version, device, env |
| `double1`, `double2` | Value (ms or score), status |

A batch that fails the schema is dropped whole; only codes, templates and numbers pass.

## Tool calls

`@columenlabs/lumen-ops/tools` meters each call an assistant or agent makes: one point per call with its latency, outcome and a hash of the code it ran, so slow or failing tools show up and the same script is grouped across runs.

```ts
import { meteredCall, meterToolCall, setToolSink } from '@columenlabs/lumen-ops/tools';

setToolSink(env.TOOL_CALLS); // an Analytics Engine dataset binding

// Wrap a call: latency and outcome are taken for you.
const rows = await meteredCall({ app: 'trade', tool: 'portfolio_list', kind: 'call' }, () => run(args));

// Or write one by hand, with the code a script ran.
meterToolCall({ app: 'trade', tool: 'script', kind: 'script', ok: true, ms: 840, code: source, rows: 120 });
```

| Column | Holds |
|---|---|
| `index1` | app |
| `blob1`…`blob9` | app, tool, kind, outcome (`ok` or `error`), error kind, code hash, source, tier, run id |
| `double1`…`double6` | ms, rows, bytes in, bytes out, tokens in, tokens out |

Arguments and results are never written; only their sizes.

| Export | What it does |
|---|---|
| `setToolSink(binding)` | The dataset tool points go to; nothing is written until it is set |
| `meterToolCall(point)` | One point by hand |
| `meteredCall(point, fn, errorKind?)` | Runs `fn`, timing it and writing its outcome |
| `codeHash(code)` | A short hash of a script, whitespace folded |

## Webhooks out

`@columenlabs/lumen-ops/webhooks` sends one delivery, signed per the [Standard Webhooks](https://www.standardwebhooks.com) spec when a secret is given, so the receiver can verify it with any Standard Webhooks library. It never throws: the result says how it went, for the app's own delivery log and retries.

```ts
import { newWebhookSecret, sendWebhook } from '@columenlabs/lumen-ops/webhooks';

const secret = newWebhookSecret(); // whsec_…, shown to its owner once, kept sealed
const r = await sendWebhook({
  url: endpoint.url,
  secret,
  id: event.id, // the same id on a retry
  body: JSON.stringify(event.payload),
  headers: { authorization: `Bearer ${endpoint.token}` },
  userAgent: 'MyApp-Webhooks/1',
});
if (!r.ok) scheduleRetry(event, r.status, r.error);
```

| Export | What it does |
|---|---|
| `sendWebhook(send)` | One POST: `{ ok, status, ms, id, error? }`; status 0 when the endpoint never answered |
| `newWebhookSecret()` | A new `whsec_` secret, 32 random bytes |

The endpoint's own headers go first, so they can never replace the signature headers. Redirects count as failures unless `redirect` says otherwise; the timeout is 10 s by default.

## Versions

0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

# Package: @columenlabs/lumen-people

Lumen's people, access and invites, server side: who may sign in, what each person may do in each part of an app, invites with a single-use link that expires, and an audit log of every change. It pairs with the People screens in `@columenlabs/lumen-ui/people`. No dependencies beyond `@columenlabs/lumen-ui-types`: Web Crypto, `Request` and `Response`, so it runs in a Worker, a Durable Object, Bun or Node.

- Source: https://github.com/columenlabs/lumen (`packages/people`). MIT.

## Install

```bash
bun add @columenlabs/lumen-people @columenlabs/lumen-ui-types
```

Pin both to the same exact version as the other Lumen packages.

## Scopes and levels

A scope is anything access is given on: an app, or a construct inside one (a folder, a collection). Each has its own ordered levels, lowest first (`None, View, Edit, Admin` when it names none). A person holds one level per scope; no grant is the lowest. Admins hold the top level everywhere; disabled people and expired invites hold the lowest.

```ts
import type { Scope } from '@columenlabs/lumen-ui-types/people';

export const SCOPES: Scope[] = [
  { id: 'tools', name: 'Tools' },
  { id: 'recipes', name: 'Recipes' },
  { id: 'collections', name: 'Collections', parent: 'recipes', resourceLabel: 'Collection' },
];
```

## The service

```ts
import { can, createPeople, doSql, sqlStore } from '@columenlabs/lumen-people';

// In a Durable Object, so the admin floor check and its write never interleave:
const people = createPeople({
  store: sqlStore(doSql(ctx.storage.sql)),   // or sqlStore(d1Sql(env.DB))
  scopes: SCOPES,
  fixedAdmins: ['owner@example.com'],        // always an active admin
  inviteDays: 7,
});

const person = await people.seen('a@example.com');   // on each sign-in: null = refuse
can(person, SCOPES[0], 'view', SCOPES);              // the one check a route makes
```

The rules it keeps:

- One active admin always; the built-in admins can never lose it.
- Only an admin invites, changes access or removes; refusals are logged too.
- An invite link is single use; only its SHA-256 hash is stored. Resend makes a new link and restarts the clock, revoke kills it. An invite past its life is refused at sign-in until resent.
- Every change is one audit event (who, what, when, from where), kept a year.

## The routes

```ts
import { peopleRoutes } from '@columenlabs/lumen-people/routes';

const routes = peopleRoutes({
  base: '/api/people',
  people: () => people,                                 // or a Durable Object stub
  actor: (req) => ({ email, admin, via: 'app' }),       // your verified caller
  scopes: SCOPES,
  appName: 'Example',
  link: (token) => `https://app.example.com/invite/${token}`,
  mailer: () => myMailer,                               // optional: (msg) => { ok, detail }
  onRemove: async (person) => { /* delete their data */ },
});

app.all('/api/people/*', (c) => routes(c.req.raw));
```

Without a mailer every invite returns its link to copy by hand; a failed send never undoes an invite.

# Package: @columenlabs/lumen-person

Lumen's one store per person: a Durable Object whose SQLite holds every app's tables for that person. Each app is a module that owns its tables (`<module>_*`), its migrations and its wake time, so app code stays apart while one person's data joins in one SQL query, one backup and one delete. No dependencies: it runs in a Worker with `nodejs_compat` (for `AsyncLocalStorage`) and any Durable Object with SQLite storage.

- Source: https://github.com/columenlabs/lumen (`packages/person`). MIT.

## Install

```bash
bun add @columenlabs/lumen-person
```

Pin it to the same exact version as the other Lumen packages.

## A store and its modules

```ts
import { DurableObject } from 'cloudflare:workers';
import { PersonObject, type PersonModule, personModule } from '@columenlabs/lumen-person';

const notes: PersonModule<Env> = {
  name: 'notes',
  migrations: [
    'CREATE TABLE notes_items (id INTEGER PRIMARY KEY, title TEXT NOT NULL, at INTEGER NOT NULL)',
  ],
  async call(ctx, method, args) {
    if (method === 'add') {
      ctx.sql.exec('INSERT INTO notes_items (title, at) VALUES (?, ?)', (args as { title: string }).title, Date.now());
      await ctx.wakeAt(Date.now() + 60_000);
      return { ok: true };
    }
    throw new Error(`no ${method}`);
  },
  async wake(ctx) {
    // small steps: stop by ctx.deadline and ask for the next time
  },
};

export class PersonStore extends DurableObject<Env> {
  private readonly person = new PersonObject(this.ctx, { modules: [notes], extra: this.env });
  call(owner: string, module: string, method: string, args?: unknown) {
    return this.person.call(owner, module, method, args);
  }
  alarm() {
    return this.person.alarm();
  }
}

// In the Worker
const mine = personModule(env.PERSON, email, 'notes');
await mine.call('add', { title: 'Buy saw blades' });
```

The first call names the person and claims the store; a later call for anyone else is refused (403).

## Row budgets: no loop can spend the account's day

Cloudflare's free plan allows an account 5M Durable Objects rows read and 100k rows written a day, across every object. Past either, every SQL call in every object throws until 00:00 UTC. Every store is bounded (`budget` in its deps, `RowBudget` in `./budget` for any other object):

| Bound | Default | Past it |
|---|---|---|
| One call | 100k rows read, 20k written | its next statement throws; the call answers 503 |
| One wake | 200k read, 20k written | the same, for that wake |
| The store's UTC day | 600k read, 12k written | calls answer 503 until 00:00 UTC |
| `background` share of the day | 0.6 | wakes wait for the next day (spread over its first half hour); calls keep working |

Counts are the cursors' own `rowsRead` and `rowsWritten`, what Cloudflare bills. `onLimit` hears each level once a day (alert someone there). `_object.budget` reads today's totals and `_object.brake {level: 'background' | 'stop' | 'ok', until?}` sets a brake from outside, for when the whole account nears its cap; both answer on a spent day. A request that needs more than one call's budget (an import, a rebuild) is a background job in small wakes, never one request.

## Rules it keeps

- **Migrations fail per module.** Each module migrates on its first call or wake, each step in one transaction. A step that throws leaves only that module answering 503 for a minute before it tries again; every other module keeps working. Never edit or reorder a released step: add one.
- **One alarm for every module.** `_wakes` keeps each module's next time and the store's alarm is the earliest. Each wake gets `ctx.deadline` (30 s by default, `wakeMs`) to stop by and set its next time. A wake that throws is tried again in 1 minute, doubling to an hour.
- **Waiting is shared, work is not.** While one call awaits the network (a fetch, a model) other calls run. Only synchronous work holds the store, so keep heavy parsing out of it.
- **Calls stay in place.** Code running in a person's store that calls the same person through `personCall` runs in place instead of a new request.

## Backup, restore, delete

The store's own module `_object` (or `personModule(...).own(method)` for one module):

| Method | Does |
| --- | --- |
| `dump` | Every module's tables as stored (sealed values stay sealed), with each module's migration level |
| `dumpModule {module}` | One module's tables |
| `loadModule {module, dump, prefix?}` | Replaces one module's tables from a dump. With `prefix`, tables named without it (`items`) load into `<module>_items`, so rows move in from an older store |
| `load` | Replaces every module's tables from a whole dump |
| `wipeModule {module}` | Empties one module's tables and its wake |
| `wipe` | Deletes the whole store (every table, key and the alarm) |
| `counts` | Rows per table, migration levels and any module whose migration is failing |

## Moving rows in from an older store

An app that kept its own Durable Object moves into the person's store a page at a time, so no step holds either store for long:

- The old store answers `exportRows(sql, table, after)`: rows after a rowid bookmark, at most 500 rows and about 4 MB a page (at least one row, so a big blob still moves), bytes as `{b64}`.
- The module's wake writes each page with `importRows(sql, table, page)` inside `ctx.transaction`, keeps the bookmark and asks to wake again. Rows keep their rowids, so a page sent twice changes nothing.
- When every table is across, `rowStats` on both sides (rows and highest rowid per table) must match before the app reads from the new store. Stop the old store's alarm and writes while it moves; a table whose stats differ goes again.
- An old store that held many people's rows in one table moves each person's part: `exportRows(sql, table, after, { where: { sql: 'scope = ?', args: [email] } })` and `rowStats(sql, tables, where)` with the same filter.

Point-in-time recovery (`ctx.storage.getBookmarkForTime`) restores the whole store, every module at once. Restore one module from its dump instead, and keep PITR for the whole store.

Virtual tables (an FTS5 word index from `@columenlabs/lumen-ai`'s `findSql`) are not copied: their triggers fill them as rows load, and a rebuild runs after.

# Package: @columenlabs/lumen-ship

Lumen's shipping kit: one release command that writes each release's notes with Claude, the changelog What's new reads, and the lint guards every Lumen app runs. Bash plus a small TypeScript reader, no framework.

- Docs: https://lumen.columenlabs.com/docs/
- For agents: https://lumen.columenlabs.com/llms.txt
- Source: https://github.com/columenlabs/lumen (`packages/ship`). MIT.

## Install

```bash
bun add -d @columenlabs/lumen-ship
```

Pin it to the same exact version as the other Lumen packages. The command needs `bash`, `git`, `gh` (with REST access to the repo), `jq` and `curl`.

## Releases

`lumen-ship release` cuts a repo's GitHub releases. Run it from the repo root, on each merge to `main` (a CI job) or by hand.

| Command | What it does |
|---|---|
| `lumen-ship release` | One patch release at `main` once `cadence.every` merges landed since the newest release tag, or on the first merge `cadence.days` days after it. `FORCE=1` cuts it now |
| `lumen-ship release minor` | Tags `main` as the next minor. Its notes are the hand-written `docs/releases/v<major>.<minor>.0.md`, which must be on `main` |
| `lumen-ship release notes` | Sets the newest minor's notes from its file again |
| `lumen-ship release tag v1.2.3` | Makes the release of a tag that already exists (for a publish job that tags first). `REDO=1` writes its notes again |

`DRY_RUN=1` prints what it would do and creates nothing.

### Notes

Claude writes each release's notes from the merged pull requests since the tag before (commits stand in where there are none), from your prompt. A reply is published only when whole: anything cut short, refused or failed is asked again, at most 3 times, then the release fails. Without `ANTHROPIC_API_KEY` the notes are GitHub's own list of pull requests.

Set `LUMEN_FORBIDDEN_NAMES` (a regex alternation, `A|B`) in a public repo: notes that name one are asked again and never published, and the pull request list shows numbers only.

### Changelog for What's new

With `changelog.path` set, each release's Key takeaways are also committed to `main` as JSON, newest first, and the tag goes on that commit, so the release deploys its own notes. Each takeaway bullet opens with tags: type tags (`[Feature]`, `[Improvement]`, `[Fix]`, `[Performance]`, `[Security]`) become its chips, and tags listed in `changelog.apps` become its `apps`. Ask for them in your prompt:

```md
- [Fix] [Console] **Exports finish**: ...
```

```json
[{ "tag": "v0.3.2", "published_at": "2026-10-24T18:00:00Z",
   "takeaways": [{ "text": "**Exports finish**: ...", "types": ["fix"], "apps": ["console"] }] }]
```

Serve it to `WhatsNew` (`LumenShell`'s `releases` prop) with the reader:

```ts
import { RELEASES_HEADERS, listReleases, type Release } from '@columenlabs/lumen-ship/releases';
import changelog from './changelog.json';

app.get('/api/releases', (c) =>
  c.json(
    { releases: listReleases(changelog as Release[], {
        limit: c.req.query('limit'),
        before: c.req.query('before'),
        canSee: (apps) => apps.some((a) => mayOpen(c, a)),   // optional
      }) },
    200,
    RELEASES_HEADERS,
  ),
);
```

`listReleases` pages newest first (`limit` 1 to 50, 20 by default; `before` an ISO time) and, with `canSee`, keeps a takeaway about some apps only for people who may open one of them.

### `lumen-ship.json`

At the repo root (or the path in `LUMEN_SHIP_CONFIG`):

```json
{
  "repo": "owner/name",
  "notes": { "prompt": ".github/release-prompt.md", "model": "claude-sonnet-5-5", "maxTokens": 16000 },
  "changelog": { "path": "src/changelog.json", "apps": { "console": "console", "api": "api" } },
  "tags": "v0.*",
  "promote": "release",
  "cadence": { "every": 10, "days": 7 }
}
```

| Key | |
|---|---|
| `repo` | The GitHub repo the releases go on. Required |
| `notes.prompt` | A file with the prompt; `{tag}` becomes the release's tag. Required |
| `notes.model`, `notes.maxTokens` | The model and its output limit (the model thinks first, so keep it large) |
| `changelog.path` | Where the What's new JSON lives on `main`; left out, no changelog |
| `changelog.apps` | Tag (lower case) → app id, for takeaways about one app |
| `tags` | The release tags as a git glob, `v[0-9]*` by default; narrow it when older tags of another scheme sort higher |
| `promote` | A branch fast-forwarded to each new release (a production deploy branch, say) |
| `cadence.every`, `cadence.days` | When a patch is due. `RELEASE_EVERY` overrides `every` |

## Lint guards

```bash
lumen-ship check kit-neutral [paths]   # no name from LUMEN_FORBIDDEN_NAMES (default: src package.json README.md)
lumen-ship check suppressions          # a useExhaustiveDependencies suppression needs a reason of 3+ words
lumen-ship check settings-copy         # a Settings section description is one plain line of 64 characters or less
lumen-ship check magic-numbers         # hard-coded px/rem class values may only go down
lumen-ship check parts <folders>       # the kit's part pages: hint-text, text-action, raw-overlay, settings-page may only go down
```

Run each from a package folder in its `lint` script; run `parts` from the repo root with the app folders (`lumen-ship check parts apps/*/web/src`). `magic-numbers` reads the repo's `scripts/magic-numbers.baseline` (or `LUMEN_SHIP_BASELINE`): one `<folder> <count>` a line, lowered in the change that removes one. `parts` reads `scripts/parts.baseline` (or `LUMEN_SHIP_PARTS_BASELINE`): one `<folder> <rule> <count>` a line; `--write-baseline` writes today's counts on a first run. Each rule is explained, with what to write instead, at https://lumen.columenlabs.com/parts/README.md.

## Behavior check

`@columenlabs/lumen-ship/behavior` checks how an app's Durable Objects act over time, without naming any bug. A sanity run drives the app in the local runtime on a simulated clock, records every wake, and holds every store to the same vital signs.

- `simClock()` replaces the global `Date` with a clock the run moves forward. `SimAlarms` keeps each store's alarm instead of the runtime, so nothing fires on real time. The run jumps the clock to the earliest alarm, fires it, and repeats, so a simulated day takes seconds.
- `judge(wakes, { from, to, stopped }, limits?)` reads the recorded `Wake`s and returns `numbers` (for a diff against main) and `broken` (every vital sign broken, in plain words). Pure: no runtime, no I/O.

| Vital sign | Broken when (defaults in `VITALS`) |
|---|---|
| Idle wakes | over 12 wakes in one hour wrote nothing and called nothing |
| Quick idle | over 5 idle wakes in one hour set the next alarm under 60 s ahead |
| Wake rate | over 120 wakes in one hour, working or not |
| Alarm in the past | a wake set an alarm before its own time |
| Rows per wake | one wake read or wrote over 10k rows |
| Rows per day | one store read over 800k or wrote over 40k rows in a day |
| Settles | the last 6 hours still woke over 12 an hour |
| Errors | a wake threw or logged an error |
| Runaway | the run stopped at 2,000 wakes before the day ended |

```ts
import { judge, type Wake } from '@columenlabs/lumen-ship/behavior';

const { numbers, broken } = judge(wakes, { from, to, stopped });
if (broken.length) console.log(broken.map((b) => `${b.rule}: ${b.detail}`).join('\n'));
```

Give it varied starting states, not failure cases: a returning user's store, the same store 30 days later, a first visit. A loop, a runaway read or stuck work then breaks a vital sign by itself, whatever caused it.

## Versions

0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

# Package: @columenlabs/lumen-tasks

Lumen's background jobs, server side: a ledger of the work a person started (a search, a sync, a backfill) with its state, progress and result, cooperative cancel, a reaper that fails anything stuck, and the routes the header Tasks list calls. It pairs with `TasksProvider`, `TasksButton` and `useTaskFor` in `@columenlabs/lumen-ui`, which show a ring while something runs, a dot for ended unseen tasks and a toast with Open when one ends. No dependencies beyond `@columenlabs/lumen-ui-types`: `Request`, `Response` and any SQLite, so it runs in a Worker, a Durable Object, Bun or Node.

- Source: https://github.com/columenlabs/lumen (`packages/tasks`). MIT.

## Install

```bash
bun add @columenlabs/lumen-tasks @columenlabs/lumen-ui-types
```

Pin both to the same exact version as the other Lumen packages.

## The ledger

```ts
import { createTasks, doSql } from '@columenlabs/lumen-tasks';

const tasks = createTasks({
  db: doSql(ctx.storage.sql),        // or d1Sql(env.DB)
  onEnd: async (t) => { /* email or push for long ones */ },
});
```

Nothing runs in the ledger. The work runs where its data is (a Durable Object's alarm, a queue, a runner elsewhere) and reports:

```ts
const t = await tasks.start({
  owner, app: 'jobs', kind: 'search', title: 'Search · Remote roles',
  link: '/feed', ref: search.id, total: 3, unit: 'sources',
});
for (const [i, source] of sources.entries()) {
  if ((await tasks.progress(t.id, { done: i })).stop) return; // cancelled or reaped
  await source.run();
}
await tasks.finish(t.id, { state: 'done', summary: '14 new jobs' });
```

- **Cancel is cooperative.** It ends the task at once; the engine's next `progress` answers `stop: true`. Pass `cancellable: false` for work that cannot stop.
- **Nothing stays running.** A task open past `limitMinutes` (15) is failed on the next read; no cron needed.
- **Kept 7 days** (`keepDays`), newest first, 100 at most in a list.
- `byRef(owner, kind, ref)` finds the newest task for one piece of work, so an engine refuses a second run while one is open.

## The routes

```ts
import { taskRoutes } from '@columenlabs/lumen-tasks';

const routes = taskRoutes({ base: '/api/tasks', tasks: () => tasks, owner: (req) => callerId(req) });
app.all('/api/tasks/*', (c) => routes(c.req.raw));
```

`GET /`, `GET /:id`, `POST /seen`, `POST /clear`, `POST /:id/clear`, `POST /:id/cancel`. Writes must be same-origin JSON. `tasks` may return a stub that forwards to a Durable Object holding the ledger (`TasksApi`).

# Package: @columenlabs/lumen-ui

Lumen's React components for data apps: the app frame, pages and views over your rows, widgets, charts, drawers and pickers, all on one theme. You give it data and a view config; it draws the screen. Built on [shadcn/ui](https://ui.shadcn.com) (Radix UI, Base UI, Tailwind CSS 4). Its view model is [`@columenlabs/lumen-ui-types`](https://www.npmjs.com/package/@columenlabs/lumen-ui-types).

- Docs and live examples: https://lumen.columenlabs.com/docs/
- For agents: https://lumen.columenlabs.com/llms.txt
- Source: https://github.com/columenlabs/lumen (`packages/ui`). MIT.

## Install

Pin both packages to the same exact version.

```bash
bun add @columenlabs/lumen-ui @columenlabs/lumen-ui-types
bun add react react-dom @tanstack/react-query @tanstack/react-router   # peers
bun add -d tailwindcss @tailwindcss/vite tw-animate-css shadcn
```

## Set up

`src/index.css`:

```css
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "@columenlabs/lumen-ui/theme.css";
@source "../node_modules/@columenlabs/lumen-ui/dist";

/* your accent, per app (LumenShell sets data-app on <html>) */
:root[data-app="myapp"] { --primary: oklch(0.55 0.15 160); }
/* optional: numbers in the text font instead of mono (code stays mono via `font-code`) */
:root[data-app="myapp"] { --num-font: var(--app-font); }
```

At start, before anything renders, tell the kit about your app. The kit names no product: your names and data come in here.

```ts
import { configureLumen } from '@columenlabs/lumen-ui';
import { registerDomains } from '@columenlabs/lumen-ui-types/registry';

configureLumen({ prefsCookie: 'myapp_prefs' });   // where display preferences live
registerDomains({ /* your joins, sources and domain keys */ });
```

Wrap your routes in the shell:

```tsx
import { LumenShell } from '@columenlabs/lumen-ui';

<LumenShell app="myapp" appLabel="My app" brand={<Logo />} nav={nav} user={{ email, name }}>
  <Outlet />
</LumenShell>
```

Your own parts go in `LumenShell`'s slots: `brand`, `headerActions`, `panel` (a side panel such as an assistant), `wrap` (providers around the page), `shared`, `profile` (the profile menu) and `statusEnd` (the right end of the status bar).

Use `createDeskQueryClient()` for the app's TanStack Query client: data stays fresh 5 minutes and cached 30.

## What's inside

**Frame.** `LumenShell` (sidebar with icons-only collapse and a drawer on phone, header, status bar, Settings, profile menu, ⌘K Find), `LumenAppSwitcher` and `LumenSuiteSwitcher` (groups, apps on other sites, a list read from an address), `WhatsNew` (release notes in a drawer), `TasksButton` and `TasksProvider` (background work in the header), `NotificationsSettings`, `McpSettings`, sign-in screens (`LumenAuthStage`, `LumenSecondStep`, `LumenSignInMethods`, `LumenBackupCodes`, `LumenBotCheck` for Cloudflare Turnstile, `authErrorText` for errors in plain words), `StatusHealth`, `LumenBoundary` (keeps a crash inside its card), `LumenPageState` (loading, empty and error), `lumenToast`.

**Pages and views.** `LumenLayout` (a page of cards from one view config: filter, tiles, widgets; Edit layout and Edit widget when you pass `onConfigChange`; a card with `header: false` is its body alone), `LumenGrid` (the 6-column grid under it), `LumenView` and `LumenViewCard` (a table that filters, groups, pivots and totals the rows you load), `LumenTable`, `LumenTokenizedFilter`, `LumenWidget` and `LumenSavedWidget` (the frame every card sits in, with its link square and controls), `LumenCard` (one number and its lines), `LumenPager`, `DetailsTable`, `LumenTree`, `LumenCalendar` (events by month, week or agenda, in a time zone), `LumenBoard` (items in columns by stage), `useAppView` (a page whose layout each person can change and reset).

**Charts.** `LumenChart` (one or more symbols' prices, with indicators), `LumenEChart`, `LumenGeoMap`, growth and price charts, `StackedBars`, `StackedColumns`, `TimeLines` (lines over time, with an optional right axis), `RankedBars` (with each bar's share of the total or of the first bar, and an empty state).

**Pickers and panels.** `LumenSelector` (every picker), `LumenDrawer` with `DrawerSection` (a side panel on desktop, a sheet on phone), `LumenTabs`, `LumenConfirm` (destructive confirms), `LumenForm`, `LumenDateInput`, `LumenChoice`, `LumenSecret`, `LumenFileField` (drop or pick a file), `RenameField`, `ResetButton`, `SaveButton` with `FormIssue` (a Save that says why it can't), `IconPicker`, `LumenPlayer` (video, audio, or slides over audio, with chapters, a following transcript and resume).

**Primitives.** The shadcn parts under `@columenlabs/lumen-ui/ui/*` (`ui/button`, `ui/badge`, `ui/input`, ...) and `theme.css` (light and dark tokens).

Every export, its props and an example are on the [docs](https://lumen.columenlabs.com/docs/) and in [`llms-full.txt`](https://lumen.columenlabs.com/llms-full.txt).

## Rules the kit follows, and apps should too

- Pickers are `LumenSelector`, side panels `LumenDrawer`, tabs `LumenTabs`, destructive confirms `LumenConfirm`; reach for the raw `ui/*` part only when no Lumen part fits.
- Every card body sits in `LumenBoundary`, so one crash never blanks a page.
- Numbers use tabular figures and a true minus `−`; a gain or loss always shows a sign or arrow.
- A page's header numbers are metric cards: `TileRow` of `Tile` (or `TileToggleGroup` when they pick what the page shows), with `fill` so they share the row, each with `spark` set to its daily history where it has one. Don't build a card of your own for this.
- Column widths: the first column (a row's name) grows only to `--lead-col-max` (18rem, theme.css); past it the cell truncates on one line and a plain text value shows in full on hover (a rendered cell brings its own hover card). Cap any other column with the field's `maxWidth` (`'12rem'`), or lift the cap with `maxWidth: false`. In a rendered name cell, put the name in a `truncate` span so the ellipsis lands on it, not on a chip after it.
- Rows never wrap. Every row (data, group, sub-group, Total) reads on one line at every width. On a phone each row is a one-line card: its name (ellipsis, full name on hover) and one value on the right, the sorted column, else the first number or date. The other values are in the row's drawer or panel. Pick which value a phone shows by sorting (Sort by) or by marking the others `hideOnPhone`.
- Column alignment is the table's, not the cell's. Text left, numbers right, and a number column has one right edge for its header, values, dashes and Total. `UnitValue` puts the unit in a fixed slot after the number (`--unit-slot`, 2rem) and its status dot just left of the number. In a LumenView table the first `UnitValue` drawn in a column marks it (`data-units` on every cell of that column, through the `UnitColumns` context and the cell's `data-col`); theme.css then widens that column's right gutter by the slot and hangs each unit in it. So a plain `—`, `Free` or `$0.21` an app draws in the same column sits on the digits' edge, and the header sits over the digits. Don't hand-place units, dots or padding to line a column up; if a column is off, draw its numbers through `UnitValue`. Outside a LumenView table (a hover card, a tile) `UnitValue` keeps its slot inline.
- A metered column (use against an allowance) shows one number per cell with `UnitValue` (right-aligned number, fixed muted unit slot, status dot), never `value [pct]`. Offer both readings through the field's `showAs` (Amount / % of allowance, picked per column in Edit view, saved as `shows`); default amounts for sizes (storage) and shares for capped counts. Put the other reading, the allowance and the cost formula in a hover card. Totals use `rollRender`: sum amounts with their unit; a share is the rows' total over their allowance, never a sum of percents.
- A floating bulk-action bar over a table's selection: Apply clears the selection and the bar goes away; the toast's Undo restores the change, not the selection. Cancel keeps the selection.
- Bars in a column line up: use `ShareMeter` (fixed track, fixed right-aligned number), never a bar sized by its label.
- A shared cap split by who used it (an account's allowance by label): `ShareMeter segments={[{ value, label }]}` names each part's share in the bar's hover; the bar itself keeps one colour, its level's, so colour always says how full it is. Roll such rows up with `poolShare(rows, { pool, used, cap })` in a field's `rollRender`: a pool's share is its rows' use over the cap (never a sum or max of their own %), and a group across several pools reads the fullest one (`top`).
- Meter levels are the kit's, not the app's. A usage share reads `ok` (green) under 75%, `watch` (amber) from 75%, `alert` (orange) from 90%, `over` (red) from 100%; past 100% the `ShareMeter` stays full and a hatched stub spills past a tick at the cap, up to +50%. A health share (`kind="health"`: uptime, success rate) reads green at 99% and over, amber from 95%, red under 95%. `ShareMeter` takes its colour from the share unless you pass `color`; `UnitValue share={0.8}` tints its number and dot from amber up (green numbers stay plain); progress cards follow the same levels. For any other mark (a dot, a chip, a "nearest cap" cell) call `meterLevel(share, levels, kind)` and colour it with `METER_LEVEL_COLOR` or `meterValueTone(share)`. Override per app with `configureLumen({ meterLevels: { watch: 0.8 }, healthLevels: { watch: 0.995 } })` (each level can move alone) or per meter with `levels`. Don't hand-roll `share >= 0.75` checks.
- Pace (time to a cap at the recent rate) is the kit's: `burnRate(samples, { per, gauge })` over the window's complete samples (hourly, or daily for `7d`), then `timeToCap(rate, used, cap, resetInHours)`. A lone sample above 3× the window's median counts as 3× the median (`spikes` says how many); a run of hot samples counts in full. Show it with `TimeToCap` (`in 2h 05m`, `At cap`, `Resets first`; `short` on a phone), coloured by the meter level of where the meter lands at reset, and pick the window with `PaceWindowPicker` (6h, 12h, 24h, 7d) in the page header; `usePaceWindow()` reads the same choice everywhere, kept in the viewer's browser (`setDefaultPaceWindow` sets the app's default). Where most hours are empty (median 0) a lone nonzero hour counts as 0, and a window with too little use (`timeToCap(..., { minTotal })`, default 0.1% of the cap) is `thin`: no time to the cap. Don't hand-roll ETAs or a window toggle.
- A change between periods (this week against last) is `trendChange(now, prev, { minBase })` drawn by `TrendValue`: `▲ 12%` over a big enough earlier period, the plain difference `▲ +3` when it is at or under `minBase`, `▲ >10×` past ten times. A % over a near-empty baseline misleads; never show one.
- Table rows are one line. A cell shows one value (with a small bar or tag at most); anything more (other metrics, the allowance, a breakdown) goes in a hover tooltip, never in stacked text or sub-rows.
- Chart colours are theme tokens (`var(--chart-1)`, `useChartTokens()`), never hex picked for one theme; `LumenEChart` resolves `var(--…)` in its option so sparklines read in light and dark.
- "No label" filters come built in: `LumenTokenizedFilter` pins a "No <field>" row on any text field where some rows have no value (an `empty` token); don't add your own toggle for it.
- Fewer tab rows: one row of tabs at most per card; narrower cuts (a product, a type) are fields in `LumenTokenizedFilter`, and a link to one opens the tab with that filter chip set.
- One selected sidebar row: give each nav item its own route, and let an open parent look neutral.
- What's new is on in every app: pass `releases="/api/releases"` to `LumenShell`, served by lumen-ship's `listReleases`.
- A Save blocked by its form's checks is a `SaveButton` that lists each issue, never a bare `disabled`.

## Notices

Charts use TradingView Lightweight Charts™ with its logo off. Please link to https://www.tradingview.com/ somewhere in your app (see NOTICE).

## Versions

0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

# Package: @columenlabs/lumen-ui-types

Lumen's view model: the schemas and registries that [`@columenlabs/lumen-ui`](https://www.npmjs.com/package/@columenlabs/lumen-ui) reads, and that your server can check against. No React, so it runs in a browser, a Worker or Node alike.

- Docs: https://lumen.columenlabs.com/docs/
- For agents: https://lumen.columenlabs.com/llms.txt
- Source: https://github.com/columenlabs/lumen (`packages/ui-types`). MIT.

## Install

```bash
bun add @columenlabs/lumen-ui-types
```

Pin it to the same exact version as `@columenlabs/lumen-ui`.

## The model in one paragraph

A **domain** is a set of rows with their own fields and the **keys** its rows carry (a symbol, an account). A **join** is a set of fields that attaches to any row with that key (a symbol's price, an account's cash). A **view** is one config over one domain: its columns, filters, grouping, formulas and widgets. The **catalog** lists every domain your pages show and the function that reads it. The kit ships the shapes and the machinery with every list empty; your app fills them once at start with `registerDomains`.

## Modules

Import each by its path, for example `@columenlabs/lumen-ui-types/views`.

| Path | What it holds |
|---|---|
| `/registry` | `registerDomains`: what your app tells the kit about its data, once at start, on the server and in the browser alike |
| `/views` | The view config schema (columns, filters, group, pivot, sort, formats, totals, widgets and their styles) and `upgradeViewConfig` |
| `/view-formula` | Formula columns in Jexl (an interpreter, no `eval`): `group_sum`, `total_sum`, names by where a field comes from, and the checker |
| `/domains` | Keys, joins and `joinFields`: which fields attach to a row by its key |
| `/catalog` | The data catalog: each domain's app, tables, fields and reader, and lookups such as `readableDomain` |
| `/frames` | Frames: named rows plus the one script that made them, linked to a card by key or a snapshot of their own |
| `/workspaces` | Workspaces: a page of tabs, each tab one view config over a frame or a domain |
| `/chart-formula` | Chart indicators as specs: a built-in with any window (`ema_13`) or a formula over open, high, low and close |
| `/market` | The market widget's symbols and the shapes of bars and quotes |
| `/tasks` | Background tasks: the shape every app reports and the header's Tasks list reads |
| `.` | What belongs to no module, such as the Refresh request header |

## Register your data

```ts
// src/registry.ts: the module every entry imports first
import { registerDomains } from '@columenlabs/lumen-ui-types/registry';

registerDomains({
  joins: { /* key → the fields that attach to a row with that key */ },
  joinSources: { /* where each join's fields come from */ },
  domainKeys: { /* domain → the keys its rows carry */ },
  catalog: { /* domain → its app, tables, fields and reader */ },
});
```

Call it before anything renders or answers, in both your server and your browser entries, so both read the same lists.

## Versions

0.x: any minor may break things until 1.0. Every merge to Lumen's `main` publishes the next patch of every Lumen package; see the [releases](https://github.com/columenlabs/lumen/releases).

# Package: @columenlabs/lumen-vault

Envelope encryption for per-person data, Web Crypto only (Workers, Durable Objects, browsers, Bun).
A master key wraps one random data key per person; values are sealed with that person's key.

Two codecs, each a fixed stored format. Their constants never change: a change would make every
stored value unreadable.

## Envelope (`@columenlabs/lumen-vault/envelope`)

One master key derives an owner key (email → `u_<40 hex>`) and a wrap key (HKDF-SHA256, empty salt).
Each person's data key is stored wrapped (`v1.` + base64, AAD `vaults:<owner>`) wherever the app keeps
keys, through a `WrappedKeyStore`. Values seal to `v1.` + base64(iv ‖ ciphertext ‖ tag) with an AAD
the app names (`table:row`), so a sealed value can't be moved to another row.

```ts
import { EnvelopeVault } from '@columenlabs/lumen-vault/envelope';

const vault = new EnvelopeVault({
  kek: env.VAULT_KEK,             // base64 of 32 bytes
  store: {
    get: async (owner) => (await db.prepare('SELECT data_key FROM vaults WHERE owner = ?').bind(owner).first())?.data_key ?? null,
    putIfAbsent: async (owner, wrapped) => { await db.prepare('INSERT OR IGNORE INTO vaults (owner, data_key) VALUES (?, ?)').bind(owner, wrapped).run(); },
  },
  onUnlock: (e) => env.VAULT_LOG.writeDataPoint({ indexes: [e.owner], blobs: [e.event, e.error ?? ''], doubles: [e.ms] }),
});
const v = await vault.for('someone@example.com');
const sealed = await v.seal(`trades:${id}`, trade);
const back = await v.open(`trades:${id}`, sealed);
const key = await v.index('AAPL');    // a lookup key: equal values match
```

No master key fails closed. An app that offers a readable mode (self-hosting without a key) passes
`allowPlain: true`, and values are stored as `plain.` + JSON.

## Regional (`@columenlabs/lumen-vault/regional`)

One master key per region (raw 32 bytes, base64). Each person's AES-GCM data key is wrapped with
AES-KW and kept beside their data; values are bytes, iv ‖ ciphertext ‖ tag, with no AAD.

```ts
import { MasterKeys, dataKey, seal, unseal } from '@columenlabs/lumen-vault/regional';

const masters = new MasterKeys<'na' | 'eu'>((r) => (r === 'na' ? env.SEAL_KEY_NA : env.SEAL_KEY_EU)?.get() ?? null);
const key = await dataKey({
  master: masters.get(region),
  owner: personId,
  slot: {
    get: () => sql.exec("SELECT value FROM meta WHERE key = 'data_key'").toArray()[0]?.value ?? null,
    putIfAbsent: (w) => sql.exec("INSERT OR IGNORE INTO meta (key, value) VALUES ('data_key', ?)", w),
  },
});
const blob = await seal(key, accessToken);
```

## Unlock events

`onUnlock` gets one event each time a data key is unwrapped (`unwrap`), made (`create`) or fails
(`fail`, with a short `error` kind), with the owner id and the time it took. Never a key or a value.
The app adds its own context when it writes the event to its log.

## Releases

The vault guards every person's data in the apps that use it, so it is published apart from the
other packages:

- Any change to `packages/vault`, the publish workflow, `scripts/pack.sh` or `CODEOWNERS` needs the
  owner's review (`.github/CODEOWNERS` and a branch rule).
- It is published only when it changed since its last version on npm, by the `vault` job of the
  publish workflow, which waits for the owner's approval in the `vault` environment (admins cannot
  skip it).
- Apps never take a vault update automatically: no Dependabot group or auto-merge covers it, and
  each bump is its own pull request.

# Components

Lumen is built on shadcn/ui (Radix UI, Base UI, Tailwind CSS). Install: `bun add @columenlabs/lumen-ui @columenlabs/lumen-ui-types` (one exact version for both), then import `@columenlabs/lumen-ui/theme.css` after Tailwind.

- Prefer LumenSelector for every picker, LumenDrawer for side panels, LumenTabs for tabs and LumenConfirm for destructive confirms over the raw ui/* parts.

## Lumeninplay



Docs: https://lumen.columenlabs.com/docs/?path=/docs/app-shell-lumen-in-play--docs

```tsx
import { LumenLayout, LumenShell, NavGroup, StatusHealth, StatusItem } from '@columenlabs/lumen-ui';
```

Example:

```tsx
const InPlay = () => (
  <LumenShell
    app="northwind"
    appLabel="Northwind"
    brand={<span className="px-2 font-semibold">Northwind</span>}
    nav={nav}
    user={{ email: 'ada@example.com', name: 'Ada Lovelace' }}
    status={
      <>
        <StatusItem label="12 stores" />
        <StatusItem label="Synced" value="2m ago" ok />
      </>
    }
    health={
      <StatusHealth
        probes={[
          { name: 'API', ok: true },
          { name: 'Warehouse', ok: true },
          { name: 'Jobs', ok: true },
        ]}
        checked="just now"
      />
    }
    statusEnd={<StatusItem label="v0.1.20" />}
  >
    <Dashboard />
  </LumenShell>
);
```

## LumenShell

The app frame: sidebar (icons-only collapse, a drawer on phone), page header, status bar, Settings and the profile menu. An app passes its brand, nav and routed page; its own parts go in the slots `brand`, `headerActions`, `panel`, `wrap`, `shared`, `profile` and `statusEnd`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/app-shell-lumenshell--docs

```tsx
import { LumenLayout, LumenShell, NavGroup, NoteLine, Tile, TileRow } from '@columenlabs/lumen-ui';
```

Props:

- `app: string` — The app's id: `data-app` on the root `<html>`, which picks its accent.
- `appLabel: string` — The app's name, heading its own Settings sections.
- `brand: ReactNode` — The sidebar's top: the app's name, or a switcher between a product's apps.
- `children: ReactNode` — The routed page (usually `<Outlet />`).
- `nav: ReactNode` — The app's sidebar content: `NavGroup`s and `SidebarSection`s.
- `bar?: StatusBarModel` — The app's status bar (DESIGN.md, Status bar): its sync and messages as data; pages add theirs with `useStatus`. Running Tasks of this app show by themselves.
- `finder?: LumenFinderConfig` — How ⌘K Find reads in this app: its chips and how the nav's pages group.
- `headerActions?: ReactNode` = null — The product's buttons on every page header, after Refresh (the product's Tasks and the assistant).
- `health?: ReactNode` — The services the app checks, as one `StatusHealth` chip at the status bar's end.
- `hideAmounts?: boolean` = false — Shows Hide amounts (eye) in the header: masks the fields and values the app marks `amount`.
- `onLogs?: (() => void)` — Opens the app's Logs page; shows Logs in the profile menu.
- `onRefresh?: (() => Promise<unknown>)` — Reloads the page's data and drops every cached read (TanStack Query `invalidateQueries`); shows Refresh in the header, which then mounts the page again.
- `panel?: ReactNode` — A panel docked right of the page (the product's assistant).
- `profile?: ReactNode` — Settings ▸ General ▸ Profile's content; no Profile section without it.
- `releaseApps?: Record<string, ReactNode>` — What's new's app chips: each app's label by id, matched to a takeaway's `apps`.
- `releases?: string` — Turns on What's new: the app's releases API (`GET ?limit=&before=` answering `{releases}`). The status bar shows the newest version, which opens each release's Key takeaways.
- `security?: ReactNode` — Settings ▸ General ▸ Security's content (LumenSignInMethods); no Security section without it.
- `settings?: SettingsSectionDef[]` — The app's own Settings sections, listed after General and the product's.
- `settingsGroups?: SettingsGroupDef[]` — More labelled Settings groups (one per app of a product), listed after `shared`, before the app's own.
- `shared?: SettingsSectionDef[]` — Sections every app of the product shows, listed after General under `sharedLabel`.
- `sharedLabel?: string`
- `signOutUrl?: string` — Where Sign out goes; no Sign out without it.
- `status?: ReactNode` — @deprecated Old JSX items, desktop only; pass `bar`, and pages call `useStatus`.
- `statusEnd?: ReactNode` — Status bar items after `health` and What's new, before the time zone.
- `tabs?: NavItem[]` — The phone's bottom tab bar: up to four main pages, then More (the sidebar). None by default.
- `user?: ShellUser | null` = null — Who is signed in (the profile button); null while it loads.
- `wrap?: ((frame: ReactNode) => ReactNode)` = (frame) => frame — Wraps the frame in the product's providers, inside the shell so they can call `useShell`.

Example:

```tsx
const Shell = () => <LumenShell
    app="sample"
    appLabel="Sample app"
    brand={<span className="px-2 font-semibold">Sample app</span>}
    nav={(<NavGroup
      label="Sample app"
      items={[
        { title: 'Home', to: '/', icon: HomeIcon, exact: true },
        { title: 'Stores', to: '/stores', icon: StoreIcon },
        { title: 'Reports', to: '/reports', icon: BarChart3Icon },
        { title: 'Setup', to: '/setup', icon: SettingsIcon },
      ]}
    />)}
    user={{ email: 'ada@example.com', name: 'Ada Lovelace' }}>(<LumenLayout
      crumbs={[{ label: 'Home' }]}
      cards={[
        {
          id: 'today',
          title: 'Today',
          children: (
            <div className="flex flex-col gap-3">
              <TileRow>
                <Tile label="Revenue" value="$41,220" caption="so far today" />
                <Tile label="Orders" value="612" />
                <Tile label="Stores open" value="11 of 12" />
              </TileRow>
              <NoteLine icon={InfoIcon} title="Faro opens late." note="Back at 11:00." />
            </div>
          ),
        },
      ]}
    />)</LumenShell>;
```

## WhatsNew

The status bar's version, which opens each release's Key takeaways. With `apps` each takeaway shows the chip of the app it is about (`everyone` for none), and a release where one app has three or more is split into one sub-section per app.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/app-shell-whatsnew--docs

```tsx
import { WhatsNew } from '@columenlabs/lumen-ui';
```

Props:

- `api: string`
- `apps?: Record<string, ReactNode>` — Each app's chip label by id, in the order groups list them; left out: no app chips.
- `everyone?: string` = Global — The chip of a takeaway about no one app.

Example:

```tsx
const AppChips = () => <WhatsNew api="/whats-new-sample" apps={{ stores: 'Stores', reports: 'Reports' }} />;
```

## LumenSignInMethods

Settings ▸ General ▸ Security (pass it to LumenShell as `security`) and the second step of a sign-in. The parts draw the screens and call the app back; each callback answers a problem to show, or anything else when it worked. Adding a passkey, setting up an authenticator app (QR code, then backup codes) and making new backup codes open in place.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-sign-in--docs

```tsx
import { LumenSecondStep, LumenSignInMethods } from '@columenlabs/lumen-ui';
```

Props:

- `app?: { on: boolean; onStart: (password: string) => Promise<string | { uri: string; backupCodes: string[]; }>; onConfirm: (code: string) => LumenResult; onTurnOff?: ((password: string) => LumenResult); replaceable?: boolean; } | undefined` — The authenticator app (TOTP). Turning it on asks for the password first.
- `backup?: { left: number | null; onRenew: (password: string) => Promise<string | string[]>; }`
- `email?: { to: string; on: boolean; onToggle?: ((on: boolean) => LumenResult); locked?: string; } | undefined` — A code emailed at each sign-in.
- `passkeys?: { list: LumenPasskey[]; onAdd: (name: string) => LumenResult; onRemove: (id: string) => LumenResult; }`
- `password?: { onChange: () => void; }` — The password row; its Change opens the app's own flow.

Example:

```tsx
const SignInMethods = () => <Methods />;
```

## LumenTabs

A page’s tab row: every tab has an icon, a name and an optional count, and actions for the open tab sit at the row’s end.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-tabs--docs

```tsx
import { Badge } from '@columenlabs/lumen-ui/ui/badge';
import { LumenTabs } from '@columenlabs/lumen-ui';
```

Props:

- `onChange: (value: V) => void`
- `tabs: LumenTab<V>[]`
- `value: string | undefined`
- `actions?: ReactNode` — What only the open tab uses, at the row's right end.

Example:

```tsx
const Tabs = () => {
    const [, update] = useArgs();

    return (
        <LumenTabs
            value="list"
            tabs={[
              {
                value: 'list',
                label: 'Stores',
                icon: ListIcon,
                after: <Badge variant="secondary">12</Badge>,
              },
              { value: 'reports', label: 'Reports', icon: BarChart3Icon },
              { value: 'setup', label: 'Setup', icon: SettingsIcon },
            ]}
            onChange={(value) => update({ value })} />
    );
};
```

## LumenLayout

A page of cards from one saved view: its filter, a grid of widgets and its table. Give it a domain (the fields), a view config and the rows; it filters, groups, totals and lays out on the client. With `onConfigChange` the page offers Edit layout and + Widget.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-page-layout--docs

```tsx
import { LumenLayout, SampleShell } from '@columenlabs/lumen-ui';
```

Props:

- `config: CustomViewConfig`
- `crumbs: Crumb[]`
- `domain: ViewDomain<T>`
- `load: LumenLoad` — The rows' loading state (`useLumenLoad` over the queries the rows come from): every view and widget shows its ↻, skeleton, error and load time from it, so it is required.
- `rows: T[]`
- `actions?: ReactNode`
- `cards?: LumenLayoutCard[]` — The page's own cards, after the saved view's. One with a `frame` joins the saved layout as a `page` card: moved and sized like the rest, last until it is placed.
- `columnPicker?: boolean` — False leaves Field out of the header's + Add column (a table whose columns are fixed, a Tune's tries); otherwise every editable view offers the Columns picker there.
- `editable?: boolean` — Whether the page's layout can be edited (every page is a saved view, with this flag set in code for now). False locks it: no Edit, no ＋ Widget, no column changes, even with `onConfigChange` given. Left out: editable where `onConfigChange` is.
- `editor?: ViewEditorSection` — An app's own section in the Edit dialog (an explorer view's columns).
- `facets?: FacetCounts | null` — The server's counts for each filter field's values over the rows the other chips keep, so the box and the filter panel count every row, not one page (with `paging`).
- `filterPanel?: { id: string; tips?: Record<string, ReactNode>; order?: string[]; title?: string | undefined; } | undefined` — A filter panel beside the page: the same filter as the box, each field's values ticked in place. `id` keeps it open or hidden per device; `tips` gives a field an InfoTip.
- `fit?: boolean` — Cards take the page's width and wide ones scroll inside themselves (coverage pages).
- `groupActions?: ((key: string, rows: T[]) => ReactNode)`
- `hideFilter?: boolean` — No filter box (a short list, e.g. a playbook's variants).
- `intro?: ReactNode` — Above the cards: tabs or a lead the app shows with this page.
- `lead?: LumenLayoutCard[]` — The page's own cards before the saved view's (a chart over the list it draws from).
- `meta?: ReactNode` — A short status line beside the breadcrumb ("Updated 18:22", a warnings badge).
- `onConfigChange?: ((config: CustomViewConfig) => void)` — Saves an edited view; without it the page has no Edit button.
- `onDelete?: (() => void)`
- `onDuplicate?: (() => void)` — Duplicate and Delete, offered in the Edit dialog's More section.
- `onOpen?: ((row: T) => void)` — A row click opens it (a page of its own) instead of the details drawer.
- `onReset?: (() => void)` — A built-in page the person changed (`useAppView`): Edit layout offers Reset to default.
- `onShownRows?: ((rows: T[]) => void)` — Told the rows the view shows after its filters, every page, whenever they change, so an app loads live data for those rows only.
- `onSummaryRows?: ((rows: T[]) => void)` — Told every row the page's Summaries draw, so an app loads live data for those too : a Summary not linked to the table covers rows the table hides.
- `onTokens?: ((tokens: FilterToken[]) => void)` — Told the filter's tokens whenever they change, so an app can load rows for what they pick (the Symbols view's `in` filter).
- `openKey?: string | null` — The key of the row `onOpen` shows in a drawer of the app's own (a docked one), so the table marks it selected; the layout's own details drawer marks its row itself.
- `paging?: ServerPaging` — The rows are one page of a server's, already filtered by `onTokens`' chips: the table shows them as given and its pager pages through the server.
- `rowPick?: string` — The `rowLink` value tapped when the page opens, so linked cards start narrowed to one row (a playbook's Results open on its Default variant).
- `rowTitle?: ((row: T) => string)` — The details drawer title for a row.
- `save?: enum` — How the person's chips, sort and grouping save (rule C, by surface): `document` (a saved view, the default) holds them for the visit and shows Changed with Save view and Revert; `sheet` (a workspace tab) saves every change at once through `onConfigChange`, like a cell in a sheet.
- `selection?: { keys: Set<string>; onChange: (keys: Set<string>) => void; }`
- `state?: ReactNode` — Shown in place of the table instead of the rows, e.g. an empty state ("No accounts yet").
- `status?: ReactNode`
- `tile?: ((key: string, rows: T[]) => ReactNode)` — Draws one of the domain's tiles over the view's rows (not the table's filter); the view's `tiles` pick which, in order.
- `viewId?: string` — The saved view's id, shown in the Edit dialog to copy for an MCP call.
- `viewTools?: ReactNode` — Buttons in the view card's header ("+ Add time").

Example:

```tsx
const TableOnly = () => <StoresPage />;
```

## LumenWidget

The frame every card sits in: header, link square, filter, ↻ and ⋯ menu. With Header off (Edit widget ▸ Controls) the card is its body alone, and a faint ⋯ in its corner keeps Ask, Refresh and Filter in reach; an active filter shows its count beside it.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-editable-widget--docs

```tsx
import { LumenTokenizedFilter, LumenWidget } from '@columenlabs/lumen-ui';
```

Props:

- `id: string`
- `kind: "table" | "metric" | "allocation" | "chart" | null` — The card's kind; null for a card a page builds in code (not in the view's config).
- `title: string`
- `assistant?: string | false` — ✦ Ask the assistant on every card where the assistant answers: what the assistant needs beyond the card's title to read it ("Tune tn_… of playbook …: read it with tune_read"); false: no button.
- `className?: string`
- `compact?: boolean` = false — A LumenCard (one number): its title is a small label over the number, no rule under it.
- `controls?: CardControls` — Left out: a card the layout cannot edit.
- `filter?: ReactNode` — The card's own filter (a view's LumenTokenizedFilter and Group): on the title's line when the header is wide, on a line under it when narrow, behind a funnel button on phone.
- `filterCount?: number` = 0 — Active filter tokens, the count on the phone's funnel button.
- `foot?: ReactNode` — A line under the body, above the load line: a table's page footer.
- `help?: ReactNode` — ⓘ How to read: a few lines on what the card shows and how to read it, opened from the header.
- `icon?: LucideIcon`
- `link?: false | CardLink` — Its link colour: the square before the title, what it follows after it, and how many of its filter's chips are linked. Left out: the page's colour for `id` (every card carries the square); false: none (a form, with no data to link).
- `load?: LumenLoad` — The card's source: its ↻, and its load time below the body.
- `loadNote?: string` — Said in the load line instead of rows, e.g. "from the view's rows".
- `menu?: ReactNode` — Entries of its own at the top of the ⋯ menu (a table's Export on a phone).
- `note?: ReactNode`
- `pad?: boolean` = true
- `phoneTitle?: boolean` — False: a phone leaves the title out and gives the header to `tools` (a view whose page header names it already).
- `pinned?: boolean` = false — The header stays in sight while a wide view scrolls sideways under it.
- `rows?: number`
- `shown?: Partial<Record<"footer" | "header" | "legend" | "filter" | "group" | "columns" | "ask" | "refresh" | "pager" | "download" | "window", boolean>>` — Its controls (Edit widget ▸ Controls): Ask the assistant, Refresh, Filter box and Footer show or hide here; missing keys take the type's default.
- `strip?: ReactNode` — A line under the header and filter (widget anatomy zone 4): what the card follows, or an offer such as Link to Holdings by Symbol.
- `style?: string` — Its style, where it sets the type (a trend's spark or tracker is a Metric).
- `tools?: ReactNode` — Buttons before the ↻, e.g. a view's pager.

Example:

```tsx
const Header = () => <Demo header />;
```

## Assistant



Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-assistant--docs

```tsx
import { Button } from '@columenlabs/lumen-ui/ui/button';
import { LumenShell, NavGroup } from '@columenlabs/lumen-ui';
```

Example:

```tsx
const Chat = () => {
  const [adapter] = useState(() => mockAdapter());
  return <Docked adapter={adapter} openChat />;
};
```

## Connection

One connection, one look: an AI provider, an email relay, an account, a connector. A row with one status pill opens to the ways it connects (pasted values, a sign-in that ends on an address the person pastes back, or the app’s own form). Two ways or more show radios and an In use tag. Each way set up shows Test, Remove (asks first) and Replace or Sign in again on the right.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-connection--docs

```tsx
import { ConnectionLogo, LumenConnection, LumenExpandList } from '@columenlabs/lumen-ui';
```

Example:

```tsx
const Connections = () => (
  <div className="max-w-2xl">
    <LumenExpandList defaultOpen="openai">
      <Provider />
      <Failing />
      <NotSet />
      <WithLines />
    </LumenExpandList>
  </div>
);
```

## LumenPeople

People and access for any app: who is in, what each can open, invites and the audit log. The
screens call a `PeopleAdapter`; `peopleClient('/api/people')` is one over the routes of
`@columenlabs/lumen-people`. These stories run on an in-memory adapter.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/blocks-people--docs

```tsx
import { LumenEmailSettings, LumenPeople } from '@columenlabs/lumen-ui/people';
import { SampleShell } from '@columenlabs/lumen-ui';
```

Props:

- `adapter: PeopleAdapter`
- `crumbs?: Crumb[]` = [] — The crumbs before the section's own (`[{ label: 'Admin' }]`).
- `fields?: ViewField<Person>[]` = [] — The app's own columns per person (their accounts, their storage).
- `onSection?: ((section: PeopleSection) => void)`
- `onSetUpMail?: (() => void)` — Opens the app's email settings, offered while no email is set up.
- `section?: enum` — The open section; left out, the block keeps it and shows its own tabs.

Example:

```tsx
const People = () => <Live mail />;
```

## DetailsTable

A small fixed table for a drawer or card: a header, rows of cells and an optional total row. `FactsTable` lists label and value pairs. Pass `onSelect` (and `selected`) to let a row be picked, for example to chart the picked row below the table.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-detailstable--docs

```tsx
import { DetailsTable, FactsTable } from '@columenlabs/lumen-ui';
```

Props:

- `head: { label: string; right?: boolean | undefined; grow?: boolean | undefined; hideOnPhone?: boolean | undefined; }[]` — `grow` marks the column that takes the spare width; the last column does by default. `hideOnPhone` drops a column on a phone, so the rest fit without scrolling sideways.
- `rows: { key: string; cells: ReactNode[]; }[]`
- `foot?: ReactNode[]` — An optional total row, one cell per column.
- `onSelect?: ((key: string) => void)` — Makes each row pickable by click or Enter/Space, for example to chart the picked row below.
- `selected?: string` — The key of the row shown as picked, when rows can be picked.

Example:

```tsx
const Details = () => <DetailsTable
    head={[{ label: 'Store' }, { label: 'Orders', right: true }, { label: 'Revenue', right: true }]}
    rows={[
      { key: 'a', cells: ['Lisbon', '1,701', '$174,155'] },
      { key: 'b', cells: ['Porto', '1,433', '$54,977'] },
      { key: 'c', cells: ['Faro', '659', '$49,175'] },
    ]}
    foot={['Total', '3,793', '$278,307']} />;
```

## LumenBoard

Items in columns by stage. Each column scrolls on its own and the board scrolls sideways inside its box, never the page. On a narrow box the columns snap one a screen with a picker to jump. Cards are one line; `tick` is an optional slot before the title, and `onMove` adds a keyboard-friendly Move to menu.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumenboard--docs

```tsx
import { Checkbox } from '@columenlabs/lumen-ui/ui/checkbox';
import { ColorChip, LumenBoard } from '@columenlabs/lumen-ui';
```

Props:

- `columns: readonly BoardColumn[]`
- `items: readonly T[]`
- `className?: string`
- `empty?: ReactNode` = Nothing here — An empty column's line.
- `maxHeight?: string` = 70vh — How tall a column's list may grow before it scrolls (any CSS length).
- `onMove?: ((item: T, toColumn: string) => void)` — Moves a card; with it each card offers a Move to menu (hover, focus or tap on a phone).
- `onOpen?: ((item: T) => void)` — A card was opened: show the app's drawer.
- `renderCard?: ((item: T) => ReactNode)` — Draws a card's body in place of the title, meta and badges. Keep it to one line.
- `tick?: ((item: T) => ReactNode)` — A slot before the title: a done tick (a `Checkbox`).

Example:

```tsx
const Plan = () => {
    const [rows, setRows] = useState<Task[]>(items);

    return (
        <LumenBoard
            columns={Array.from({ length: 12 }, (_, i) => ({
              id: `c${i + 1}`,
              label: `Checkpoint ${i + 1}${i === 2 ? ': ship the first version to the pilot group' : ''}`,
            }))}
            maxHeight="28rem"
            items={rows}
            tick={(it) => (
              <Checkbox
                aria-label={`Done: ${it.title}`}
                checked={it.done}
                onCheckedChange={(v) =>
                  setRows((r) => r.map((x) => (x.id === it.id ? { ...x, done: v === true } : x)))
                }
              />
            )}
            onMove={(it, to) =>
              setRows((r) => r.map((x) => (x.id === it.id ? { ...x, column: to } : x)))
            } />
    );
};
```

## LumenCalendar

An events calendar over plain data: Month, Week (with a time axis) and Agenda, switched with tabs. Category chips filter, Today, previous and next are icon buttons, and a click on an event calls `onSelect` so the app opens its drawer. On a narrow box Month shows dots and the picked day’s list, and Agenda is the default. Every day and time is shown in `timeZone`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumencalendar--docs

```tsx
import { LumenCalendar } from '@columenlabs/lumen-ui';
```

Props:

- `events: readonly E[]`
- `categories?: readonly CalendarCategory[]`
- `className?: string`
- `date?: Date` — A day in the period shown, controlled; or `defaultDate` (today).
- `defaultDate?: Date`
- `defaultView?: enum`
- `empty?: string` = No events — Shown when the period has no events.
- `onDateChange?: ((date: Date) => void)`
- `onRangeChange?: ((range: CalendarRange) => void)` — The days on screen changed (and once at first): fetch by range.
- `onSelect?: ((event: E) => void)` — An event was clicked: open the app's drawer.
- `onViewChange?: ((view: CalendarView) => void)`
- `timeZone?: string` — An IANA zone every day and time is shown in; the browser's by default.
- `view?: enum` — The open view, controlled; or `defaultView` (Agenda on a narrow box, else Month).
- `weekStartsOn?: enum` = 0 — 0 Sunday (default) or 1 Monday.

Example:

```tsx
const Program = () => {
    const [picked, setPicked] = useState<CalendarEvent | null>(null);

    return (
        <div className="flex flex-col gap-2">
            <LumenCalendar
                events={Array.from({ length: 192 }, (_, i) => {
                  const cat = categories[i % categories.length]?.id ?? 'talk';
                  const day = Date.UTC(2026, 8, 1) + Math.floor((i * 91) / 192) * 86_400_000;
                  const hour = 8 + ((i * 7) % 10);
                  const start = new Date(day + hour * 3_600_000 + (i % 2) * 1_800_000);
                  if (cat === 'deadline')
                    return {
                      id: `e${i}`,
                      title: names[9] ?? '',
                      start: start.toISOString().slice(0, 10),
                      category: cat,
                    };
                  return {
                    id: `e${i}`,
                    title: names[i % 9] ?? '',
                    start,
                    end: new Date(start.getTime() + (1 + (i % 3)) * 1_800_000),
                    category: cat,
                  };
                })}
                categories={[
                  { id: 'talk', label: 'Talks', color: 'var(--chart-1)' },
                  { id: 'workshop', label: 'Workshops', color: 'var(--chart-2)' },
                  { id: 'office', label: 'Office hours', color: 'var(--chart-3)' },
                  { id: 'social', label: 'Socials', color: 'var(--chart-5)' },
                  { id: 'deadline', label: 'Deadlines', color: 'var(--chart-10)' },
                ]}
                defaultDate={new Date('2026-10-15T12:00:00Z')}
                timeZone="America/New_York"
                onSelect={setPicked} />
            <p className="truncate text-xs text-muted-foreground">
                {picked ? `Opened: ${picked.title}` : 'Click an event to open it'}
            </p>
        </div>
    );
};
```

## LumenFilterPanel

The filter box laid out as a panel: each field a section of values with counts, ticked in place. It shares `useLumenFilter`’s state with `LumenTokenizedFilter`, so a tick is a chip and a chip’s × unticks it. A field counts the rows the other fields keep. Over a server’s page pass the server’s counts as `facets` to `useLumenFilter` (or `LumenLayout facets`). Desktop: a side panel that hides to a filter icon; phone: a bottom sheet. On a page, use `LumenLayout filterPanel={{ id }}`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumenfilterpanel--docs

```tsx
import { LumenFilterPanel, LumenFilterPanelButton, LumenTokenizedFilter } from '@columenlabs/lumen-ui';
```

Props:

- `filter: LumenFilterState<T>` — The filter's state, the same one the page's filter box draws.
- `onOpenChange: (open: boolean) => void`
- `open: boolean` — Open (desktop: shown beside the page; phone: the sheet is up).
- `className?: string`
- `order?: string[]` — The fields in the order shown (default: the filter's own order). Fields left out are not shown here, but still filter from the box.
- `tips?: Record<string, ReactNode>` — A field's details, behind an (i) beside its name. Most fields need none.
- `title?: string` = Filters — Its heading (default `Filters`).

Example:

```tsx
const Panel = () => <Demo />;
```

## LumenPager

The compact pager every table uses: the count opens the page sizes, the chevrons turn the page.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumenpager--docs

```tsx
import { LumenPageFooter, LumenPager } from '@columenlabs/lumen-ui';
```

Props:

- `onPage: (page: number) => void`
- `onSize: (size: number) => void`
- `page: number`
- `size: number`
- `total: number` — The rows there are, or (with `more`) the rows known so far.
- `more?: boolean` = false — A server-paged source has rows past `total` it has not counted: shows `of 50+` and Next.
- `noun?: string` = rows
- `sizes?: readonly number[]` = [10, 25, 50, 100, 250] as const — Page sizes offered; a server-paged source takes its own.

Example:

```tsx
const Pager = () => {
    const [, update] = useArgs();

    return (
        <LumenPager
            total={240}
            page={0}
            size={25}
            noun="rows"
            onPage={(page) => update({ page })}
            onSize={(size) => update({ size, page: 0 })} />
    );
};
```

## LumenStackedList

Rows that nest and fold, with columns that line up at every level: a source, the groups inside it, the items inside those. Each row is one line, a name over an optional meta line. A row with children or a `notice` starts folded; its notice shows only while it is open. `actions` show on hover or focus only. On a phone the columns marked `phone` stack at the row’s end.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumenstackedlist--docs

```tsx
import { Badge } from '@columenlabs/lumen-ui/ui/badge';
import { ColorChip, LumenStackedList, LumenStackedRow, RenameField, ToneDot } from '@columenlabs/lumen-ui';
import { Spinner } from '@columenlabs/lumen-ui/ui/spinner';
```

Props:

- `columns: StackedColumn[]`
- `aria-label?: string`
- `className?: string`
- `flat?: boolean` = false — One level that never folds (a short list in a card): no chevron space, compact rows.
- `lead?: string` — The header over the names.

Example:

```tsx
const Nested = () => (
  <LumenStackedList columns={columns} lead="Source" aria-label="Sources">
    <LumenStackedRow
      name="North Bank"
      adornments={<ColorChip color="var(--chart-1)">Direct</ColorChip>}
      meta="3 items · updated 4 min ago"
      cells={{ status: <Status tone="ok">Up to date</Status>, amount: num('$14,702.11') }}
    >
      <Item name="Everyday" mask="1001" amount="$978.56" />
      <Item name="Savings" mask="2040" amount="$13,723.55" />
    </LumenStackedRow>
    <LumenStackedRow
      name="feed.example.org"
      adornments={<ColorChip color="var(--chart-4)">Feed</ColorChip>}
      meta="3 groups · 6 items · 1 needs you"
      defaultOpen
      cells={{ status: <Status tone="warn">Needs you</Status>, amount: num('$22,410.90') }}
    >
      <LumenStackedRow
        name="River Credit Union"
        meta="Sign-in broke at the source"
        notice={
          <p className="text-sm text-warning">
            The source can’t reach this group. Sign in again where the feed is kept.
          </p>
        }
        cells={{ status: <Status tone="warn">Needs you</Status>, amount: num('$9,120.55') }}
      >
        <Item name="Checking" mask="3310" amount="$9,120.55" />
      </LumenStackedRow>
      <LumenStackedRow
        name="Harbor Card"
        meta="2 items"
        cells={{ status: <Status tone="ok">Synced</Status>, amount: num('−$1,804.22') }}
      >
        <Item name="Rewards card" mask="7781" amount="−$1,804.22" />
      </LumenStackedRow>
      <LumenStackedRow
        name="Summit Invest"
        meta="Reading history · 4 of 9"
        cells={{ status: <Status tone="idle">Loading</Status>, amount: num('$15,094.57') }}
      />
    </LumenStackedRow>
  </LumenStackedList>
);
```

## LumenTokenizedFilter

The filter box: type to search, or pick `field:value` chips grouped by field with counts. Number fields take one condition (`> 100`, `a..b`). A text field where some rows have no value pins a "No <field>" row above its values: Include keeps the rows with none, Exclude the rows with any (token `{ key, value: \'∅\', op: \'empty\', not? }`); typing "no…" or "empty" offers it as a quick filter. Use it for many-valued fields like labels, never a separate tab. `useLumenFilter` holds the state and returns the matching rows.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumentokenizedfilter--docs

```tsx
import { LumenTokenizedFilter } from '@columenlabs/lumen-ui';
```

Props:

- `filter: { fields: FilterField<T>[]; rows: T[]; indexed: { row: T; values: Record<string, string[]>; nums: Record<string, number | null>; }[]; tokens: FilterToken[]; setTokens: (next: FilterToken[]) => void; text: string; setText: Dispatch<SetStateAction<string>>; results: T[]; hasText: boolean; partial: boolean; facets: FacetCounts | null; clear: () => void; }`
- `changed?: boolean` — Other unsaved changes the save icon also saves (the page's link colours).
- `className?: string`
- `label?: string` = Filter — The input's accessible name.
- `link?: FilterLink | null` — Its card's link colour; a coloured card shares every chip. `null`: it never shares (a widget's own fixed filter).
- `onSave?: ((tokens: FilterToken[]) => void)` — Saves the box's filters as the view's own.
- `placeholder?: string` = Filter…
- `saved?: FilterToken[]` — The view's saved filters; the save button shows when the box differs from them.

Example:

```tsx
const Filter = () => <Demo />;
```

## LumenView

One view as a card: a table of the rows a page hands it, with sort, totals, grouping and a pivot. LumenLayout puts it on a page with its filter; use it alone for a second table.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-lumenview--docs

```tsx
import { LumenView } from '@columenlabs/lumen-ui';
```

Props:

- `config: CustomViewConfig`
- `domain: ViewDomain<T>` — The view's domain, its formula columns included (`withViewFields`).
- `rows: T[]` — The rows the view shows: its page's filter already applied.
- `allRows?: T[]` — Every row before the page's filter: Export then offers Filtered or All while a filter hides some. Left out: Export takes the rows shown, or a server's `paging.all`.
- `cardId?: string` = view — The card's id on its page (its fold is kept per id); a page's second table passes its own.
- `controls?: CardControls` — Its place in a LumenLayout: the layout's edit state and the card's ⋯ menu.
- `filter?: ReactNode` — The view's own filter and Group in its header (the filter is the table's, not the page's), and how many tokens it holds.
- `filterCount?: number`
- `groupActions?: ((key: string, rows: T[]) => ReactNode)` — Buttons at the end of a group row's label (pin a group), given its key and rows.
- `groupBy?: ViewField<T> | null` = null — The grouping the page picked (its Group by switch); null: flat rows.
- `inLayout?: boolean` = false — In a LumenLayout's scroller: the table scrolls with the page, its header pinned.
- `link?: CardLink` — Its link colour on the layout.
- `load?: LumenLoad` — The rows' loading state (`useLumenLoad`): the view shows its skeleton, progress bar, ↻, a failure with Retry and, with Observability details on, its load time.
- `note?: ReactNode` — A short subtitle after the title (a repo path).
- `onAddColumn?: AddColumn` — The + at the end of the header (Edits in place): Field (the Columns picker, at the +), Formula, Your data and Ask the assistant; each left out is not offered.
- `onClearFilter?: (() => void)` — Takes every filter off: an empty table under a filter offers Clear filters.
- `onColumns?: ((keys: string[]) => void)` — The Columns picker in the header: turns any of the domain's fields on or off and hands back the view's new columns. Left out: no picker.
- `onDetails?: ((row: T) => void)` — A row click: opens the details drawer, or the row's own page.
- `onSort?: ((sort: { key: string; desc: boolean; } | null) => void)` — Told when a header click changes the sort.
- `openKey?: string | null` — The key of the row whose details are open (a docked drawer beside the table): the row reads as selected (an accent fill and edge bar, `aria-selected`) and scrolls into view when it shows. ↑ and ↓ on a focused row move to the next one, and open it while a row is open.
- `paging?: ServerPaging` — The rows are one page of a server's: the pager pages through the server.
- `pivot?: boolean` = false — Shows the view's pivot instead of its rows.
- `resizable?: boolean` — A grip on each header's right edge resizes its column (desktop), kept on the device per table (the domain's id and `cardId`); left out: `configureLumen({ resizableColumns })`.
- `selection?: { keys: Set<string>; onChange: (keys: Set<string>) => void; }` — Row checkboxes (strategy lab): the checked row keys and their setter; the header box checks every shown row.
- `shown?: Partial<Record<"footer" | "header" | "legend" | "filter" | "group" | "columns" | "ask" | "refresh" | "pager" | "download" | "window", boolean>>` — Its controls from its card (Edit widget ▸ Controls); missing keys take the Table defaults.
- `sort?: { key: string; desc: boolean; } | null` = z
    .object({ key: fieldKey, desc: z.boolean().default(false) })
    .nullable()
    .default(null) — The sort shown, when the page holds it (rule C); left out: the view's saved sort.
- `state?: ReactNode` — Shown in place of the table instead of the rows, e.g. an empty state ("No accounts yet"). While a filter is on it shows in the table's body instead, under the headers, so the filter stays in reach.
- `strip?: ReactNode` — A line under the filter: the card's Link offer.
- `subgroup?: string | null` — What each row opens, by the domain's sub-group key (the page's Group button); null: none, left out: the view's saved pick.
- `tapped?: ((row: T) => boolean)` — Rows picked by a tap (a linked table's row filter): a muted fill, no border.
- `title?: string` = config.name — The card's title; left out: the view's name.
- `tools?: ReactNode` — Buttons in the card's header before the pager ("+ Add time").
- `total?: number` = rows.length — Every row before the filter, for "12 of 40 rows"; left out: `rows`.

Example:

```tsx
const Table = () => <LumenView domain={STORE_DOMAIN} config={storeView()} rows={STORES} />;
```

## Tile

One headline number with its label and up to a few lines under it. `TileRow` lays tiles in a row that wraps on phones.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pages-and-views-tile--docs

```tsx
import { Tile, TileRow } from '@columenlabs/lumen-ui';
```

Props:

- `label: ReactNode`
- `value: ReactNode`
- `caption?: ReactNode`
- `className?: string`
- `lines?: ReactNode[]` — Secondary lines under the value, one each (a Summary card's).
- `spark?: number[]` — The number's history (oldest first), drawn as a small line under it: a metric card.
- `sparkColor?: string` — The line's colour, a theme token; left out, `var(--chart-1)`.
- `valueClassName?: string`

Example:

```tsx
const One = () => <Tile label="Revenue" value="$1,257,027" caption="this month" />;
```

## LumenConfirm

Asks before an action that cannot be undone. Wrap the button that opens it, or control `open` yourself. Destructive by default (a red action); `destructive={false}` for a plain confirm. When `onConfirm` returns a promise the dialog stays open and busy until it settles: a failure shows in the dialog (`problem` words it), a success closes it or shows `done`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumenconfirm--docs

```tsx
import { Button } from '@columenlabs/lumen-ui/ui/button';
import { LumenConfirm } from '@columenlabs/lumen-ui';
```

Props:

- `onConfirm: () => unknown` — Return a promise to keep the dialog open, busy, until it settles.
- `title: ReactNode` — The question, e.g. `Delete view Options?`.
- `action?: ReactNode` = Delete — The confirm button's label.
- `busyAction?: ReactNode` = Working… — The action's label while the promise runs.
- `cancel?: string` = Cancel — The button that backs out (Keep, Keep running).
- `children?: ReactNode` — The button that opens the dialog; leave it out and control `open` instead.
- `description?: ReactNode` = This cannot be undone.
- `destructive?: boolean` = true — False for a confirm that destroys nothing (a new version): its action is not red.
- `done?: { title: ReactNode; description?: ReactNode; action?: ReactNode; }` — What the dialog says after the promise succeeds; leave it out to close instead.
- `onDone?: (() => void)` — Runs when the person dismisses the `done` state.
- `onOpenChange?: ((open: boolean) => void)`
- `open?: boolean`
- `problem?: ((error: unknown) => unknown)` = (e) => e — Turns a failed promise's error into what the dialog says (a string, or the error itself).
- `size?: enum` = sm — `default` is wider, for a longer description.
- `typeToConfirm?: string` — A word the person must type before the action unlocks, for a step that loses a lot (`DELETE`).

Example:

```tsx
const Destructive = () => <LumenConfirm title="Delete view Stores?" onConfirm={fn()}>(<Button variant="outline">
      <Trash2Icon />Delete
            </Button>)</LumenConfirm>;
```

## LumenDateInput

A date field with ‹ › to step one day back or forward (Alt+← and Alt+→ while it has focus). Pass `isOpen` to step only over open days, such as a trading calendar, and `unit` to name them in the tooltips. A step past `min` or `max` is off. `onToday` adds a Today icon button.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumendateinput--docs

```tsx
import { LumenDateInput } from '@columenlabs/lumen-ui';
```

Props:

- `onChange: (iso: string) => void`
- `value: string` — The day as ISO `yyyy-mm-dd`, or '' for none.
- `aria-label?: string`
- `atToday?: boolean` — Today is already shown: the Today button is off.
- `className?: string`
- `disabled?: boolean`
- `id?: string`
- `isOpen?: ((iso: string) => boolean)` — Which days the steps land on (a trading calendar); every day when left out.
- `max?: string`
- `min?: string` — Earliest and latest day the picker and the steps reach.
- `onToday?: (() => void)` — Shows a Today icon button that runs this.
- `size?: enum` = sm — `sm` for toolbars and card headers, `default` in forms.
- `unit?: string` = day — What a day is called in the step tooltips: "Previous trading day". Default "day".

Example:

```tsx
const EveryDay = (args) => <Demo size={args.size} unit={args.unit} />;
```

## LumenDrawer

The one pullout drawer: a right-side panel on desktop whose width drags (320px to 60%), a bottom sheet on phone. Its body holds `DrawerSection`s; its footer always shows (Close when you pass no actions).

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumendrawer--docs

```tsx
import { Button } from '@columenlabs/lumen-ui/ui/button';
import { DrawerSection, LumenDrawer } from '@columenlabs/lumen-ui';
```

Props:

- `children: ReactNode` — Stacked DrawerSections; the drawer pads and scrolls them.
- `onClose: () => void`
- `open: boolean`
- `title: ReactNode`
- `actions?: readonly DrawerAction[]` — The footer's actions as data, right-aligned in order, before `footer`: always icons.
- `defaultSize?: Size` = 32% — Width on desktop: starts at `defaultSize`, drags between `minSize` and `maxSize`.
- `description?: ReactNode` — A muted line under the title ("Active · invited Oct 16"); read aloud only when left out.
- `dock?: string` — Docks it beside the page on desktop instead of over it, under this name: a click on the page leaves it open (a list's next row swaps what it shows), it folds to a rail, and its width and fold are kept in this browser. A phone still gets the bottom sheet.
- `footer?: ReactNode` — Last in the footer, after `actions`: the `SaveButton`. No footer when this, `actions` and `footerStart` are left out.
- `footerStart?: ReactNode` — Left side of the footer: a count or status line ("12 releases").
- `maxSize?: Size` = 60%
- `minSize?: Size` = 320px

Example:

```tsx
const Drawer = () => {
    const [, update] = useArgs();

    return (
        <>
            <Button variant="outline" onClick={() => update({ open: true })}>Open drawer
                        </Button>
            <LumenDrawer
                open
                title="Lisbon"
                description="Flagship · opened Jan 2014"
                onClose={() => update({ open: false })}
                footer={<Button onClick={() => update({ open: false })}>Save</Button>}>
                <DrawerSection title="About" icon={InfoIcon} defaultOpen>
                    <p className="text-sm">The first store, on the river front.</p>
                </DrawerSection>
                <DrawerSection title="Orders" icon={ReceiptIcon} count={1701}>
                    <p className="text-sm">1,701 orders this month.</p>
                </DrawerSection>
            </LumenDrawer>
        </>
    );
};
```

## LumenForm

A form from a list of fields: text, secret, number, date, textarea, select and multi. Each field checks itself; Save lists what needs fixing and takes you to it instead of saving.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumenform--docs

```tsx
import { LumenForm } from '@columenlabs/lumen-ui';
```

Props:

- `fields: readonly LumenFormField[]`
- `onSave: (values: LumenFormValues) => void` — Runs only when every check passes. A secret left empty is left out.
- `busy?: boolean` = false
- `footer?: ReactNode` — Beside Save, on the left (a Test button, a note).
- `initial?: LumenFormValues`
- `onCancel?: (() => void)`
- `saveLabel?: string` = Save

Example:

```tsx
const Form = () => <LumenForm
    onSave={fn()}
    onCancel={fn()}
    fields={[
      { id: 'name', label: 'Name', required: true, placeholder: 'Lisbon' },
      {
        id: 'url',
        label: 'Webhook',
        hint: 'Gets each event as JSON.',
        check: (v) => String(v).startsWith('https://') || 'Must start with https://',
      },
      { id: 'key', label: 'API key', kind: 'secret', saved: '••••3f9a' },
      {
        id: 'region',
        label: 'Region',
        kind: 'select',
        options: [
          { value: 'north', label: 'North' },
          { value: 'centre', label: 'Centre' },
          { value: 'south', label: 'South' },
        ],
      },
      { id: 'notes', label: 'Notes', kind: 'textarea' },
    ]} />;
```

## LumenPlayer

A recording on the browser’s own video or audio element with the kit’s controls: play, back and forward 15 seconds, seek, speed, captions and full screen. Chapters jump, a timed transcript follows and plays from a line, and `onProgress` reports the place about every 10 seconds, on pause and at the end. A slides source shows pictures in step with audio. Keys (space, j, l, arrows) work while it has focus.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumenplayer--docs

```tsx
import { LumenPlayer } from '@columenlabs/lumen-ui';
```

Props:

- `autoPlay?: boolean` — Plays as soon as it can (the next item of a series, after the last one ended).
- `chapters?: readonly PlayerChapter[]`
- `className?: string`
- `kind?: enum` — `video` or `audio`; read from the address's extension by default (video when unsure).
- `onEnded?: (() => void)`
- `onProgress?: ((seconds: number, info: { duration: number | null; ended: boolean; }) => void)` — The place, about every 10 s while playing, on pause and at the end.
- `poster?: string`
- `source?: PlayerSource`
- `src?: string` — The recording's address; or `source` for slides over audio.
- `start?: number` — Where to start, in seconds (a saved place, or a search hit's minute).
- `title?: string` — The recording's name, for screen readers and full screen.
- `tracks?: readonly PlayerTrack[]` — Captions (video).
- `transcript?: readonly PlayerLine[]`

Example:

```tsx
const Video = () => {
    const [saved, setSaved] = useState<number | null>(null);

    return (
        <div className="flex flex-col gap-2">
            <LumenPlayer
                src="./clips/edit-layout.mp4"
                title="Edit layout"
                chapters={[
                  { at: 0, title: 'The page' },
                  { at: 3, title: 'Edit layout' },
                  { at: 11, title: 'Save or reset' },
                ]}
                transcript={[
                  { start: 0, text: 'Here is the page before anything changes.', who: 'Host' },
                  { start: 3, text: 'Edit layout opens the grid: every card can move and resize.', who: 'Host' },
                  { start: 7, text: 'A card dragged to a new spot pushes the others down.', who: 'Host' },
                  { start: 11, text: 'Done saves the layout for this person only.', who: 'Host' },
                  { start: 15, text: 'Reset to default puts the shared layout back.', who: 'Host' },
                ]}
                onProgress={(s) => setSaved(s)} />
            <p className="num text-xs text-muted-foreground">Saved place: {saved ?? '–'}</p>
        </div>
    );
};
```

## LumenSelector

Every picker in one part: one value or many, groups, search past 8 options, and an Add row that turns typed text into a new value. On a phone the list opens as a bottom sheet.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-lumenselector--docs

```tsx
import { LumenSelector } from '@columenlabs/lumen-ui';
```

Props:

- `onChange: ((value: V) => void) | ((value: V[]) => void)`
- `value: string | readonly V[] | null | undefined`
- `align?: enum`
- `className?: string`
- `create?: ((query: string) => V | null)` — Turns typed text into a new value (a ticker, "ema 13", a new sector); null refuses it.
- `createLabel?: ((query: string) => string)` — The create row's text; `Add "…"` by default.
- `disabled?: boolean`
- `display?: ReactNode` — What the closed field shows instead of the picked option's label (a zone's short name, PT).
- `empty?: string` — Shown when nothing matches.
- `groups?: readonly LumenOptionGroup<V>[]`
- `header?: ReactNode` — Above the list (a scope switch such as "for SPY / All").
- `icon?: Icon` — The icon trigger's icon, or a leading icon in a field or chip.
- `id?: string`
- `label?: string` — Accessible name; also the phone sheet's title.
- `max?: number` — At most this many picked; the rest of the list greys out.
- `multiple?: boolean`
- `onHighlight?: ((value: V) => void)` — A row was highlighted (hover or arrow keys): a caller reads it ahead (the assistant's Chats).
- `onOpenChange?: ((open: boolean) => void)`
- `open?: boolean`
- `options?: readonly LumenOption<V>[]` — The options; or `groups` to fix the group order.
- `placeholder?: string`
- `search?: boolean | "auto"` — `auto`: a search box past 8 options.
- `size?: enum`
- `trigger?: enum` — `field` by default.

Example:

```tsx
const Single = () => {
    const [, update] = useArgs();

    return (
        <div className="w-64">
            <LumenSelector
                options={[
                  { value: 'daily', label: 'Daily', group: 'Often' },
                  { value: 'weekly', label: 'Weekly', group: 'Often' },
                  { value: 'monthly', label: 'Monthly', group: 'Now and then', detail: '1st' },
                  { value: 'yearly', label: 'Yearly', group: 'Now and then', detail: 'Jan 1' },
                ]}
                value="weekly"
                label="Cadence"
                onChange={(value: unknown) => update({ value })} />
        </div>
    );
};
```

## RenameField

A name renamed in place: Enter or leaving the field saves, Escape undoes, and empty or ↺ goes back to the source’s own name.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-renamefield--docs

```tsx
import { RenameField } from '@columenlabs/lumen-ui';
```

Props:

- `onSave: (name: string | null) => void` — null resets to `original`.
- `original: string` — The source's own name (the broker's, the bank's), what Reset goes back to.
- `originLabel: string` — Where `original` comes from, for the tooltip: "At the broker", "At the bank".
- `value: string` — The name shown now: the person's own, or `original`.

Example:

```tsx
const Rename = args => {
    const [, update] = useArgs();

    return (
        <RenameField
            value="Main checking"
            original="CHK ••4410"
            originLabel="At the bank"
            onSave={(name) => update({ value: name ?? args.original })} />
    );
};
```

## ResetButton

Puts a setting back to its default: a ↺ that shows only while something differs, its tooltip naming what it goes back to.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-resetbutton--docs

```tsx
import { ResetButton } from '@columenlabs/lumen-ui';
```

Props:

- `changed: boolean` — Whether anything differs from the default; nothing shows when it doesn't.
- `label: string` — The tooltip and accessible name: "Reset to 15 – 45", "Reset all".
- `onReset: () => void`
- `size?: enum` = icon-xs

Example:

```tsx
const Reset = () => <ResetButton changed label="Reset to 15 – 45" onReset={fn()} />;
```

## SaveButton

Save that says why it cannot save: with issues, a chip before it counts them and lists each; tapping Save takes you to the first one. Never a bare disabled button.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-and-panels-savebutton--docs

```tsx
import { SaveButton } from '@columenlabs/lumen-ui';
```

Props:

- `issues: FormIssue[]`
- `busy?: boolean` = false — Saving now: Save waits.
- `className?: string`
- `disabled?: boolean` = false — Nothing to save (no change): Save is greyed and needs no reason.
- `icon?: ComponentType<{ className?: string; }> | null` — `null` is the check, as left out.
- `label?: string` = Save — The tooltip and accessible name.
- `onSave?: (() => void)`
- `type?: enum` = button — `submit` inside a form: the form's own submit runs only when there are no issues.

Example:

```tsx
const Ready = () => <SaveButton issues={[]} onSave={fn()} />;
```

## GrowthChart

Growth of $1 for a set of lines on a log, linear or fit scale, with optional bands, markers and this year’s start. `format` changes the axis from `1.23×` to any unit.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-growthchart--docs

```tsx
import { GrowthChart, paletteAt } from '@columenlabs/lumen-ui';
```

Props:

- `className: string`
- `lines: Series[]`
- `scale: enum`
- `bands?: ChartBand[]` = []
- `format?: ((v: number) => string)` = (v: number) =>
  `${v < 0 ? MINUS : ''}${Math.abs(v).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}×`
- `markers?: ChartMarker[]` = []
- `sinceYears?: number`
- `ytd?: boolean` = true

Example:

```tsx
const Growth = () => <GrowthChart
    lines={[
      {
        key: 'a',
        label: 'Plan A',
        color: paletteAt(0),
        hold: false,
        dashed: false,
        points: curve(1, 0.0008),
      },
      {
        key: 'b',
        label: 'Plan B',
        color: paletteAt(1),
        hold: false,
        dashed: false,
        points: curve(0.6, 0.0012),
      },
      {
        key: 'bench',
        label: 'Benchmark',
        color: paletteAt(2),
        hold: true,
        dashed: true,
        points: curve(0.4, 0.0005),
      },
    ]}
    scale="log"
    className="h-72 w-full" />;
```

## LumenEChart

Any Apache ECharts option, themed: `useChartTokens` gives the theme’s colours and fonts and redraws on a theme change; `axisStyle` and `baseOption` style axes the kit’s way.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-lumenechart--docs

```tsx
import { LumenEChart } from '@columenlabs/lumen-ui';
```

Props:

- `label: string` — What the chart shows, for screen readers.
- `option: ECBasicOption`
- `className?: string`
- `height?: number` = 260
- `on?: EChartHandlers` — Event handlers by ECharts event name ('click', 'axisareaselected').

Example:

```tsx
const Bars = () => <Demo />;
```

## LumenGeoMap

A world map shaded by one number per country (ISO alpha-2 codes); countries left out draw empty.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-lumengeomap--docs

```tsx
import { LumenGeoMap } from '@columenlabs/lumen-ui';
```

Props:

- `label: string` — What the map shows, for screen readers.
- `values: Record<string, number>` — The number for each country, by ISO alpha-2 code; countries left out draw empty.
- `height?: number` = 260
- `unit?: string` — What the number counts ("visits"), shown in the tooltip after it.

Example:

```tsx
const World = () => <LumenGeoMap
    label="Visits by country"
    unit="visits"
    values={{
      PT: 4200,
      ES: 2600,
      FR: 1900,
      DE: 1500,
      GB: 1300,
      US: 3100,
      BR: 2200,
      CA: 600,
      IN: 900,
      JP: 400,
    }} />;
```

## PriceChart

A price chart on TradingView Lightweight Charts™: candles, OHLC bars, line, area or Heikin-Ashi, with volume, overlays on the price and a pane per oscillator. Indicators are worked out in the browser from the bars (`computeIndicators`). Made-up bars here.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-pricechart--docs

```tsx
import { PriceChart, resolveIndicator, computeIndicators } from '@columenlabs/lumen-ui';
```

Props:

- `bars: ChartBar[]`
- `chosen: ChartIndicator[]` — Overlays drawn on the price and oscillators in their own panes.
- `type: enum`
- `values: IndicatorValues`
- `baseline?: number | null` = null — Draws this level as a dashed line (the prior close).
- `className?: string`
- `navigator?: boolean` = false — The timeline under the chart: drag its window to move, its edges to zoom.
- `onOutside?: ((span: TimeSpan) => void)` — The timeline asked for a span the chart's bars do not cover (intraday bars, older days).
- `onRange?: ((span: TimeSpan, byPerson: boolean) => void)` — The shown span (first and last bar), and whether the person moved it (drag, wheel, timeline).
- `range?: TimeSpan` — The span to show; a new object moves the chart there, panning and zooming move it after.
- `timeline?: ChartBar[]` — The navigator's bars when they differ from the chart's: the symbol's whole history, coarser, with the shown span cut out of it. Left out: the chart's own bars.
- `timeZone?: string` = America/Los_Angeles — The person's time zone, for intraday bars (Unix seconds).
- `visible?: number` — Bars shown at first, counted from the latest; left out: all of them.
- `zoom?: boolean` = false — Wheel and pinch zoom (off where the page itself scrolls under the chart).

Example:

```tsx
const Candles = () => <PriceChart
    bars={sampleBars(260)}
    type="candles"
    chosen={['sma_20', 'sma_50', 'rsi_14'].flatMap((id) => resolveIndicator(id) ?? [])}
    values={computeIndicators(bars, chosen)}
    className="h-96 w-full"
    navigator />;
```

## RankedBars

Labelled counts as a ranked list on full tracks. Each value carries its share: of all bars (`total`), of the first bar (`first`, for a funnel), your own text, or none. With no bars it shows `empty`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-rankedbars--docs

```tsx
import { RankedBars } from '@columenlabs/lumen-ui';
```

Props:

- `items: Item[]`
- `empty?: ReactNode` = None yet. — Shown in place of the bars when there are none.
- `fmt?: Fmt` = (v) => v.toLocaleString()
- `id?: string` — Keeps the bars' gradients apart when one page draws several; one is made when left out.
- `label?: string` — What the bars show, for screen readers.
- `share?: false | "first" | "total" | ((v: number) => string)` = total — The small figure before each value: its % of all bars (`total`), of the first bar (`first`, for a funnel), the app's own text, or `false` for none.
- `signed?: boolean` = false — Bars can go below zero (a loss); otherwise they start at zero.

Example:

```tsx
const ShareOfTotal = () => <RankedBars
    label="Sign-ups by country"
    items={[
      { name: 'United States', v: 412, fill },
      { name: 'Canada', v: 96, fill },
      { name: 'United Kingdom', v: 61, fill },
    ]} />;
```

## StackedColumns

Columns over time, oldest on the left, each split into stacked parts (what worked and what failed per day). The highest part with a value gets the rounded cap; the tooltip lists each part and the total.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-stackedcolumns--docs

```tsx
import { StackedColumns } from '@columenlabs/lumen-ui';
```

Props:

- `label: string` — What the chart shows, for screen readers.
- `parts: { name: string; key: string; fill: string; }[]`
- `rows: Record<string, string | number>[]` — One row per period, oldest first: the `x` field plus a number for each part's key.
- `x: string` — The field that names each column (a date, a month).
- `fmt?: Fmt` = (v) => v.toLocaleString()
- `height?: number` = 220
- `legend?: boolean` = true — The parts' names under the columns.
- `tick?: ((v: string) => string)` — How a column's name reads under it (a date as `10-22`).

Example:

```tsx
const PerDay = () => <StackedColumns
    rows={Array.from({ length: 14 }, (_, i) => {
      const date = new Date(Date.UTC(2026, 9, 9 + i)).toISOString().slice(0, 10);
      return { date, ok: 20 + ((i * 7) % 13), failed: i % 4 === 0 ? 3 : i % 5 === 0 ? 1 : 0 };
    })}
    x="date"
    label="Requests per day, last 14 days"
    tick={(d: string) => d.slice(5)}
    parts={[
      { key: 'ok', name: 'Worked', fill: 'var(--gain)' },
      { key: 'failed', name: 'Failed', fill: 'var(--loss)' },
    ]} />;
```

## TimeLines

Lines over time, oldest on the left. A line with `right` reads off a second axis, for a count far smaller than the others; a null leaves a gap.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-charts-timelines--docs

```tsx
import { TimeLines } from '@columenlabs/lumen-ui';
```

Props:

- `label: string` — What the chart shows, for screen readers.
- `lines: { name: string; key: string; fill: string; right?: boolean | undefined; }[]`
- `rows: Record<string, string | number | null>[]` — One row per period, oldest first: the `x` field plus a number (or null for no data) for each line's key.
- `x: string` — The field that names each period (a date, a month).
- `fmt?: Fmt` = (v) => v.toLocaleString()
- `height?: number` = 220
- `legend?: boolean` = true — The lines' names under the chart.
- `tick?: ((v: string) => string)` — How a period's name reads under the chart (a date as `10-22`).

Example:

```tsx
const PerDay = () => <TimeLines
    rows={Array.from({ length: 30 }, (_, i) => {
      const date = new Date(Date.UTC(2026, 8, 27 + i)).toISOString().slice(0, 10);
      return { date, visits: 120 + ((i * 37) % 90), joins: 2 + ((i * 5) % 7), accounts: i % 3 };
    })}
    x="date"
    label="Visits, sign-ups and new accounts per day, last 30 days"
    tick={(d: string) => d.slice(5)}
    lines={[
      { key: 'visits', name: 'Visits', fill: 'var(--chart-6)' },
      { key: 'joins', name: 'Sign-ups', fill: 'var(--primary)', right: true },
      { key: 'accounts', name: 'New accounts', fill: 'var(--chart-3)', right: true },
    ]} />;
```

## LumenCodeEditor

An editable code box (CodeMirror) for SQL, JavaScript or JSON, loaded only when it first shows.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-code-lumencodeeditor--docs

```tsx
import { LumenCodeEditor } from '@columenlabs/lumen-ui';
```

Props:

- `onChange: (value: string) => void`
- `value: string`
- `className?: string`
- `lang?: enum`
- `readOnly?: boolean`
- `wrap?: boolean` — Wraps long lines instead of scrolling sideways (off by default).

Example:

```tsx
const Editor = () => {
    const [, update] = useArgs();

    return (
        <LumenCodeEditor
            lang="sql"
            className="h-40"
            value="SELECT region, sum(revenue) AS revenue\nFROM stores\nGROUP BY region\nORDER BY revenue DESC"
            onChange={(value) => update({ value })} />
    );
};
```

## LumenCode

Read-only code, highlighted by Shiki in the theme’s light and dark colours, with a copy button in its header.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-code-lumencode--docs

```tsx
import { LumenCode } from '@columenlabs/lumen-ui';
```

Props:

- `code: string`
- `className?: string`
- `header?: boolean` = true — The label and copy icon over the code (chat); off where the page has its own (a file view).
- `lang?: string` — The fence tag or file extension; none draws plain text.
- `lineNumbers?: boolean` = false — Numbers each line (files); off for chat snippets.
- `wrap?: boolean` = false — Wraps long lines instead of scrolling sideways.

Example:

```tsx
const Code = () => <LumenCode
    lang="ts"
    lineNumbers
    code={`import { LumenSelector } from '@columenlabs/lumen-ui';

export function Cadence({ value, onChange }: Props) {
  return <LumenSelector options={CADENCES} value={value} onChange={onChange} />;
}`} />;
```

## ColorDot

A small dot in any CSS colour (a theme token reads in both themes); `ColorChip` puts one before a label.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-feedback-colordot--docs

```tsx
import { ColorChip, ColorDot } from '@columenlabs/lumen-ui';
```

Props:

- `color: string`
- `className?: string`

Example:

```tsx
const Dot = () => <ColorDot color="var(--chart-2)" />;
```

## LumenBoundary

Keeps a crash inside its card: the card says it hit an error, with Try again and Reload, and the page around it keeps working. Every grid card and widget body sits in one.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-feedback-lumenboundary--docs

```tsx
import { LumenBoundary } from '@columenlabs/lumen-ui';
```

Props:

- `where: string` — Logged with the error: the card's id, or the panel's name ("assistant").
- `what?: enum` = card

Example:

```tsx
const CaughtError = () => <LumenBoundary where="sample-card"><Broken /></LumenBoundary>;
```

## NoteLine

One muted line over a card or page: an icon, what it says, and an optional button.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-feedback-noteline--docs

```tsx
import { Button } from '@columenlabs/lumen-ui/ui/button';
import { NoteLine } from '@columenlabs/lumen-ui';
```

Props:

- `icon: LucideIcon`
- `title: ReactNode` — The point, in a few words.
- `action?: ReactNode` — A button the note carries.
- `note?: ReactNode` — The detail, one line.

Example:

```tsx
const Note = () => <NoteLine
    icon={PlugIcon}
    title="Connect a data source"
    note="to see live numbers here."
    action={(<Button size="sm" variant="outline">Connect
            </Button>)} />;
```

## Badge

shadcn/ui's Badge with Lumen's `success`, `warning` and `info` tones added.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-base-parts-badge--docs

```tsx
import { Badge } from '@columenlabs/lumen-ui/ui/badge';
```

Props:

- `asChild?: boolean` = false
- `variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "success" | "warning" | "info" | null` = default

Example:

```tsx
const Default = () => <Badge variant="success">Live</Badge>;
```

## Button

shadcn/ui's Button in Lumen's theme. `destructive` stays muted until hovered and always opens a confirm; its final button is `destructive-confirm`.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-base-parts-button--docs

```tsx
import { Button } from '@columenlabs/lumen-ui/ui/button';
```

Props:

- `asChild?: boolean` = false
- `size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null` = default
- `variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "destructive-confirm" | null` = default

Example:

```tsx
const Default = () => <Button variant="default" size="default">Save</Button>;
```

## Gallery

The common base parts in one place, in the light or dark theme. Each is the shadcn/ui component of the same name; its own docs list every prop.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-base-parts-gallery--docs

```tsx
import { Alert, AlertDescription, AlertTitle } from '@columenlabs/lumen-ui/ui/alert';
import { Badge } from '@columenlabs/lumen-ui/ui/badge';
import { Button } from '@columenlabs/lumen-ui/ui/button';
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@columenlabs/lumen-ui/ui/card';
import { Checkbox } from '@columenlabs/lumen-ui/ui/checkbox';
import { Input } from '@columenlabs/lumen-ui/ui/input';
import { Kbd, KbdGroup } from '@columenlabs/lumen-ui/ui/kbd';
import { Label } from '@columenlabs/lumen-ui/ui/label';
import { Progress } from '@columenlabs/lumen-ui/ui/progress';
import { Separator } from '@columenlabs/lumen-ui/ui/separator';
import { Skeleton } from '@columenlabs/lumen-ui/ui/skeleton';
import { Slider } from '@columenlabs/lumen-ui/ui/slider';
import { Spinner } from '@columenlabs/lumen-ui/ui/spinner';
import { Switch } from '@columenlabs/lumen-ui/ui/switch';
import { Textarea } from '@columenlabs/lumen-ui/ui/textarea';
```

Example:

```tsx
const Gallery = () => (
  <div className="grid max-w-3xl gap-6 sm:grid-cols-2">
    <Card>
      <CardHeader>
        <CardTitle>Buttons and badges</CardTitle>
        <CardDescription>Variants share one height per size.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-wrap gap-2">
        <Button>Save</Button>
        <Button variant="outline">Cancel</Button>
        <Button variant="ghost">More</Button>
        <Button variant="destructive">Delete</Button>
        <Separator className="my-1" />
        <Badge variant="success">Live</Badge>
        <Badge variant="warning">Late</Badge>
        <Badge variant="info">New</Badge>
        <Badge variant="outline">Draft</Badge>
      </CardContent>
    </Card>
    <Card>
      <CardHeader>
        <CardTitle>Fields</CardTitle>
        <CardDescription>Inputs, switches and sliders.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-3">
        <div className="grid gap-1.5">
          <Label htmlFor="g-name">Name</Label>
          <Input id="g-name" placeholder="Lisbon" />
        </div>
        <Textarea placeholder="Notes" rows={2} />
        <div className="flex items-center gap-2">
          <Switch id="g-on" defaultChecked />
          <Label htmlFor="g-on">On</Label>
          <Checkbox id="g-check" defaultChecked className="ml-4" />
          <Label htmlFor="g-check">Include</Label>
        </div>
        <Slider defaultValue={[40]} max={100} />
      </CardContent>
    </Card>
    <Card>
      <CardHeader>
        <CardTitle>Progress and loading</CardTitle>
      </CardHeader>
      <CardContent className="flex flex-col gap-3">
        <Progress value={62} />
        <div className="flex items-center gap-3">
          <Spinner />
          <Skeleton className="h-4 w-40" />
        </div>
        <KbdGroup>
          <Kbd>⌘</Kbd>
          <Kbd>K</Kbd>
        </KbdGroup>
      </CardContent>
    </Card>
    <Alert>
      <InfoIcon />
      <AlertTitle>Built on shadcn/ui</AlertTitle>
      <AlertDescription>
        These parts come from shadcn/ui, on Radix and Base UI, styled with Tailwind.
      </AlertDescription>
    </Alert>
  </div>
);
```

## IconButton

Every icon button: the icon alone, its name in a tooltip and the accessible name. `busy` spins it, `pressed` fills it, `to` and `href` make it a link.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-base-parts-iconbutton--docs

```tsx
import { IconButton } from '@columenlabs/lumen-ui';
```

Props:

- `icon: ComponentType<{ className?: string | undefined; }>` — A lucide icon, or any icon component that takes `className` (a view's own icon).
- `label: string` — The action's name: the tooltip and the accessible name.
- `asChild?: boolean`
- `busy?: boolean` — Spins the icon while the action runs.
- `href?: string` — Opens this outside address in a new tab instead of running `onClick`.
- `pressed?: boolean` — A toggle that is on (pinned, followed): its icon fills in the app colour.
- `size?: enum` = icon-sm — `icon-sm` (headers, toolbars) by default; `icon-xs` in table rows and chips, `icon` in forms.
- `to?: string` — Opens this route instead of running `onClick`.
- `variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "destructive-confirm" | null` = ghost

Example:

```tsx
const Plain = () => <IconButton icon={RefreshCwIcon} label="Refresh" onClick={fn()} />;
```

## LumenFileField

A file to bring in: drop it on the field or Choose one. The app holds the file, so setting it back to null after an upload empties the field.

Docs: https://lumen.columenlabs.com/docs/?path=/docs/components-pickers-lumenfilefield--docs

```tsx
import { LumenFileField } from '@columenlabs/lumen-ui';
```

Props:

- `file: File | null` — The chosen file, or null for none.
- `label: string` — What the field takes, for screen readers and the empty field ("CSV file").
- `onFile: (file: File | null) => void`
- `accept?: string` — File types the picker offers, as the input's `accept` (`.csv,text/csv`).
- `className?: string`
- `disabled?: boolean`

Example:

```tsx
const Csv = () => {
    const [file, setFile] = useState<File | null>(null);
    return <LumenFileField accept=".csv,text/csv" label="CSV file" file={file} onFile={setFile} />;
};
```

## Releasenotes



Docs: https://lumen.columenlabs.com/docs/?path=/docs/changelog-release-notes--docs

```tsx
import { Badge } from '@columenlabs/lumen-ui/ui/badge';
import { DrawerSection } from '@columenlabs/lumen-ui';
```

Example:

```tsx
const Page = () => <Changelog />;
```

# Reference

Parts that need an app behind them; their pages list each prop.

## Market

Docs: https://lumen.columenlabs.com/docs/?path=/docs/reference-market--docs

- LumenChart: The chart dialog: up to 8 symbols, % or price, indicators.
- MarketWidget: Live market widget: index lines, tiles and today's movers.
- IndicatorPicker: Pick and set up chart indicators, or type a formula.
- OptionChainTable: An option chain by expiration: calls and puts around the strike.
- SymbolSheetProvider: Opens the symbol sheet from any symbol cell.

## Widgets and pages

Docs: https://lumen.columenlabs.com/docs/?path=/docs/reference-widgets-and-pages--docs

- LumenWidget: The frame every card sits in: header, link square, size and collapse.
- LumenViewCard: A second table on a page, with its own filter.
- LumenCard: One number and its lines.
- LumenPageState: Loading, empty and error states for a page.
- LumenTabDrawer: Manage tabs: rename, reorder and remove.
- IconPicker: Pick an icon from the kit's set.
- OverviewPage: A home page of stages, each a list of rows.
- LumenCoverageMap: A calendar heatmap of what data exists by day.