@close-by/clay 0.2.7 → 0.2.8

package/docs/ops-patterns.md

@@ -0,0 +1,176 @@
+# Ops console patterns
+
+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.
+
+## Status chips
+
+```ts
+ui.badge('ok', { size: 'xs', color: 'emerald' });
+ui.badge('warn', { size: 'xs', color: 'amber', variant: 'outline' });
+ui.badge('error', { size: 'xs', color: 'red' });
+```
+
+| Prop | Notes |
+|------|--------|
+| `size: 'xs'` | Compact ops chip (`h-5` / `text-[10px]`) |
+| `color` | Named (`green`, `red`, `amber`, …) or CSS (`#22c55e`); overrides `variant` |
+| `variant` | `default` / `secondary` / `destructive` / `outline` when `color` unset |
+
+## Copy & external links
+
+```ts
+ui.copyButton(traceId); // icon-only
+ui.copyButton(traceId, { label: 'Copy', size: 'sm' });
+
+ui.externalLink('Open in SigNoz', signozUrl);
+// or
+ui.link('Docs', 'https://example.com', { external: true });
+ui.openExternal(signozUrl); // no visible control — protocol helper
+```
+
+Never use `navigator.clipboard` / `window.open` in page code — see [Browser APIs](./browser-apis.md).
+
+## Master–detail with `ui.resizable`
+
+```ts
+const live = ui.state({ selectedId: null as string | null, rows: [] as Row[] });
+
+ui.auto(() => {
+  ui.resizable(
+    { orientation: 'horizontal', className: 'h-[calc(100vh-8rem)] w-full min-h-[24rem]' },
+    (r) => {
+      r.panel({ defaultSize: 40, minSize: 28 }, () => {
+        ui.auto(() => {
+          for (const row of live.rows) {
+            ui.button(row.id, {
+              variant: row.id === live.selectedId ? 'secondary' : 'ghost',
+              className: 'w-full justify-start',
+              onClick: () => {
+                live.selectedId = row.id;
+              },
+            });
+          }
+        });
+      });
+      r.panel({ defaultSize: 60, minSize: 36 }, () => {
+        ui.auto(() => {
+          const row = live.rows.find((x) => x.id === live.selectedId);
+          if (!row) {
+            ui.label('Select a row').classes('text-sm text-muted-foreground');
+            return;
+          }
+          // detail…
+          ui.label(row.id);
+        });
+      });
+    },
+  );
+});
+```
+
+Keep **separate** `ui.auto` regions for list vs detail so selection updates do not remount the whole shell. Default panel sizes (`defaultSize` / `minSize`) are percentages.
+
+## Live feed rows (not `ui.list`)
+
+`ui.list` is a **grouped drag-and-drop** list — wrong tool for a live ops feed. Use **`ui.feedList`** + **`ui.feedRow`** (app still owns polling, merge, and filters):
+
+```ts
+ui.auto(() => {
+  ui.feedList(() => {
+    for (const unit of live.units) {
+      ui.feedRow(
+        {
+          selected: live.selectedId === unit.id,
+          status: { color: unit.ok ? 'emerald' : 'red' },
+          title: unit.id,
+          meta: unit.summary,
+          issue: unit.error ?? undefined,
+          marker: unit.isNew ? 'new' : undefined,
+          trailing: () => formatRelative(unit.at, live.clock),
+          onClick: () => {
+            live.selectedId = unit.id;
+          },
+          onTrailingClick: () => toggleAbsoluteTime(unit.id),
+        },
+        () => {
+          for (const chip of unit.chips) {
+            ui.badge(chip.label, { size: 'xs', color: chip.color });
+          }
+        },
+      );
+    }
+  });
+});
+```
+
+| Primitive | Role |
+|-----------|------|
+| `ui.feedList` | Bordered `divide-y` container — default ops feed chrome |
+| `ui.feedRow` | One row: status dot, link title, meta / issue / hint, trailing time |
+| Footer callback | Optional chips or extra content when there is no `issue` line |
+
+Manual `ui.row` composition still works when you need a custom layout.
+
+## Logs / traces — sensitive bodies
+
+Structured logs often contain API keys or partner tokens. Scrubbing is the **app’s** job; Clay can still reduce shoulder-surfing:
+
+```ts
+ui.codeBlock({
+  code: rawLogLine,
+  language: 'json',
+  sensitive: true, // blurred until Reveal; copy disabled until then
+});
+```
+
+Still redact before display when possible. Prefer VPN + auth for hubs that surface production logs.
+
+## Auth + role-filtered nav
+
+Nav filtering is UX only — always enforce roles in the page builder.
+
+```ts
+// pageMeta
+export const pageMeta = {
+  label: 'Admin',
+  icon: 'settings',
+  order: 90,
+  roles: ['admin'],
+};
+
+// shell
+ui.run({
+  authSecret: process.env.CLAY_AUTH_SECRET!,
+  app: {
+    title: 'Hub',
+    nav: () => ui.navFromPages({ role: currentUser.role }),
+  },
+});
+
+// page
+ui.page('/admin', () => {
+  requireRole('admin'); // @close-by/clay-auth
+  // …
+});
+```
+
+See `/examples/auth` and [API — auth](./api.md).
+
+## `ui.ai.chat` and state
+
+`AiChatElement` owns messages via `setMessages` / imperative updates. That is intentional — the chat widget is a stateful client control, not a pure `auto` tree.
+
+```ts
+const session = ui.state({ conversationId: '…' });
+var messages: AiChatMessage[] = [/* welcome */];
+
+const chat = ui.ai.chat({
+  messages,
+  onSubmit: async (text) => {
+    // update messages, then:
+    chat.setMessages(messages);
+  },
+});
+```
+
+Use `ui.state` for surrounding controls (conversation id, busy flags). Prefer documenting this exception over forcing chat through `ui.auto` (would remount the composer). Full API: [AI UI](./ai.md).

package/docs/production.md

@@ -0,0 +1,71 @@
+# Production & security
+
+Clay apps are **server-driven**: page builders and most event handlers run in your Bun process. Every button click, input change, and timer tick can hit server code. Treat Clay like a web API plus UI, not a static site.
+
+## Server exposure
+
+| Fact | Implication |
+|------|-------------|
+| WebSocket + HTTP to one Bun process | Scale horizontally only with shared session/storage adapters; rate-limit at the edge or in middleware |
+| Page code runs with full server privileges | Never expose unauthenticated Clay hubs to the public internet without hardening |
+| No built-in multi-tenant isolation | One process serves all connected clients; use auth + per-user data in handlers |
+
+**Defaults that fit internal ops tools:** VPN or private network, single-team auth, read-heavy dashboards.
+
+## Authentication
+
+Clay ships hooks for real identity beyond anonymous `userId`:
+
+```ts
+import { ui } from '@close-by/clay';
+import { requireRole } from '@close-by/clay-auth';
+
+ui.run({
+  authSecret: process.env.CLAY_AUTH_SECRET!,
+  app: {
+    title: 'Hub',
+    nav: () => ui.navFromPages({ role: currentUser.role }),
+  },
+});
+
+ui.page('/admin', () => {
+  requireRole('admin');
+  // …
+});
+```
+
+- `pageMeta.roles` — hide nav items via `ui.navFromPages({ role })` (UX only)
+- `requireRole` / guards in the page builder — **enforce** access before building sensitive UI
+- See [API — auth](./api.md), `/examples/auth`, and [Ops patterns — auth nav](./ops-patterns.md#auth--role-filtered-nav)
+
+Nav filtering is not authorization. Always guard pages that must not leak data.
+
+## Rate limits & abuse
+
+Clay does not ship a global rate limiter. For handlers that trigger expensive work (ClickHouse queries, re-dispatch, file export):
+
+- Keep queries bounded (limits, time windows)
+- Use app-level throttling/debounce on hot actions
+- Put the hub behind a reverse proxy with rate limits if exposed beyond VPN
+
+## Sensitive data in UI
+
+Logs, traces, and config payloads may contain secrets. Clay provides `ui.codeBlock({ sensitive: true })` to reduce shoulder-surfing; **scrubbing before display is still the app's job**. See [Ops patterns — sensitive bodies](./ops-patterns.md#logs--traces--sensitive-bodies).
+
+## Boot parity (CLI vs library)
+
+Production should use **library mode** (`ui.run`) with the same port, CSS, and flags as dev CLI. Checklist: [Boot: CLI vs library](./boot.md).
+
+| Setting | CLI | Library |
+|---------|-----|---------|
+| Port | `-p` / `_run.ts` | `ui.run({ port })` |
+| CSS | `_run.ts` → `css` | `ui.run({ css })` |
+| Client assets | bundled `clientDir` | `resolveClayClientDir()` |
+| Reactive-let | `--reactive-let` (opt-in) | off unless you register the plugin |
+| Reload stubs | `.clay-reload/` (gitignored) | N/A in prod |
+
+## Related
+
+- [Browser APIs](./browser-apis.md) — never `window` / `navigator` in page code
+- [Concepts — canonical recipe](./concepts.md#canonical-recipe-state--auto--timer)
+- [Reactive let — decision table](./reactive-let.md#decision-table-complex-pages)

package/docs/protocol.md

@@ -0,0 +1,238 @@
+# WebSocket protocol
+
+All fields are **camelCase**. Transport: single WebSocket at `/ws`.
+
+## Connection flow
+
+1. Browser loads SPA HTML + `/assets/index.js` + `/assets/index.css`
+2. Client opens `ws://host/ws` (or `wss://`)
+3. Client sends `{ op: "hello", path: "/examples/todo" }`
+4. Server creates `ClientSession`, runs the page builder, replies `{ op: "mount", sessionId, tree }`
+5. Interaction continues with `event` ↔ `patch` (plus optional `notify` / `navigate` / `theme`)
+
+On unexpected socket close, the client reconnects with exponential backoff (500ms → 10s) and shows a corner **Clay** status chip (`reloading` / brief `ready`). A sticky “Disconnected — reconnecting…” toast appears only if the outage lasts longer than ~4s. Matching `app` chrome stays mounted across remounts.
+## Client → server
+
+### `hello`
+
+```json
+{ "op": "hello", "path": "/examples/counter", "userId": "optional-stable-id", "hash": "optional-hash-without-hash-sign", "browserStorage": {}, "clientStorage": {}, "tabStorage": {} }
+```
+
+Client connects (or sends another `hello` after navigate on the same socket) and identifies the page. Optional `userId` (from localStorage/cookie) enables `ui.storage.user` unless overridden by `resolveUserId`. Optional `hash` (no leading `#`) hydrates `ui.getUrlHash()`. Optional `browserStorage` / `clientStorage` / `tabStorage` bags hydrate `ui.storage.browser` / `ui.storage.client` / `ui.storage.tab`.
+
+Sent on connect and after client-side navigation. The React client keeps matching `app` shell chrome mounted across remounts; only inset content is replaced.
+
+### `event`
+
+```json
+{ "op": "event", "id": "input_abc", "type": "input", "value": "hello" }
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Element id |
+| `type` | `string` | Event name (`click`, `input`, `change`, …) |
+| `value` | `unknown` | Optional payload (string, number, boolean, …) |
+
+## Server → client
+
+### `mount`
+
+```json
+{
+  "op": "mount",
+  "sessionId": "session_…",
+  "tree": {
+    "id": "root_…",
+    "type": "root",
+    "props": {},
+    "children": [ /* ElementNode[] */ ]
+  }
+}
+```
+
+### `patch`
+
+```json
+{
+  "op": "patch",
+  "patches": [
+    { "op": "updateProps", "id": "label_1", "props": { "text": "Count: 1" } },
+    { "op": "setChildren", "id": "refreshable_1", "children": [ /* … */ ] }
+  ]
+}
+```
+
+### Patch ops
+
+| `op` | Fields | Meaning |
+|------|--------|---------|
+| `replace` | `id`, `node` | Replace entire subtree at `id` |
+| `updateProps` | `id`, `props` | Shallow-merge props |
+| `setChildren` | `id`, `children` | Replace children array |
+| `remove` | `id` | Remove node from parent |
+
+### `navigate`
+
+```json
+{ "op": "navigate", "path": "/examples/todo" }
+```
+
+Client updates history (`pushState` + `popstate`) and sends a new `hello` on the same WebSocket. Matching `app` chrome stays mounted on the client; inset content remounts.
+
+### `reconnect`
+
+```json
+{ "op": "reconnect" }
+```
+
+Client closes the socket and reconnects (picks up updated HttpOnly cookies on the next upgrade). Used after auth cookie changes when a full soft-reconnect is requested without going through `authSession`.
+
+### `authSession`
+
+```json
+{ "op": "authSession", "action": "establish", "token": "signed…", "path": "/account" }
+```
+
+```json
+{ "op": "authSession", "action": "clear", "path": "/login" }
+```
+
+Client `POST`s / `DELETE`s `/auth/session` (credentials included), optionally updates the SPA path, then soft-reconnects so the next `hello` sees the cookie. Requires `ui.run({ authSecret })`.
+
+### `notify`
+
+```json
+{
+  "op": "notify",
+  "id": "toast_1",
+  "message": "Saved!",
+  "type": "success",
+  "duration": 2500,
+  "position": "bottom-right",
+  "description": "Optional secondary line"
+}
+```
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `id` | `string` | required (server) | Passed to Sonner as toast id |
+| `message` | `string` | | Toast title |
+| `type` | `info\|success\|warning\|error` | `info` | Maps to `toast.info` / `success` / `warning` / `error` |
+| `duration` | `number` | `2500` | ms; `0` → Sonner `Infinity` (sticky) |
+| `position` | `top-left\|top-right\|bottom-left\|bottom-right` | `bottom-right` | Sonner position |
+| `description` | `string` | | Optional Sonner description |
+
+Client renders via ShadCN `<Toaster />` + imperative `toast` from `sonner`.
+
+### `dismissNotify`
+
+```json
+{ "op": "dismissNotify", "id": "toast_1" }
+```
+
+Calls `toast.dismiss(id)` on the client.
+
+### `download`
+
+```json
+{
+  "op": "download",
+  "filename": "data.csv",
+  "mime": "text/csv;charset=utf-8",
+  "content": "Title,Status\nAlpha,done"
+}
+```
+
+Client triggers a file download via a temporary Blob URL.
+
+### `clipboard`
+
+```json
+{ "op": "clipboard", "content": "Title\tStatus\nAlpha\tdone" }
+```
+
+Client writes `content` with `navigator.clipboard.writeText` (shows an error toast on failure). Prefer `ui.clipboard` from page code.
+
+### `setUrlHash`
+
+```json
+{ "op": "setUrlHash", "hash": "trace-abc" }
+```
+
+Client sets `location.hash` via `history.replaceState` (`hash` has no leading `#`; empty string clears). Hydrated the other way on `hello.hash`. Prefer `ui.setUrlHash` / `ui.getUrlHash`.
+
+### `openExternal`
+
+```json
+{ "op": "openExternal", "url": "https://example.com" }
+```
+
+Client runs `window.open(url, '_blank', 'noopener,noreferrer')`. Prefer `ui.openExternal`.
+
+### `theme`
+
+```json
+{ "op": "theme", "theme": "dark" }
+```
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `theme` | `light\|dark\|system` | Applied via next-themes; persisted under `clay-theme` |
+
+Sent by `ui.theme.set(...)`.
+
+### `runJavaScript`
+
+```json
+{ "op": "runJavaScript", "code": "console.log('hi')" }
+```
+
+Client evaluates the snippet (trusted server-authored code).
+
+### `scroll`
+
+```json
+{ "op": "scroll", "target": "window", "top": "bottom", "behavior": "smooth" }
+```
+
+```json
+{ "op": "scroll", "target": "selector", "selector": "#footer", "block": "start" }
+```
+
+### `clientStorage`
+
+```json
+{ "op": "clientStorage", "scope": "browser", "action": "set", "key": "theme", "value": "dark" }
+```
+
+Updates the client Web Storage bag used by `ui.storage.browser` (`localStorage`), `ui.storage.client` (`sessionStorage`), or `ui.storage.tab` (`sessionStorage`, key `clay-tab-storage`). Write-through keeps the bag warm for the next `hello`.
+
+### `error`
+
+```json
+{ "op": "error", "message": "No page registered for /missing" }
+```
+
+## Element JSON
+
+```typescript
+type ElementNode = {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  children: ElementNode[];
+};
+```
+
+- No functions on the wire
+- Interactive nodes include `props.events: string[]`
+- Values for forms live in `props.value` (checkboxes use boolean `value`)
+
+## TypeScript types
+
+Shared definitions live in:
+
+- `packages/core/src/protocol.ts`
+- `packages/client/src/protocol.ts` (mirror for the browser bundle)