@close-by/clay 0.2.24 → 0.2.26

package/README.md

@@ -18,4 +18,6 @@ export default function () {
 bunx clay hello.ts
 ```
 
-Docs: shipped with the package at `node_modules/@close-by/clay/docs/`. Agent skill: `node_modules/@close-by/clay/SKILL.md` (or `@close-by/clay/skill`). See [getting-started.md](docs/getting-started.md) after install.
+Live demo: [clay.close-by.org](https://clay.close-by.org/).
+
+Docs: shipped with the package at `node_modules/@close-by/clay/docs/`. Agent skill: `node_modules/@close-by/clay/SKILL.md` (or `@close-by/clay/skill`). See [getting-started.md](https://github.com/closeby-corp/clay/blob/main/docs/getting-started.md) after install.

package/docs/README.md

@@ -6,11 +6,14 @@ You write imperative `ui.*` code on the server. Clay owns a per-client element t
 
 For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these guides. The [agent skill](./SKILL.md) ships with `@close-by/clay` at package root (`SKILL.md`).
 
+[Live demo](https://clay.close-by.org/) · [Examples catalog](./examples.md)
+
 ## Guides
 
 | 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 +27,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`) |
@@ -34,20 +38,19 @@ For coding agents: the repo-root [llms.txt](../llms.txt) is a short map of these
 
 ## Quick start
 
+The runtime packages are published to npm. The CLI includes prebuilt client assets.
+
 ```bash
-bun install
-bun run build:client   # monorepo: build + copy client into @close-by/clay-cli
-bun run clay hello.ts
+bun add @close-by/clay-cli @close-by/clay
+bunx clay hello.ts
 # → http://localhost:3000
 ```
 
-Outside the monorepo: `bun run pack:publishable` then install the `dist-pack/*.tgz` set (see [Getting started](./getting-started.md)), or `bun add @close-by/clay-cli @close-by/clay` once published. Maintainers: `bun run publish:dry` / `publish:npm` (order core → … → cli). Shipped CLI includes prebuilt client assets — no separate `build:client` after install.
-
 ```typescript
 // hello.ts
 import { ui } from '@close-by/clay';
 
-ui.run(() => {
+export default function () {
   let count = 0;
   const label = ui.label(`Count: ${count}`);
 
@@ -65,15 +68,17 @@ ui.run(() => {
       },
     });
   });
-});
+}
 ```
 
 Multi-page with shell:
 
 ```bash
-bun run clay ./pages --app --title "My App"
+bunx clay ./pages --app --title "My App"
 ```
 
+`ui.run` is library mode; see [Boot](./boot.md).
+
 Or library-style entry (`loadPages` + `ui.run({ app })`) — see [Getting started](./getting-started.md).
 
 ## Naming

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 |
@@ -999,7 +1000,7 @@ registerFlowEdgeTypes({ labeled: BaduiLabeledEdge });
 
 Then reference those keys from the server: `flow.node({ nodeType: 'fancy', … })` / edge `type: 'labeled'`, and optionally list them on the flow as `customNodeTypes` / `customEdgeTypes`.
 
-See Flow Demo (`/examples/flow`) for richer patterns:
+See the Flow demos (`/examples/flow` for 1–2, `/examples/flow-editing` for 3–4) for richer patterns:
 
 1. **ETL pipeline** — select/switch/progress/buttons inside nodes; labeled smoothstep edges + dagre auto-layout  
 2. **Branching approval** — multi-handle triage (`yes` / `no` sources), rating + badges  
@@ -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) |
@@ -1832,6 +1833,7 @@ onClick: async () => {
 | `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 |
+| `ui.onDispose(callback)` | `void` | Register synchronous cleanup during a page build or event; runs once on disconnect, navigation, or reconnect page replacement. Requires an active session, so call it synchronously during the build or at the start of a handler (not after an `await`); callbacks run in registration order and errors are logged without stopping other cleanup. |
 | `ui.timer(interval, callback, options?)` | `TimerHandle` | Session-scoped timer; `interval` in **seconds**; `{ once? }`; `.activate()` / `.deactivate()` / `.cancel()` |
 | `ui.upload(props?)` | `Element` | Multipart HTTP upload; see below |
 | `ui.storage.tab` | | Per-browser-tab map (sessionStorage mirror) |
@@ -1893,9 +1895,10 @@ User storage requires a `userId` on the session. The built-in client sends an an
 const messages = ui.storage.app.create<Message[]>('chatMessages', []);
 const online = ui.storage.app.create<string[]>('onlineUsers', [], { persist: false });
 
-messages.subscribe((list) => {
+// Inside a page builder, unsubscribe when this page is disposed.
+ui.onDispose(messages.subscribe((list) => {
   // update UI for this session
-});
+}));
 
 await messages.set([...(await messages.get()), newMessage]);
 await messages.update((prev) => [...prev, newMessage]);
@@ -1909,12 +1912,12 @@ await messages.update((prev) => [...prev, newMessage]);
 | `storage.app.create(key, initial, options?)` | Get or create named store; `{ persist?: boolean }` |
 | `.get()` | `Promise<T>` — load from adapter when persisted |
 | `.set(v)` / `.update(fn)` | `Promise<void>` — save when persisted |
-| `.subscribe(listener)` | Listen for changes |
+| `.subscribe(listener)` | Listen for changes; returns an unsubscribe function. Pass it to `ui.onDispose` for page-scoped listeners; subscriptions created outside a session remain process-wide. |
 | `storage.app.clearAll()` | Test helper (clears app stores only) |
 | `storage.clearAll()` | Test helper (clears app stores + user bags + both adapters) |
 | `createMemoryPersistence()` | In-memory adapter for tests (`@close-by/clay-core`) |
 | `createFilePersistence({ dir })` | File-backed adapter (`@close-by/clay-persistence-file`) |
-| `createRedisPersistence({ client, keyPrefix? })` | Redis adapter (`@close-by/clay-persistence-redis`) — multi-process app/user bags; keep WS sticky |
+| `createRedisPersistence({ client, keyPrefix? })` | Redis adapter (`@close-by/clay-persistence-redis`; monorepo only — not published to npm yet) — multi-process app/user bags; keep WS sticky |
 
 `PersistenceAdapter`:
 
@@ -1960,6 +1963,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 +2118,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/boot.md

@@ -98,7 +98,7 @@ If you run **`tsc --noEmit`** (or IDE typecheck) on the app repo, exclude reload
 
 Without that exclude, a leftover stub from a crashed dev session can produce spurious TS errors until you delete `.clay-reload/`. Clay apps that only typecheck `pages/` and `src/` rarely need more; monorepos should exclude `.clay-reload` at the app root `tsconfig.json`.
 
-Legacy `_clay-reload-*.ts` files under `pages/` (pre-0.2.5) should be deleted; modern Clay writes outside the tree.
+Legacy `_clay-reload-*.ts` files under `pages/` (pre-0.2.5) should be deleted; modern Clay writes to `<cwd>/.clay-reload/`, inside the project tree but outside `pages/`.
 
 ## Reactive-let
 

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/duckdb.md

@@ -2,9 +2,7 @@
 
 Multi-database DuckDB wrapper: named instances, `ATTACH` for DuckDB/SQLite/Postgres/MySQL, and insert/update/delete helpers.
 
-```bash
-bun add @close-by/clay-duckdb   # or depend on workspace:* inside this monorepo
-```
+**Monorepo only — not published to npm yet.** Depend on `@close-by/clay-duckdb` with `workspace:*` inside this monorepo.
 
 ## Connect multiple databases
 

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

@@ -3,11 +3,15 @@
 Demo entry: [`apps/demo/src/main.ts`](../apps/demo/src/main.ts)  
 Pages: [`apps/demo/src/examples/`](../apps/demo/src/examples/) (auto-loaded via `ui.loadPages`)
 
-After `bun run build:client && bun run demo` (or `bun run demo:cli`), open http://localhost:4000.
+Live: https://clay.close-by.org/ · locally in this repo: `bun run build:client && bun run demo` (or `bun run demo:cli`), then open http://localhost:4000.
+
+## Standalone apps
+
+- [`examples/tailwind-app/`](../examples/tailwind-app/): Standalone app with Tailwind utilities.
 
 ## 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 +20,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`, plus the equivalent reactive `let` source (runnable copy: `examples/reactive-let-orders.ts` with the Clay CLI) |
 | `/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` | `ui.flow` ETL pipeline with in-node controls, labeled edges and dagre auto-layout; multi-handle approval branches |
+| `/examples/flow-editing` | `FlowEditingDemo.ts` | Fan-in/out with `addNode` dynamic stages; group/`parentId` nesting |
 | `/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

@@ -6,13 +6,21 @@
 - Node-compatible OS (macOS / Linux / WSL)
 - For local tarball installs: npm (links co-installed `file:` packages; Bun may try the registry for rewritten versions)
 
-## Outside the monorepo
+## Install from npm
+
+```bash
+bun add @close-by/clay-cli @close-by/clay
+# transitive: core, components, server, persistence-file
+# optional: bun add @close-by/clay-auth
+```
+
+Use `bun init`’s tsconfig or set `"extends": "@close-by/clay/page-tsconfig"` in your `tsconfig.json`.
 
 Consumers import `@close-by/clay` and run apps with the `clay` binary from `@close-by/clay-cli`. The CLI ships prebuilt Vite assets (`client-dist`); you do **not** need `@close-by/clay-client` or a monorepo `build:client`.
 
 Walkthrough (tasks list → two pages + `--app`): [Sample app](./tutorial.md).
 
-### From local packs (this repo)
+### Contributors: local packs
 
 ```bash
 # In the Clay checkout:
@@ -22,38 +30,21 @@ bun run pack:publishable   # build:client + bun pm pack → dist-pack/*.tgz
 
 # In your app directory:
 npm install \
-  /path/to/clay/dist-pack/close-by-clay-core-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-auth-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-compiler-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-persistence-file-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-components-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-server-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-0.1.0.tgz \
-  /path/to/clay/dist-pack/close-by-clay-cli-0.1.0.tgz
+  '/path/to/clay/dist-pack/close-by-clay-core-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-auth-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-compiler-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-persistence-file-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-components-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-server-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-<version>.tgz' \
+  '/path/to/clay/dist-pack/close-by-clay-cli-<version>.tgz'
 ```
 
-Install **all** runtime tarballs together so `@close-by/clay` and `@close-by/clay-*@0.1.0` resolve from the co-installed packs (they are not on the public registry yet).
-
-### When published to npm
-
-```bash
-bun add @close-by/clay-cli @close-by/clay
-# transitive: core, components, server, persistence-file
-# optional: bun add @close-by/clay-auth
-```
+Replace `<version>` with the packed version. Install **all** runtime tarballs together so `@close-by/clay` and `@close-by/clay-*@<version>` resolve from the co-installed packs.
 
 ### Publishing to npm (maintainers)
 
-Runtime packages are scoped (`@close-by/clay` and `@close-by/clay-*`) and public (`publishConfig.access: public`). Publish **in dependency order** so the registry can resolve rewritten versions:
-
-1. `@close-by/clay-core`
-2. `@close-by/clay-auth`
-3. `@close-by/clay-compiler`
-4. `@close-by/clay-persistence-file`
-5. `@close-by/clay-components`
-6. `@close-by/clay-server`
-7. `@close-by/clay`
-8. `@close-by/clay-cli`
+Runtime packages are scoped and public. The canonical package list and dependency publish order are in [`scripts/publishable.ts`](../scripts/publishable.ts).
 
 ```bash
 # In the Clay checkout:
@@ -65,20 +56,6 @@ bun run publish:npm                # pack + validate + real npm publish (same or
 # Re-run is safe: versions already on npm are skipped.
 ```
 
-Equivalent manual flow from packed tarballs:
-
-```bash
-bun run pack:publishable
-npm publish ./dist-pack/close-by-clay-core-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-auth-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-compiler-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-persistence-file-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-components-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-server-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-0.1.0.tgz --access public
-npm publish ./dist-pack/close-by-clay-cli-0.1.0.tgz --access public
-```
-
 `publish:dry` checks each tarball for rewritten deps (no `workspace:*`), `license` / README / LICENSE, CLI `bin` + `client-dist`, `@close-by/clay` `docs/` (via `prepack` → `scripts/sync-docs.ts`), then runs `npm publish --dry-run`. `publish:npm` looks up each `name@version` on the registry and **skips** if it is already published (resume after a partial failure). Use `--skip-pack` to reuse an existing `dist-pack/`: `bun scripts/publish-from-pack.ts --dry-run --skip-pack`.
 
 After install, version-matched docs live at `node_modules/@close-by/clay/docs/` (import paths like `@close-by/clay/docs/api.md` with Bun, or `resolveClayDocsDir` from `@close-by/clay/docs-dir`).
@@ -149,6 +126,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 +159,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 |
@@ -201,7 +179,7 @@ Open:
 - Source packages keep `workspace:*` for the monorepo; `bun pm pack` / publish rewrites them to the package version.
 - `@close-by/clay-client` is **private**; only its Vite `dist` is copied into `@close-by/clay-cli` (`copy-client` / CLI `prepack`, also invoked by `build:client`).
 - Root stays `private: true`. Each runtime package ships `license`, `README.md`, `LICENSE`, and `publishConfig.access: public`.
-- Publish order: `core` → `auth` → `compiler` → `persistence-file` → `components` → `server` → `ui` → `cli` (see **Publishing to npm** above).
+- Publishable packages and dependency order: [`scripts/publishable.ts`](../scripts/publishable.ts).
 
 ## Library mode (multi-page entrypoint)
 

package/docs/kibana.md

@@ -2,6 +2,8 @@
 
 Authenticated (or internal) Kibana REST client: arbitrary API calls, Elasticsearch via console proxy or `/elasticsearch`, and `search_after` pagination for walking every matching log line.
 
+**Monorepo only — not published to npm yet.** Depend on `@close-by/clay-kibana` with `workspace:*` inside this monorepo.
+
 ```typescript
 import { Kibana } from '@close-by/clay-kibana';
 

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
@@ -30,6 +33,8 @@ Notes for agents:
 
 ## Examples
 
+- [Live demo](https://clay.close-by.org/): Browse the running examples
+
 - [Examples catalog](docs/examples.md): Demo routes and patterns
 - [Demo pages](apps/demo/src/examples/): Runnable `ui.page` modules
 
@@ -37,9 +42,11 @@ 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`
+- [DuckDB](docs/duckdb.md): `@close-by/clay-duckdb` — monorepo only — not published to npm yet
+- Redis persistence: `@close-by/clay-persistence-redis` — monorepo only — not published to npm yet (see [storage API](docs/api.md))
 - [ClickHouse](docs/clickhouse.md): `@close-by/clay-clickhouse`
-- [Kibana](docs/kibana.md): `@close-by/clay-kibana`
+- [Kibana](docs/kibana.md): `@close-by/clay-kibana` — monorepo only — not published to npm yet
 - [NiceGUI](https://nicegui.io/documentation): Inspiration for the `ui.*` style

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/reactive-let.md

@@ -66,7 +66,7 @@ Clay lifts `count` into `ui.state`, turns the label into `bindText`, and leaves
 | When to use `let` + pragma | When to stay on Phase 1 |
 |-----------------------------|-------------------------|
 | Counters, toggles, filters on demo pages | Async fetch before first paint, heavy CJS imports |
-| Orders-shaped proof pages (`ReactiveLetOrdersLet.ts`) | Per-row mutable state without stable row keys |
+| Orders-shaped proof pages (`examples/reactive-let-orders.ts`) | Per-row mutable state without stable row keys |
 | Teaching / prototyping NiceGUI-style UX | You want zero Bun loader / compiler in the path |
 
 Phase 1 remains the **escape hatch** — copy patterns from [`ReactiveLetOrders.ts`](../apps/demo/src/examples/ReactiveLetOrders.ts) when Phase 2 limits bite.
@@ -206,13 +206,15 @@ Tests: `packages/compiler/src/transform.test.ts`, `packages/core/src/auto.test.t
 | Page | Syntax | Run |
 |------|--------|-----|
 | [`ReactiveLetOrders.ts`](../apps/demo/src/examples/ReactiveLetOrders.ts) | Phase 1 `state` / `auto` | `bun run cli` |
-| [`ReactiveLetOrdersLet.ts`](../apps/demo/src/examples/ReactiveLetOrdersLet.ts) | `let` + `// @clay-reactive` | `bun run cli:reactive-let` |
+| [`examples/reactive-let-orders.ts`](../examples/reactive-let-orders.ts) | `let` + `// @clay-reactive` | `bun run clay examples/reactive-let-orders.ts --reactive-let` (from repo root) |
 
 ```bash
-cd apps/demo && bun run cli                 # Orders (state/auto) — always interactive
-cd apps/demo && bun run cli:reactive-let    # both pages; let page needs this
+bun run demo:cli                           # Orders at /examples/reactive-let-orders, always interactive
+bun run clay examples/reactive-let-orders.ts --reactive-let  # standalone let proof, same route
 ```
 
-Compiler coverage: `packages/compiler/src/orders-proof.test.ts` transforms the let demo and asserts separate list/detail regions (no mega-`auto`).
+The demo Orders page includes the let source as a code block. The standalone copy stays outside the auto-loaded demo pages.
+
+Compiler coverage: `packages/compiler/src/orders-proof.test.ts` transforms the standalone let example and asserts separate list/detail regions (no mega-`auto`).
 
 Without `--reactive-let`, `let` assignments are silent no-ops (no error).

package/package.json

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

package/src/index.ts

@@ -501,10 +501,12 @@ import {
 } from '@close-by/clay-core';
 import {
   ClayServer,
+  onDispose,
   type ClayServerConfig,
   establishAuthSession as establishAuthSessionCore,
   clearAuthSession as clearAuthSessionCore,
 } from '@close-by/clay-server';
+export { onDispose };
 import {
   loadPages,
   navFromPages,
@@ -2075,6 +2077,7 @@ export const ui = {
   runJavaScript,
   scroll,
   timer,
+  onDispose,
   storage,
   theme,
   sound,