@close-by/clay 0.2.7 → 0.2.9

package/README.md

@@ -18,4 +18,4 @@ export default function () {
 bunx clay hello.ts
 ```
 
-Docs: [Getting started](https://github.com/closeby-corp/clay/blob/main/docs/getting-started.md).
+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.

package/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: clay
+description: >-
+  Build Clay server-driven UI apps with ui.* on Bun. Use when authoring Clay
+  pages, demos, or ops consoles; importing @close-by/clay; running clay CLI;
+  ui.page/ui.run/ui.state/ui.auto; or when the user asks about Clay, NiceGUI-style
+  TypeScript UI, or server-owned element trees.
+---
+
+# Clay
+
+Server-driven UI for TypeScript. Write imperative `ui.*` on the server; Clay owns a per-tab element tree and syncs it to a React + ShadCN client over WebSocket.
+
+**Clay is not React.** Do not write React components, JSX, or client-side screen logic for app pages. The React client is a renderer only.
+
+## Install and run
+
+```bash
+bun add @close-by/clay-cli @close-by/clay
+```
+
+```typescript
+// hello.ts
+import { ui } from '@close-by/clay';
+
+export default function () {
+  ui.label('Hello Clay');
+  ui.button('Ping', { onClick: () => ui.notify('hi', 'success') });
+}
+```
+
+```bash
+bunx clay hello.ts   # http://localhost:3000
+```
+
+**Monorepo (this repo):** `bun run build:client` before `bun run demo` or `bun run clay …` — new wire types require a rebuilt client bundle.
+
+## Mental model
+
+1. `ui.page(path, fn)` or `ui.run(fn)` builds an **element tree** on the server.
+2. Each browser tab = one **WebSocket session**; page code runs once per tab.
+3. User events → server handlers → **patches** (`updateProps`, `setChildren`) → client re-render.
+4. Local `let` / session state is **per tab**, not shared. Use `ui.storage.app` for process-wide data.
+
+## Reactive UI (preferred)
+
+Keep mutable state **outside** rebuild blocks:
+
+```typescript
+const s = ui.state({ count: 0, items: [] as string[] });
+
+ui.auto(() => {
+  ui.label(`Count: ${s.count}`);
+  ui.button('+', { onClick: () => { s.count++; } });
+  for (const item of s.items) ui.label(item);
+});
+
+// Or bind one label without a full block:
+ui.label(() => `Count: ${s.count}`);
+```
+
+| API | Use when |
+|-----|----------|
+| `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
+| `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
+| `bindValue` | Two-way inputs |
+| `ui.refreshable` + `.refresh()` | Simple one-shot structural rebuilds |
+| `ui.timer(ms, fn)` | Poll / clock ticks inside reactive pages |
+
+**Inside `ui.auto`:** child tree shape (types + counts) should stay stable when possible — then updates use `updateProps` instead of remounting. For toggling optional `className`, use `undefined` to clear (Clay sends `null` patches).
+
+**Button groups:** use `variant: 'outline'` on all segmented buttons; highlight selection with `className: active ? 'bg-accent' : undefined`.
+
+## Pages and layout
+
+```typescript
+ui.page('/dashboard', () => {
+  ui.column({ gap: 4 }, () => {
+    ui.row({ gap: 2 }, () => {
+      ui.button('Save', { onClick: save });
+    });
+    ui.card({ title: 'Stats' }, () => {
+      ui.label('…');
+    });
+  });
+});
+```
+
+- Nest with callbacks: `ui.row(() => { … })`, `ui.column(() => { … })`.
+- Tailwind: `ui.label('x').classes('text-sm text-muted-foreground')` or pass `className` in props.
+- Toasts: `ui.notify('Saved', 'success')`.
+
+## Do not
+
+- Import React, write JSX, or add client components for screens.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Assume `let` is shared across tabs or users.
+- Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
+
+## Docs (shipped with package)
+
+After install, read version-matched docs at `node_modules/@close-by/clay/docs/`:
+
+| Doc | Purpose |
+|-----|---------|
+| `getting-started.md` | CLI, first app, publish |
+| `concepts.md` | Sessions, patches, storage |
+| `api.md` | Full `ui.*` reference |
+| `elements.md` | Wire types → client mapping |
+| `reactive-let.md` | `ui.state` / `ui.auto` / compile-time `let` |
+| `ops-patterns.md` | Dense consoles, feeds, tables |
+| `examples.md` | Demo route catalog |
+
+Resolve docs programmatically: `resolveClayDocsDir()` from `@close-by/clay/docs-dir`.
+
+## Optional compile-time reactive `let`
+
+Opt-in via `// @clay-reactive` + `clay app.ts --reactive-let`. Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps.
+
+## Package map (monorepo)
+
+| npm | Role |
+|-----|------|
+| `@close-by/clay` | `ui.*` facade (this skill ships here) |
+| `@close-by/clay-cli` | `clay` binary + bundled client |
+| `@close-by/clay-core` | Element tree, sessions, patches |
+| `@close-by/clay-components` | Wire element factories |
+| `@close-by/clay-server` | HTTP + WebSocket server |
+
+## Agent checklist
+
+1. Read `api.md` / `elements.md` before adding unfamiliar wire types.
+2. Use `ui.state` + `ui.auto` for live data; avoid manual `setText` loops.
+3. Rebuild client in monorepo after new element types (`bun run build:client`).
+4. Match existing demo patterns under `apps/demo/src/examples/` when unsure.
+5. Run `bun test` in touched packages; keep diffs minimal.

package/docs/README.md

@@ -0,0 +1,80 @@
+# Clay Documentation
+
+Server-driven UI for TypeScript, inspired by [NiceGUI](https://nicegui.io/).
+
+You write imperative `ui.*` code on the server. Clay owns a per-client element tree and syncs it to a thin React + ShadCN client over WebSocket.
+
+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`).
+
+## Guides
+
+| Doc | Description |
+|-----|-------------|
+| [Getting started](./getting-started.md) | Install, `clay` CLI, create a page |
+| [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 |
+| [Concepts](./concepts.md) | Mental model: sessions, elements, patches; **canonical `state`/`auto`/`timer` recipe**; reactive `let` alternative |
+| [Browser APIs](./browser-apis.md) | Prefer `ui.clipboard` / hash / `openExternal` — never `window` in page code |
+| [Production & security](./production.md) | Auth, server exposure, rate limits, boot parity |
+| [Ops patterns](./ops-patterns.md) | Dense consoles: chips, master–detail, feeds, sensitive logs, auth nav |
+| [API reference](./api.md) | `ui.*`, `Element` methods, `reactive`, helpers |
+| [Elements](./elements.md) | All element types and props |
+| [WebSocket protocol](./protocol.md) | Client ↔ server message formats |
+| [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`) |
+| [AI UI](./ai.md) | `ui.ai.*` visual AI primitives (no model runtime) |
+| [DuckDB](./duckdb.md) | Multi-DB DuckDB wrapper (`@close-by/clay-duckdb`) |
+| [Kibana](./kibana.md) | Kibana REST + ES search (`@close-by/clay-kibana`) |
+| [ClickHouse](./clickhouse.md) | Multi-connection ClickHouse wrapper (`@close-by/clay-clickhouse`) |
+
+## Quick start
+
+```bash
+bun install
+bun run build:client   # monorepo: build + copy client into @close-by/clay-cli
+bun run 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(() => {
+  let count = 0;
+  const label = ui.label(`Count: ${count}`);
+
+  ui.row(() => {
+    ui.button('-', {
+      onClick: () => {
+        count--;
+        label.setText(`Count: ${count}`);
+      },
+    });
+    ui.button('+', {
+      onClick: () => {
+        count++;
+        label.setText(`Count: ${count}`);
+      },
+    });
+  });
+});
+```
+
+Multi-page with shell:
+
+```bash
+bun run clay ./pages --app --title "My App"
+```
+
+Or library-style entry (`loadPages` + `ui.run({ app })`) — see [Getting started](./getting-started.md).
+
+## Naming
+
+Public Clay APIs and the wire protocol use **camelCase** (`onClick`, `bindValue`, `setText`, element `type: "button"`).
+
+React/ShadCN components inside `@close-by/clay-client` stay PascalCase because React requires it — that layer is an implementation detail.

package/docs/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: clay
+description: >-
+  Build Clay server-driven UI apps with ui.* on Bun. Use when authoring Clay
+  pages, demos, or ops consoles; importing @close-by/clay; running clay CLI;
+  ui.page/ui.run/ui.state/ui.auto; or when the user asks about Clay, NiceGUI-style
+  TypeScript UI, or server-owned element trees.
+---
+
+# Clay
+
+Server-driven UI for TypeScript. Write imperative `ui.*` on the server; Clay owns a per-tab element tree and syncs it to a React + ShadCN client over WebSocket.
+
+**Clay is not React.** Do not write React components, JSX, or client-side screen logic for app pages. The React client is a renderer only.
+
+## Install and run
+
+```bash
+bun add @close-by/clay-cli @close-by/clay
+```
+
+```typescript
+// hello.ts
+import { ui } from '@close-by/clay';
+
+export default function () {
+  ui.label('Hello Clay');
+  ui.button('Ping', { onClick: () => ui.notify('hi', 'success') });
+}
+```
+
+```bash
+bunx clay hello.ts   # http://localhost:3000
+```
+
+**Monorepo (this repo):** `bun run build:client` before `bun run demo` or `bun run clay …` — new wire types require a rebuilt client bundle.
+
+## Mental model
+
+1. `ui.page(path, fn)` or `ui.run(fn)` builds an **element tree** on the server.
+2. Each browser tab = one **WebSocket session**; page code runs once per tab.
+3. User events → server handlers → **patches** (`updateProps`, `setChildren`) → client re-render.
+4. Local `let` / session state is **per tab**, not shared. Use `ui.storage.app` for process-wide data.
+
+## Reactive UI (preferred)
+
+Keep mutable state **outside** rebuild blocks:
+
+```typescript
+const s = ui.state({ count: 0, items: [] as string[] });
+
+ui.auto(() => {
+  ui.label(`Count: ${s.count}`);
+  ui.button('+', { onClick: () => { s.count++; } });
+  for (const item of s.items) ui.label(item);
+});
+
+// Or bind one label without a full block:
+ui.label(() => `Count: ${s.count}`);
+```
+
+| API | Use when |
+|-----|----------|
+| `ui.state(initial)` | Reactive object; writes trigger tracked rebuilds |
+| `ui.auto(fn)` | Rebuild a UI block when tracked state changes |
+| `ui.label(() => …)` / `bindText` | Patch text only (stable tree) |
+| `bindValue` | Two-way inputs |
+| `ui.refreshable` + `.refresh()` | Simple one-shot structural rebuilds |
+| `ui.timer(ms, fn)` | Poll / clock ticks inside reactive pages |
+
+**Inside `ui.auto`:** child tree shape (types + counts) should stay stable when possible — then updates use `updateProps` instead of remounting. For toggling optional `className`, use `undefined` to clear (Clay sends `null` patches).
+
+**Button groups:** use `variant: 'outline'` on all segmented buttons; highlight selection with `className: active ? 'bg-accent' : undefined`.
+
+## Pages and layout
+
+```typescript
+ui.page('/dashboard', () => {
+  ui.column({ gap: 4 }, () => {
+    ui.row({ gap: 2 }, () => {
+      ui.button('Save', { onClick: save });
+    });
+    ui.card({ title: 'Stats' }, () => {
+      ui.label('…');
+    });
+  });
+});
+```
+
+- Nest with callbacks: `ui.row(() => { … })`, `ui.column(() => { … })`.
+- Tailwind: `ui.label('x').classes('text-sm text-muted-foreground')` or pass `className` in props.
+- Toasts: `ui.notify('Saved', 'success')`.
+
+## Do not
+
+- Import React, write JSX, or add client components for screens.
+- Use `window`, `document`, `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Assume `let` is shared across tabs or users.
+- Use `ui.ai.*` as an LLM runtime — it is visual primitives only.
+
+## Docs (shipped with package)
+
+After install, read version-matched docs at `node_modules/@close-by/clay/docs/`:
+
+| Doc | Purpose |
+|-----|---------|
+| `getting-started.md` | CLI, first app, publish |
+| `concepts.md` | Sessions, patches, storage |
+| `api.md` | Full `ui.*` reference |
+| `elements.md` | Wire types → client mapping |
+| `reactive-let.md` | `ui.state` / `ui.auto` / compile-time `let` |
+| `ops-patterns.md` | Dense consoles, feeds, tables |
+| `examples.md` | Demo route catalog |
+
+Resolve docs programmatically: `resolveClayDocsDir()` from `@close-by/clay/docs-dir`.
+
+## Optional compile-time reactive `let`
+
+Opt-in via `// @clay-reactive` + `clay app.ts --reactive-let`. Prefer explicit `ui.state` + `ui.auto` for production/async-heavy apps.
+
+## Package map (monorepo)
+
+| npm | Role |
+|-----|------|
+| `@close-by/clay` | `ui.*` facade (this skill ships here) |
+| `@close-by/clay-cli` | `clay` binary + bundled client |
+| `@close-by/clay-core` | Element tree, sessions, patches |
+| `@close-by/clay-components` | Wire element factories |
+| `@close-by/clay-server` | HTTP + WebSocket server |
+
+## Agent checklist
+
+1. Read `api.md` / `elements.md` before adding unfamiliar wire types.
+2. Use `ui.state` + `ui.auto` for live data; avoid manual `setText` loops.
+3. Rebuild client in monorepo after new element types (`bun run build:client`).
+4. Match existing demo patterns under `apps/demo/src/examples/` when unsure.
+5. Run `bun test` in touched packages; keep diffs minimal.

package/docs/ai.md

@@ -0,0 +1,65 @@
+# AI UI (`ui.ai.*`)
+
+Visual, data-driven primitives for AI-native interfaces. Callers pass props (messages, tools, status, text) and handle events (`onSubmit`, `onApprove`, …). **No AI SDK / model runtime** lives inside clay.
+
+Inspired by [Beautiful UI](https://www.beautifului.dev/) patterns; reimplemented with clay factories + ShadCN/Tailwind on the client.
+
+## Quick start
+
+```ts
+import { ui } from '@close-by/clay';
+
+ui.ai.chat({
+  tabs: [{ id: 'flavors', label: 'Flavors' }],
+  activeTab: 'flavors',
+  messages: [
+    { id: '1', role: 'user', text: 'Compare mint chip…' },
+    {
+      id: '2',
+      role: 'assistant',
+      text: 'Mint chip is up 12%.',
+      thinking: [{ kind: 'reasoning', title: 'Comparison', durationMs: 2000 }],
+    },
+  ],
+  onSubmit: (text) => {
+    // App owns state; patch via chat.setMessages(...) or refreshable
+  },
+});
+
+ui.ai.promptBar({
+  placeholder: 'Ask…',
+  sources: [{ id: 'v1', label: 'Vanilla 1' }],
+  models: [{ id: 'gpt', label: 'GPT' }],
+  onSubmit: (value) => {},
+});
+```
+
+Demo gallery: `/examples/ai` (`AiDemo.ts`).
+
+**State note:** `ui.ai.chat` is intentionally imperative (`var messages` + `chat.setMessages`). Surrounding controls can use `ui.state`; do not wrap the whole chat in `ui.auto` (remounts the composer). See [Ops patterns — ai.chat](./ops-patterns.md#uiaichat-and-state).
+
+## Wire types
+
+| `ui.ai.*` | Wire `type` | Notes |
+|-----------|-------------|--------|
+| `loader` | `aiLoader` | Variants: `drive` / `dots` / `orbit` / `pixel`; optional `startedAt` elapsed |
+| `thinking` | `aiThinking` | Expandable step traces (`steps` / `reasoning` / `search` / `coding`) |
+| `message` | `aiMessage` | Role, markdown/text, sources, actions, follow-ups, `streaming?` |
+| `chat` | `aiChat` | Tabs + messages + composer; `AiChatElement` owns `setMessages` / `setActiveTab` |
+| `promptBar` | `aiPromptBar` | Textarea, @sources, /commands, model picker, dictate stub |
+| `codeBlock` | `aiCodeBlock` | Filename + optional streaming cue (Shiki) |
+| `approval` | `aiApproval` | HITL option cards |
+| `toolChips` | `aiToolChips` | Compact tool / edit chips |
+| `tasks` | `aiTasks` | Nested running / failed / completed rows |
+| `recommendation` | `aiRecommendation` | Confidence + alternatives |
+| `context` | `aiContext` | Retrieved chunks + sources |
+| `diffTable` | `aiDiffTable` | Compact proposed-edit table (not DataTable) |
+| `insights` | `aiInsights` | Paged insight cards |
+| `selectionActions` | `aiSelectionActions` | Selection text + action strip |
+| `fineTune` | `aiFineTune` | Inspector-style field editors → `onChange` |
+
+**Skipped overlaps:** use `ui.dataTable` for records/filter tables, `ui.app` for sidebar nav, `ui.command` for search.
+
+## Events (common)
+
+`submit`, `followUp`, `action`, `tabChange`, `sourceRemove`, `modelChange`, `command`, `dictate`, `approve`, `reject`, `chipClick`, `taskClick`, `accept`, `alternative`, `chunkClick`, `rowClick`, `indexChange`, `prompt`, `change`, `toggle`.