@close-by/clay 0.2.24 → 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,6 +93,7 @@ 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 |
@@ -1822,7 +1823,7 @@ onClick: async () => {
 | `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) |
@@ -1960,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.
@@ -2114,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.24",
+  "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.24",
-    "@close-by/clay-core": "0.2.24",
-    "@close-by/clay-components": "0.2.24",
-    "@close-by/clay-server": "0.2.24",
+    "@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"
   }