@close-by/clay 0.2.17 → 0.2.19

package/docs/README.md

@@ -15,12 +15,14 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | [Tailwind](./tailwind.md) | Zero-config utilities from page modules; optional tokens |
 | [Sample app](./tutorial.md) | Step-by-step tasks list, then two pages + shell |
 | [Concepts](./concepts.md) | Mental model: sessions, elements, patches; **canonical `state`/`auto`/`timer` recipe**; reactive `let` alternative |
+| [Updating in place](./updating-in-place.md) | Patch instead of rebuild: `setText`, keyed `setRows`, keyed `refreshable` / `auto` lists (no flicker) |
 | [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / search / `openExternal` — never `window` in page code |
 | [URL search](./url-search.md) | `ui.urlState` + query helpers for shareable filters |
 | [Production & security](./production.md) | Auth, server exposure, rate limits, boot parity |
 | [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
 | [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |
 | [Elements](./elements.md) | All element types and props |
+| [Maps](./maps.md) | `ui.map`: MapLibre markers, routes, arcs, GeoJSON, clusters; palette theming and in-place updates |
 | [WebSocket protocol](./protocol.md) | Client ↔ server message formats |
 | [Architecture](./architecture.md) | Packages, data flow, and ownership |
 | [Examples](./examples.md) | Demo apps and patterns |

package/docs/api.md

@@ -91,6 +91,7 @@ ui.run({
 | `title` | `string` | `'Clay'` | HTML `<title>` |
 | `clientDir` | `string` | `resolveClayClientDir()` | Built Vite assets (`@close-by/clay-cli/client-dist` when installed). Prefer `resolveClayClientDir()` over hardcoding `node_modules` paths — see [Boot](./boot.md). |
 | `css` | `string \| string[]` | | Extra CSS file path(s) served after the client bundle (absolute or cwd-relative). Override theme tokens without rebuilding the client. |
+| `sound` | `boolean` | | Play short synthesized interface sounds by default (`false`). See [Sound](#sound). |
 | `app` | `AppProps` | | Global dashboard shell; client keeps chrome sticky across navigate |
 | `authSecret` | `string` | | Enables signed auth cookies (`POST`/`DELETE /auth/session`), `ui.establishAuthSession` / `ui.clearAuthSession`, and default `resolveUserId` from the cookie |
 | `authCookieMaxAgeSec` | `number` | `43200` (12h) | Auth cookie Max-Age |
@@ -1801,6 +1802,13 @@ onClick: async () => {
 | `ui.openExternal(url)` | `void` | `window.open` in a new tab (`noopener`) |
 | `ui.theme.set(mode)` | `void` | Push `light` \| `dark` \| `system` to this client |
 | `ui.theme.get()` | `ThemeMode \| null` | Last value set on this session |
+| `ui.theme.palette(name)` | `void` | Switch colour palette for this client (`kiln`, `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `neon`, `sky`, `navy`, `indigo`, `denim`, `midnight`, or a custom one); remembered across reloads |
+| `ui.theme.getPalette()` | `ThemePalette \| null` | Last palette set, else the one the client reported on connect |
+| `ui.theme.palettes` | `readonly string[]` | Built-in palette names |
+| `ui.sound.set(on)` | `void` | Turn automatic interface sounds on/off for this client; remembered across reloads. See [Sound](#sound) |
+| `ui.sound.volume(v)` | `void` | Master volume `0`–`1` (default `0.5`); remembered across reloads |
+| `ui.sound.play(name)` | `void` | Play one cue now, even when automatic sounds are off |
+| `ui.sound.names` | `readonly string[]` | Built-in cue names |
 | `ui.runJavaScript(code)` | `void` | Eval trusted snippet in the browser |
 | `ui.scroll.to(opts)` | `void` | Scroll window (`top` / `bottom` / px) |
 | `ui.scroll.intoView(selector, opts?)` | `void` | `Element.scrollIntoView` via selector |
@@ -1911,9 +1919,11 @@ All layout helpers accept either `(fn, props?)` or `(props, fn)`.
 | `ui.row` | Horizontal flex |
 | `ui.column` | Vertical flex |
 | `ui.container` | Width-constrained wrapper |
+| `ui.grid` | Responsive grid that fills the width (auto-fit columns, or fixed `cols`) |
 | `ui.hero` | Centered hero region |
 | `ui.card` | Card; callback receives the card element |
 | `ui.app` | SPA shell: sidebar nav + centered main content |
+| `ui.map` | Live map (MapLibre): markers, routes, arcs, GeoJSON, clusters, popup. See [Maps](./maps.md) |
 
 #### `ui.app(props, fn)`
 
@@ -1965,8 +1975,44 @@ Shared layout props:
 | `className` | `string` | | Extra classes |
 | `centered` | `boolean` | | `mx-auto` (container) |
 | `width` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl' \| '7xl' \| 'full'` | `'lg'` for container | Max width |
+| `align` | `'start' \| 'center' \| 'end' \| 'baseline' \| 'stretch'` | row: `center` (`stretch` when the row grows) | Cross-axis alignment |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | | Main-axis distribution |
+| `wrap` | `boolean` | row: `true` | Flex wrap |
+| `grow` | `boolean \| number` | | Take the remaining space in the parent row/column. A number sets the share (`grow: 2` gets twice `grow: 1`) |
+| `scroll` | `boolean \| 'x' \| 'y'` | | Scroll inside this element instead of growing the page. On a card, the body scrolls and the header stays |
+| `fillViewport` | `boolean` | | Height = visible page area (viewport minus the app shell header/padding). Use on the outermost page column |
 
-Card also accepts `title?: string`.
+Card also accepts `title?: string` and `description?: string`; `grow` / `scroll` / `fillViewport` work on cards too.
+
+#### `ui.grid(props, fn)`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `minColWidth` | `string \| number` | `'16rem'` | Auto-fit as many columns as fit, each at least this wide (numbers are px). Wraps to one column on phones |
+| `cols` | `number` | | Fixed column count instead of auto-fit (one column below `sm`) |
+| `gap` | `number` | `4` | Gap scale |
+
+```typescript
+ui.grid({ minColWidth: '14rem' }, () => {
+  for (const kpi of kpis) ui.card({ title: kpi.label }, () => ui.label(kpi.value));
+});
+```
+
+#### Filling the page
+
+Make a page fill the window and let panels scroll instead of the page:
+
+```typescript
+ui.column({ fillViewport: true, gap: 4 }, () => {
+  ui.grid({ minColWidth: '12rem' }, () => { /* KPI cards — natural height */ });
+  ui.row({ grow: true, wrap: false, gap: 4 }, () => {     // takes the remaining height
+    ui.card({ title: 'Inbox', scroll: true, className: 'w-80 shrink-0' }, () => { /* list */ });
+    ui.card({ title: 'Detail', grow: true, scroll: true }, () => { /* body */ });
+  });
+});
+```
+
+Without `fillViewport`, `grow` still stretches to fill free space (the app shell content area is a flex column), but the page scrolls when content is taller than the window.
 
 ```typescript
 ui.container(() => {
@@ -1976,6 +2022,15 @@ ui.container(() => {
 }, { centered: true, width: 'md' });
 ```
 
+#### `ui.map(props?)`
+
+A live map: MapLibre with markers, routes, arcs, GeoJSON layers, clusters and a popup. Setters (`setMarkers`, `upsertMarker`, `updateRoute`, `flyTo`, `fitBounds`, ...) update it in place. Props, tones, events and layout are in the [Maps guide](./maps.md).
+
+```typescript
+const fleet = ui.map({ fill: true, markers: vehicles(), onMarkerClick: (m) => select(m.id) });
+fleet.fitBounds('markers', { padding: 48 });
+```
+
 ---
 
 ## `Element` methods (`@close-by/clay-core`)
@@ -2143,6 +2198,33 @@ import { button, input /* … */ } from '@close-by/clay-components';
 
 ---
 
+## Sound
+
+Clay can answer interactions with short interface sounds, synthesized in the browser with Web Audio (no audio files). They're **off by default**. Turn them on for every visitor with `createServer({ sound: true })`, or per session with `ui.sound.set(true)`. The client remembers the last choice.
+
+Once sound is on, a mute button appears next to the Clay connection chip in the bottom-left corner, so each user can silence it. A user's mute choice is remembered for their browser. Apps that never turn sound on don't show the button.
+
+When enabled, a page-wide listener picks the cue from the element, so components need no wiring:
+
+| Interaction | Cue |
+|---|---|
+| Button, link, `role="button"` | `tap` (`soft` for `ghost` / `link` variants, `destructive` for the destructive variant) |
+| Tab, menu item, option, radio | `select` (pitch rises with position) |
+| Switch, checkbox | `toggleOn` / `toggleOff` |
+| Disabled control (when it still receives the press) | `blocked` |
+| Dialog / sheet / alert dialog opens or closes | `open` / `close` |
+| Slider value changes | `tick` |
+| OTP digit typed | `key` |
+| `ui.notify` toast | `success` / `error` / `warning` / `notification` by type |
+| `ui.clipboard` / code block copy | `copy` |
+
+Set `data-sound="<cue>"` on an element to override its cue, or `data-sound="none"` to silence it. Use `ui.sound.play(name)` to play a cue from server code, for example when a long job finishes. Cues: `tap`, `soft`, `select`, `destructive`, `blocked`, `toggleOn`, `toggleOff`, `open`, `close`, `tick`, `key`, `copy`, `success`, `error`, `warning`, `notification`.
+
+```ts
+// A settings switch that lets each user turn sounds on or off
+ui.switch({ label: 'Interface sounds', onChange: (on) => ui.sound.set(on) });
+```
+
 ## DuckDB (`@close-by/clay-duckdb`)
 
 See [DuckDB](./duckdb.md) for the multi-database wrapper (`connect`, `attach`, CRUD).

package/docs/demo-deployment.md

@@ -0,0 +1,64 @@
+# Demo deployment on Pi
+
+The demo runs at https://clay.close-by.org/ on Pi as the `bad-ui-demo` systemd service. It runs Bun as the `pi` user from `/home/pi/bad-ui-demo` on port 4000. The existing Flock Cloudflare tunnel forwards `clay.close-by.org` to `http://localhost:4000`; the Cloudflare DNS record is a proxied CNAME to that tunnel.
+
+## Update the demo
+
+From the repository root on a machine with SSH access to the `pi` host, copy the working tree and rebuild on Pi:
+
+```sh
+tar --exclude-vcs --exclude=node_modules --exclude=dist-pack \
+  --exclude=.env --exclude='.env.*' --exclude=.badui-user-data \
+  --exclude=.clay-user-data --exclude=.clay --exclude=.tmp \
+  -czf /tmp/clay-demo-deploy.tgz .
+scp /tmp/clay-demo-deploy.tgz pi:/tmp/clay-demo-deploy.tgz
+ssh pi 'tar -xzf /tmp/clay-demo-deploy.tgz -C ~/bad-ui-demo && \
+  cd ~/bad-ui-demo && export PATH="$HOME/.local/bin:$PATH" && \
+  bun install --frozen-lockfile && bun run build:client && \
+  sudo systemctl restart bad-ui-demo'
+```
+
+This copies the current working tree, including uncommitted changes. Extraction does not delete files removed from the source tree; remove obsolete deployed files deliberately when needed. The service keeps running the previous process until the restart, but the copy and build happen in its working directory.
+
+Check the service and public endpoint:
+
+```sh
+ssh pi 'systemctl status bad-ui-demo --no-pager; journalctl -u bad-ui-demo -n 50 --no-pager'
+curl -I https://clay.close-by.org/
+```
+
+## Service and tunnel setup
+
+The service is enabled with `sudo systemctl enable --now bad-ui-demo`. Its unit is `/etc/systemd/system/bad-ui-demo.service`:
+
+```ini
+[Unit]
+Description=Clay demo
+After=network.target
+
+[Service]
+User=pi
+WorkingDirectory=/home/pi/bad-ui-demo
+Environment=PORT=4000
+Environment=PATH=/home/pi/.local/bin:/usr/local/bin:/usr/bin:/bin
+EnvironmentFile=/home/pi/.config/bad-ui-demo/service.env
+ExecStart=/home/pi/.local/bin/bun apps/demo/src/main.ts
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The environment file contains `CLAY_AUTH_SECRET`; keep it private and stable across restarts. To create it on a fresh deployment, use `umask 077`, create `/home/pi/.config/bad-ui-demo`, and write `CLAY_AUTH_SECRET=` followed by a random secret (for example, from `openssl rand -hex 32`). Changing it invalidates existing signed sessions. After changing a unit, run `sudo systemctl daemon-reload` and restart the service.
+
+The tunnel configuration is `/etc/cloudflared/flock.yml`, managed by `flock-tunnel.service`. Its Clay ingress entry must precede the final catch-all:
+
+```yaml
+- hostname: clay.close-by.org
+  service: http://localhost:4000
+```
+
+Validate changes with `sudo cloudflared tunnel --config /etc/cloudflared/flock.yml ingress validate`, then restart `flock-tunnel`. This is shared with Flock, so preserve its existing ingress entries. The DNS CNAME must point to the existing tunnel's `<tunnel-id>.cfargotunnel.com` and be proxied; the tunnel credentials on Pi alone do not grant permission to edit Cloudflare DNS.
+
+This is a public demo with example authentication and data, not a hardened production application. See [Production & security](./production.md) before deploying real data or applications.

package/docs/elements.md

@@ -211,4 +211,6 @@ ui.label('Hello').classes('text-3xl font-bold text-muted-foreground');
 
 Layout `gap` uses a small numeric scale mapped to `gap-0` … `gap-8` in the client.
 
-The client ships a light ShadCN-style theme (CSS variables in `packages/client/src/index.css`). Override tokens at runtime with `ui.run({ css: './globals.css' })`.
+The client ships the "kiln" theme — warm neutrals, a fired-clay primary, vivid chart colours, light + dark (ShadCN-style CSS variables in `packages/client/src/index.css`, Plus Jakarta Sans bundled). Override tokens at runtime with `ui.run({ css: './globals.css' })`; Clay extras include `--clay-brand-from` / `--clay-brand-to` and the `clay-brand-gradient`, `clay-brand-text`, `clay-ambient` classes.
+
+Twelve more palettes ship alongside kiln — `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `neon`, plus the blues `sky`, `navy`, `indigo`, `denim`, `midnight` (each light + dark, in `packages/client/src/palettes.css`). Pick the app default with `ui.run({ palette: 'ocean' })` or switch per session with `ui.theme.palette('neon')`. Custom palettes: define `:root[data-palette="mine"] { … }` and `:root.dark[data-palette="mine"] { … }` in your `css` file, then `ui.theme.palette('mine')`.

package/docs/examples.md

@@ -5,11 +5,15 @@ Pages: [`apps/demo/src/examples/`](../apps/demo/src/examples/) (auto-loaded via
 
 After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http://localhost:4000.
 
+## Sidebar groups
+
+Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the home page's catalog share one structure: **Start here** (themes, fill layout, counter, todo, kitchen sink) → **Reactivity** → **Data** → **Maps** (gallery, delivery tracker, store locator, globe, uptime monitor) → **Forms & controls** → **Overlays & layout** → **Apps** → **Account** → **ReUI batches**. Order within a group is `pageMeta.order`.
+
 ## Catalog
 
 | Route | File | Patterns shown |
 |-------|------|----------------|
-| `/` | `Home.ts` | `ui.hero`, `ui.icon`, `ui.link`, `ui.navigate`; catalog via `ui.navFromPages()` (same as sidebar) |
+| `/` | `Home.ts` | Landing page: hero, live counter + source side by side (`ui.codeBlock`), feature grid, catalog grouped via `ui.navFromPages()` (same as sidebar) |
 | `/examples/counter` | `Counter.ts` | `setText`, `refreshable`, button variants |
 | `/examples/todo` | `Todo.ts` | `reactive`, `bindValue`, list `refreshable`, filters |
 | `/examples/chat` | `Chat.ts` | `ui.storage.app` (persisted messages + ephemeral presence), async `get`/`set` |
@@ -23,6 +27,8 @@ After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http:
 | `/examples/reui-batch-7` | `ReuiBatch7Demo.ts` | ReUI batch 7: `inputGroup`, `toggle`, `descriptionList`, `staticTable`, `aspectRatio`, `itemList`, `checkboxGroup` |
 | `/examples/charts` | `ChartDemo.ts` | `ui.chart.*`, `ui.sparkline`, composed/scatter charts |
 | `/examples/slider-demo` | `SliderDemo.ts` | Slider, checkbox, select + bindings |
+| `/examples/themes` | `ThemesDemo.ts` | Palette gallery: `ui.theme.palette`, light/dark, component preview |
+| `/examples/layout` | `LayoutDemo.ts` | Fill layout: `fillViewport`, `grow`, `scroll`, `ui.grid` |
 | `/examples/feedback` | `FeedbackDemo.ts` | Alerts, progress, timer, `ui.theme`, `ui.runJavaScript` / `ui.scroll` |
 | `/examples/form-demo` | `FormDemo.ts` | Form + validate + `ui.draft` + rating / colorPicker / tags |
 | `/examples/auth` | `Auth.ts` (+ login/admin/change-password) | Signed cookie session, hashed passwords, login lockout, role-gated admin + audit log |
@@ -38,6 +44,11 @@ After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http:
 | `/examples/gantt` | `GanttDemo.ts` | `ui.gantt` owned rows/dates/markers/deps, cross-row drag, header double-click markers, `itemMove` / `markerAdd` settle |
 | `/examples/flow` | `FlowDemo.ts` | Four `ui.flow` demos: ETL with in-node controls + labeled edges + dagre auto-layout, multi-handle approval branches, fan-in/out + `addNode` dynamic stages, group/`parentId` nesting (flow-owned edges/positions; no outer diagram `ui.auto`) |
 | `/examples/data-clients` | `DataClientsDemo.ts` | DuckDB / Kibana / ClickHouse integration story (mock-friendly) |
+| `/examples/maps` | `MapsGallery.ts` | `ui.map` gallery: markers and popups, routes, arcs, choropleth, clusters, compact analytics map |
+| `/examples/delivery-tracker` | `DeliveryTracker.ts` | `ui.map` route progress and courier marker: `updateRoute` / `upsertMarker` on a timer, `fill` layout |
+| `/examples/store-locator` | `StoreLocator.ts` | `ui.map` filtered markers, `flyTo` / `fitBounds('markers')`, popups; list and map select each other by key |
+| `/examples/globe` | `CommunityGlobe.ts` | `ui.map` globe projection, arcs, `setMarkers` / `setArcs` on a 30 s timer |
+| `/examples/uptime` | `UptimeMonitor.ts` | `ui.map` status markers on a globe, refreshed every 2 s with `setMarkers` |
 | `/examples/kitchen-sink` | `KitchenSink.ts` | ShadCN catalog preview (client `KitchenSink`) |
 
 Each page file exports optional `pageMeta` (`label`, `icon`, `order`, optional `nav: false`, optional `roles`) for `ui.navFromPages()`.

package/docs/maps.md

@@ -0,0 +1,214 @@
+# Maps
+
+`ui.map(props)` is a live map with markers, routes, arcs, GeoJSON layers, clusters, heatmaps and a popup. It renders with [MapLibre GL](https://maplibre.org/) through a vendored copy of [mapcn](https://mapcn.vercel.app) (MIT). You create the map on the server, change it with setters, and handle clicks on the server.
+
+- **Lazy.** The client loads the map code only when a page renders a map (`React.lazy` in the element renderer). Other pages do not download MapLibre.
+- **Worker bundled.** The MapLibre worker ships with the client build. No CDN script is loaded.
+
+## Quick start
+
+```typescript
+import { ui } from '@close-by/clay';
+
+ui.page('/fleet', () => {
+  const fleet = ui.map({
+    center: [-9.14, 38.72],
+    zoom: 11,
+    height: '28rem',
+    markers: [
+      { id: 'hq', lngLat: [-9.142, 38.7108], label: 'HQ', popup: { title: 'Head office' } },
+      { id: 'truck-1', lngLat: [-9.1393, 38.7097], tone: 'chart-2', icon: 'truck', pulse: true },
+    ],
+    onMarkerClick: (marker) => ui.notify(`Selected ${marker.id}`),
+  });
+
+  fleet.fitBounds('markers', { padding: 48 });
+});
+```
+
+Coordinates are always `[longitude, latitude]`.
+
+## Theming
+
+- **Light and dark.** The basemap follows the page theme. Markers, routes, arcs and fills take their colours from the active palette.
+- **Tones.** Colour props accept a tone name or a CSS colour such as `#2563eb`:
+
+  | Tone | Palette token |
+  |------|---------------|
+  | `primary` | `--primary` (default for markers, routes and fills) |
+  | `chart-1` … `chart-5` | `--chart-1` … `--chart-5` |
+  | `destructive` | `--destructive` |
+  | `muted` | `--muted-foreground` |
+  | `foreground` | `--foreground` |
+
+- **Live palette changes.** The map watches the root element's `class`, `data-palette` and `style`, and the system colour scheme. A palette change re-resolves the colours in place. The map is not remounted, so the camera and open popups stay put.
+- **`tint`** (default `true`) lightly tints the basemap toward the palette: background, water, and parks or green areas.
+- **`basemap`** (default `'auto'`) pins the basemap to `'light'` or `'dark'`, whatever the page theme.
+- **`styles`** replaces the basemap style URLs: `{ light?: string; dark?: string }`. See [Tiles](#tiles).
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `center` | `LngLat` | `[0, 20]` | Initial centre, read at mount. See [Camera](#camera) |
+| `zoom` | `number` | `1.5` | Initial zoom |
+| `pitch` / `bearing` | `number` | `0` | Initial pitch and bearing |
+| `projection` | `'mercator' \| 'globe'` | `'mercator'` | |
+| `height` | `string` | `'24rem'` | CSS length. Ignored with `fill` |
+| `fill` | `boolean` | `false` | Fill the parent. See [Layout](#layout) |
+| `interactive` | `boolean` | `true` | `false` disables pan, zoom and click |
+| `basemap` | `'auto' \| 'light' \| 'dark'` | `'auto'` | |
+| `styles` | `{ light?, dark? }` | CARTO styles | Custom MapLibre style URLs |
+| `tint` | `boolean` | `true` | Palette tint on the basemap |
+| `controls` | `MapControls \| false` | `{ zoom: true, position: 'bottom-right' }` | Object values merge over the default. `false` hides all controls |
+| `markers` | `MapMarkerDatum[]` | `[]` | |
+| `routes` | `MapRouteDatum[]` | `[]` | |
+| `arcs` | `MapArcGroup[]` | `[]` | |
+| `geojson` | `MapGeoJSONLayer[]` | `[]` | |
+| `clusters` | `MapClusterGroup[]` | `[]` | |
+| `heatmaps` | `MapHeatmapLayer[]` | `[]` | |
+| `popup` | `{ lngLat, title?, description? } \| null` | closed | Standalone popup |
+
+`MapControls` is `{ zoom?, compass?, locate?, fullscreen?, position? }`. `compass`, `locate` and `fullscreen` are off by default. `position` is `top-left`, `top-right`, `bottom-left` or `bottom-right`.
+
+## Data layers
+
+**Markers.** `id` (required, unique) and `lngLat` are required. Optional: `tone`, `label` (always visible), `tooltip` (on hover), `popup` (on click: `title`, `description`, `meta: [{ label, value }]`), `icon` (Lucide kebab-case name, drawn in a 28 px pin), `size` (`sm` / `md` / `lg` dots of 10 / 14 / 20 px, used when there is no icon), `pulse` (animated ring), `draggable`.
+
+**Routes.** `id` and `coordinates: [lng, lat][]` are required. Optional: `tone`, `width` (px), `opacity`, `dashed`, `progress` (0..1: draws a progress overlay and a marker there), `progressIcon` (default `navigation`), `progressMarker` (default `true`; set `false` when you track the vehicle with your own marker), `progressTone` (colour of the travelled part, default `primary`), `active` (emphasise the selected route), `showEndpoints` (start ring and end dot). Change one route with `updateRoute` (see [Live data](#live-data--in-place-updates)).
+
+**Arcs.** Grouped. A group has `id`, `tone`, `width`, `curvature` and `data: { id, from, to, label? }[]`. Arc ids are unique within their group.
+
+```typescript
+ui.map({
+  projection: 'globe',
+  arcs: [{ id: 'lanes', tone: 'chart-1', data: [{ id: 'lis-mad', from: [-9.14, 38.72], to: [-3.7, 40.42], label: 'Lisbon to Madrid' }] }],
+  onArcClick: (arc, group) => ui.notify(`${arc.label ?? arc.id} (${group.id})`),
+});
+```
+
+**GeoJSON.** `{ id, data, fillTone?, lineTone?, fillOpacity?, choropleth?, interactive?, promoteId? }`. `data` is a FeatureCollection, a Feature, or a URL string. A choropleth is `{ property, stops: [value, tone][] }`, with at least two stops. Without a choropleth the layer uses `fillTone`. The default fill opacity is `0.6` for a choropleth and `0.25` otherwise. The server does not validate GeoJSON.
+
+**Clusters.** Grouped points: `{ id, points: [{ id, lngLat, properties? }], tone?, clusterRadius?, clusterMaxZoom? }`. Cluster bubbles use the group tone, `chart-2` and `chart-3`.
+
+**Heatmaps.** `{ id, points: [{ lngLat, weight? }], ramp?, radius?, intensity?, opacity?, maxWeight?, showPointsAtZoom? }`. Weights default to `1` and must be finite and at least `0`. `maxWeight` is the weight that reaches full intensity; it defaults to the largest weight. The `ramp` runs from low to high density and defaults to `['chart-3', 'chart-4', 'primary', 'destructive']`, so it follows the palette and light or dark mode. `radius` (default `20` px at zoom 9) scales with zoom. Set `showPointsAtZoom` to fade the heatmap into individual circles when zoomed in. Replace the data with `setHeatmaps(layers)`; the client updates the source in place.
+
+```typescript
+const heat = ui.map({ projection: 'globe', heatmaps: [{ id: 'quakes', points, maxWeight: 7, showPointsAtZoom: 6 }] });
+heat.setHeatmaps([{ id: 'quakes', points: points.filter((p) => (p.weight ?? 0) >= 5) }]);
+```
+
+**Standalone popup.** `showPopup([lng, lat], { title?, description? })` opens one, and `closePopup()` closes it. The `popup` prop does the same declaratively. Only marker popups take `meta` rows.
+
+## Camera
+
+| Method | Behaviour |
+|--------|-----------|
+| `flyTo(center, zoom?, { duration? })` | Animates. Keeps the current zoom when `zoom` is omitted |
+| `fitBounds([sw, ne], { padding? })` | Fits the given bounds |
+| `fitBounds('markers', { padding? })` | Fits all current markers. Does nothing when there are none |
+| `jumpTo(center, zoom?)` | Moves without animation |
+| `setProjection('mercator' \| 'globe')` | Sends a new `projection` |
+
+Each camera call runs once on the client. The server attaches a nonce, so repeating a call moves the map again.
+
+The client reads `center`, `zoom`, `pitch`, `bearing` and `interactive` once, at mount. Changing those props later does not move an existing map. Use the camera methods instead.
+
+## Events
+
+Handlers are registered only when you pass them. Each handler runs on the server, and receives:
+
+| Handler | Fires when | Argument |
+|---------|------------|----------|
+| `onMarkerClick(marker)` | A marker is clicked | The current marker datum |
+| `onMarkerDragEnd(marker, lngLat)` | A draggable marker is dropped | The updated marker and its new `lngLat`. The stored position is updated first |
+| `onRouteClick(route)` | A route is clicked | The current route datum |
+| `onArcClick(arc, group)` | An arc is clicked | The arc and its group |
+| `onFeatureClick(feature)` | A GeoJSON feature is clicked | `{ layerId, featureId?, properties }` |
+| `onClusterPointClick(point, group)` | A clustered point is clicked | The point and its group |
+| `onMapClick(lngLat)` | The map is clicked | `[lng, lat]` |
+| `onViewportChange(viewport)` | The camera stops moving (`moveend`) | `{ center, zoom, bearing, pitch }` |
+| `onLocate(lngLat)` | The locate control is used (needs `controls.locate`) | `[lng, lat]` |
+
+
+`markerDragEnd` is always recorded on the server, even without `onMarkerDragEnd`, so a later `fitBounds('markers')` uses the dropped position.
+
+## Live data & in-place updates
+
+The map owns its marker, route, arc, cluster and popup state. Each setter sends only the prop it changes, so the client patches the map instead of rebuilding it. Markers are keyed by `id`: when a marker's `lngLat` changes, it moves, and its DOM node stays.
+
+| Method | What it does |
+|--------|--------------|
+| `setMarkers(list)` | Replaces all markers |
+| `upsertMarker(marker)` | Inserts, or replaces the marker with the same id |
+| `removeMarker(id)` | Removes a marker. No-op if absent |
+| `setRoutes(list)` / `updateRoute(id, patch)` | Replaces all routes, or merges `patch` into one. The id cannot change |
+| `setArcs(groups)` / `setGeoJSON(layers)` / `setClusters(groups)` / `setHeatmaps(layers)` | Replace that layer type |
+
+A courier moving along a route:
+
+```typescript
+ui.timer(0.25, () => {
+  progress = Math.min(1, progress + 0.006);
+  map.updateRoute('delivery-route', { progress });
+  map.upsertMarker({ id: 'courier', lngLat: pointAt(progress), tone: 'chart-2', icon: 'truck' });
+});
+```
+
+**Validation** runs when you create the map or call a setter, before anything is sent. It throws on:
+
+- a missing or empty id, or a duplicate id within its list (markers, routes, arc groups, arcs in a group, cluster groups, points in a group). The message is `duplicate id "…"`.
+- a coordinate that is not `[lng, lat]` with two finite numbers. This covers markers, cluster points, route coordinates, arc endpoints, popups, `flyTo` and `jumpTo` centres, and `fitBounds` corners.
+
+## Layout
+
+`height` gives a fixed-size map in normal flow:
+
+```typescript
+ui.card({ title: 'Stores', className: 'p-0 overflow-hidden' }, () => {
+  ui.map({ height: '26rem', center: [-6, 40], zoom: 5 });
+});
+```
+
+`fill: true` makes the map fill its parent (`h-full min-h-0 flex-1`), so the parent needs a definite height. On a page that fills the window, put `fillViewport` on the outer column and `grow` on the panel that holds the map:
+
+```typescript
+ui.column({ fillViewport: true, gap: 4 }, () => {
+  ui.row({ grow: true, wrap: false, gap: 4 }, () => {
+    ui.card({ title: 'Stores', scroll: true, className: 'w-80 shrink-0' }, () => { /* list */ });
+    ui.column({ grow: true }, () => {
+      ui.map({ fill: true, center: [-6, 40], zoom: 5 });
+    });
+  });
+});
+```
+
+See [API reference: Filling the page](./api.md#filling-the-page).
+
+## Tiles
+
+By default the basemap uses CARTO's hosted styles: Positron for light and Dark Matter for dark, served from `basemaps.cartocdn.com`. Those styles are built on OpenStreetMap data. CARTO's free tier and terms apply, and OpenStreetMap data requires attribution.
+
+Before production, check CARTO's current terms and attribution rules, or pass your own styles. Any MapLibre style URL works:
+
+```typescript
+ui.map({ styles: { light: 'https://your-host.example/light.json', dark: 'https://your-host.example/dark.json' } });
+```
+
+[OpenFreeMap](https://openfreemap.org) publishes free style URLs. Check its terms before you rely on it.
+
+## Demos
+
+All five are under the **Maps** group in the sidebar.
+
+- [`/examples/maps`](../apps/demo/src/examples/MapsGallery.ts): markers and popups, routes, arcs, a choropleth, clusters, a seismic heatmap on a globe, and a compact analytics map.
+- [`/examples/delivery-tracker`](../apps/demo/src/examples/DeliveryTracker.ts): a courier moving along a route, with `updateRoute` and `upsertMarker` on a timer.
+- [`/examples/store-locator`](../apps/demo/src/examples/StoreLocator.ts): a filterable store list where list rows and markers select each other.
+- [`/examples/globe`](../apps/demo/src/examples/CommunityGlobe.ts): a globe with arcs and markers that refresh every 30 seconds.
+- [`/examples/uptime`](../apps/demo/src/examples/UptimeMonitor.ts): a status globe of edge locations, refreshed every 2 seconds.
+
+## See also
+
+- [Updating in place](./updating-in-place.md): the general rules for patching instead of rebuilding
+- [API reference](./api.md#uimapprops): `ui.map` in the Layout section
+- [Examples](./examples.md): the demo catalog

package/docs/protocol.md

@@ -19,7 +19,7 @@ On unexpected socket close, the client reconnects with exponential backoff (500m
 { "op": "hello", "path": "/examples/counter", "userId": "optional-stable-id", "hash": "optional-hash-without-hash-sign", "browserStorage": {}, "clientStorage": {}, "tabStorage": {} }
 ```
 
-Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `search` (no leading `?`) hydrates `ui.getUrlSearch()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
+Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `search` (no leading `?`) hydrates `ui.getUrlSearch()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`. Optional `palette` reports the palette the page shows, so `ui.theme.getPalette()` is correct after a reload.
 
 Sent on connect and after client-side navigation. The React client keeps matching `app` shell chrome mounted across remounts; only inset content is replaced.
 
@@ -199,6 +199,18 @@ Client runs `window.open(url, '_blank', 'noopener,noreferrer')`. Prefer `ui.open
 
 Sent by `ui.theme.set(...)`.
 
+### `palette`
+
+```json
+{ "op": "palette", "palette": "ocean" }
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `palette` | `string` | Sets `<html data-palette>` (`kiln` / empty clears to default); persisted under `clay-palette` and restored before first paint |
+
+Sent by `ui.theme.palette(...)`.
+
 ### `runJavaScript`
 
 ```json

package/docs/updating-in-place.md

@@ -0,0 +1,124 @@
+# Updating in place (no flicker)
+
+Clay sends every change over one WebSocket as patches. How your server code changes the element tree decides which patches go out, and therefore what the user sees.
+
+New data should patch what is on screen, not rebuild it.
+
+## The rule
+
+There are two ways to show a new value:
+
+- **Rebuild.** You create new `ui.*` elements for the section (a new table, a new row of cards, a new list). Each new element gets a fresh id. The client receives a `setChildren` with those new ids and mounts new DOM. The old DOM is removed. Whatever lived in it is gone: scroll position, focus, what the user typed in an input, the selected row, and any enter animation runs again. The user sees a blank or jumping section.
+- **Patch.** You keep the element you already have and change one prop on it, for example `label.setText(...)`. The client receives a single `updateProps` for that id, such as `{"op":"updateProps","id":"…","props":{"text":"42"}}`. The DOM node stays the same, so nothing else on the screen moves.
+
+The flicker is caused by the remount, not by the new value. If a frame carries only the changed prop, the browser has nothing to redraw except that text.
+
+## Pick the right tool
+
+| Situation | API | What goes out |
+|-----------|-----|---------------|
+| Change one value (a label, badge, or input) | `label.setText(…)`, `el.setValue(…)`, `el.update({ … })` | `updateProps` for that element |
+| Live table data | `table.setRows(rows)` on a table created with a stable `keyField` (add `highlightChanges: true` to flash changed rows) | `updateProps` on the table; rows keyed by `keyField` keep their DOM |
+| Table refetch | `table.setLoading(true)` / `table.withLoading(fn)` | `updateProps` (`loading`); previous rows stay, dimmed, instead of blanking |
+| A section whose structure depends on data | `ui.refreshable(() => …)` + `.refresh()`, or `ui.auto(() => …)` | Reconciled: matched children get `updateProps` only; added, removed, or reordered children cause one `setChildren` per affected parent |
+| Items in a list inside either of the above | `.key(item.id)` on each item | Items keep their identity through reorder, filter, and prepend |
+
+Use the first row whenever the shape of the screen does not change. Reach for `refreshable` or `auto` only when children really are added, removed, or reordered.
+
+## How reconciliation matches
+
+When a `refreshable` or `auto` block re-runs, Clay builds a fresh tree and matches it against the children already on screen:
+
+1. **Keyed first.** A new child with `.key(k)` matches the old child with the same key and the same element type. Keyed children are matched only by key.
+2. **Unkeyed by position.** Unkeyed children are matched in order, by element type. If the next old child matches the current new one, the current old child was removed and is skipped. If the current old child matches the next new one, the new child was inserted. Otherwise the pair is treated as a replacement at that position. This lookahead covers a single insert or remove; larger reshuffles should be keyed.
+3. **Matched pairs keep the old element and its id.** The fresh element's handlers and props are copied onto the old one. Only props that actually changed are sent, as one `updateProps`.
+4. **Leftovers.** Old children with no match are destroyed. New children with no match are mounted. The parent sends one `setChildren` only if its list of ids changed. A child whose type changed at a position is replaced; its siblings keep their ids.
+5. **Nested blocks keep their instance.** A nested `refreshable` or `auto` keeps its id and its subscriptions and adopts the new builder, so its own refreshes keep working.
+
+## Examples
+
+### Live orders list (`ui.auto` with keys)
+
+```ts
+import { ui } from '@close-by/clay';
+
+type Order = { id: string; customer: string; status: string; total: number };
+const orders = ui.state({ list: [] as Order[], filter: '' });
+
+ui.auto(() => {
+  const shown = orders.list.filter((o) => o.status.includes(orders.filter));
+  for (const o of shown) {
+    ui.row(() => {
+      ui.label(o.customer);
+      ui.badge(o.status, { size: 'xs' });
+      ui.label(`$${o.total}`);
+    }).key(o.id);
+  }
+});
+
+// From your feed handler. Replacing the array re-runs the block once.
+// Each order keeps its element because its key is unchanged, so a
+// status change is an updateProps on that row's badge.
+orders.list = nextSnapshot;
+```
+
+Keys must be stable. Use the order id, not the array index or a timestamp.
+
+### Dashboard KPI row (`setText`)
+
+```ts
+let revenue: ReturnType<typeof ui.label>;
+let openCount: ReturnType<typeof ui.label>;
+
+ui.row(() => {
+  revenue = ui.label('$0').classes('text-2xl', 'font-semibold');
+  openCount = ui.label('0').classes('text-2xl', 'font-semibold');
+});
+
+// Called whenever new metrics arrive. Two updateProps frames, no rebuild.
+function onMetrics(m: { revenue: number; open: number }) {
+  revenue.setText(`$${m.revenue.toLocaleString()}`);
+  openCount.setText(String(m.open));
+}
+```
+
+### Live table (`setRows` + `highlightChanges` + `setLoading`)
+
+```ts
+const table = ui.dataTable([], {
+  keyField: 'id',
+  highlightChanges: true,
+  searchable: true,
+});
+
+// fetchOrders() is your own data call.
+async function refresh() {
+  await table.withLoading(async () => {
+    table.setRows(await fetchOrders());
+  });
+}
+```
+
+`withLoading` sets loading before `fn` runs and clears it afterwards, so the previous rows stay on screen under a dimmed body until `setRows` runs. Rows whose `id` did not change keep their DOM, and changed or new rows flash.
+
+If you want columns to stay fixed across refreshes, pass `columns` explicitly. Otherwise columns are inferred again on each `setRows`.
+
+## Anti-patterns
+
+- **Rebuilding a whole section when one value changes.** Wrapping a whole page in `ui.refreshable` and calling `.refresh()` every second to update a clock. Keep a reference to the clock label and call `setText`.
+- **Unkeyed lists that get sorted or filtered.** Without `.key()`, position is the identity. After a sort, the element in slot 3 is reused for whatever item is now third, so focus and typed text stay in the slot instead of following the row.
+- **Creating a new table instead of `setRows`.** A `ui.dataTable(...)` created inside a refreshable on every tick remounts the table and loses sort, scroll, selection, and search. Create the table once and call `setRows`.
+- **Tables without `keyField`.** Rows are stamped `__rowId` by their index, so inserting or re-sorting the source shifts every row's identity. Set `keyField` to your primary key.
+- **Toggling a constructor option by rebuilding.** Recreating a table with `zebra: on` inside an `auto` block. Use the setters instead: `setZebra`, `setDensity`, `setHighlightChanges`.
+
+## Checking it works
+
+1. **Devtools, DOM node.** Open the browser Elements panel and select a row, label, or input. Trigger an update (wait for the next feed tick or change the filter). The same node should still be selected and highlighted. For an input, click into it, let an update arrive, and confirm the caret stays. If the node is replaced, the block was rebuilt.
+2. **Devtools, WebSocket frames.** Open the Network panel, filter to WS, select the connection, and watch the frames as data arrives. A value change should show `updateProps` with a small payload for one id. `setChildren` should appear only when rows are added, removed, or reordered. If an unchanged list sends `setChildren` on every tick, the child ids are changing: check that `.key()` values are stable and that the block is not creating new parent elements on each run.
+
+## See also
+
+- [Concepts: Updates](./concepts.md#updates-settext-vs-refreshable) for the basic `setText` vs `refreshable` split
+- [API reference](./api.md) for `ui.refreshable`, `ui.auto`, `ui.dataTable`, and `Element` methods
+- [Reactive `let`](./reactive-let.md) for the compile-time alternative to hand-written `ui.auto`
+- [WebSocket protocol](./protocol.md) for the patch message formats

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -37,10 +37,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.17",
-    "@close-by/clay-core": "0.2.17",
-    "@close-by/clay-components": "0.2.17",
-    "@close-by/clay-server": "0.2.17",
+    "@close-by/clay-compiler": "0.2.19",
+    "@close-by/clay-core": "0.2.19",
+    "@close-by/clay-components": "0.2.19",
+    "@close-by/clay-server": "0.2.19",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -66,6 +66,7 @@ import {
   column as columnFactory,
   container as containerFactory,
   hero as heroFactory,
+  grid as gridFactory,
   card as cardFactory,
   dialog as dialogFactory,
   dialogStack as dialogStackFactory,
@@ -112,6 +113,9 @@ import {
   list as listFactory,
   imageCrop as imageCropFactory,
   gantt as ganttFactory,
+  map as mapFactory,
+  type MapElement,
+  type MapProps,
   chart as chartNamespace,
   table as tableFactory,
   flow as flowFactory,
@@ -242,6 +246,8 @@ import {
   type LineChartStyleProps,
   type SparklineProps,
   type CardProps,
+  type GridProps,
+  type LayoutProps,
   type DialogProps,
   type DialogStackProps,
   type DialogStackStepOptions,
@@ -343,6 +349,14 @@ import {
   type GanttDependency,
   type GanttRange,
   type GanttItemMovePayload,
+  type MapMarkerDatum,
+  type MapRouteDatum,
+  type MapArcGroup,
+  type MapGeoJSONLayer,
+  type MapClusterGroup,
+  type MapHeatmapLayer,
+  type LngLat,
+  type MapTone,
   type FlowProps,
   type FlowNodeProps,
   type FlowNodeKind,
@@ -452,6 +466,7 @@ import {
   timer as timerCore,
   storage as storageCore,
   theme as themeCore,
+  sound as soundCore,
   reactive as reactiveCore,
   state as stateCore,
   subscribe as subscribeCore,
@@ -471,6 +486,7 @@ import {
   TimerHandle,
   type TimerOptions,
   type ThemeMode,
+  type ThemePalette,
   type DraftStorage,
   type DraftOptions,
   type UrlStateOptions,
@@ -512,6 +528,8 @@ export {
 
 
 export type {
+  GridProps,
+  LayoutProps,
   ButtonProps,
   IconButtonProps,
   ButtonVariant,
@@ -636,6 +654,15 @@ export type {
   GanttDependency,
   GanttRange,
   GanttItemMovePayload,
+  MapProps,
+  MapMarkerDatum,
+  MapRouteDatum,
+  MapArcGroup,
+  MapGeoJSONLayer,
+  MapClusterGroup,
+  MapHeatmapLayer,
+  LngLat,
+  MapTone,
   FlowProps,
   FlowNodeProps,
   FlowNodeKind,
@@ -698,6 +725,7 @@ export type {
   NotifyType,
   ToastPosition,
   ThemeMode,
+  ThemePalette,
   PageMeta,
   NavFromPagesOptions,
   PageOptions,
@@ -1173,6 +1201,15 @@ export function gantt(props?: GanttProps): GanttElement {
   return ganttFactory(props);
 }
 
+/**
+ * Live map (MapLibre, styled to the Clay theme) with markers, routes, arcs,
+ * GeoJSON layers, clusters and a popup. Owns its marker / route / popup /
+ * camera state; setters update in place. See {@link MapProps}.
+ */
+export function map(props?: MapProps): MapElement {
+  return mapFactory(props);
+}
+
 /**
  * Interactive flow diagram (`@xyflow/react`). Owns edges + positions;
  * node bodies are Clay trees; drag by card chrome (controls are nodrag);
@@ -1255,33 +1292,43 @@ export function sparkline(props: SparklineProps): Element {
 }
 
 /** Horizontal flex row (`fn` or props-first). Prefer `ui.row`. */
-export function row(fn: () => void, props?: Parameters<typeof rowFactory>[1]): Element;
-export function row(props: Parameters<typeof rowFactory>[0], fn: () => void): Element;
+export function row(fn: () => void, props?: LayoutProps): Element;
+export function row(props: LayoutProps, fn: () => void): Element;
 export function row(a: any, b?: any): Element {
   return rowFactory(a, b);
 }
 
 /** Vertical flex column (`fn` or props-first). Prefer `ui.column`. */
-export function column(fn: () => void, props?: Parameters<typeof columnFactory>[1]): Element;
-export function column(props: Parameters<typeof columnFactory>[0], fn: () => void): Element;
+export function column(fn: () => void, props?: LayoutProps): Element;
+export function column(props: LayoutProps, fn: () => void): Element;
 export function column(a: any, b?: any): Element {
   return columnFactory(a, b);
 }
 
 /** Layout container (`fn` or props-first). Prefer `ui.container`. */
-export function container(fn: () => void, props?: Parameters<typeof containerFactory>[1]): Element;
-export function container(props: Parameters<typeof containerFactory>[0], fn: () => void): Element;
+export function container(fn: () => void, props?: LayoutProps): Element;
+export function container(props: LayoutProps, fn: () => void): Element;
 export function container(a: any, b?: any): Element {
   return containerFactory(a, b);
 }
 
 /** Hero section (`fn` or props-first). Prefer `ui.hero`. */
-export function hero(fn: () => void, props?: Parameters<typeof heroFactory>[1]): Element;
-export function hero(props: Parameters<typeof heroFactory>[0], fn: () => void): Element;
+export function hero(fn: () => void, props?: LayoutProps): Element;
+export function hero(props: LayoutProps, fn: () => void): Element;
 export function hero(a: any, b?: any): Element {
   return heroFactory(a, b);
 }
 
+/**
+ * Responsive grid that fills the width (`fn` or props-first). Prefer `ui.grid`.
+ * `minColWidth` auto-fits columns (default 16rem); `cols` fixes the count. See {@link GridProps}.
+ */
+export function grid(fn: () => void, props?: GridProps): Element;
+export function grid(props: GridProps, fn: () => void): Element;
+export function grid(a: any, b?: any): Element {
+  return gridFactory(a, b);
+}
+
 /** Card with optional header/footer (`fn` or props-first). Prefer `ui.card`. See {@link CardProps}. */
 export function card(fn: (card: Element) => void, props?: CardProps): Element;
 export function card(props: CardProps, fn: (card: Element) => void): Element;
@@ -1660,6 +1707,9 @@ export const storage = storageCore;
 /** Server-driven appearance (`light` | `dark` | `system`). */
 export const theme = themeCore;
 
+/** Interface sound cues: `ui.sound.set(on)`, `ui.sound.volume(0..1)`, `ui.sound.play(name)`. */
+export const sound = soundCore;
+
 /** Proxy that notifies subscribers on property change. Prefer this over importing from `@close-by/clay-core`. */
 export const reactive = reactiveCore;
 
@@ -1907,6 +1957,7 @@ export const ui = {
   list,
   imageCrop,
   gantt,
+  map,
   flow,
   stat,
   dataTable,
@@ -1925,6 +1976,7 @@ export const ui = {
   row,
   column,
   container,
+  grid,
   hero,
   card,
   app,
@@ -1973,6 +2025,7 @@ export const ui = {
   timer,
   storage,
   theme,
+  sound,
   reactive,
   state,
   urlState,