@close-by/clay 0.2.25 → 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,6 +6,8 @@ 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 |
@@ -36,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}`);
 
@@ -67,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

@@ -1000,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  
@@ -1833,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) |
@@ -1894,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]);
@@ -1910,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`:
 

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

@@ -3,7 +3,11 @@
 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
 
@@ -16,8 +20,7 @@ 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/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` |
@@ -39,7 +42,8 @@ Each page sets `group` / `groupIcon` in its `pageMeta`, so the sidebar and the h
 | `/examples/kanban` | `KanbanDemo.ts` | `ui.kanban` swimlanes, card detail drawer, element-owned `cardMove`/`cardSelect`, reset via APIs |
 | `/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 with interactive edges and positions |
+| `/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`).
@@ -202,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

@@ -33,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
 
@@ -43,7 +45,8 @@ Notes for agents:
 - [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/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.25",
+  "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.25",
-    "@close-by/clay-core": "0.2.25",
-    "@close-by/clay-components": "0.2.25",
-    "@close-by/clay-server": "0.2.25",
+    "@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,