@close-by/clay 0.2.6 → 0.2.8

package/docs/reactive-let.md

@@ -0,0 +1,217 @@
+# Compile-time reactive `let`
+
+Status: **Phase 1 shipped** (`ui.state` + `ui.auto`). **Phase 2 shipped** (`@close-by/clay-compiler` transform + optional `clay --reactive-let`; implicit regions, dep-isolated `auto`, compile-time `bindText` for labels, rest/nested destructuring, loop-scoped keyed state, shadow renames).
+
+**Recommended for new demos and toy pages:** write plain `let` with `// @clay-reactive` and `clay --reactive-let` — see [Happy path](#happy-path-let--clay-reactive) below.
+
+**Production / dense apps:** Prefer Phase 1 (`ui.state` / `ui.auto`) when you need explicit control, async load patterns, or want zero compiler surface. Phase 2 remains **opt-in** (CLI plugin off unless `--reactive-let`; transform only with a pragma or `"use reactive";`). Silent page-wide rewrites caused blank mounts and CJS interop pain in production hubs — see [Known failure modes](#known-failure-modes).
+
+## Goal
+
+NiceGUI-style automatic UI updates when local state changes, without manual `setText` / `refresh` on every write.
+
+## Phase 1 (shipped)
+
+Runtime helpers — no compiler:
+
+```ts
+const s = ui.state({ count: 0 });
+ui.auto(() => {
+  ui.button('Inc', { onClick: () => { s.count++; } });
+  ui.label(`Count: ${s.count}`); // patches text when s.count changes (stable tree)
+});
+
+// Or bind a single label without wrapping `auto`:
+ui.label(() => `Count: ${s.count}`);
+```
+
+| API | Behavior |
+|-----|----------|
+| `ui.state(initial)` | Alias for `reactive()` — proxy that notifies on property writes |
+| `ui.auto(fn)` | `RefreshableElement` that tracks `state`/`reactive` **reads** during `fn`, then rebuilds on those writes. When the child tree **shape** (types + counts) is unchanged and contains no nested `refreshable`/`auto`, updates go via `updateProps` (`setText`/`setValue`-style) instead of `setChildren` remount |
+| `ui.label(() => string)` | Creates a label and `.bindText(compute)` — re-runs compute when tracked reads change |
+| `Element.bindText(fn)` | Same tracking as `auto`, but only patches `text` |
+| `reactive` / `subscribe` / `bindValue` / `bindTextFrom` | Unchanged |
+
+**Rules**
+
+- Keep mutable state **outside** `ui.auto` (or it resets each rebuild).
+- Only properties **read** during the last builder run are tracked.
+- Prefer `ui.label(() => …)` / `bindText` / `bindTextFrom` / `bindValue` when a full block rebuild is unnecessary.
+- Structural changes inside `auto` (added/removed children, type changes, nested `auto`) still remount via `setChildren`.
+
+Tests: `packages/core/src/auto.test.ts`, `packages/core/src/element.test.ts`.
+
+## Happy path: `let` + `@clay-reactive`
+
+For counter-style pages and demos, you can skip manual `ui.auto` / `label.setText`:
+
+```ts
+// counter-let.ts — run: clay counter-let.ts --reactive-let
+// @clay-reactive
+import { ui } from '@close-by/clay';
+
+export default function () {
+  let count = 0;
+  ui.label(`Count: ${count}`);
+  ui.row({ gap: 2 }, () => {
+    ui.button('-', { onClick: () => { count--; } });
+    ui.button('+', { onClick: () => { count++; } });
+  });
+}
+```
+
+Clay lifts `count` into `ui.state`, turns the label into `bindText`, and leaves buttons as handler-only writes. No `refresh()` calls.
+
+| 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 |
+| 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.
+
+## Phase 2 (shipped, opt-in)
+
+Package `@close-by/clay-compiler` rewrites a **documented subset** of `let` into Phase 1 APIs.
+
+### Opt-in (required)
+
+Both of:
+
+1. **CLI / loader:** pass `--reactive-let` to `clay` (or call `registerReactiveLetPlugin()` yourself). Off by default.
+2. **Source:** one of:
+   - File pragma: `// @clay-reactive` (near the top of the file) — applies to **`ui.page` / `page` callbacks only**
+   - Block directive as the first statement: `"use reactive";` — required for nested helpers / `ui.column(() => …)` lets
+
+`ui.page(...)` alone does **not** opt in. Module-level helpers (`function mergeUnits() { … }`) and nested `function` / arrow bodies do **not** inherit the file pragma — use `"use reactive";` inside the page callback or a nested site when needed.
+
+### Who wraps `ui.auto`?
+
+Compile-time region analysis **does not** see into nested function bodies. Authors must still wrap rebuild regions when UI is built from helpers or widget callbacks:
+
+| Pattern | Who wraps `ui.auto`? |
+|---------|----------------------|
+| Inline UI in the reactive site body that reads lets | Transform (or `bindText` on labels) |
+| Named `renderX()` builders | **Author** — `ui.auto(() => { renderFeed(); })` |
+| UI inside widget callbacks (`row` / `column` / `dialog` / …) that need rebuild | **Author**, **or** read lets at the site top level so the transform can see them |
+
+Bare top-level `renderFeed()` calls that read lifted lets are **auto-wrapped** in `ui.auto(() => { renderFeed(); })` by default (`autoWrapBuilders: true`). The same applies to bare builder calls **inside Clay widget callbacks** (`ui.row`, `ui.column`, `ui.resizable` / `r.panel`, …) — including **composer** helpers that only call other state-reading builders, and calls **with arguments** (`renderFeed('cls')`). Event handlers (`onClick`, `onChange`, …) are excluded. Pass `{ autoWrapBuilders: false }` to the transform to **warn** instead.
+
+Inline UI in widget callbacks (`ui.label(expr)`, `ui.icon(…, { className: expr })`, …) gets **bindText** or nested **`ui.auto`** via region analysis — no manual wrap when the transform can see the reads.
+
+### Decision table (complex pages)
+
+| You wrote… | Clay does… | You must… |
+|------------|------------|-----------|
+| `let x = Date.now()` / `defaultRangeFrom()` / `new Map()` | Lifts into `ui.state({ x: … })` one-shot | Nothing |
+| `renderList()` at page top level (bare call) | Wraps in `ui.auto` | Nothing |
+| `renderList()` inside `ui.row(() => …)` (bare call) | Wraps in `ui.auto` inside the widget callback | Nothing |
+| Inline `ui.label` / `ui.icon` reads in widget callback | `bindText` or nested `ui.auto` | Nothing (when reads are visible to the transform) |
+| `units.filter(u => { … })` reading lifted state | Plain JS (no `ui.auto` inside filter) | Nothing |
+| `onClick` / `onChange` / `ui.timer` handler | Not a build region | Normal JS |
+| `const live = ui.state({…})` (no pragma) | Unchanged | Explicit `ui.auto` (Phase 1) |
+| Local `const detail = …` shadows lifted `let detail` | Renames in emit + compile warning | Prefer distinct names |
+
+### What transforms
+
+Simple `let` / `const` declarations (identifier or object/array destructuring, including **nested** and **rest** patterns) with a simple initializer **anywhere** in an eligible function body, including nested blocks (`if` / bare blocks / `try` / `switch`) and **inside loops** (loop-scoped bindings use keyed `ui.state` maps), but **not** inside nested function scopes (nested functions are separate sites only with their own `"use reactive";`):
+
+```ts
+// @clay-reactive
+import { ui } from '@close-by/clay';
+
+ui.page('/', () => {
+  ui.label('hi');
+  let count = 0;
+  ui.label(`Count: ${count}`);
+  ui.button('+', { onClick: () => { count++; } });
+});
+```
+
+Becomes roughly:
+
+```ts
+ui.page('/', () => {
+  const __clay_s0 = ui.state({ count: 0 });
+  ui.label('hi'); // inert — no build-time read of count
+  ui.label(() => `Count: ${__clay_s0.count}`); // compile-time bindText
+  ui.button('+', { onClick: () => { __clay_s0.count++; } }); // handler-only write
+});
+```
+
+**Implicit regions**
+
+| Pattern | Result |
+|---------|--------|
+| `ui.label(expr)` that reads tracked state | `ui.label(() => expr)` — runtime `bindText`, no `auto` |
+| Other build-time reads (e.g. `ui.badge({ text: String(n) })`, `ui.badge(String(n))`, `ui.button(String(n))`, `ui.iconText(String(n), { icon })`) | compile-time bindText when the text expr reads state |
+| Other build-time reads without bindText sugar | `ui.auto` around that statement |
+| Contiguous autos with **disjoint** deps | Separate `auto` regions |
+| Contiguous autos with **overlapping** deps | One shared `auto` |
+| Shell / layout / handler-only writes | Stay outside any `auto` |
+| Nested `ui.column(() => …)` reading outer state | Inner region / bindText inside the callback |
+
+**Simple initializers:** literals; `undefined`; unary `±!~`; binary / conditional / template expressions of simples; property / element access of simples; identifiers (outer bindings); shallow array/object literals; **call / `new`** with simple callees and args; nullish coalescing (`??`) for destructuring defaults. **Destructuring:** simple and **nested** patterns (`let { a: { b } }`); **rest** (`let { x, ...rest }`) lifts named fields and keeps `const { ...rest }`. **Loop-scoped** `let` inside `for` / `for-of` bodies becomes keyed state (`__clay_l0_open[key]`) so each iteration keeps its own mutable slot. **Not** transformed: `await`, sibling-let refs (`let a = 1; let b = a + 1` aborts the site), spread args in initializers.
+
+**Shadowing:** a later local `const detail = …` that reuses a lifted name is **renamed** in emit by default (`renameShadowedLocals: true`) and emits a compile warning with the generated name. Pass `{ renameShadowedLocals: false }` to warn without renaming.
+
+Type positions are never rewritten — a lifted `let loading` may share a name with `type DetailState { loading: boolean }` without breaking emit.
+
+### CLI
+
+```bash
+clay ./pages --app --reload                 # no reactive-let plugin
+clay hello.ts --reactive-let                # enable Bun loader; still need pragma / "use reactive"
+clay hello.ts --no-reactive-let             # explicit off (same as default)
+```
+
+Programmatic:
+
+```ts
+import { registerReactiveLetPlugin } from '@close-by/clay-compiler/plugin';
+import { transformReactiveLet } from '@close-by/clay-compiler';
+
+registerReactiveLetPlugin();
+```
+
+### Known failure modes
+
+When the transform or Bun loader was on by default (pre–opt-in), dense apps hit:
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Blank UI / mount errors | Simple `let`s inside `ui.page` rewritten into a mega-`auto` that fights async load / structural patterns |
+| `@clickhouse/client` (and similar CJS) named-export breakage | Bun `onLoad` plugin in the path; prefer `--no-reactive-let` (default) or Clay’s HTTP helpers until interop is proven. Dev: `[clay-reactive-let]` warns when a rewritten file imports a known-fragile package. |
+
+Mitigation today: leave the plugin off; use Phase 1 APIs. If you enable `--reactive-let`, only mark intentional toy/demo files with the pragma.
+
+### Limits
+
+- No `var`. Deeply nested patterns with rest at inner levels may abort the site.
+- Sibling initializers abort the site (`let b = a + 1` when both would lift).
+- Duplicate binding names in nested blocks abort the transform for that function.
+- Loop-scoped state keys prefer `String(row.id)` for `for (const row of …)` loops, with loop-index fallback when `.id` is missing.
+- Compile-time bindText covers `ui.label` / `label`, `ui.badge` / `badge` (positional + `{ text }`), `ui.button` / `button`, and `ui.iconText`.
+- Running the demo via plain `bun apps/demo/...` does **not** load the plugin unless you register it; use `clay --reactive-let` or `--preload`.
+- `const` is lifted like `let` (assignments become state writes). Prefer `let` in typed source if you reassign — `const` reassignment is a TS error before the transform runs.
+
+**Runtime:** nested `auto` / `refreshable` trees reuse in place when structure matches (`canReuseElementTree` in `@close-by/clay-core`) — inner regions keep their ids when an outer `auto` refreshes without touching inner deps.
+
+Tests: `packages/compiler/src/transform.test.ts`, `packages/core/src/auto.test.ts`.
+
+## Proof (Orders-shaped)
+
+| 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` |
+
+```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
+```
+
+Compiler coverage: `packages/compiler/src/orders-proof.test.ts` transforms the let demo and asserts separate list/detail regions (no mega-`auto`).
+
+Without `--reactive-let`, `let` assignments are silent no-ops (no error).

package/docs/tailwind.md

@@ -0,0 +1,73 @@
+# Tailwind CSS for Clay apps
+
+Clay auto-builds Tailwind utilities from your page modules. Use `.classes(...)` / `className` freely — no app Tailwind config, no separate CSS build step.
+
+## Zero-config (default)
+
+**CLI** (`clay ./pages` or `clay ./pages --reload`):
+
+- On by default; scans the entry directory
+- With `--reload`, rebuilds utilities on file changes
+- Opt out: `--no-tailwind`
+
+**Library mode** (`ui.run`):
+
+```typescript
+ui.run({
+  // default when `pages/`, `src/`, or `app/` exists under cwd
+  // tailwind: true,
+  // or: tailwind: { content: ['./pages'], watch: true },
+});
+```
+
+Generated CSS lands in `.clay/tailwind.css` and is injected via `css`. Add `.clay/` to `.gitignore`.
+
+`@close-by/clay` depends on `tailwindcss` and `@tailwindcss/cli` — you do not need to install them yourself.
+
+## What you get
+
+| Need | How |
+|------|-----|
+| Utilities in pages (`text-[10px]`, `w-[32rem]`, …) | Automatic scan + build |
+| Theme tokens (`--primary`, `--background`, …) | Optional extra `css` file (merged after utilities) |
+| Disable | `--no-tailwind` / `ui.run({ tailwind: false })` / `CLAY_NO_TAILWIND=1` |
+
+Clay’s shipped client already includes a Tailwind + shadcn **baseline**. Auto Tailwind adds **app-scanned** utilities on top (theme + utilities only — not a second full preflight).
+
+## Token overrides
+
+```css
+/* src/tokens.css */
+:root {
+  --primary: oklch(0.45 0.12 150);
+}
+```
+
+```typescript
+ui.run({
+  css: './src/tokens.css', // merged with auto Tailwind output
+});
+```
+
+## Custom scan roots
+
+```typescript
+ui.run({
+  tailwind: {
+    content: ['./pages', './lib/ui-helpers'],
+    watch: true,
+    appendCss: '/* optional extra CSS in the Tailwind input */',
+  },
+});
+```
+
+## Manual pipeline (optional)
+
+If you prefer your own Tailwind input/`@source` setup, turn auto off and inject a prebuilt file:
+
+```bash
+bunx clay ./pages --no-tailwind
+# and ui.run({ tailwind: false, css: './src/globals.generated.css' })
+```
+
+See [`examples/tailwind-app/`](../examples/tailwind-app/) for a minimal zero-config app.

package/docs/tutorial.md

@@ -0,0 +1,234 @@
+# Sample app: tasks
+
+A short walkthrough with the `clay` CLI: a tasks list, then two pages and a sidebar. Needs [Bun](https://bun.sh/) 1.1+.
+
+You will use a default export (the CLI registers `/` and starts the server), `bindValue` for the input, and `ui.refreshable` when the list changes.
+
+**Alternative:** for a counter-style app without manual `.refresh()`, see [reactive `let`](./reactive-let.md#happy-path-let--clay-reactive) (`// @clay-reactive` + `clay --reactive-let`). This tutorial teaches Phase 1 explicitly so the update model stays visible.
+
+## 1. Create a project
+
+```bash
+mkdir clay-tasks && cd clay-tasks
+bun init -y
+bun add @close-by/clay-cli @close-by/clay
+```
+
+In this Clay checkout, skip `bun add` and use `bun run clay …` after `bun run build:client`.
+
+## 2. A page the CLI can run
+
+Create `tasks.ts`. Export a **default function** — `clay` mounts it at `/`.
+
+```typescript
+// tasks.ts
+import { ui } from '@close-by/clay';
+
+export default function () {
+  ui.label('Tasks').classes('text-2xl font-semibold');
+  ui.label('Add items in the next step.').classes('text-sm text-muted-foreground');
+}
+```
+
+```bash
+bunx clay tasks.ts --reload --title Tasks
+```
+
+The browser should open on http://localhost:3000. Leave `--reload` on so later saves restart the server.
+
+## 3. Capture input
+
+`reactive` + `bindValue` keep the field in sync. `let` in the page builder is **per browser tab**.
+
+```typescript
+import { ui, reactive } from '@close-by/clay';
+
+export default function () {
+  const draft = reactive({ text: '' });
+
+  ui.label('Tasks').classes('text-2xl font-semibold');
+
+  ui.row(() => {
+    ui.input({ placeholder: 'What needs doing?' }).classes('flex-1').bindValue(draft, 'text');
+    ui.button('Add', {
+      onClick: () => {
+        const text = draft.text.trim();
+        if (!text) return;
+        ui.notify(`Would add: ${text}`, 'success');
+        draft.text = '';
+      },
+    });
+  }, { gap: 2 });
+}
+```
+
+Save, wait for the reload, type a line, click **Add**. You should get a toast.
+
+## 4. Render the list
+
+`setText` / `setValue` update an existing node. When rows appear or disappear, wrap that region in `ui.refreshable` and call `.refresh()`.
+
+```typescript
+import { ui, reactive } from '@close-by/clay';
+
+type Task = { id: string; text: string; done: boolean };
+
+export default function () {
+  const tasks: Task[] = [];
+  const draft = reactive({ text: '' });
+  let list: ReturnType<typeof ui.refreshable>;
+
+  ui.label('Tasks').classes('text-2xl font-semibold');
+
+  ui.row(() => {
+    ui.input({ placeholder: 'What needs doing?' }).classes('flex-1').bindValue(draft, 'text');
+    ui.button('Add', {
+      onClick: () => {
+        const text = draft.text.trim();
+        if (!text) return;
+        tasks.push({ id: String(Date.now()), text, done: false });
+        draft.text = '';
+        list.refresh();
+      },
+    });
+  }, { gap: 2 });
+
+  list = ui.refreshable(() => {
+    if (tasks.length === 0) {
+      ui.label('Nothing yet.').classes('text-sm text-muted-foreground');
+      return;
+    }
+    ui.column(() => {
+      for (const task of tasks) {
+        ui.label(task.text);
+      }
+    }, { gap: 2 });
+  });
+}
+```
+
+Add a couple of items. The list should grow without a full page reload.
+
+## 5. Toggle and delete
+
+Replace the `ui.label(task.text)` loop body with a checkbox and a delete button:
+
+```typescript
+        ui.row(() => {
+          ui.checkbox({
+            checked: task.done,
+            label: task.text,
+            onChange: (checked) => {
+              task.done = Boolean(checked);
+              list.refresh();
+            },
+          }).classes(task.done ? 'flex-1 line-through opacity-60' : 'flex-1');
+          ui.button('Delete', {
+            variant: 'ghost',
+            size: 'sm',
+            onClick: () => {
+              const i = tasks.indexOf(task);
+              if (i >= 0) tasks.splice(i, 1);
+              list.refresh();
+            },
+          });
+        }, { gap: 2 }).classes('items-center');
+```
+
+Handlers run on the **server**. Clay patches the client.
+
+## 6. Two pages and a shell
+
+Directory mode does **not** pick up default exports. Each file calls `ui.page` and may export `pageMeta` for the sidebar.
+
+```typescript
+// pages/tasks.ts
+import { ui, reactive } from '@close-by/clay';
+
+export const pageMeta = { label: 'Tasks', icon: 'list-todo', order: 10 };
+
+type Task = { id: string; text: string; done: boolean };
+
+ui.page('/', () => {
+  const tasks: Task[] = [];
+  const draft = reactive({ text: '' });
+  let list: ReturnType<typeof ui.refreshable>;
+
+  ui.label('Tasks').classes('text-2xl font-semibold');
+
+  ui.row(() => {
+    ui.input({ placeholder: 'What needs doing?' }).classes('flex-1').bindValue(draft, 'text');
+    ui.button('Add', {
+      onClick: () => {
+        const text = draft.text.trim();
+        if (!text) return;
+        tasks.push({ id: String(Date.now()), text, done: false });
+        draft.text = '';
+        list.refresh();
+      },
+    });
+  }, { gap: 2 });
+
+  list = ui.refreshable(() => {
+    if (tasks.length === 0) {
+      ui.label('Nothing yet.').classes('text-sm text-muted-foreground');
+      return;
+    }
+    ui.column(() => {
+      for (const task of tasks) {
+        ui.row(() => {
+          ui.checkbox({
+            checked: task.done,
+            label: task.text,
+            onChange: (checked) => {
+              task.done = Boolean(checked);
+              list.refresh();
+            },
+          }).classes(task.done ? 'flex-1 line-through opacity-60' : 'flex-1');
+          ui.button('Delete', {
+            variant: 'ghost',
+            size: 'sm',
+            onClick: () => {
+              const i = tasks.indexOf(task);
+              if (i >= 0) tasks.splice(i, 1);
+              list.refresh();
+            },
+          });
+        }, { gap: 2 }).classes('items-center');
+      }
+    }, { gap: 2 });
+  });
+});
+```
+
+```typescript
+// pages/about.ts
+import { ui } from '@close-by/clay';
+
+export const pageMeta = { label: 'About', icon: 'info', order: 20 };
+
+ui.page('/about', () => {
+  ui.label('About').classes('text-2xl font-semibold');
+  ui.label('This page is a TypeScript module. The CLI discovered it and put it in the nav.');
+});
+```
+
+```bash
+bunx clay ./pages --app --title Tasks --reload
+```
+
+`--app` wraps every page in a dashboard shell. Nav comes from `pageMeta` (`label`, `icon`, `order`).
+
+## What you used
+
+| Piece | Role |
+|-------|------|
+| `clay` CLI | Run a file or a page directory; ships the React client |
+| Default export | Single-file `/` (file mode only) |
+| `ui.page` + `pageMeta` | Routes and sidebar (directory mode) |
+| `reactive` / `bindValue` | Input without manual `setValue` |
+| `ui.refreshable` | Rebuild a list when items change (simple panels) |
+| `ui.state` / `ui.auto` / `ui.timer` | Preferred for async / live / multi-region UIs — see [Concepts](./concepts.md#canonical-recipe-state--auto--timer) |
+| `let` in the builder | Per-tab state (not shared across users) |
+
+Next: [Concepts](./concepts.md), [API reference](./api.md), or the [demo catalog](./examples.md).

package/package.json

@@ -1,22 +1,29 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./page-tsconfig": "./page-tsconfig.json"
+    "./page-tsconfig": "./page-tsconfig.json",
+    "./docs-dir": "./src/docs-dir.ts",
+    "./docs/*": "./docs/*"
   },
   "files": [
     "src",
+    "docs",
     "page-tsconfig.json",
     "README.md",
     "LICENSE",
     "!src/**/*.test.ts",
     "!src/**/__fixtures__"
   ],
+  "scripts": {
+    "sync-docs": "bun ../../scripts/sync-docs.ts",
+    "prepack": "bun run sync-docs"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/closeby-corp/clay.git",
@@ -27,10 +34,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.6",
-    "@close-by/clay-core": "0.2.6",
-    "@close-by/clay-components": "0.2.6",
-    "@close-by/clay-server": "0.2.6",
+    "@close-by/clay-compiler": "0.2.8",
+    "@close-by/clay-core": "0.2.8",
+    "@close-by/clay-components": "0.2.8",
+    "@close-by/clay-server": "0.2.8",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/docs-dir.ts

@@ -0,0 +1,44 @@
+import { access } from 'fs/promises';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolve shipped markdown docs for the installed Clay version.
+ *
+ * 1. `packages/ui/docs` when developing in the monorepo (after sync-docs)
+ * 2. `@close-by/clay/docs` when installed from npm
+ */
+export async function resolveClayDocsDir(fromDir?: string): Promise<string> {
+  const base = fromDir ?? dirname(fileURLToPath(import.meta.url));
+  const local = join(base, '../docs');
+  if (await hasDocIndex(local)) return local;
+
+  try {
+    const pkgJson = require.resolve('@close-by/clay/package.json');
+    const shipped = join(dirname(pkgJson), 'docs');
+    if (await hasDocIndex(shipped)) return shipped;
+  } catch {
+    // not installed as dependency
+  }
+
+  throw new Error(
+    'Clay docs not found. Install @close-by/clay from npm or run bun scripts/sync-docs.ts in the monorepo.',
+  );
+}
+
+export function resolveClayDocPath(docsDir: string, name: string): string {
+  const file = name.endsWith('.md') ? name : `${name}.md`;
+  return join(docsDir, file);
+}
+
+async function hasDocIndex(dir: string): Promise<boolean> {
+  try {
+    await access(join(dir, 'getting-started.md'));
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -27,6 +27,8 @@ import {
   icon as iconFactory,
   iconText as iconTextFactory,
   statusDot as statusDotFactory,
+  feedRow as feedRowFactory,
+  feedList as feedListFactory,
   stat as statFactory,
   dataTable as dataTableFactory,
   areaChart as areaChartFactory,
@@ -129,6 +131,9 @@ import {
   type IconSlotProps,
   type StatusDotProps,
   type StatusDotColor,
+  type FeedRowProps,
+  type FeedRowStatus,
+  type FeedListProps,
   type StatItem,
   type DataTableProps,
   type DataTableAction,
@@ -841,6 +846,24 @@ export function statusDot(props?: StatusDotProps): Element {
   return statusDotFactory(props);
 }
 
+/** Bordered container for live feed rows. See {@link FeedListProps}. */
+export function feedList(props: FeedListProps, fn: () => void): Element;
+export function feedList(fn: () => void): Element;
+export function feedList(
+  propsOrFn: FeedListProps | (() => void),
+  fn?: () => void,
+): Element {
+  if (typeof propsOrFn === 'function') {
+    return feedListFactory(propsOrFn);
+  }
+  return feedListFactory(propsOrFn, fn!);
+}
+
+/** One live-feed row (status, link title, meta/issue, trailing time). See {@link FeedRowProps}. */
+export function feedRow(props: FeedRowProps, footer?: () => void): Element {
+  return feedRowFactory(props, footer);
+}
+
 /** Render markdown to HTML. Prefer `ui.markdown`. See {@link MarkdownProps}. */
 export function markdown(text?: string, props?: MarkdownProps): Element {
   return markdownFactory(text, props);
@@ -1594,6 +1617,10 @@ export const ui = {
   progress,
   separator,
   icon,
+  iconText,
+  statusDot,
+  feedRow,
+  feedList,
   markdown,
   html,
   image,