@close-by/clay 0.2.23 → 0.2.25

package/docs/README.md

@@ -11,6 +11,7 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | Doc | Description |
 |-----|-------------|
 | [Getting started](./getting-started.md) | Install, `clay` CLI, create a page |
+| [Mobile and installable apps](./mobile.md) | Phone tab bar (`mobileNav`), installable app (`pwa`, `--pwa`) |
 | [Boot: CLI vs library](./boot.md) | Production `ui.run` path, `clientDir`, `_run.ts`, reload stubs |
 | [Tailwind](./tailwind.md) | Zero-config utilities from page modules; optional tokens |
 | [Sample app](./tutorial.md) | Step-by-step tasks list, then two pages + shell |
@@ -24,6 +25,7 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 | [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 |
+| [Compatibility](./compatibility.md) | Public API promise, aliases, and compatibility checks |
 | [Architecture](./architecture.md) | Packages, data flow, and ownership |
 | [Examples](./examples.md) | Demo apps and patterns |
 | [Reactive `let`](./reactive-let.md) | NiceGUI-style `let` transform (opt-in `--reactive-let`) |

package/docs/api.md

@@ -93,12 +93,14 @@ ui.run({
 | `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 |
+| `pwa` | `boolean \| ClayPwaConfig` | | Installable app: web manifest, icons, and a service worker that caches the app shell. See [Mobile and installable apps](./mobile.md#installable-app-pwa) |
 | `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 |
 | `sessionIdleMs` | `number` | | Optional: clear auth + redirect after this idle time |
 | `sessionAbsoluteMs` | `number` | | Optional: clear auth + redirect after this time since hello |
 | `sessionExpiredPath` | `string` | `'/'` | SPA path after idle/absolute expiry |
 | `resolveUserId` | `(ctx) => …` | cookie helper when `authSecret` set | Trusted identity on WebSocket hello |
+| `getRoles` | `() => string \| string[] \| null` | | Current user's roles. Enables `ui.forRoles`, `ui.hasRole`, `.roles()`, and default filtering in `ui.navFromPages()` / `requireRole` — see [Production — role-based content](./production.md#role-based-content) |
 | `routes` | `Record<path, (req, ctx) => Response>` | | Extra HTTP routes, exact path, any method. `ctx.signIn(userId, location)` / `ctx.signOut(location)` redirect and set/clear the auth cookie. Used for OAuth callbacks — see [Production — single sign-on](./production.md#single-sign-on-oidc) |
 
 #### Auth cookie recipe
@@ -1816,10 +1818,12 @@ onClick: async () => {
 | `ui.updateUrlSearch(patch, opts?)` | `void` | Merge query keys; `null`/`''` deletes |
 | `ui.urlState(defaults, opts?)` | reactive object | `ui.state` + hydrate/sync query string (prefer this) |
 | `ui.openExternal(url)` | `void` | `window.open` in a new tab (`noopener`) |
+| `ui.forRoles(roles, build, fallback?)` | `void` | Run `build` only for users with one of `roles`, else `fallback`; skipped content never reaches the browser |
+| `ui.hasRole(roles)` | `boolean` | Current user has one of `roles` |
 | `ui.redirect(url)` | `void` | Full-page navigation in the current tab (`location.assign`) — for sign-in routes / external pages; use `ui.navigate` for app pages |
 | `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.palette(name)` | `void` | Switch colour palette for this client (`kiln`, `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `chalk`, `brutal`, `terminal`, `editorial`, `bubble`, `soothe`, `nebula`, `studio`, `iris`, `ledger`, `contrast`, `dim`, `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) |
@@ -1957,6 +1961,7 @@ Sidebar layout for multi-page apps. Prefer `ui.run({ app })` so every page inher
 | `user` | `AppUser` | Optional user menu (`name`, `email`, `avatar?`) |
 | `variant` | `'sidebar' \| 'inset'` | Shell layout variant |
 | `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | Sidebar collapse behavior |
+| `mobileNav` | `'tabs' \| 'menu'` | Phone navigation. Default `'tabs'` (bottom tab bar); `'menu'` keeps only the sidebar sheet. See [Mobile](./mobile.md#keep-only-the-menu) |
 | `className` | `string` | Extra classes on the shell |
 
 `AppNavItem`: `{ label, href, icon?, description?, items? }` — `icon` is a Lucide kebab-case name (full set; e.g. `home`, `gauge`, `sparkles`). Nested `items` render as collapsible sub-links in the sidebar.
@@ -2057,6 +2062,7 @@ Returned by every `ui.*` factory.
 | Method | Description |
 |--------|-------------|
 | `.classes(...names)` | Append Tailwind/utility classes; patches `className` |
+| `.roles(list)` | Keep only for users with one of the roles (`ui.run({ getRoles })`); otherwise removed before it reaches the client. Call while building |
 | `.style(string \| Record)` | Set inline style string / object |
 | `.on(event, handler)` | Register additional event handler |
 | `.setText(text)` | Set `props.text` and patch |
@@ -2110,7 +2116,7 @@ form.name = 'Ada'; // persisted
 ui.draft.clear('formDemo'); // drop storage key; reset the object yourself if needed
 ```
 
-See Form Demo (`/examples/form-demo`).
+See Forms (`/examples/forms`).
 
 ### `ui.auto(fn)`
 

package/docs/compatibility.md

@@ -0,0 +1,79 @@
+# Compatibility
+
+An app written for a Clay release keeps working on later releases unchanged.
+If an app breaks after a Clay update, that is a bug in Clay unless the release
+notes list the change under **Breaking**.
+
+## What this covers
+
+The promise covers the public surface apps use:
+
+- `ui.*` functions and namespaces, including `ui.ai`, `ui.storage`, and `ui.theme`.
+- Element methods such as `setText`, `classes`, and `bindValue`.
+- Package exports, including exports moved to another module.
+- Factory option names and element prop names.
+- Event names and their payloads.
+- Element wire types and protocol operations.
+- CLI flags, defaults, and behavior.
+
+The client and server ship together, but the wire format still matters.
+Apps use `ui.runJavaScript` and custom clients, and old browser tabs reconnect
+to new servers. Updating the server must account for those callers too.
+
+## Rules for changes
+
+1. What a release shipped stays available in later releases, unless its removal
+   is explicitly listed under Breaking in the release notes.
+2. A rename keeps the old name as an alias of the same implementation.
+   Mark the old name with JSDoc `@deprecated Use newName.` so editors can guide
+   callers to the replacement. Moving an export keeps it in the old module too.
+3. Types only widen: options gain optional members, unions gain cases, and
+   functions gain optional trailing parameters or overloads. Apps should handle
+   values they do not know, for example with a default branch in a switch.
+4. Behavior does not change silently. Defaults, units, payload shapes, and
+   callback order are part of the contract even when the names stay the same.
+
+For example, a renamed helper keeps a direct alias:
+
+```typescript
+export function newName(text: string) {
+  return ui.label(text);
+}
+
+/** @deprecated Use newName. */
+export const oldName = newName;
+```
+
+## How we check it
+
+[compat/surface.json](../compat/surface.json) records the public names.
+[packages/ui/src/compat.test.ts](../packages/ui/src/compat.test.ts) compares that
+record with the current source as part of `bun run test`.
+Missing names fail the test; new names also fail until the record is updated.
+
+The record contains:
+
+- `ui.<path>`: functions and plain-object namespaces, up to three levels deep.
+  Session-created values and getters requiring a session are excluded.
+- `export:<package-name>:<name>`: runtime exports from Clay, core, components,
+  server, auth, and file persistence. Type-only exports are absent at runtime.
+- `element.<method>`: methods on the core Element prototype chain.
+- `class.<ExportName>.<method>`: own methods of other Element classes exported
+  by `@close-by/clay`.
+- `wire.<type>`: element types handled by the client renderer.
+- `op.server.<op>`, `op.client.<op>`, and `op.patch.<op>`: protocol operations.
+- `cli.<flag>`: CLI flags, including short aliases.
+
+After adding public API, run `bun scripts/compat-surface.ts --write` and commit
+`compat/surface.json` with the implementation. Review its diff before committing.
+For a rename, restore the old alias before updating the record.
+For an intentional removal, list it under Breaking in the release notes and
+regenerate the record. Run `bun test packages/ui` to check it.
+Run `bun scripts/compat-surface.ts` for counts without changing the record.
+
+This check records names, not full signatures or behavior. Option and prop names,
+event payload shapes, defaults, units, and callback order are not checked
+automatically yet. Reviewers check these, along with type compatibility.
+Native and network adapter packages are outside the mechanical record.
+
+Practice adapted from [Native Shell's compatibility policy](https://nsh.dev/docs/compatibility).

package/docs/elements.md

@@ -201,6 +201,12 @@ Server patches still reconcile when `props.value` changes (e.g. `draft.text = ''
 
 Field `error` is **server-owned** (via initial props, `.setError`, or `ui.validate`). It is not optimistic — the client shows `props.error` after `updateProps` patches.
 
+## On phones
+
+On phone-sized touch screens (max-width 767px and coarse pointer), `select` uses the native picker
+and `date` uses the native date picker. `dropdownmenu` and `combobox` open bottom sheets.
+Props and events stay the same. Desktop rendering is unchanged.
+
 ## Styling
 
 Prefer Tailwind utility classes via `.classes(...)`:
@@ -213,4 +219,4 @@ Layout `gap` uses a small numeric scale mapped to `gap-0` … `gap-8` in the cli
 
 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')`.
+Twenty-four more palettes ship alongside kiln — `cobalt`, `ocean`, `forest`, `orchid`, `citrus`, `graphite`, `chalk`, `brutal`, `terminal`, `editorial`, `bubble`, `soothe`, `nebula`, `studio`, `iris`, `ledger`, `contrast`, `dim`, `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')`. `chalk`, `brutal`, `terminal`, `editorial`, `bubble`, `soothe`, `nebula`, `studio`, `iris`, `ledger`, `contrast`, and `dim` also change font, radius and shadows. `contrast` is the accessibility option, with high-contrast colours and explicit focus indicators. 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

@@ -7,7 +7,7 @@ After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http:
 
 ## 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`.
+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** (map gallery, delivery tracker, store locator, globe, uptime monitor) → **Forms & controls** → **Components** → **Apps** (including List, Kanban, Gantt, Flow, and Ops console) → **Account**. Order within a group is `pageMeta.order`.
 
 ## Catalog
 
@@ -16,34 +16,30 @@ Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the h
 | `/` | `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/reactive-let-orders` | `ReactiveLetOrders.ts` | Order filters and master–detail views with `ui.state` / `ui.auto` |
+| `/examples/reactive-let-orders-let` | `ReactiveLetOrdersLet.ts` | The same order workflow with reactive `let` variables and the Clay CLI transform |
 | `/examples/chat` | `Chat.ts` | `ui.storage.app` (persisted messages + ephemeral presence), async `get`/`set` |
 | `/examples/ai` | `AiDemo.ts` | `ui.ai.*` gallery — chat, prompt bar, loader/thinking, agent cards, diff/insights/fine-tune (static props; no model runtime) |
 | `/examples/upload` | `FileUpload.ts` | `ui.upload` button + dropzone (progress/abort/size), `ui.storage.tab` / `user`, `ui.download`, `ui.clipboard` |
 | `/examples/dashboard` | `Dashboard.ts` | `stat`, `areaChart`, full-chrome `dataTable` (views, editors, detail drawer) |
 | `/examples/datatable` | `DataTableDemo.ts` | Multi-sort (Shift+click / badges), footer aggregates + a11y hints, column pin, remote filter/sort + pagination; density/zebra, editors (Enter/Esc + focus restore), resize, virtualization (≥40, coexists with reorder via windowed drop targets); facets, bulk, collapse/expand, loading/empty; `ui.table` sugar |
-| `/examples/composed` | `ComposedDemo.ts` | ReUI batch 1: `ui.timeline`, `ui.stepper`, `ui.dateRange`, `ui.feedList`/`ui.feedRow`, `ui.sparkline` |
-| `/examples/ops-console` | `OpsConsoleDemo.ts` | Dogfood ops console: `filterBar` → `feedList` → `descriptionList` / `staticTable` (batches 1–7 in one surface) |
-| `/examples/reui-batches` | `ReuiBatchesDemo.ts` | ReUI batches 3–6: `buttonGroup`, `empty`, `pagination`, `filterBar`, form inputs, `navigationMenu`, `notice`, `stat`+sparkline, `eventCalendar`, datatable `showFilterChips` |
-| `/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/ops-console` | `OpsConsoleDemo.ts` | Order triage: `filterBar` → `feedList` → `descriptionList` / `staticTable` |
+| `/examples/charts` | `ChartDemo.ts` | `ui.chart.*`, `ui.sparkline`, composed/scatter charts, `stat` + sparkline |
+| `/examples/live-table` | `LiveTableStress.ts` | High-frequency table updates, configurable row count, and live price changes |
 | `/examples/live-charts` | `LiveCharts.ts` | Live charts: `appendData` sliding windows, `setData` tweens, `upsertData` buckets, live gauge and sparklines |
-| `/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/feedback` | `FeedbackDemo.ts` | Feedback & status: alert, spinner, progress, `runJavaScript` / scroll, live timer clock, notice, empty, timeline |
+| `/examples/forms` | `FormDemo.ts` | Forms: validation, `ui.draft`, slider, checkbox, select, rating, color picker, tags, field, numberField, phoneInput, nativeSelect, inputGroup, toggle, checkboxGroup, dateRange, stepper |
 | `/examples/auth` | `Auth.ts` (+ login/admin/change-password) | Signed cookie session, hashed passwords, login lockout, role-gated admin + audit log |
-| `/examples/timer-content` | `TimerContent.ts` | `ui.timer`, markdown, html, image |
-| `/examples/overlays` | `OverlaysDemo.ts` | Breadcrumb, dropdown/context menu, hover card, popover, dialog/sheet/drawer |
-| `/examples/dialog-stack` | `DialogStackDemo.ts` | `ui.dialogStack` multi-step stacked modal |
-| `/examples/controls` | `ControlsDemo.ts` | Menubar (submenu/checkbox/radio), command dialog + inline, carousel, resizable, scroll-area, `ui.state` / `ui.auto` |
-| `/examples/controls-extra` | `ControlsExtra.ts` | `ui.codeBlock` (Shiki), `ui.tree` |
-| `/examples/media-extra` | `MediaExtra.ts` | `ui.relativeTime`, `ui.qrCode`, `ui.imageZoom`, `ui.imageCrop` |
+| `/examples/overlays` | `OverlaysDemo.ts` | Breadcrumb, dropdown/context menu, hover card, popover, dialog/sheet/drawer, `dialogStack` multi-step stacked modal |
+| `/examples/navigation` | `NavigationDemo.ts` | Navigation & layout: menubar, command, carousel, resizable, scrollArea, keybind, viewportEnter, navigationMenu, buttonGroup, pagination, aspectRatio |
+| `/examples/content` | `ContentDemo.ts` | Content & media: markdown, html, codeBlock, descriptionList, staticTable, itemList, tree, image, imageZoom, imageCrop, qrCode, iframe, relativeTime, eventCalendar |
 | `/examples/editor` | `EditorDemo.ts` | `ui.editor` HTML + Markdown side-by-side, bindValue |
 | `/examples/kanban` | `KanbanDemo.ts` | `ui.kanban` swimlanes, card detail drawer, element-owned `cardMove`/`cardSelect`, reset via APIs |
-| `/examples/list` | `ListDemo.ts` | `ui.list` element-owned groups, `itemMove` settle, reset via `setGroups` |
+| `/examples/list` | `ListDemo.ts` | Apps: `ui.list` groups, drag to reorder, reset via `setGroups` |
 | `/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/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 with interactive edges and positions |
 | `/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 |

package/docs/getting-started.md

@@ -149,6 +149,7 @@ bun run clay ./pages --app --title "My App"
 | `-p, --port` | Port (default `3000`) |
 | `-t, --title` | HTML / shell title |
 | `--app` | Dashboard shell + nav from discovered pages |
+| `--pwa` | Installable app: manifest + service worker ([Mobile and installable apps](./mobile.md)) |
 | `--no-open` | Do not open the browser |
 | `--reload` | Restart on file changes (`bun --watch`); opens the browser once; prints `↻ clay: reloading…` and re-imports pages (clears `require.cache`) |
 | `--reactive-let` | Enable compile-time reactive `let` Bun loader (**off** by default; still needs `// @clay-reactive` or `"use reactive";` in source) |
@@ -181,7 +182,7 @@ Open:
 - http://localhost:4000 — home with links to examples
 - http://localhost:4000/examples/counter
 - http://localhost:4000/examples/todo
-- http://localhost:4000/examples/form-demo
+- http://localhost:4000/examples/forms
 - http://localhost:4000/examples/auth
 
 | Script | What it does |

package/docs/llms.txt

@@ -11,6 +11,8 @@ Notes for agents:
 - Update existing nodes with `setText` / `setValue` / bindings. Prefer `ui.state` + `ui.auto` (+ `ui.timer`) for async/live UIs; `ui.refreshable` for simple one-shot rebuilds. Shared or persisted state: `ui.storage` (`tab` / `user` / `app`).
 - Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.getUrlSearch` / `ui.updateUrlSearch`, `ui.openExternal`.
 - Runtime is Bun. In this repo: `bun run build:client`, then `bun run demo` (http://localhost:4000) or `bun run clay hello.ts`.
+- Installable app is opt-in: `ui.run({ pwa: true })` or `clay ./pages --app --pwa` adds a manifest and an app-shell service worker (see docs/mobile.md).
+- On phones the `app` nav becomes a bottom tab bar; `app: { mobileNav: 'menu' }` keeps only the sidebar sheet.
 - `ui.ai.*` is visual primitives only — no model or streaming runtime.
 - Agent skill (Cursor / compatible tools): `@close-by/clay/SKILL.md` — copy to `.cursor/skills/clay/SKILL.md` or read from `node_modules` when installed.
 
@@ -20,6 +22,7 @@ Notes for agents:
 - [Getting started](docs/getting-started.md): Install, `clay` CLI, first app, publishing
 - [Boot](docs/boot.md): CLI vs library, `clientDir`, `_run.ts`, reload stubs
 - [Tailwind](docs/tailwind.md): Scanned utilities + `ui.run({ css })`
+- [Mobile and installable apps](docs/mobile.md): Phone tab bar (`mobileNav`), installable PWA (`ui.run({ pwa })`, `--pwa`)
 - [Sample app](docs/tutorial.md): Step-by-step tasks list, then two pages + shell
 - [Concepts](docs/concepts.md): Sessions, element tree, patches, refreshable, bindings, storage
 - [Browser APIs](docs/browser-apis.md): `ui.clipboard` / hash / `openExternal` — no `window` in page code
@@ -37,6 +40,7 @@ Notes for agents:
 
 - [Architecture](docs/architecture.md): Packages and data flow
 - [WebSocket protocol](docs/protocol.md): Message formats
+- [Compatibility](docs/compatibility.md): Public API promise, aliases, and compatibility checks
 - [AI UI](docs/ai.md): `ui.ai.*` visual primitives
 - [Reactive let](docs/reactive-let.md): `ui.state` / `ui.auto` and the compile-time `let` transform
 - [DuckDB](docs/duckdb.md): `@close-by/clay-duckdb`

package/docs/mobile.md

@@ -0,0 +1,111 @@
+# Mobile and installable apps
+
+Apps built with the `app` shell work on phones without changes. You can also make an app installable to the home screen, which is opt-in.
+
+## Phone layout
+
+On phone-sized screens (narrow, with a touch pointer) the shell changes on its own:
+
+- **Bottom tab bar.** Up to 4 top-level `nav` items become tabs. When there are more items, or `navSecondary`, `documents` or `user` is set, a **More** tab opens the sidebar sheet. A tab is highlighted when its page, or one of its child pages, is active.
+- **Bottom sheets.** Dialogs open as bottom sheets.
+- **Safe areas.** Content clears the iPhone notch and home indicator.
+- **Toasts and the connection chip** sit above the tab bar.
+- **16px form text.** iOS doesn't zoom when a field is focused.
+
+`select`, `combobox`, `date` and `dropdownMenu` also use native pickers or bottom drawers on phones. See [Elements](./elements.md#on-phones).
+
+### Keep only the menu
+
+Set `mobileNav: 'menu'` to keep the hamburger sheet and skip the tab bar:
+
+```typescript
+ui.run({
+  app: {
+    title: 'My App',
+    nav: ui.navFromPages(),
+    mobileNav: 'menu', // default: 'tabs'
+  },
+});
+```
+
+`mobileNav` is also a [`ui.app()`](./api.md#uiappprops-fn) prop.
+
+## Installable app (PWA)
+
+Opt in with the CLI flag or the `pwa` option:
+
+```bash
+clay ./pages --app --pwa
+```
+
+```typescript
+ui.run({ pwa: true }); // defaults
+
+ui.run({
+  title: 'My App',
+  pwa: {
+    shortName: 'App',
+    description: 'Track my work',
+    themeColor: '#1d4ed8',
+    backgroundColor: '#ffffff',
+    display: 'standalone',
+    startUrl: '/',
+    icon: './assets/icon-512.png',
+  },
+});
+```
+
+`ClayPwaConfig` is exported from `@close-by/clay-server`.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `name` | `title` | App name in the install prompt and splash screen |
+| `shortName` | `name` | Label under the home-screen icon |
+| `description` | | Manifest description |
+| `themeColor` | Clay light/dark background | Browser and OS chrome color |
+| `backgroundColor` | Clay light background | Splash screen background |
+| `display` | `'standalone'` | `'standalone' \| 'fullscreen' \| 'minimal-ui' \| 'browser'` |
+| `startUrl` | `'/'` | URL opened from the home screen |
+| `icon` | Clay's bundled icons | Square PNG (512px+ recommended) or SVG, relative to the working directory |
+
+It adds:
+
+- `/manifest.webmanifest`, with name, icons, colors and display mode.
+- `theme-color` and Apple meta tags, plus `viewport-fit=cover` so content can use the full screen.
+- `/sw.js`, a service worker that caches the app shell (HTML, JS, CSS and icons). It uses network-first, so online users always get the latest build.
+
+### Icons
+
+- Without `icon`, Clay's bundled icons are used.
+- `icon` must be a `.png` or `.svg` file. A missing or unsupported file throws at startup.
+- iOS home-screen icons need a PNG. SVG gets no apple-touch-icon, so use a PNG if the app will be installed on iOS.
+
+### Offline
+
+The installed app still opens without a connection and shows Clay's reconnecting state. There is no offline mode for pages, since every screen runs on the server.
+
+### HTTPS
+
+Service workers require HTTPS. `localhost` is exempt, so you can test locally. Serve the app over HTTPS before asking people to install it.
+
+### Install
+
+- **Android and desktop Chrome:** an install prompt or menu item appears when the app is installable.
+- **iOS Safari:** Share → Add to Home Screen.
+
+### Turn it off
+
+Remove `pwa` (or the `--pwa` flag). Clay then serves a `/sw.js` that clears the app cache and unregisters itself. Browsers that installed the app earlier clean up the next time they load it.
+
+### Override the worker or manifest
+
+`/sw.js` and `/manifest.webmanifest` can be replaced with `routes`, which match by exact path before pages:
+
+```typescript
+ui.run({
+  pwa: true,
+  routes: {
+    '/sw.js': () => new Response(mySource, { headers: { 'Content-Type': 'text/javascript' } }),
+  },
+});
+```

package/docs/ops-patterns.md

@@ -2,7 +2,7 @@
 
 Dense internal tools (live feeds, master–detail, logs/traces) push Clay past card dashboards. Prefer Phase 1 reactivity ([Concepts](./concepts.md#canonical-recipe-state--auto--timer)) and the helpers below.
 
-**Runnable dogfood:** `/examples/ops-console` (`OpsConsoleDemo.ts`) — one Orders-shaped surface using `filterBar`, `inputGroup`, `feedList`/`feedRow`, `descriptionList`, `staticTable`, `pagination`, `empty`, `notice`, and `toggle`. Use that page to find API friction before adding more wire types.
+**Runnable example:** `/examples/ops-console` (`OpsConsoleDemo.ts`) — one Orders-shaped surface using `filterBar`, `inputGroup`, `feedList`/`feedRow`, `descriptionList`, `staticTable`, `pagination`, `empty`, `notice`, and `toggle`. Use that page to find API friction before adding more wire types.
 
 ## Status chips
 

package/docs/production.md

@@ -65,6 +65,35 @@ ui.page('/admin', () => {
 
 Nav filtering is not authorization. Always guard pages that must not leak data.
 
+### Role-based content
+
+Tell Clay how to read the current user's roles once, then show or hide parts of a page by role:
+
+```ts
+ui.run({
+  authSecret,
+  getRoles: () => getSessionUser()?.roles ?? [], // string, string[] or null
+});
+
+ui.page('/projects', () => {
+  if (!requireAuth()) return;
+
+  ui.forRoles(['admin', 'manager'], () => {
+    ui.button('Delete project', { onClick: deleteProject });
+    ui.dataTable(auditRows);
+  }, () => ui.label('Ask an admin for access')); // optional fallback
+
+  ui.button('Approve', { onClick: approve }).roles(['admin']);
+  if (ui.hasRole('admin')) { /* plain check */ }
+});
+```
+
+- Checks run on the server while the page builds. Hidden content is never sent to the browser, and its handlers don't exist, so they can't be triggered.
+- With `getRoles` set, `ui.navFromPages()` (no arguments) and `requireRole(...)` use the same roles — no need to pass them separately.
+- Roles are read when the page builds. Signing in or out reconnects and rebuilds, so the UI follows. A role changed while someone is signed in applies on their next page load.
+- Without `getRoles`, role checks treat the user as having no roles (fail closed) and log a warning once.
+- Still check the role inside handlers that change data — cheap protection against mistakes elsewhere.
+
 ## Single sign-on (OIDC)
 
 `@close-by/clay-auth` signs users in with any OpenID Connect provider (authorization code + PKCE). The provider is only used to sign in: once its ID token is verified, Clay sets its usual signed auth cookie, so everything above (`resolveUserId`, guards, idle expiry) works unchanged and there are no provider tokens to refresh.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "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.23",
-    "@close-by/clay-core": "0.2.23",
-    "@close-by/clay-components": "0.2.23",
-    "@close-by/clay-server": "0.2.23",
+    "@close-by/clay-compiler": "0.2.25",
+    "@close-by/clay-core": "0.2.25",
+    "@close-by/clay-components": "0.2.25",
+    "@close-by/clay-server": "0.2.25",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -465,6 +465,10 @@ import {
   updateUrlSearch as updateUrlSearchCore,
   openExternal as openExternalCore,
   redirect as redirectCore,
+  setRoleResolver,
+  hasRole as hasRoleCore,
+  forRoles as forRolesCore,
+  type RoleResolver,
   scroll as scrollCore,
   timer as timerCore,
   storage as storageCore,
@@ -1690,6 +1694,30 @@ export function redirect(url: string): void {
   redirectCore(url);
 }
 
+/** True when the current user has at least one of `roles` (needs `ui.run({ getRoles })`). */
+export function hasRole(roles: string | readonly string[]): boolean {
+  return hasRoleCore(roles);
+}
+
+/**
+ * Build `content` only for users with one of `roles`, else `fallback`.
+ * Skipped content is never sent to the browser. Needs `ui.run({ getRoles })`.
+ *
+ * @example
+ * ```ts
+ * ui.forRoles(['admin', 'manager'], () => {
+ *   ui.button('Delete project', { onClick: remove });
+ * }, () => ui.label('Ask an admin for access'));
+ * ```
+ */
+export function forRoles(
+  roles: string | readonly string[],
+  content: () => void,
+  fallback?: () => void,
+): void {
+  forRolesCore(roles, content, fallback);
+}
+
 /** Open a URL in a new tab. Prefer over `runJavaScript('window.open…')`. */
 export function openExternal(url: string): void {
   openExternalCore(url);
@@ -1789,6 +1817,12 @@ export function page(path: string, fn: () => void, options?: PageOptions): void
  * Extends {@link ClayServerConfig} (port, auth, storage, uploads, session timeouts).
  */
 export type RunConfig = ClayServerConfig & {
+  /**
+   * Current user's role(s), read while pages build. Enables `ui.forRoles`,
+   * `element.roles([...])`, `ui.hasRole`, and default role filtering in
+   * `ui.navFromPages()` / `requireRole`. Return `null` / `[]` when signed out.
+   */
+  getRoles?: RoleResolver;
   /** Global dashboard shell; wraps every page unless `ui.page(..., { shell: false })`. */
   app?: AppProps;
   /**
@@ -1887,7 +1921,8 @@ export function run(rootOrConfig: PageFn | RunConfig = {}, config: RunConfig = {
 
   cfg = applyClayTailwind(cfg);
 
-  const { app: appProps, tailwind: _tailwind, ...serverConfig } = cfg;
+  const { app: appProps, tailwind: _tailwind, getRoles, ...serverConfig } = cfg;
+  setRoleResolver(getRoles ?? null);
   if (appProps) {
     setPageWrapper((pageFn) => app(appProps, pageFn));
   } else {
@@ -2035,6 +2070,8 @@ export const ui = {
   updateUrlSearch,
   openExternal,
   redirect,
+  forRoles,
+  hasRole,
   runJavaScript,
   scroll,
   timer,

package/src/pages.ts

@@ -1,3 +1,4 @@
+import { currentRoles, hasRoleResolver } from '@close-by/clay-core';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { join } from 'path';
 import { readFile } from 'fs/promises';
@@ -249,6 +250,10 @@ export function navFromPages(opts?: NavFromPagesOptions): AppNavItem[] {
   if (opts?.roles) {
     for (const r of opts.roles) viewer.add(r);
   }
+  // No explicit role given → use ui.run({ getRoles }) when configured.
+  if (opts?.role === undefined && opts?.roles === undefined && hasRoleResolver()) {
+    for (const r of currentRoles()) viewer.add(r);
+  }
 
   const paths = getRegisteredPaths();
   const ranked: RankedNavPage[] = paths