@vertz/ui 0.2.0 → 0.2.2

package/README.md

@@ -1,1138 +1,620 @@
 # @vertz/ui
 
-A compiler-driven UI framework with fine-grained reactivity. Write plain variables and JSX -- the compiler transforms them into efficient reactive DOM operations. No virtual DOM.
-
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Reactivity](#reactivity)
-- [Components](#components)
-- [Conditional Rendering](#conditional-rendering)
-- [List Rendering](#list-rendering)
-- [Styling](#styling)
-- [Data Fetching](#data-fetching)
-- [Routing](#routing)
-- [Forms](#forms)
-- [Lifecycle](#lifecycle)
-- [Primitives](#primitives)
-- [When to Use effect()](#when-to-use-effect)
-
----
-
-## Quick Start
-
-### Install
-
-```bash
-npm install @vertz/ui @vertz/ui-compiler
-```
-
-### Vite Config
-
-```ts
-// vite.config.ts
-import vertz from '@vertz/ui-compiler/vite';
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  plugins: [vertz()],
-});
-```
-
-The plugin transforms all `.tsx` and `.jsx` files by default. You can customize with `include` and `exclude` globs:
-
-```ts
-vertz({
-  include: ['**/*.tsx'],
-  exclude: ['**/vendor/**'],
-  cssExtraction: true, // default: true in production
-})
-```
-
-### Hello World
+**Use `let` for state. Use `const` for derived. Write JSX. Done.**
 
 ```tsx
-function App() {
-  let name = 'World';
+function Counter() {
+  let count = 0;
 
   return (
     <div>
-      <h1>Hello, {name}!</h1>
-      <input
-        value={name}
-        onInput={(e) => (name = (e.target as HTMLInputElement).value)}
-      />
+      <p>Count: {count}</p>
+      <button onClick={() => count++}>Increment</button>
     </div>
   );
 }
-
-document.body.appendChild(App());
 ```
 
-That's it. `name` is reactive. Typing in the input updates the heading. No hooks, no store setup, no subscriptions.
+That's it. `count` is reactive. The compiler transforms your code into efficient reactive DOM updates. No virtual DOM, no hooks, no boilerplate.
 
 ---
 
-## Reactivity
+## Installation
 
-This is the core mental model of the framework. The compiler does the heavy lifting -- you write normal-looking code and get fine-grained reactive DOM updates.
+```bash
+npm install @vertz/ui @vertz/ui-compiler
+```
 
-### `let` = Reactive State
+### Bun Setup
 
-Any `let` declaration inside a component that is read in JSX becomes a signal:
+The `@vertz/ui-server/bun-plugin` handles compiler transforms, CSS extraction, and Fast Refresh automatically when using `Bun.serve()` with HTML imports or `vertz dev`.
 
-```tsx
-// What you write:
-function Counter() {
-  let count = 0;
-  return <span>{count}</span>;
-}
+---
 
-// What the compiler produces:
-function Counter() {
-  const count = signal(0);
-  const __el = __element("span");
-  __el.appendChild(__text(() => count.value));
-  return __el;
-}
-```
+## The Basics
 
-Assignments work naturally:
+### Reactive State: `let`
+
+Any `let` variable read in JSX becomes reactive:
 
 ```tsx
-function Counter() {
-  let count = 0;
+function TodoInput() {
+  let text = '';
 
   return (
     <div>
-      <span>{count}</span>
-      <button onClick={() => count++}>+</button>
+      <input value={text} onInput={(e) => (text = e.target.value)} />
+      <p>You typed: {text}</p>
     </div>
   );
 }
 ```
 
-The compiler transforms `count++` to `count.value++`, `count = 5` to `count.value = 5`, and `count += 1` to `count.value += 1`.
+Assignments work naturally: `text = 'hello'`, `count++`, `items.push(item)`.
 
-### `const` = Derived State
+### Derived State: `const`
 
-A `const` that references a signal becomes a computed:
+A `const` that reads a reactive variable becomes computed (cached, lazy):
 
 ```tsx
-// What you write:
-function Pricing() {
+function Cart() {
   let quantity = 1;
-  const total = 10 * quantity;
-  const formatted = `$${total}`;
-
-  return <span>{formatted}</span>;
-}
-
-// What the compiler produces:
-function Pricing() {
-  const quantity = signal(1);
-  const total = computed(() => 10 * quantity.value);
-  const formatted = computed(() => `$${total.value}`);
-  // ...
-}
-```
+  let price = 10;
 
-Computeds are lazy and cached -- they only recompute when their dependencies change.
-
-Destructuring also works:
-
-```tsx
-function Profile() {
-  let user = { name: 'Alice', age: 30 };
-  const { name, age } = user;
+  const total = quantity * price;
+  const formatted = `$${total}`;
 
-  return <span>{name} - {age}</span>;
+  return <p>Total: {formatted}</p>;
 }
-// Compiler produces:
-// const name = computed(() => user.name)
-// const age = computed(() => user.age)
-```
-
-### JSX Text Interpolation
-
-`{expr}` in JSX creates a reactive text node when `expr` depends on signals:
-
-```tsx
-<span>{count}</span>
-// becomes: __text(() => count.value)
 ```
 
-Static expressions produce plain text nodes:
-
-```tsx
-const title = "Hello";
-<span>{title}</span>
-// becomes: document.createTextNode(title)
-```
+`total` only recalculates when `quantity` or `price` change.
 
-### JSX Reactive Attributes
+### Components
 
-Attributes that depend on signals auto-update:
+Components are plain functions returning DOM:
 
 ```tsx
-function App() {
-  let isActive = false;
-
-  return (
-    <div className={isActive ? 'active' : 'inactive'}>
-      <button onClick={() => isActive = !isActive}>Toggle</button>
-    </div>
-  );
+function Greeting({ name }) {
+  return <h1>Hello, {name}!</h1>;
 }
-// The compiler wraps the reactive className in __attr(el, "className", () => ...)
-```
-
-### Mutations
-
-The compiler intercepts mutations on signal-backed variables and generates peek/notify calls so the reactivity system is notified:
 
-```tsx
 function App() {
-  let items = ['a', 'b'];
-
-  // .push(), .splice(), etc. all work:
-  items.push('c');
-  // compiles to: (items.peek().push('c'), items.notify())
-
-  // Property assignment:
-  let user = { name: 'Alice' };
-  user.name = 'Bob';
-  // compiles to: (user.peek().name = 'Bob', user.notify())
-
-  // Index assignment:
-  items[0] = 'z';
-  // compiles to: (items.peek()[0] = 'z', items.notify())
-
-  // Object.assign:
-  Object.assign(user, { age: 30 });
-  // compiles to: (Object.assign(user.peek(), { age: 30 }), user.notify())
-
-  // delete:
-  let config = { debug: true };
-  delete config.debug;
-  // compiles to: (delete config.peek().debug, config.notify())
-}
-```
-
-### Event Handlers
-
-`onClick`, `onInput`, etc. are transformed to `__on(el, "click", handler)`:
-
-```tsx
-<button onClick={() => count++}>+</button>
-```
-
-### DO vs DON'T
-
-```tsx
-// DON'T -- imperative DOM manipulation
-// This ignores the compiler entirely. You're doing its job by hand, badly.
-import { signal, effect } from '@vertz/ui';
-
-function Counter() {
-  const count = signal(0);
-  const label = document.createElement('span');
-  effect(() => { label.textContent = String(count.value); });
-  const btn = document.createElement('button');
-  btn.onclick = () => { count.value++; };
-  btn.textContent = '+';
-  const div = document.createElement('div');
-  div.append(label, btn);
-  return div;
-}
+  let name = 'World';
 
-// DO -- declarative JSX (let the compiler handle reactivity)
-function Counter() {
-  let count = 0;
   return (
     <div>
-      <span>{count}</span>
-      <button onClick={() => count++}>+</button>
+      <Greeting name={name} />
+      <button onClick={() => (name = 'Alice')}>Change Name</button>
     </div>
   );
 }
 ```
 
-The declarative version is shorter, clearer, and produces the same (or better) runtime code. The compiler generates exactly the reactive bindings needed -- no more, no less.
-
----
-
-## Components
-
-Components are functions that return `HTMLElement` (or `Node`). There is no component class, no `render()` method.
+### Mounting
 
-### Basic Component
+Mount your app to the DOM with `mount()`:
 
 ```tsx
-function Greeting() {
-  return <h1>Hello</h1>;
-}
+import { mount } from '@vertz/ui';
 
-// Use it:
-document.body.appendChild(Greeting());
-```
-
-### Props
-
-Props are plain objects. For reactive props (values that can change), use getter functions:
-
-```tsx
-interface CardProps {
-  title: string;        // static -- value captured once
-  count: () => number;  // reactive -- getter re-evaluated on access
-}
-
-function Card(props: CardProps) {
-  return (
-    <div>
-      <h2>{props.title}</h2>
-      <span>{props.count()}</span>
-    </div>
-  );
-}
-
-// Usage:
 function App() {
-  let n = 0;
-  return (
-    <div>
-      <Card title="Score" count={() => n} />
-      <button onClick={() => n++}>+</button>
-    </div>
-  );
+  let count = 0;
+  return <button onClick={() => count++}>Count: {count}</button>;
 }
-```
-
-The `() => n` getter ensures `Card` re-reads the value reactively. A bare `n` would capture the value once and never update.
 
-### Children
+const { unmount, root } = mount(App, '#app');
+```
 
-Components can accept children via the `children` helper:
+**With options:**
 
 ```tsx
-import { children, type ChildrenAccessor } from '@vertz/ui';
+import { mount } from '@vertz/ui';
+import { defineTheme } from '@vertz/ui/css';
 
-interface PanelProps {
-  children: ChildrenAccessor;
-}
+const theme = defineTheme({
+  colors: { primary: { 500: '#3b82f6' } },
+});
 
-function Panel(props: PanelProps) {
-  const getChildren = children(props.children);
-  const el = <div className="panel" />;
-  for (const child of getChildren()) {
-    (el as HTMLElement).appendChild(child);
-  }
-  return el;
-}
+mount(App, '#app', {
+  theme,
+  styles: ['body { margin: 0; }'],
+  onMount: (root) => console.log('Mounted to', root),
+});
 ```
 
-### Composition
+`mount(app, selector, options?)` accepts:
 
-Components compose by returning DOM nodes. No special syntax needed:
+- `selector` — CSS selector string or `HTMLElement`
+- `options.theme` — theme definition for CSS vars
+- `options.styles` — global CSS strings to inject
+- `options.hydration` — `'replace'` (default) or `false`
+- `options.registry` — component registry for per-component hydration
+- `options.onMount` — callback after mount completes
 
-```tsx
-function App() {
-  return (
-    <div>
-      {Header()}
-      {MainContent()}
-      {Footer()}
-    </div>
-  );
-}
-```
-
----
+Returns a `MountHandle` with `unmount()` and `root`.
 
-## Conditional Rendering
+### Lifecycle: `onMount`
 
-Use standard JSX conditional patterns. The compiler transforms them into efficient reactive DOM operations with automatic disposal:
+Run code once when the component is created:
 
 ```tsx
-function Toggle() {
-  let show = false;
+import { onMount } from '@vertz/ui';
 
-  return (
-    <div>
-      {show && <p>Now you see me</p>}
-      <button onClick={() => show = !show}>Toggle</button>
-    </div>
-  );
-}
-```
-
-Ternaries work too:
+function Timer() {
+  let seconds = 0;
 
-```tsx
-function StatusBadge() {
-  let online = true;
+  onMount(() => {
+    const id = setInterval(() => seconds++, 1000);
+    return () => clearInterval(id);
+  });
 
-  return (
-    <div>
-      {online ? <span className="green">Online</span> : <span className="gray">Offline</span>}
-    </div>
-  );
+  return <p>{seconds}s</p>;
 }
 ```
 
-Under the hood, the compiler transforms these into `__conditional()` calls that manage DOM insertion, replacement, and cleanup automatically. When the condition changes, the old branch is disposed and the new branch is rendered in place.
-
-### Manual Control
+### Data Fetching: `query`
 
-For advanced use cases where you need direct access to the dispose function or more control over the condition lifecycle, you can use `__conditional()` from `@vertz/ui/internals` directly:
+Fetch data reactively:
 
 ```tsx
-import { __conditional } from '@vertz/ui/internals';
+import { query } from '@vertz/ui';
 
-function Toggle() {
-  let show = false;
+function UserProfile() {
+  let userId = 1;
 
-  return (
-    <div>
-      {__conditional(
-        () => show,
-        () => <p>Now you see me</p>,
-        () => <p>Now you don't</p>
-      )}
-      <button onClick={() => show = !show}>Toggle</button>
-    </div>
+  const { data, loading } = query(() =>
+    fetch(`/api/users/${userId}`).then((r) => r.json())
   );
-}
-```
-
-`__conditional` takes three arguments:
-
-1. `condFn: () => boolean` -- reactive condition
-2. `trueFn: () => Node` -- rendered when true
-3. `falseFn: () => Node` -- rendered when false
-
----
-
-## List Rendering
-
-Use `.map()` in JSX with a `key` prop for efficient keyed reconciliation. The compiler transforms it into optimized list operations:
-
-```tsx
-function TodoList() {
-  let todos = [
-    { id: '1', text: 'Learn vertz' },
-    { id: '2', text: 'Build something' },
-  ];
 
   return (
     <div>
-      <ul>
-        {todos.map(todo => <li key={todo.id}>{todo.text}</li>)}
-      </ul>
-      <button onClick={() => {
-        todos = [...todos, { id: String(Date.now()), text: 'New todo' }];
-      }}>
-        Add
-      </button>
+      {loading.value ? 'Loading...' : <p>{data.value?.name}</p>}
+      <button onClick={() => userId++}>Next User</button>
     </div>
   );
 }
 ```
 
-The `key` prop is extracted by the compiler for efficient keyed reconciliation -- existing DOM nodes are reused and reordered, not recreated. Always provide a stable, unique key for each item.
-
-### Manual Control
-
-For advanced use cases where you need direct access to the list lifecycle or want to work with the signal directly, you can use `__list()` from `@vertz/ui/internals`:
-
-```tsx
-import { signal } from '@vertz/ui';
-import { __list } from '@vertz/ui/internals';
-
-function TodoList() {
-  const todosSignal = signal([
-    { id: '1', text: 'Learn vertz' },
-    { id: '2', text: 'Build something' },
-  ]);
-
-  const container = <ul /> as HTMLElement;
-
-  __list(
-    container,
-    todosSignal,
-    (todo) => todo.id,             // key function
-    (todo) => <li>{todo.text}</li> // render function (called once per key)
-  );
-
-  return (
-    <div>
-      {container}
-      <button onClick={() => {
-        todosSignal.value = [...todosSignal.value, { id: String(Date.now()), text: 'New todo' }];
-      }}>
-        Add
-      </button>
-    </div>
-  );
-}
-```
+---
 
-`__list` arguments:
+## You're Done (Probably)
 
-1. `container: HTMLElement` -- parent element
-2. `items: Signal<T[]>` -- reactive array
-3. `keyFn: (item: T) => string | number` -- unique key extractor
-4. `renderFn: (item: T) => Node` -- creates DOM for each item (called once per key)
+**90% of apps only need the above.** The rest is for special cases.
 
 ---
 
 ## Styling
 
-Import from `@vertz/ui/css` or from the main `@vertz/ui` export.
-
-### `css()` -- Scoped Style Blocks
+### `css` — Scoped Styles
 
 ```tsx
 import { css } from '@vertz/ui/css';
 
 const styles = css({
-  card: ['p:4', 'bg:background', 'rounded:lg'],
-  title: ['font:xl', 'weight:bold', 'text:foreground'],
+  card: ['p:4', 'bg:white', 'rounded:lg', 'shadow:md'],
+  title: ['font:xl', 'weight:bold', 'mb:2'],
 });
 
-function Card() {
+function Card({ title, children }) {
   return (
-    <div className={styles.classNames.card}>
-      <h2 className={styles.classNames.title}>Hello</h2>
+    <div className={styles.card}>
+      <h2 className={styles.title}>{title}</h2>
+      {children}
     </div>
   );
 }
 ```
 
-Shorthand syntax: `property:value` maps to CSS custom properties and design tokens. Pseudo-states are supported:
-
-```tsx
-const button = css({
-  root: ['p:4', 'bg:primary', 'hover:bg:primary.700', 'rounded:md'],
-});
-```
-
-Object form for complex selectors:
-
-```tsx
-const fancy = css({
-  card: [
-    'p:4', 'bg:background',
-    { '&::after': ['content:empty', 'block'] },
-  ],
-});
-```
-
-### `variants()` -- Typed Component Variants
+### `variants` — Typed Variants
 
 ```tsx
 import { variants } from '@vertz/ui/css';
 
 const button = variants({
-  base: ['flex', 'font:medium', 'rounded:md'],
+  base: ['px:4', 'py:2', 'rounded:md', 'font:medium'],
   variants: {
     intent: {
-      primary: ['bg:primary.600', 'text:foreground'],
-      secondary: ['bg:background', 'text:muted'],
+      primary: ['bg:blue.600', 'text:white'],
+      secondary: ['bg:gray.100', 'text:gray.800'],
     },
     size: {
-      sm: ['text:xs', 'h:8'],
-      md: ['text:sm', 'h:10'],
-      lg: ['text:base', 'h:12'],
+      sm: ['px:2', 'py:1', 'text:sm'],
+      lg: ['px:6', 'py:3', 'text:lg'],
     },
   },
   defaultVariants: { intent: 'primary', size: 'md' },
-  compoundVariants: [
-    { intent: 'primary', size: 'sm', styles: ['px:2'] },
-  ],
 });
 
-// Returns a className string:
-button({ intent: 'secondary', size: 'sm' }); // => "base_abc secondary_def sm_ghi"
-button();                                      // => uses defaults
+function Button({ intent, size, children }) {
+  return <button className={button({ intent, size })}>{children}</button>;
+}
 ```
 
-The variant function is fully typed -- TypeScript infers the allowed values for `intent` and `size`.
+### `s` — Inline Dynamic Styles
+
+```tsx
+import { s } from '@vertz/ui/css';
+
+function ProgressBar({ percent }) {
+  return <div style={s([`w:${percent}%`, 'bg:green.500', 'h:4'])} />;
+}
+```
 
-### `defineTheme()` and `ThemeProvider`
+### Theming
 
 ```tsx
 import { defineTheme, compileTheme, ThemeProvider } from '@vertz/ui/css';
 
 const theme = defineTheme({
   colors: {
-    primary: { 500: '#3b82f6', 600: '#2563eb', 700: '#1d4ed8' },
+    primary: { 500: '#3b82f6', 600: '#2563eb' },
     background: { DEFAULT: '#ffffff', _dark: '#111827' },
-    foreground: { DEFAULT: '#111827', _dark: '#f9fafb' },
-  },
-  spacing: {
-    1: '0.25rem',
-    2: '0.5rem',
-    4: '1rem',
-    8: '2rem',
   },
 });
 
-// Generate CSS custom properties:
 const compiled = compileTheme(theme);
-// compiled.css contains:
-//   :root { --color-primary-500: #3b82f6; --color-background: #ffffff; ... }
-//   [data-theme="dark"] { --color-background: #111827; ... }
-
-// Apply theme to a subtree:
-const app = ThemeProvider({
-  theme: 'dark',
-  children: [MyApp()],
-});
-document.body.appendChild(app);
-```
-
-Contextual tokens use `DEFAULT` for the base value and `_dark` for the dark variant. The `ThemeProvider` sets `data-theme` on a wrapper element.
-
-### `globalCss()` -- Global Styles
 
-```tsx
-import { globalCss } from '@vertz/ui/css';
-
-globalCss({
-  '*, *::before, *::after': {
-    boxSizing: 'border-box',
-    margin: '0',
-  },
-  body: {
-    fontFamily: 'system-ui, sans-serif',
-    lineHeight: '1.5',
-  },
-});
+ThemeProvider({ theme: 'dark', children: [<App />] });
 ```
 
-Properties use camelCase and are converted to kebab-case. CSS custom properties (`--*`) are passed through as-is.
+---
 
-### `s()` -- Inline Styles
+## Forms
 
-For truly dynamic styles that can't be static:
+Bind forms to server actions with type-safe validation:
 
 ```tsx
-import { s } from '@vertz/ui/css';
-
-function Bar(props: { width: number }) {
-  return <div style={s([`w:${props.width}px`, 'h:4', 'bg:primary.500'])} />;
-}
-```
-
-Pseudo-states are not supported in `s()` -- use `css()` for those.
+import { form } from '@vertz/ui';
 
----
-
-## Data Fetching
+const createUser = Object.assign(
+  async (body: { name: string; email: string }) => {
+    const res = await fetch('/api/users', { method: 'POST', body: JSON.stringify(body) });
+    return res.json() as Promise<{ id: string }>;
+  },
+  { url: '/api/users', method: 'POST' }
+);
 
-Import from `@vertz/ui/query` or the main `@vertz/ui` export.
+const userSchema = { /* validation schema */ };
 
-```tsx
-import { query } from '@vertz/ui/query';
+function CreateUser() {
+  const f = form(createUser, {
+    schema: userSchema,
+    onSuccess: (result) => console.log('User created:', result.id),
+  });
 
-function UserProfile() {
-  let userId = 1;
+  return (
+    <form action={f.action} method={f.method} onSubmit={f.onSubmit}>
+      <input name="name" placeholder="Name" />
+      {f.name.error && <span class="error">{f.name.error}</span>}
 
-  const { data, loading, error, refetch } = query(
-    () => fetch(`/api/users/${userId}`).then(r => r.json()),
-  );
+      <input name="email" type="email" placeholder="Email" />
+      {f.email.error && <span class="error">{f.email.error}</span>}
 
-  return (
-    <div>
-      {/* data, loading, error are signals -- read .value in reactive contexts */}
-      <span>{loading.value ? 'Loading...' : ''}</span>
-      <span>{data.value?.name}</span>
-      <button onClick={() => userId++}>Next User</button>
-      <button onClick={refetch}>Refresh</button>
-    </div>
+      <button type="submit" disabled={f.submitting}>
+        {f.submitting.value ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
   );
 }
 ```
 
-The thunk runs inside an effect, so reactive dependencies read before the `await` are automatically tracked. When `userId` changes, the query re-fetches.
-
-### Options
-
-```tsx
-const result = query(() => fetchData(), {
-  initialData: cachedValue,    // skip initial fetch
-  debounce: 300,               // debounce re-fetches (ms)
-  enabled: true,               // set false to disable
-  key: 'custom-cache-key',     // explicit cache key
-  cache: myCustomCache,        // custom CacheStore implementation
-});
-```
-
-### Cleanup
-
-```tsx
-const { dispose } = query(() => fetchData());
-
-// Stop the reactive effect and clean up in-flight requests:
-dispose();
-```
-
-`revalidate()` is an alias for `refetch()`.
-
 ---
 
 ## Routing
 
-Import from `@vertz/ui/router` or the main `@vertz/ui` export.
-
-### Define Routes
-
 ```tsx
-import { defineRoutes, createRouter, createLink, createOutlet } from '@vertz/ui/router';
+import { defineRoutes, createRouter, createLink } from '@vertz/ui/router';
 
 const routes = defineRoutes({
-  '/': {
-    component: () => HomePage(),
-  },
+  '/': { component: () => <HomePage /> },
   '/users/:id': {
-    component: () => UserPage(),
-    loader: async ({ params, signal }) => {
-      const res = await fetch(`/api/users/${params.id}`, { signal });
+    component: () => <UserPage />,
+    loader: async ({ params }) => {
+      const res = await fetch(`/api/users/${params.id}`);
       return res.json();
     },
-    errorComponent: (error) => <div>Failed: {error.message}</div>,
-  },
-  '/about': {
-    component: () => AboutPage(),
   },
 });
-```
-
-### Create Router
-
-```tsx
-const router = createRouter(routes, window.location.pathname + window.location.search);
-
-// Reactive state:
-router.current;      // Signal<RouteMatch | null>
-router.loaderData;   // Signal<unknown[]>
-router.loaderError;  // Signal<Error | null>
-router.searchParams; // Signal<Record<string, unknown>>
-
-// Navigation:
-await router.navigate('/users/42');
-await router.navigate('/home', { replace: true });
-
-// Re-run loaders:
-await router.revalidate();
 
-// Cleanup:
-router.dispose();
-```
-
-### Link Component
-
-```tsx
-const Link = createLink(router.current, (url) => router.navigate(url));
+const router = createRouter(routes);
+const Link = createLink(router.current, router.navigate);
 
 function Nav() {
   return (
     <nav>
-      {Link({ href: '/', children: 'Home', activeClass: 'active' })}
-      {Link({ href: '/about', children: 'About', activeClass: 'active' })}
+      <Link href="/">Home</Link>
+      <Link href="/users/1">User 1</Link>
     </nav>
   );
 }
 ```
 
-Links intercept clicks for SPA navigation (modifier-key clicks still open new tabs). The `activeClass` is applied reactively when the link's `href` matches the current path.
-
-### Nested Routes and Outlets
+---
 
-```tsx
-import { createContext } from '@vertz/ui';
-import { createOutlet, type OutletContext } from '@vertz/ui/router';
+## Context
 
-const outletCtx = createContext<OutletContext>();
-const Outlet = createOutlet(outletCtx);
-
-const routes = defineRoutes({
-  '/dashboard': {
-    component: () => DashboardLayout(),
-    children: {
-      '/': {
-        component: () => DashboardHome(),
-      },
-      '/settings': {
-        component: () => DashboardSettings(),
-      },
-    },
-  },
-});
-```
-
-### Search Params
+Share values without passing props:
 
 ```tsx
-import { parseSearchParams, useSearchParams } from '@vertz/ui/router';
-
-// Parse raw URLSearchParams, optionally through a schema:
-const params = parseSearchParams(new URLSearchParams('?page=1&sort=name'), mySchema);
-
-// Read reactively inside an effect or computed:
-const search = useSearchParams(router.searchParams);
-```
+import { createContext, useContext } from '@vertz/ui';
 
-### Type-Safe Params
+const ThemeContext = createContext<'light' | 'dark'>('light');
 
-Route params are extracted from the path pattern at the type level:
+function App() {
+  let theme = 'light';
 
-```tsx
-import type { ExtractParams } from '@vertz/ui/router';
+  return (
+    <ThemeContext.Provider value={theme}>
+      <ThemeToggle />
+    </ThemeContext.Provider>
+  );
+}
 
-type Params = ExtractParams<'/users/:id/posts/:postId'>;
-// => { id: string; postId: string }
+function ThemeToggle() {
+  const theme = useContext(ThemeContext);
+  return <p>Current theme: {theme}</p>;
+}
 ```
 
 ---
 
-## Forms
-
-Import from `@vertz/ui/form` or the main `@vertz/ui` export.
+## Error Handling
 
 ```tsx
-import { form } from '@vertz/ui/form';
-import type { SdkMethod } from '@vertz/ui/form';
-
-// An SDK method with endpoint metadata (typically from @vertz/codegen):
-declare const createUser: SdkMethod<{ name: string; email: string }, { id: string }>;
-
-const userForm = form(createUser, {
-  schema: userSchema, // any object with parse(data): T
-});
+import { ErrorBoundary } from '@vertz/ui';
 
-function CreateUserForm() {
+function App() {
   return (
-    <form
-      {...userForm.attrs()}
-      onSubmit={userForm.handleSubmit({
-        onSuccess: (result) => console.log('Created:', result.id),
-        onError: (errors) => console.log('Errors:', errors),
-      })}
+    <ErrorBoundary
+      fallback={(error, retry) => (
+        <div>
+          <p>Error: {error.message}</p>
+          <button onClick={retry}>Retry</button>
+        </div>
+      )}
     >
-      <input name="name" />
-      {userForm.error('name') && <span className="error">{userForm.error('name')}</span>}
-
-      <input name="email" type="email" />
-      {userForm.error('email') && <span className="error">{userForm.error('email')}</span>}
-
-      <button type="submit" disabled={userForm.submitting.value}>
-        {userForm.submitting.value ? 'Saving...' : 'Create'}
-      </button>
-    </form>
+      {() => <RiskyComponent />}
+    </ErrorBoundary>
   );
 }
 ```
 
-### API
-
-- `form(sdkMethod, { schema })` -- creates a form instance
-- `.attrs()` -- returns `{ action, method }` for progressive enhancement
-- `.handleSubmit({ onSuccess?, onError? })` -- returns an event handler or accepts `FormData` directly
-- `.error(field)` -- returns the error message for a field (reactive)
-- `.submitting` -- `Signal<boolean>` for loading state
-
-The schema can be any object with a `parse(data: unknown): T` method (compatible with `@vertz/schema`). On failure, if the error has a `fieldErrors` property, those are surfaced per-field. Otherwise, a generic `_form` error is set.
-
 ---
 
-## Lifecycle
-
-### `onMount(callback)`
-
-Runs once when the component is created. Does not re-run on signal changes. Supports `onCleanup` inside for teardown:
-
-```tsx
-import { onMount, onCleanup } from '@vertz/ui';
-
-function Timer() {
-  let elapsed = 0;
-
-  onMount(() => {
-    const id = setInterval(() => elapsed++, 1000);
-    onCleanup(() => clearInterval(id));
-  });
-
-  return <span>{elapsed}s</span>;
-}
-```
-
-### `onCleanup(fn)`
-
-Registers a teardown function with the current disposal scope. Called in LIFO order when the scope is disposed:
-
-```tsx
-import { onCleanup } from '@vertz/ui';
-
-function WebSocketView() {
-  const ws = new WebSocket('wss://example.com');
-  onCleanup(() => ws.close());
-  // ...
-}
-```
-
-Must be called inside a disposal scope (`effect()`, `watch()`, `onMount()`, or a `pushScope()/popScope()` block). Throws `DisposalScopeError` if called outside a scope.
+## Advanced
 
-### `watch(dep, callback)`
+### Watch
 
-Watches a reactive dependency and runs the callback whenever it changes. Runs immediately with the current value:
+Watch a dependency and run a callback when it changes:
 
 ```tsx
-import { watch, onCleanup } from '@vertz/ui';
+import { watch } from '@vertz/ui';
 
 function Logger() {
   let count = 0;
 
   watch(
     () => count,
-    (value) => {
-      console.log('count changed to', value);
-      const id = setTimeout(() => console.log('delayed log', value), 1000);
-      onCleanup(() => clearTimeout(id));
-    }
+    (value) => console.log('count changed to', value)
   );
 
-  return <button onClick={() => count++}>+</button>;
+  return <button onClick={() => count++}>Increment</button>;
 }
 ```
 
-The `dep` function is the only tracked dependency. The callback runs untracked, so signal reads inside it don't create additional subscriptions. Before each re-run, any `onCleanup` registered in the previous callback execution runs first.
+### Refs
 
-### `ref()`
-
-Access a DOM element after creation:
+Access DOM elements after mount:
 
 ```tsx
 import { ref, onMount } from '@vertz/ui';
 
-function FocusInput() {
+function AutoFocus() {
   const inputRef = ref<HTMLInputElement>();
 
   onMount(() => {
     inputRef.current?.focus();
   });
 
-  // Assign ref.current after element creation:
-  const el = <input /> as HTMLInputElement;
-  inputRef.current = el;
-
-  return el;
+  return <input ref={inputRef} placeholder="Auto-focused" />;
 }
 ```
 
-### Context
-
-Share values down the component tree without prop-drilling:
+---
 
-```tsx
-import { createContext, useContext } from '@vertz/ui';
+## Testing
 
-const ThemeCtx = createContext<'light' | 'dark'>('light');
+Import from `@vertz/ui/test`:
 
-function App() {
-  const el = document.createDocumentFragment();
+```tsx
+import { renderTest, findByText, click, waitFor } from '@vertz/ui/test';
 
-  ThemeCtx.Provider('dark', () => {
-    el.appendChild(ThemedCard());
-  });
+// Mount a component for testing
+const { container, findByText, click, unmount } = renderTest(<Counter />);
 
-  return el;
-}
+// Query the DOM
+const button = findByText('Increment');
+await click(button);
+const label = findByText('Count: 1');
 
-function ThemedCard() {
-  const theme = useContext(ThemeCtx); // => 'dark'
-  return <div className={theme === 'dark' ? 'card-dark' : 'card-light'}>Themed</div>;
-}
+// Clean up
+unmount();
 ```
 
-`useContext` works in both synchronous component code and inside `effect`/`watch` callbacks (the context scope is captured when the effect is created).
+### Query Helpers
 
-### ErrorBoundary
+| Export | Description |
+|---|---|
+| `findByTestId(id)` | Find element by `data-testid` — throws if not found |
+| `findByText(text)` | Find element by text content — throws if not found |
+| `queryByTestId(id)` | Find element by `data-testid` — returns `null` if not found |
+| `queryByText(text)` | Find element by text content — returns `null` if not found |
+| `waitFor(fn, options?)` | Retry an assertion until it passes |
 
-Catch errors thrown by child components:
+### Interaction Helpers
 
-```tsx
-import { ErrorBoundary } from '@vertz/ui';
-
-function App() {
-  return ErrorBoundary({
-    children: () => RiskyComponent(),
-    fallback: (error, retry) => (
-      <div>
-        <p>Something broke: {error.message}</p>
-        <button onClick={retry}>Retry</button>
-      </div>
-    ),
-  });
-}
-```
+| Export | Description |
+|---|---|
+| `click(el)` | Simulate a click event |
+| `type(el, text)` | Simulate typing into an input |
+| `press(key)` | Simulate a key press |
+| `fillForm(form, values)` | Fill multiple form fields |
+| `submitForm(form)` | Submit a form |
 
-The `retry` function re-invokes `children()` and swaps the result into the DOM if it succeeds.
-
-### Suspense
-
-Handle async boundaries (components that throw promises):
+### Route Testing
 
 ```tsx
-import { Suspense } from '@vertz/ui';
+import { createTestRouter } from '@vertz/ui/test';
 
-function App() {
-  return Suspense({
-    children: () => AsyncComponent(),
-    fallback: () => <div>Loading...</div>,
-  });
-}
-```
+const { component, router, navigate } = await createTestRouter(
+  {
+    '/': { component: () => <Home /> },
+    '/about': { component: () => <About /> },
+  },
+  { initialPath: '/' }
+);
 
-If `children()` throws a `Promise`, the fallback is rendered. When the promise resolves, `children()` is called again and the result replaces the fallback in the DOM. Non-promise errors are re-thrown for `ErrorBoundary` to catch.
+await navigate('/about');
+```
 
 ---
 
-## Primitives
+## JSX Runtime
 
-`@vertz/primitives` provides headless, WAI-ARIA compliant UI components. These are intentionally imperative -- they create pre-wired DOM elements with proper ARIA attributes, keyboard handling, and state management.
+The `@vertz/ui/jsx-runtime` subpath provides the JSX factory used by the compiler. This is configured automatically by the Bun plugin — you don't need to set it up manually.
 
-```bash
-npm install @vertz/primitives
-```
+---
 
-Available components: `Accordion`, `Button`, `Checkbox`, `Combobox`, `Dialog`, `Menu`, `Popover`, `Progress`, `Radio`, `Select`, `Slider`, `Switch`, `Tabs`, `Toast`, `Tooltip`.
+## Gotchas
 
-### Usage Pattern
+### `onMount` runs synchronously
 
-Primitives return DOM elements and reactive state. Compose them with your JSX:
+`onMount` fires during component initialization, not after DOM insertion. This means the DOM node exists but may not be in the document yet. If you need to measure layout or interact with the painted DOM, use `requestAnimationFrame` inside `onMount`:
 
 ```tsx
-import { Button } from '@vertz/primitives';
-import { css } from '@vertz/ui/css';
-
-const styles = css({
-  btn: ['px:4', 'py:2', 'bg:primary.600', 'text:foreground', 'rounded:md'],
-});
-
-function MyButton() {
-  const { root, state } = Button.Root({
-    disabled: false,
-    onPress: () => console.log('pressed!'),
+onMount(() => {
+  // DOM node exists but may not be painted yet
+  requestAnimationFrame(() => {
+    // Now it's safe to measure layout
   });
-
-  root.textContent = 'Click me';
-  root.classList.add(styles.classNames.btn);
-
-  return root;
-}
+});
 ```
 
-Primitives handle:
-- ARIA roles and attributes (`role="button"`, `aria-pressed`, `aria-expanded`, etc.)
-- Keyboard interaction (Enter/Space for buttons, arrow keys for menus, Escape for dialogs)
-- Focus management
-- State via signals (`state.disabled`, `state.pressed`, `state.open`, etc.)
-
-You provide the styling. They provide the behavior and accessibility.
-
----
+### Cleanup uses the return-callback pattern
 
-## When to Use `effect()`
-
-`effect()` is a low-level reactive primitive. In most cases, the compiler handles reactivity for you through JSX. Reach for `effect()` only when you need side effects that the compiler cannot express:
-
-### Appropriate Uses
+Register cleanup logic by returning a function from `onMount`. This runs when the component unmounts:
 
 ```tsx
-import { effect, onCleanup } from '@vertz/ui';
-
-function Analytics() {
-  let page = '/home';
-
-  // Side effect: send analytics
-  effect(() => {
-    sendPageView(page);
-  });
-
-  // Third-party library integration
-  effect(() => {
-    chart.updateData(chartData);
-  });
-
-  // DOM operations the compiler can't handle
-  effect(() => {
-    element.scrollTo({ top: scrollPosition, behavior: 'smooth' });
-  });
-
-  // localStorage sync
-  effect(() => {
-    localStorage.setItem('preference', preference);
-  });
-}
+onMount(() => {
+  const id = setInterval(() => seconds++, 1000);
+  return () => clearInterval(id);
+});
 ```
 
-### NOT Appropriate
+### Primitives are uncontrolled only
 
-```tsx
-// DON'T: manual DOM text updates -- use JSX interpolation instead
-effect(() => { span.textContent = String(count); });
-// DO:
-<span>{count}</span>
-
-// DON'T: manual attribute updates -- use JSX attributes instead
-effect(() => { div.className = isActive ? 'on' : 'off'; });
-// DO:
-<div className={isActive ? 'on' : 'off'} />
-
-// DON'T: manual child rendering -- use JSX conditionals and .map() instead
-effect(() => {
-  container.innerHTML = '';
-  if (show) container.appendChild(createChild());
-});
-```
+`@vertz/ui-primitives` components (Dialog, Select, Tabs, etc.) currently only support uncontrolled mode with `defaultValue` + callbacks. Controlled mode (where a parent prop overrides internal state) is not yet supported.
 
-`effect()` returns a dispose function. It auto-registers with the current disposal scope, so cleanup happens automatically when the parent scope is disposed:
+### Popover has no focus trap
 
-```tsx
-const dispose = effect(() => {
-  console.log('count is', count);
-});
+`Popover` focuses the first element on open but does not trap focus. Tab will move focus outside the popover. This is correct for non-modal popovers (tooltips, menus), but if you need modal behavior with a focus trap, use `Dialog` instead.
 
-// Manual cleanup if needed:
-dispose();
-```
+---
 
-### `batch()`
+## What You Don't Need to Know
 
-Group multiple signal writes to avoid redundant effect runs:
+- How the compiler transforms your code
+- Internal signal implementation details
+- The reactive graph structure
+- How dependency tracking works under the hood
 
-```tsx
-import { batch } from '@vertz/ui';
+**Write ordinary JavaScript. The compiler handles the rest.**
 
-batch(() => {
-  firstName = 'Jane';
-  lastName = 'Doe';
-  age = 30;
-});
-// Effects that depend on any of these signals run once, not three times.
-```
+---
 
-### `untrack()`
+## API Reference
+
+### Lifecycle
+
+| Export | Description |
+|---|---|
+| `onMount` | Run code once when a component mounts (return a function for cleanup) |
+| `watch` | Watch a dependency and run a callback on change |
+
+### Components
+
+| Export | Description |
+|---|---|
+| `createContext` | Create a context for dependency injection |
+| `useContext` | Read a context value |
+| `children` | Access resolved children |
+| `ref` | Create a ref for DOM element access |
+| `ErrorBoundary` | Catch errors in a component tree |
+| `Suspense` | Show fallback while async content loads |
+
+### Mounting
+
+| Export | Description |
+|---|---|
+| `mount` | Mount an app to a DOM element |
+
+### CSS (`@vertz/ui/css`)
+
+| Export | Description |
+|---|---|
+| `css` | Create scoped styles |
+| `variants` | Create typed variant styles |
+| `s` | Inline dynamic styles |
+| `defineTheme` | Define a theme |
+| `compileTheme` | Compile a theme to CSS |
+| `ThemeProvider` | Provide a theme to descendants |
+| `globalCss` | Inject global CSS |
+
+### Forms
+
+| Export | Description |
+|---|---|
+| `form` | Create a form bound to an SDK method |
+| `formDataToObject` | Convert FormData to a plain object |
+| `validate` | Run schema validation |
+
+### Data
+
+| Export | Description |
+|---|---|
+| `query` | Reactive data fetching |
+
+### Routing (`@vertz/ui/router`)
+
+| Export | Description |
+|---|---|
+| `defineRoutes` | Define route configuration |
+| `createRouter` | Create a router instance |
+| `createLink` | Create a `<Link>` component |
+| `createOutlet` | Create a route outlet |
+| `parseSearchParams` | Parse URL search parameters |
+| `useSearchParams` | Reactive search parameters |
+
+### Testing (`@vertz/ui/test`)
+
+| Export | Description |
+|---|---|
+| `renderTest` | Mount a component for testing |
+| `findByTestId` | Find element by `data-testid` (throws) |
+| `findByText` | Find element by text content (throws) |
+| `queryByTestId` | Find element by `data-testid` (nullable) |
+| `queryByText` | Find element by text content (nullable) |
+| `waitFor` | Retry an assertion until it passes |
+| `click` | Simulate a click |
+| `type` | Simulate typing |
+| `press` | Simulate a key press |
+| `fillForm` | Fill multiple form fields |
+| `submitForm` | Submit a form |
+| `createTestRouter` | Create a router for testing |
 
-Read a signal without subscribing to it:
+---
 
-```tsx
-import { untrack } from '@vertz/ui';
+## License
 
-effect(() => {
-  const tracked = count;                    // subscribes to count
-  const notTracked = untrack(() => other);  // reads other without subscribing
-});
-```
+MIT