@close-by/clay 0.2.16 → 0.2.18

package/docs/README.md

@@ -15,6 +15,7 @@ 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 |

package/docs/api.md

@@ -1801,6 +1801,9 @@ 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.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,6 +1914,7 @@ 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 |
@@ -1965,8 +1969,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(() => {

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** → **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 |

package/docs/ops-patterns.md

@@ -220,6 +220,28 @@ Still redact before display when possible. Prefer VPN + auth for hubs that surfa
 Nav filtering is UX only — always enforce roles in the page builder.
 
 ```ts
+import { ui } from '@close-by/clay';
+import { getCurrentSession } from '@close-by/clay-core';
+import { resolveUserIdFromAuthCookie } from '@close-by/clay-server';
+import { createAuthGuards } from '@close-by/clay-auth';
+
+type User = { role: 'admin' | 'member' };
+const userById = new Map<string, User>(); // Your app's user store, keyed by user ID.
+const authSecret = process.env.CLAY_AUTH_SECRET!;
+const anonymousUserId = '__clay_anonymous__';
+const resolveSignedUserId = resolveUserIdFromAuthCookie(authSecret);
+
+function getSessionUser(): User | null {
+  const userId = getCurrentSession()?.userId;
+  if (!userId || userId === anonymousUserId) return null;
+  return userById.get(userId) ?? null;
+}
+
+const { requireRole } = createAuthGuards({
+  getUser: getSessionUser,
+  onUnauthenticated: () => ui.navigate('/login'),
+});
+
 // pageMeta
 export const pageMeta = {
   label: 'Admin',
@@ -230,20 +252,26 @@ export const pageMeta = {
 
 // shell
 ui.run({
-  authSecret: process.env.CLAY_AUTH_SECRET!,
+  authSecret,
+  resolveUserId: (context) => resolveSignedUserId(context) ?? anonymousUserId,
   app: {
     title: 'Hub',
-    nav: () => ui.navFromPages({ role: currentUser.role }),
+    get nav() {
+      const user = getSessionUser();
+      return ui.navFromPages(user ? { role: user.role } : {});
+    },
   },
 });
 
 // page
 ui.page('/admin', () => {
-  requireRole('admin'); // @close-by/clay-auth
+  if (!requireRole('admin')) return;
   // …
 });
 ```
 
+`get nav()` is evaluated while each page shell is built, so it filters routes for the current session. Reserve `__clay_anonymous__` outside `userById`: the resolver substitutes it for missing or invalid cookies, and `getSessionUser` treats it as signed out. Replace `userById` with your app's user store.
+
 See `/examples/auth` and [API — auth](./api.md).
 
 ## `ui.ai.chat` and state

package/docs/production.md

@@ -18,22 +18,47 @@ Clay ships hooks for real identity beyond anonymous `userId`:
 
 ```ts
 import { ui } from '@close-by/clay';
-import { requireRole } from '@close-by/clay-auth';
+import { getCurrentSession } from '@close-by/clay-core';
+import { resolveUserIdFromAuthCookie } from '@close-by/clay-server';
+import { createAuthGuards } from '@close-by/clay-auth';
+
+type User = { role: 'admin' | 'member' };
+const userById = new Map<string, User>(); // Your app's user store, keyed by user ID.
+const authSecret = process.env.CLAY_AUTH_SECRET!;
+const anonymousUserId = '__clay_anonymous__';
+const resolveSignedUserId = resolveUserIdFromAuthCookie(authSecret);
+
+function getSessionUser(): User | null {
+  const userId = getCurrentSession()?.userId;
+  if (!userId || userId === anonymousUserId) return null;
+  return userById.get(userId) ?? null;
+}
+
+const { requireRole } = createAuthGuards({
+  getUser: getSessionUser,
+  onUnauthenticated: () => ui.navigate('/login'),
+});
 
 ui.run({
-  authSecret: process.env.CLAY_AUTH_SECRET!,
+  authSecret,
+  resolveUserId: (context) => resolveSignedUserId(context) ?? anonymousUserId,
   app: {
     title: 'Hub',
-    nav: () => ui.navFromPages({ role: currentUser.role }),
+    get nav() {
+      const user = getSessionUser();
+      return ui.navFromPages(user ? { role: user.role } : {});
+    },
   },
 });
 
 ui.page('/admin', () => {
-  requireRole('admin');
+  if (!requireRole('admin')) return;
   // …
 });
 ```
 
+`get nav()` is evaluated while each page shell is built, so it filters routes for the current session. Reserve `__clay_anonymous__` outside `userById`: the resolver substitutes it for missing or invalid cookies, and `getSessionUser` treats it as signed out. Replace `userById` with your app's user store.
+
 - `pageMeta.roles` — hide nav items via `ui.navFromPages({ role })` (UX only)
 - `requireRole` / guards in the page builder — **enforce** access before building sensitive UI
 - See [API — auth](./api.md), `/examples/auth`, and [Ops patterns — auth nav](./ops-patterns.md#auth--role-filtered-nav)

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.16",
+  "version": "0.2.18",
   "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.16",
-    "@close-by/clay-core": "0.2.16",
-    "@close-by/clay-components": "0.2.16",
-    "@close-by/clay-server": "0.2.16",
+    "@close-by/clay-compiler": "0.2.18",
+    "@close-by/clay-core": "0.2.18",
+    "@close-by/clay-components": "0.2.18",
+    "@close-by/clay-server": "0.2.18",
     "@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,
@@ -242,6 +243,8 @@ import {
   type LineChartStyleProps,
   type SparklineProps,
   type CardProps,
+  type GridProps,
+  type LayoutProps,
   type DialogProps,
   type DialogStackProps,
   type DialogStackStepOptions,
@@ -471,6 +474,7 @@ import {
   TimerHandle,
   type TimerOptions,
   type ThemeMode,
+  type ThemePalette,
   type DraftStorage,
   type DraftOptions,
   type UrlStateOptions,
@@ -512,6 +516,8 @@ export {
 
 
 export type {
+  GridProps,
+  LayoutProps,
   ButtonProps,
   IconButtonProps,
   ButtonVariant,
@@ -698,6 +704,7 @@ export type {
   NotifyType,
   ToastPosition,
   ThemeMode,
+  ThemePalette,
   PageMeta,
   NavFromPagesOptions,
   PageOptions,
@@ -1255,33 +1262,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;
@@ -1925,6 +1942,7 @@ export const ui = {
   row,
   column,
   container,
+  grid,
   hero,
   card,
   app,