@close-by/clay 0.2.7 → 0.2.9

package/docs/architecture.md

@@ -0,0 +1,103 @@
+# Architecture
+
+## Package responsibilities
+
+| Package | Role |
+|---------|------|
+| `@close-by/clay` | App-facing `ui` object: factories, `page`, `loadPages`, `navFromPages`, `run` |
+| `@close-by/clay-cli` | `clay` binary: run a `.ts` file or page directory with sane defaults |
+| `@close-by/clay-components` | Thin `Element` factories (no HTML strings) |
+| `@close-by/clay-core` | Element tree, session, page wrapper, reactive, protocol, `storage` (`tab` / `user` / `app`) + PersistenceAdapter |
+| `@close-by/clay-persistence-file` | File-backed `PersistenceAdapter` for `storage.configure` |
+| `@close-by/clay-server` | Bun.serve: static SPA assets + `/ws` upgrade, `/auth/session`, session timeouts |
+| `@close-by/clay-auth` | Optional helpers: password hash, login limiter, `requireAuth` / `requireRole`, `auditRecord` |
+| `@close-by/clay-client` | Vite/React app: WS session hook + element → ShadCN (Sonner, BoundDataTable, …). **Private** — build output is copied into `@close-by/clay-cli` via `bun run build:client` / `pack:publishable`. |
+
+`@close-by/clay-compiler` (old Datastar `let` transform) was removed; compile-time reactive `let` remains a Later backlog item.
+
+## Runtime data flow
+
+```
+clay <file|dir> ──► import / loadPages
+        │
+ui.run({ app? }) ──► setPageWrapper(app shell)
+        │
+        ▼
+ClayServer ──HTTP──► SPA shell (index.html + assets)
+```
+
+Or library entry:
+
+```
+ui.loadPages(dir) ──► ui.page registrations + pageMeta
+        │
+ui.run({ app }) ──► setPageWrapper(app shell)
+        │
+        ▼
+ClayServer ──HTTP──► SPA shell (index.html + assets)
+        │
+        └──WS /ws──► ClientSession
+                        │
+                        ├─ mount: wrapper? → builder() → Element tree → JSON
+                        ├─ event: element.handleEvent → handlers
+                        └─ patch: updateProps / setChildren / …
+                                    │
+                                    ▼
+                         React useClaySession + ElementRenderer
+                         (notify → Sonner toast)
+```
+
+## Ownership boundaries
+
+- **Server** owns truth for structure and business state.
+- **Client** owns presentation and optimistic form UX.
+- **Handlers never run in the browser**; only event names and values cross the wire.
+
+## Session lifecycle
+
+1. Upgrade to WebSocket; `data.session = null`
+2. On first `hello`, `new ClientSession(path, send)` → `mount()`
+3. Page path change → destroy previous session, mount new path (same socket; client sends another `hello`)
+4. Socket close → `session.destroy()`
+
+On the client, a durable WebSocket + sticky React key for `type: 'app'` keeps sidebar/header mounted across navigate when chrome identity matches; only the inset tree remounts.
+
+Per-tab isolation: local `let` / `reactive` state inside a page builder is not shared across tabs. Use `ui.storage.app` when you need a process-wide store. Optional `PersistenceAdapter` (via `storage.configure({ app })` or `ui.run({ appStorageDir })`) persists keys by default; `{ persist: false }` keeps a key in memory only. Use `createFilePersistence` from `@close-by/clay-persistence-file` for disk-backed JSON, or bring your own adapter. Persisted `get()` always reloads from the adapter.
+
+## Extending the system
+
+### New element type
+
+1. Add a factory in `packages/components/src/index.ts` (`new Element('myType', props)`).
+2. Re-export via `packages/ui/src/index.ts` on the `ui` object.
+3. Add a `case 'myType':` in `packages/client/src/ElementRenderer.tsx`.
+4. Rebuild the client (`bun run build:client`).
+
+### Custom server
+
+```typescript
+import { ClayServer } from '@close-by/clay-server';
+import { setPageWrapper } from '@close-by/clay-core';
+import { app } from '@close-by/clay-components';
+import './pages';
+
+setPageWrapper((pageFn) =>
+  app({ title: 'App', nav: [{ label: 'Home', href: '/' }] }, pageFn),
+);
+
+const server = new ClayServer({ port: 4000, title: 'App' });
+server.start();
+```
+
+Or use `ui.run({ app, … })` which sets the page wrapper and starts the server.
+
+## Retired stack
+
+The previous Datastar + DaisyUI + SSE signal-sync architecture is removed:
+
+- No `/clay/stream` or `/clay/events`
+- No DaisyUI CDN page template
+- No signal cache / PatchBus as the primary update path
+- Compiler preload (`bunfig.toml`) removed
+
+Historical notes may remain under `iterations/`.

package/docs/boot.md

@@ -0,0 +1,103 @@
+# Boot: CLI vs library
+
+Clay has two entry styles. Prefer **one production path** (library mode) and treat the CLI as a thin dev wrapper so port, CSS, and `clientDir` do not drift.
+
+## Recommended production path — library mode
+
+```typescript
+// index.ts
+import { ui, resolveClayClientDir } from '@close-by/clay';
+import { join } from 'path';
+
+await ui.loadPages(new URL('./pages', import.meta.url));
+
+ui.run({
+  port: Number(process.env.PORT) || 3000,
+  title: 'My App',
+  clientDir: resolveClayClientDir(),
+  css: join(import.meta.dir, 'src/globals.generated.css'),
+  app: {
+    title: 'My App',
+    nav: ui.navFromPages(),
+  },
+});
+```
+
+```bash
+bun ./index.ts
+# Docker / ship: CMD ["bun", "./index.ts"]
+```
+
+### `clientDir`
+
+| Approach | Notes |
+|----------|--------|
+| **Omit `clientDir`** | `ui.run` defaults via `resolveClayClientDir()` — prefers `@close-by/clay-cli/client-dist` when that package is installed |
+| **`resolveClayClientDir()`** | Explicit; same resolution — use this instead of `join(..., 'node_modules/@close-by/clay-cli/client-dist')` |
+| **Custom path** | Only if you ship your own built client |
+
+`resolveClayClientDir` is exported from `@close-by/clay`. The CLI also exposes `resolveBundledClientDir` from `@close-by/clay-cli/helpers` for advanced tooling.
+
+## Dev path — `clay` CLI
+
+```bash
+bunx clay ./pages --app --title "My App" --reload
+```
+
+Optional `pages/_run.ts` merges into the same `RunConfig` the CLI would pass to `ui.run`:
+
+```typescript
+import type { RunConfig } from '@close-by/clay';
+import { resolve } from 'path';
+
+export function configureRun(base: RunConfig): RunConfig {
+  return {
+    ...base,
+    port: 4200,
+    css: resolve(import.meta.dir, '../src/globals.generated.css'),
+    // clientDir already set by the CLI to shipped client-dist
+  };
+}
+```
+
+Keep `_run.ts` as the single place for port/CSS/auth so CLI and library mode stay aligned — library `index.ts` should mirror those values (or import a shared `createRunConfig()` helper).
+
+### Reload stubs
+
+`--reload` writes stubs under **`.clay-reload/`** in the project cwd (not inside `pages/`). Add to `.gitignore`:
+
+```
+.clay-reload
+```
+
+Stubs are dev-only transient files (`_clay-reload-<pid>.ts`). They must not land in `pages/` or page discovery will pick them up.
+
+### CI and `tsc`
+
+`bunx clay --reload` is for local dev only — do **not** pass `--reload` in CI or production starts.
+
+If you run **`tsc --noEmit`** (or IDE typecheck) on the app repo, exclude reload artifacts explicitly — **`tsc` does not read `.gitignore`**:
+
+```json
+{
+  "exclude": [".clay-reload", "**/_clay-reload-*.ts"]
+}
+```
+
+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.
+
+## Reactive-let
+
+The CLI leaves the compile-time `let` transform **off** unless you pass `--reactive-let`. Library mode never registers the Bun loader unless you call `registerReactiveLetPlugin()` yourself. Prefer Phase 1 `ui.state` / `ui.auto` for real apps — see [reactive-let](./reactive-let.md).
+
+## Checklist (avoid drift)
+
+| Setting | CLI | Library |
+|---------|-----|---------|
+| Port | `-p` / `_run.ts` | `ui.run({ port })` |
+| CSS | `_run.ts` → `css` | `ui.run({ css })` |
+| Client assets | CLI sets `clientDir` | `resolveClayClientDir()` or omit |
+| Reactive-let | off by default | off unless you register the plugin |
+| Nav / shell | `--app` | `app: { nav: ui.navFromPages() }` |

package/docs/browser-apis.md

@@ -0,0 +1,65 @@
+# Browser APIs in Clay pages
+
+Page builders and event handlers run on the **server** (Bun), not in the browser. DOM globals such as `window`, `document`, `navigator`, and `location` are missing or wrong there — using them is a common source of silent no-ops (e.g. URL hash deep-links that never update).
+
+## Do
+
+| Need | Use |
+|------|-----|
+| Copy text | `ui.clipboard(text)` |
+| Read / set URL hash | `ui.getUrlHash()` / `ui.setUrlHash(hash)` |
+| Open a URL in a new tab | `ui.openExternal(url)` |
+| In-app route change | `ui.navigate(path)` |
+| Scroll | `ui.scroll.to` / `ui.scroll.intoView` |
+| Escape hatch | `ui.runJavaScript(code)` (trusted snippets only) |
+
+```ts
+ui.button('Copy id', {
+  onClick: () => {
+    ui.clipboard(orderId);
+    ui.notify('Copied', 'success');
+  },
+});
+
+const focus = ui.getUrlHash(); // from last hello / setUrlHash
+ui.setUrlHash(traceId);
+ui.openExternal('https://signoz.example/trace/' + traceId);
+```
+
+`getUrlHash` returns the hash **without** a leading `#`. It is hydrated from the client on each `hello` (connect, reconnect, SPA navigate) and updated when you call `setUrlHash`.
+
+## Don’t
+
+```ts
+// Wrong — server has no clipboard / location
+await navigator.clipboard.writeText(value);
+window.location.hash = traceId;
+window.open(url, '_blank');
+```
+
+Even with `typeof window !== 'undefined'` guards, page code still runs on the server: those branches never run, so the UI looks fine while deep-links and copy do nothing.
+
+## TypeScript: keep DOM globals out of page folders
+
+Clay page modules run on Bun, not in the browser. Extend **`@close-by/clay/page-tsconfig`** for folders that hold page builders so `window`, `navigator`, and friends are compile-time errors:
+
+```json
+{
+  "extends": "@close-by/clay/page-tsconfig",
+  "include": ["pages/**/*.ts", "src/examples/**/*.ts"]
+}
+```
+
+That tsconfig omits the DOM `lib` — only `ESNext` + `bun-types`.
+
+## Dev warnings at load time
+
+When the CLI or `ui.loadPages` imports a page module, Clay logs **`[clay-page]`** warnings for forbidden DOM globals (line numbers + suggested helpers). Disable with `CLAY_NO_PAGE_CHECKS=1`.
+
+With **`clay --reactive-let`**, transformed files that import known-fragile CJS packages (e.g. `@clickhouse/client`) also emit **`[clay-reactive-let]`** warnings — the Bun loader can break CJS named-export interop.
+
+## Related
+
+- Helpers table: [API — dialogs and feedback](./api.md#dialogs-and-feedback)
+- Protocol: `clipboard`, `setUrlHash`, `openExternal` in [WebSocket protocol](./protocol.md)
+- Phase 1 reactivity (preferred over DOM hacks): [reactive-let](./reactive-let.md)

package/docs/clickhouse.md

@@ -0,0 +1,59 @@
+# ClickHouse (`@close-by/clay-clickhouse`)
+
+Multi-connection ClickHouse wrapper with the same shape as [`@close-by/clay-duckdb`](./duckdb.md): named clients, `exec` / `query` / `queryOne`, and insert/update/delete helpers. Also includes `stream` for large SELECTs.
+
+```typescript
+import { ClickHouse } from '@close-by/clay-clickhouse';
+
+const ch = new ClickHouse();
+
+await ch.connect('analytics', {
+  url: process.env.CLICKHOUSE_URL ?? 'http://localhost:8123',
+  username: process.env.CLICKHOUSE_USER ?? 'default',
+  password: process.env.CLICKHOUSE_PASSWORD ?? '',
+  database: 'analytics',
+});
+
+const db = ch.db('analytics');
+```
+
+| Method | Description |
+|--------|-------------|
+| `connect(name, config)` | Open HTTP client and register under `name` |
+| `db(name)` | Get a named `Connection` |
+| `has(name)` / `list()` | Registry helpers |
+| `close(name)` / `closeAll()` | Disconnect and drop from registry |
+
+## Query / exec
+
+ClickHouse query parameters use `{name:Type}` in SQL:
+
+```typescript
+const rows = await db.query<{ id: number; name: string }>(
+  `SELECT id, name FROM users WHERE day = {day:String}`,
+  { day: '2026-07-01' },
+);
+
+const one = await db.queryOne('SELECT count() AS c FROM users');
+await db.exec('CREATE TABLE IF NOT EXISTS scratch (id UInt64) ENGINE = Memory');
+
+for await (const row of db.stream('SELECT * FROM events')) {
+  // large result sets
+}
+```
+
+## CRUD
+
+```typescript
+await db.insert('users', { id: 1, name: 'Ada' });
+await db.update('users', { name: 'Ada Lovelace' }, { id: 1 });
+await db.delete('users', { id: 1 });
+```
+
+`update` / `delete` require a non-empty `where` and emit ClickHouse mutations (`ALTER TABLE … UPDATE/DELETE`).
+
+Use `db.raw` for the underlying `@clickhouse/client` when needed.
+
+```typescript
+await ch.closeAll();
+```

package/docs/concepts.md

@@ -0,0 +1,269 @@
+# Concepts
+
+## Mental model
+
+Clay is **server-owned UI**:
+
+1. Your page callback runs on the server and builds an **element tree**.
+2. Each browser tab gets a **`ClientSession`** over WebSocket.
+3. The React client mounts that tree and renders ShadCN components.
+4. User events go to the server as `{ op: "event", id, type, value? }`.
+5. Server handlers mutate elements; Clay sends **patches** back.
+
+You do not write React for app screens. You write `ui.button`, `ui.input`, `ui.refreshable`, etc.
+
+```
+┌─────────────┐  hello(path)   ┌──────────────────┐
+│ React client│ ─────────────► │ ClayServer / WS │
+│ (ShadCN)    │ ◄── mount ──── │ ClientSession    │
+│             │ ◄── patch ──── │ element tree     │
+│             │ ── event ────► │ page handlers    │
+└─────────────┘                └──────────────────┘
+```
+
+## Pages and sessions
+
+```typescript
+ui.page('/examples/todo', () => {
+  // runs once per WebSocket session when the client connects to this path
+});
+```
+
+- Register routes with `ui.page(path, fn)` (or `page` from `@close-by/clay-core`).
+- On `hello`, the server creates a session, runs the page builder, and sends `mount`.
+- State in local variables (`let count = 0`) is **per session** (per tab), not shared.
+- Use `ui.storage.app` for process-wide shared data (e.g. chat messages). Configure a `PersistenceAdapter` via `storage.configure({ app })` or `ui.run({ appStorageDir })` to persist stores (default on when configured; opt out with `{ persist: false }`). `await state.get()` reloads from the adapter when persisted.
+
+## Elements
+
+Every `ui.*` factory returns an `Element`:
+
+```typescript
+const label = ui.label('Hello');
+label.classes('text-xl font-bold');
+label.setText('Hello again');
+```
+
+Elements:
+
+- Have an `id`, `type`, `props`, and `children`
+- Attach to the current parent (context stack inside `ui.row(() => { … })`)
+- Serialize to JSON for the client (handlers stay on the server; only event *names* are sent)
+
+## Updates: `setText` vs `refreshable`
+
+### Prop updates
+
+For changing text/value on an existing node:
+
+```typescript
+label.setText(`Count: ${count}`);
+input.setValue('');
+```
+
+These enqueue `updateProps` patches.
+
+### Structural updates
+
+When children appear/disappear or lists change, wrap the region in `ui.refreshable`:
+
+```typescript
+const list = ui.refreshable(() => {
+  for (const item of items) {
+    ui.label(item);
+  }
+});
+
+// later
+items.push('new');
+list.refresh(); // rebuilds children and sends setChildren
+```
+
+`refresh()` clears the refreshable’s children, re-runs the builder, and patches the client.
+
+## Canonical recipe: `state` + `auto` (+ `timer`)
+
+For async loads, filters, and live panels, prefer Phase 1 APIs over `refreshable` + manual `.refresh()`:
+
+```typescript
+const live = ui.state({
+  units: [] as Unit[],
+  loading: true,
+  error: null as string | null,
+});
+
+async function load() {
+  live.loading = true;
+  try {
+    live.units = await fetchUnits();
+    live.error = null;
+  } catch (e) {
+    live.error = e instanceof Error ? e.message : String(e);
+  } finally {
+    live.loading = false;
+  }
+}
+
+ui.auto(() => {
+  if (live.loading) ui.spinner();
+  else if (live.error) ui.alert(live.error, { variant: 'destructive' });
+  else {
+    for (const u of live.units) {
+      ui.button(u.id, { onClick: () => { /* … */ } });
+    }
+  }
+});
+
+void load();
+ui.timer(30, () => void load()); // poll; mutates `live` → auto rebuilds
+```
+
+**Rules**
+
+- Keep mutable state in `ui.state` **outside** `ui.auto` (locals inside the builder reset each rebuild).
+- One `auto` can wrap many widgets that share the same reads; split `auto` regions when list vs detail should update independently.
+- Prefer `ui.label(() => …)` / `bindValue` when only text/value changes.
+
+### When to use what
+
+| Need | Use |
+|------|-----|
+| Data that drives the tree (lists, loading, selection) | `ui.state` + `ui.auto` |
+| Polling / intervals | `ui.timer` mutating state |
+| One-shot structural rebuild you trigger yourself | `ui.refreshable` + `.refresh()` |
+| Single label/input sync | `ui.label(() => …)` / `bindValue` / `bindText` |
+| NiceGUI-style `let` sugar (demos, counters) | `// @clay-reactive` + `clay --reactive-let` — see [reactive-let](./reactive-let.md#happy-path-let--clay-reactive) |
+| Production async / dense ops consoles | `ui.state` + `ui.auto` (Phase 1) |
+
+### Alternative: reactive `let` (Phase 2)
+
+For teaching and small demos you can write plain `let` and opt in with a file pragma:
+
+```typescript
+// @clay-reactive
+import { ui } from '@close-by/clay';
+
+export default function () {
+  let count = 0;
+  ui.label(`Count: ${count}`);
+  ui.button('+', { onClick: () => { count++; } });
+}
+```
+
+Run with `clay page.ts --reactive-let`. The compiler lifts `count` to `ui.state` and wires labels automatically. Full rules and limits: [reactive-let.md](./reactive-let.md).
+
+## Bindings and `reactive`
+
+Two-way bind form controls to a reactive object:
+
+```typescript
+import { ui, reactive } from '@close-by/clay';
+
+const draft = reactive({ text: '' });
+const input = ui.input({ placeholder: '…' });
+input.bindValue(draft, 'text');
+
+// read
+const value = draft.text;
+
+// write (also updates the input via patch)
+draft.text = '';
+```
+
+- `reactive(obj)` — Proxy that notifies subscribers on property change
+- `ui.state(obj)` — alias for `reactive` (prefer in app code)
+- `ui.auto(fn)` — rebuild a region when tracked `state`/`reactive` reads change; stable trees patch via `updateProps` (see [`reactive-let.md`](./reactive-let.md))
+- `ui.label(() => string)` / `.bindText(fn)` — computed label text without wrapping `auto`
+- `bindValue(obj, key)` — syncs element value ↔ `obj[key]` on `input`/`change`
+- `bindTextFrom(obj, key)` — one-way sync into label text
+- `subscribe(obj, key, fn)` — run a callback when a key changes (e.g. refresh a summary panel)
+
+## Events
+
+Declare handlers with camelCase props (`onClick`, `onChange`, `onInput`) or `.on(event, handler)`:
+
+```typescript
+ui.button('Save', {
+  onClick: async () => {
+    await save();
+  },
+});
+
+ui.input({
+  onInput: (value) => console.log(value),
+});
+```
+
+The client keeps local optimistic state for inputs, textareas, checkboxes, switches, selects, radio groups, comboboxes, dates, sliders, tabs, accordions, collapsibles, and DataTable filter inputs so typing/toggling feels instant while the server confirms.
+
+## Layout context
+
+Layout helpers push a parent onto a stack:
+
+```typescript
+ui.column(() => {
+  ui.label('Title');
+  ui.row(() => {
+    ui.button('A');
+    ui.button('B');
+  });
+});
+```
+
+Children created inside the callback become children of that layout element.
+
+### App shell (`ui.run({ app })`)
+
+Configure chrome once at startup; page modules only register content. `ui.loadPages(dir)` imports every page file under a directory; optional `pageMeta` feeds `ui.navFromPages()` for the primary sidebar.
+
+```typescript
+await ui.loadPages(new URL('./pages', import.meta.url));
+
+ui.run({
+  app: {
+    title: 'My App',
+    nav: ui.navFromPages(),
+  },
+});
+```
+
+```typescript
+// pages/Charts.ts
+export const pageMeta = { label: 'Charts', icon: 'chart-area', order: 90 };
+
+ui.page('/examples/charts', () => {
+  ui.label('Charts'); // inherits global shell
+});
+```
+
+Opt out per route with `ui.page(path, fn, { shell: false })`. Keep explicit `ui.app(props, fn)` for advanced cases.
+
+The client keeps this chrome **sticky** across SPA navigate: the WebSocket stays open, a new `hello` remounts the server session, and React reuses the `app` shell (sidebar / header) when the chrome structure matches. Only the inset page content remounts; nav `active` flags update from the new tree.
+
+## Notifications and navigation
+
+```typescript
+ui.notify('Saved!', 'success');
+ui.notify('Look here', {
+  type: 'warning',
+  duration: 0,
+  position: 'top-right',
+  description: 'Sticky toast via Sonner',
+});
+
+// still available:
+import { notify, navigate } from '@close-by/clay-core';
+navigate('/examples/todo');
+```
+
+`ui.notify` / `notify` map to [Sonner](https://ui.shadcn.com/docs/components/sonner) on the client (`toast.success` / `info` / `warning` / `error`). `duration: 0` is sticky; optional `description` is Sonner’s secondary line. `navigate` tells the client to change path and send a new `hello` on the same WebSocket (server remounts the page; client keeps matching `app` chrome mounted).
+
+## Imperative overlays
+
+```typescript
+const sure = await ui.confirm('Continue?');
+const name = await ui.prompt('Your name');
+const pick = await ui.choose('Pick one', ['A', 'B']);
+```
+
+These open ephemeral dialogs, return Promises, and only work inside an active session (e.g. `onClick` / `onAction`). They are not synchronous — a WebSocket round-trip is required.

package/docs/duckdb.md

@@ -0,0 +1,68 @@
+# DuckDB (`@close-by/clay-duckdb`)
+
+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
+```
+
+## Connect multiple databases
+
+```typescript
+import { DuckDB } from '@close-by/clay-duckdb';
+
+const duck = new DuckDB();
+
+await duck.connect('app', './data/app.duckdb');
+await duck.connect('scratch', ':memory:');
+
+const app = duck.db('app');
+await app.exec(`CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY,
+  name VARCHAR,
+  email VARCHAR
+)`);
+```
+
+| Method | Description |
+|--------|-------------|
+| `connect(name, path?)` | Open/create a DuckDB file (default `:memory:`) |
+| `db(name)` | Get a named `Connection` |
+| `has(name)` / `list()` | Registry helpers |
+| `close(name)` / `closeAll()` | Disconnect and drop from registry |
+
+## CRUD
+
+```typescript
+await app.insert('users', { id: 1, name: 'Ada', email: 'a@x.com' });
+await app.update('users', { name: 'Ada Lovelace' }, { id: 1 });
+await app.delete('users', { id: 1 });
+
+const rows = await app.query<{ id: number; name: string }>(
+  'SELECT * FROM users WHERE id = $id',
+  { id: 1 },
+);
+const one = await app.queryOne('SELECT * FROM users WHERE id = $id', { id: 1 });
+```
+
+`update` and `delete` require a non-empty `where` object (safety guard).
+
+Use `app.raw` for the underlying `@duckdb/node-api` connection when you need appenders or streaming.
+
+## ATTACH external databases
+
+```typescript
+await duck.attach('app', {
+  alias: 'legacy',
+  type: 'sqlite',          // 'duckdb' | 'sqlite' | 'postgres' | 'mysql'
+  path: './legacy.sqlite', // file path or DSN for postgres/mysql
+  readOnly: false,
+});
+
+await app.query('SELECT * FROM legacy.users');
+await app.insert('legacy.users', { id: 2, name: 'Grace' });
+
+await duck.detach('app', 'legacy');
+```
+
+Extensions (`sqlite`, `postgres`, `mysql`) are `INSTALL`/`LOAD`ed once per process when first needed. Prefer `type: 'duckdb'` for sibling DuckDB files (no extension).