# Whisq Documentation — Full Text

> Every page on whisq.dev, concatenated for AI models that prefer a single fetch over crawling. Regenerated on every build. Canonical site: https://whisq.dev/. Machine-readable exports list: https://unpkg.com/@whisq/core@latest/dist/public-api.json.

Pages: 86
---
# Custom Elements
URL: https://whisq.dev/advanced/custom-elements/
---

Most of the time, you'll use named element functions like `div()`, `button()`, and `input()`. But when you need a tag that isn't in the standard set — a web component, an SVG element, or a custom tag — use `h()`.

## The h() Function

`h()` creates any HTML element by tag name:

```ts

// Standard element (same as using div())
h("div", { class: "card" }, "Hello");

// Web component
h("my-dropdown", { value: "option1" },
  h("my-option", { value: "option1" }, "Option 1"),
  h("my-option", { value: "option2" }, "Option 2"),
);

// Custom element
h("app-header", { class: "main-header" },
  h("app-logo"),
  h("app-nav"),
);
```

## Web Components

Whisq works with any web component registered via `customElements.define()`:

```ts

// Assume a <color-picker> web component is registered
const selectedColor = signal("#4f46e5");

mount(
  h("color-picker", {
    value: () => selectedColor.value,
    onchange: (e) => selectedColor.value = e.target.value,
  }),
  document.getElementById("app")!,
);
```

Reactive props and event handlers work the same way as with built-in elements.

## SVG Elements

Use `h()` for SVG elements that aren't covered by the standard element functions:

```ts

const icon = h("svg", { viewBox: "0 0 24 24", width: "24", height: "24" },
  h("circle", { cx: "12", cy: "12", r: "10", fill: "none", stroke: "currentColor" }),
  h("path", { d: "M12 6v6l4 2", stroke: "currentColor", fill: "none" }),
);
```

## Wrapping Third-Party Components

Create a typed wrapper around a web component for better ergonomics:

```ts

interface DatePickerProps {
  value?: () => string;
  onchange?: (e: Event) => void;
  min?: string;
  max?: string;
}

function DatePicker(props: DatePickerProps, ...children: any[]) {
  return h("date-picker", props, ...children);
}

// Now use it like a native Whisq element
DatePicker({
  value: () => selectedDate.value,
  onchange: (e) => selectedDate.value = e.target.value,
  min: "2024-01-01",
});
```

:::tip[🐱 Whisker Tip]
Use `h()` as an escape hatch. For elements you use frequently, create a wrapper function with typed props — you get the same DX as built-in elements.
:::

## When to Use h() vs Named Functions

| Use case | Approach |
|---|---|
| Standard HTML (`div`, `button`, `input`) | Named functions — `div()`, `button()` |
| Web components (`my-component`) | `h("my-component", ...)` |
| SVG elements (`circle`, `path`) | `h("circle", ...)` |
| Dynamic tag names | `h(tagName, ...)` |

## Next Steps

- [Elements](https://whisq.dev/core-concepts/elements/) — Built-in element functions
- [Components](https://whisq.dev/core-concepts/components/) — Whisq's component model
- [Performance](https://whisq.dev/advanced/performance/) — Optimizing custom element usage

---
# Error Boundaries
URL: https://whisq.dev/advanced/error-boundaries/
---

When something inside a Whisq component tree throws — a render-time error, a signal-driven recomputation, an event handler, an effect, or even a child component's setup — you usually want to show fallback UI instead of crashing the whole page. Whisq ships a first-class primitive for exactly this: `errorBoundary()`.

## The `errorBoundary()` primitive

Wrap any subtree in `errorBoundary(fallback, child)`:

```ts

errorBoundary(
  (error, retry) =>
    div({ class: "error-boundary" },
      p(`Something went wrong: ${error.message}`),
      button({ onclick: retry }, "Try again"),
    ),
  () => RiskyComponent({}),
);
```

- **`fallback`** — `(error, retry) => Node`. Called when the wrapped subtree throws. Receives the caught error and a `retry` function that re-runs the child.
- **`child`** — `() => Node`. The protected subtree. The thunk lets `errorBoundary` re-invoke it on retry.

**Why use the primitive instead of a hand-rolled `try`/`catch` in a component?** A `try`/`catch` inside a component setup function only sees errors thrown synchronously while that setup runs. Anything that happens later — a child component's setup, a re-render after a signal changes, an event handler, an async callback — runs outside that `try` block and is not caught. `errorBoundary()` is integrated with Whisq's render machinery and is scoped to the wrapped subtree, so it sees errors thrown anywhere in that subtree's rendering. **Use the primitive — don't roll your own.**

For asynchronous failures (network, timers, deferred promises), see [Async data](#async-data) below — `resource()` is the right tool, not `errorBoundary()`.

## Granular boundaries

Wrap individual sections rather than the entire app — if one widget fails, the rest of the page keeps working:

```ts

const Dashboard = component(() =>
  div(
    h1("Dashboard"),
    errorBoundary(
      (err) => p("Stats unavailable"),
      () => StatsWidget({}),
    ),
    errorBoundary(
      (err) => p("Chart failed to load"),
      () => ChartWidget({}),
    ),
    errorBoundary(
      (err) => p("Table unavailable"),
      () => TableWidget({}),
    ),
  )
);
```

If the chart throws, the stats and table still render normally.

## Error reporting

Silently swallowing errors hides bugs. Always log them — either in the fallback callback or via a small reporter helper:

```ts

const reportError = (error: Error, where: string) => {
  console.error(`[${where}]`, error);
  // fetch("/api/errors", { method: "POST", body: JSON.stringify({ where, message: error.message }) });
};

errorBoundary(
  (error, retry) => {
    reportError(error, "ChartWidget");
    return div({ class: "error" },
      p("This section failed to load."),
      button({ onclick: retry }, "Retry"),
    );
  },
  () => ChartWidget({}),
);
```

## Async data

For network and other async failures, you don't need a separate error boundary at all. `resource()` already exposes loading and error state as signals:

```ts

const data = resource(() =>
  fetch("/api/data").then((r) => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.text();
  }),
);

div(
  when(() => data.loading(), () => p("Loading…")),
  when(() => !!data.error(), () =>
    div(
      p(() => `Error: ${data.error()!.message}`),
      button({ onclick: () => data.refetch() }, "Retry"),
    ),
  ),
  when(() => !!data.data(), () => p(() => data.data()!)),
);
```

Reach for `errorBoundary()` around a subtree that uses `resource()` only when you also want to catch unexpected render-time errors in that subtree — `resource()` handles the documented async failure path, `errorBoundary()` is the safety net for everything else.

## Best practices

1. **Wrap at section boundaries, not every component.** Logical units (widgets, panels, routes) are the right granularity.
2. **Always provide actionable fallback UI** — explain what failed and offer a retry button when it makes sense.
3. **Always log or report** — `console.error` at minimum; a real reporting service in production.
4. **Use `resource()` for async failures**; reserve `errorBoundary()` for unexpected throws.

## Next steps

- [Components — Error Boundaries](https://whisq.dev/core-concepts/components/#error-boundaries) — short reference for the primitive next to component composition basics.
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — `resource()` with built-in error handling.
- [Performance](https://whisq.dev/advanced/performance/) — Optimizing component rendering.
- [Testing](https://whisq.dev/guides/testing/) — Testing error states.

---
# Performance
URL: https://whisq.dev/advanced/performance/
---

Whisq's signal-based reactivity is efficient by default — only the DOM nodes that read a signal update when it changes. But in complex applications, a few patterns can make a significant difference.

## Fine-Grained Signals

Prefer many small signals over one big object:

```ts
// ❌ Less efficient — entire UI re-checks when any field changes
const user = signal({ name: "Alice", age: 30, email: "alice@example.com" });

// ✅ More efficient — only name UI updates when name changes
const name = signal("Alice");
const age = signal(30);
const email = signal("alice@example.com");
```

With fine-grained signals, changing `name.value` only updates DOM nodes that read `name.value`. With a single object signal, every node that reads any property re-evaluates.

:::tip[🐱 Whisker Tip]
Signals are cheap. Creating 50 small signals is better than 1 large object signal with 50 properties.
:::

## Batch Updates

When updating multiple signals at once, wrap them in `batch()`:

```ts

const x = signal(0);
const y = signal(0);
const z = signal(0);

// ❌ Three separate UI updates
x.value = 1;
y.value = 2;
z.value = 3;

// ✅ One UI update
batch(() => {
  x.value = 1;
  y.value = 2;
  z.value = 3;
});
```

`batch()` defers all reactive updates until the function completes, then flushes them once.

## Use peek() in Effects

When an effect needs to read a signal without subscribing to it, use `peek()`:

```ts

const count = signal(0);
const log = signal<string[]>([]);

// ❌ Infinite loop — effect reads log.value, which triggers re-run
effect(() => {
  log.value = [...log.value, `Count changed to ${count.value}`];
});

// ✅ peek() reads without creating a dependency
effect(() => {
  const current = log.peek();
  log.value = [...current, `Count changed to ${count.value}`];
});
```

`peek()` reads the signal's current value without tracking it as a dependency. The effect above re-runs when `count` changes but not when `log` changes.

:::danger[Common Mistake]
```ts
// ❌ WRONG — creates dependency, may cause infinite loop
effect(() => {
  items.value = [...items.value, newItem];
});

// ✅ RIGHT — peek() avoids the dependency
effect(() => {
  items.value = [...items.peek(), newItem];
});
```
:::

## Avoid Unnecessary Computed Values

`computed()` caches its result and only re-evaluates when dependencies change. But avoid creating computed values for trivial derivations:

```ts
// ❌ Overkill — computed overhead for a simple check
const isEmpty = computed(() => items.value.length === 0);

// ✅ Just inline it
when(() => items.value.length === 0, () => p("No items"));
```

Use `computed()` when:
- The derivation is expensive (filtering, sorting, mapping large arrays)
- Multiple parts of the UI read the same derived value
- You want to name the value for readability

## Lazy Component Loading

Split large apps by loading components on demand:

```ts

const Dashboard = component(() => {
  const loaded = signal<(() => Node) | null>(null);

  // Load the heavy component on demand
  const loadChart = async () => {
    const { ChartWidget } = await import("./ChartWidget");
    loaded.value = () => ChartWidget({});
  };

  return div(
    button({ onclick: loadChart }, "Load Chart"),
    when(() => !!loaded.value, () => loaded.value!()),
  );
});
```

## Profiling with DevTools

Use `@whisq/devtools` to attach a runtime hook that browser extensions or console scripts can read. Apps opt in explicitly — the hook is a passive surface, not an auto-instrumenter:

```ts

if (import.meta.env.DEV) connectDevTools();
```

The installed hook exposes, via `globalThis.__WHISQ_DEVTOOLS__`:

- **`registerSignal(name, signal)` / `getSignals()`** — a ledger of named signals and their current values (read via `.peek()`, so inspection doesn't subscribe).
- **`registerComponent(name)` / `getComponents()`** — a list of active component names.
- **`logEvent(type, data)` / `getEvents()` / `clearEvents()`** — an append-only event log with timestamps.

Full API: [`/api/devtools/`](https://whisq.dev/api/devtools/).

## Performance Checklist

| Pattern | Impact | When to use |
|---|---|---|
| Fine-grained signals | High | Always — prefer small signals |
| batch() | Medium | When updating 2+ signals together |
| peek() | Medium | When reading a signal in an effect without tracking |
| Lazy loading | High | For large components not needed at startup |
| computed() caching | Medium | For expensive derivations read in multiple places |

## Next Steps

- [Signals](https://whisq.dev/core-concepts/signals/) — How reactivity works
- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — onMount, onCleanup, effect
- [Sandbox](https://whisq.dev/advanced/sandbox/) — Isolated execution for untrusted code

---
# Portals
URL: https://whisq.dev/advanced/portals/
---

A portal renders a component's output into a DOM node that lives outside the parent component's tree. This is useful for modals, tooltips, dropdown menus, and any UI that needs to visually escape its parent's layout.

## How Portals Work in Whisq

Since Whisq elements are real DOM nodes (not virtual), creating a portal is straightforward — mount your component into any DOM element:

```ts

const Modal = component((props: { onClose: () => void }) =>
  div({ class: "modal-overlay", onclick: props.onClose },
    div({
      class: "modal-content",
      onclick: (e) => e.stopPropagation(),
    },
      p("This is a modal!"),
      button({ onclick: props.onClose }, "Close"),
    ),
  )
);

const App = component(() => {
  const showModal = signal(false);
  let cleanup: (() => void) | null = null;

  const openModal = () => {
    showModal.value = true;
    // Mount modal into a separate DOM node
    const container = document.getElementById("modal-root")!;
    cleanup = mount(
      Modal({ onClose: closeModal }),
      container,
    );
  };

  const closeModal = () => {
    showModal.value = false;
    cleanup?.();
    cleanup = null;
  };

  return div(
    button({ onclick: openModal }, "Open Modal"),
  );
});
```

Your HTML needs a separate mount point:

```html
<body>
  <div id="app"></div>
  <div id="modal-root"></div>
</body>
```

## A Reusable Portal Helper

Wrap the pattern into a helper function:

```ts

function portal(node: Node, target: string | HTMLElement) {
  const container = typeof target === "string"
    ? document.querySelector(target)!
    : target;

  const dispose = mount(node, container);
  onCleanup(dispose);
  return node;
}
```

Use it inside components:

```ts

const App = component(() => {
  const open = signal(false);

  return div(
    button({ onclick: () => open.value = true }, "Show Tooltip"),
    when(() => open.value, () =>
      portal(
        div({ class: "tooltip" }, p("I'm rendered in #tooltip-root")),
        "#tooltip-root",
      )
    ),
  );
});
```

## Use Cases

**Modals and dialogs** — render above everything else, outside the app's CSS stacking context:

```ts
portal(
  div({ class: "dialog-overlay" },
    div({ class: "dialog" }, /* content */),
  ),
  "#modal-root",
);
```

**Tooltips and popovers** — position relative to a trigger but render in a top-level container to avoid overflow clipping:

```ts
portal(
  div({
    class: "tooltip",
    style: () => `top: ${y.value}px; left: ${x.value}px`,
  }, "Tooltip text"),
  document.body,
);
```

**Notification toasts** — render into a fixed notification container:

```ts
portal(
  div({ class: "toast" }, "Saved successfully!"),
  "#toast-container",
);
```

:::tip[🐱 Whisker Tip]
Because Whisq works with real DOM nodes, portals are just `mount()` calls. There's no special API — you're mounting a component subtree into a different DOM element.
:::

## Cleanup

Always clean up portals when the parent unmounts. The `portal()` helper above uses `onCleanup` to handle this automatically. If you're using `mount()` directly, store the dispose function and call it when done.

:::danger[Common Mistake]
```ts
// ❌ WRONG — portal is never cleaned up
mount(Modal({}), document.getElementById("modal-root"));

// ✅ RIGHT — store dispose and clean up
const dispose = mount(Modal({}), document.getElementById("modal-root"));
onCleanup(dispose);
```
:::

## Next Steps

- [Components](https://whisq.dev/core-concepts/components/) — Component lifecycle
- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — onMount and onCleanup
- [Error Boundaries](https://whisq.dev/advanced/error-boundaries/) — Handling errors in component trees

---
# Sandbox
URL: https://whisq.dev/advanced/sandbox/
---

`@whisq/sandbox` provides a secure execution environment for running untrusted code. It's designed for interactive playgrounds, code editors, and educational tools where user-submitted code needs to run safely.

## Setup

```bash
npm install @whisq/sandbox
```

## Basic Usage

```ts

const sandbox = createSandbox();

const result = await sandbox.execute(`
  const x = 2 + 2;
  x;
`);

console.log(result);
// { success: true, value: 4 }

sandbox.dispose();
```

## Error Handling

When code throws an error, the sandbox catches it:

```ts
const result = await sandbox.execute(`
  throw new Error("something broke");
`);

console.log(result);
// { success: false, error: "Error: something broke" }
```

Your application doesn't crash — the error is captured and returned.

## Timeouts

Set a maximum execution time to prevent infinite loops:

```ts
const sandbox = createSandbox({ timeout: 3000 }); // 3 seconds

const result = await sandbox.execute(`
  while (true) {} // infinite loop
`);

console.log(result);
// { success: false, error: "Execution timed out" }
```

The default timeout is 5,000ms (5 seconds).

## Blocked APIs

The sandbox blocks access to browser APIs that could be dangerous:

- `document`, `window`, `globalThis`
- `fetch`, `XMLHttpRequest`, `WebSocket`
- `localStorage`, `sessionStorage`, `indexedDB`
- `navigator`, `location`, `history`
- `alert`, `confirm`, `prompt`

Attempting to access any of these throws an error:

```ts
const result = await sandbox.execute(`
  fetch("/api/data");
`);

// { success: false, error: "fetch is not defined" }
```

## Communication

Send messages between the sandbox and your application:

```ts
const sandbox = createSandbox();

// Listen for messages from sandboxed code
sandbox.onMessage((msg) => {
  console.log("From sandbox:", msg);
});

await sandbox.execute(`
  postMessage({ type: "result", value: 42 });
`);
```

## Building a Code Playground

Combine the sandbox with Whisq UI for an interactive playground:

```ts

const Playground = component(() => {
  const code = signal('const x = 2 + 2;\nx;');
  const output = signal("");
  const sandbox = createSandbox({ timeout: 3000 });

  const run = async () => {
    const result = await sandbox.execute(code.value);
    output.value = result.success
      ? String(result.value)
      : `Error: ${result.error}`;
  };

  return div({ class: "playground" },
    textarea({
      value: () => code.value,
      oninput: (e) => code.value = e.target.value,
      rows: "8",
    }),
    button({ onclick: run }, "Run"),
    pre({ class: "output" }, () => output.value),
  );
});

mount(Playground({}), document.getElementById("app")!);
```

## Cleanup

Always dispose the sandbox when you're done:

```ts
const sandbox = createSandbox();

// ... use the sandbox ...

sandbox.dispose(); // clean up resources
```

In a Whisq component, use `onCleanup`:

```ts

const PlaygroundComponent = component(() => {
  let sandbox: Sandbox;

  onMount(() => {
    sandbox = createSandbox();
    onCleanup(() => sandbox.dispose());
  });

  // ... use sandbox in event handlers
});
```

## API Reference

### createSandbox(options?)

| Option | Type | Default | Description |
|---|---|---|---|
| `timeout` | number | 5000 | Maximum execution time in ms |

### sandbox.execute(code)

Returns `Promise<ExecutionResult>`:

```ts
interface ExecutionResult {
  success: boolean;
  value?: unknown;   // result of the last expression
  error?: string;    // error message if failed
}
```

### sandbox.onMessage(handler)

Listen for `postMessage()` calls from sandboxed code.

### sandbox.dispose()

Clean up sandbox resources.

## Next Steps

- [Performance](https://whisq.dev/advanced/performance/) — Optimizing Whisq applications
- [Testing](https://whisq.dev/guides/testing/) — Testing components that use sandboxes
- [Error Boundaries](https://whisq.dev/advanced/error-boundaries/) — Handling errors in UI

---
# Claude Code
URL: https://whisq.dev/ai/claude-code/
---

Claude Code works with Whisq out of the box. Every Whisq project includes a `CLAUDE.md` file that gives Claude the complete API reference in under 5,000 tokens.

## Setup

When you create a new Whisq project, `CLAUDE.md` is included automatically:

```bash
npm create whisq@latest my-app
cd my-app
# CLAUDE.md is already at the project root
```

Claude Code reads `CLAUDE.md` when it opens your project — no extra configuration needed.

## What CLAUDE.md Contains

The file provides Claude with:

- **Complete API reference** — every export from `@whisq/core`
- **Usage patterns** — signal creation, element functions, component structure
- **Anti-patterns** — what NOT to generate (e.g., `count.value` as a child instead of `() => count.value`)
- **Project conventions** — file structure, naming, git workflow

This is enough for Claude to generate correct Whisq components on the first attempt.

## Example Workflow

Open your Whisq project in Claude Code and describe what you need:

```
Create a todo list component with:
- An input field to add new items
- A list of todos with checkboxes to mark as done
- A count of remaining items
- A "Clear completed" button
```

Claude will generate working Whisq code using `signal()`, `computed()`, `each()`, and proper reactive patterns — because it has the full API in context.

## Tips for Better Results

1. **Name specific APIs** — "use `resource()` to fetch data" is better than "load some data from the server."

2. **Describe the component structure** — "a form with email and password fields, a submit button that's disabled until valid" gives Claude clear requirements.

3. **Reference the store pattern** — "create a store in `stores/cart.ts` with exported signals and functions" and Claude will follow the convention.

4. **Point out mistakes** — if Claude generates `span(count.value)`, tell it to use `span(() => count.value)`. It will apply the pattern consistently for the rest of the conversation.

## Using the MCP Server

For deeper integration, install the `@whisq/mcp-server`:

```bash
npm install -D @whisq/mcp-server
```

This gives Claude Code access to two tools:
- **scaffold_component** — generate components from descriptions
- **validate_code** — check code for common Whisq anti-patterns

See [MCP Server](https://whisq.dev/ai/mcp-server/) for setup details.

## Next Steps

- [MCP Server](https://whisq.dev/ai/mcp-server/) — Advanced AI tooling
- [LLM Reference](https://whisq.dev/ai/llm-reference/) — The complete API in paste-ready format
- [AI Integration Guide](https://whisq.dev/guides/ai-integration/) — Prompt patterns and tips

---
# GitHub Copilot
URL: https://whisq.dev/ai/copilot/
---

GitHub Copilot works with Whisq through pattern recognition. The more Whisq code in your project, the better Copilot's suggestions become.

## Getting Started

Copilot doesn't read `.cursorrules` or `CLAUDE.md` the same way dedicated AI editors do. Instead, it learns from:

- **Open files** — keep a few Whisq components open as reference
- **Existing code in the project** — Copilot picks up patterns from your codebase
- **Comments** — describe what you want above where you're writing

## Writing Effective Comments

Guide Copilot with descriptive comments:

```ts

// Whisq component: email signup form
// - email input bound to signal
// - validation: must contain @
// - submit button disabled when invalid
// - show success message after submission
const EmailSignup = component(() => {
  // Copilot will generate the implementation here
```

Copilot sees the imports, the comment, and the `component()` call — it has enough context to generate correct Whisq code.

## Patterns Copilot Handles Well

**Signal creation and reactive text:**
```ts
const name = signal("");
// Copilot correctly suggests:
span(() => `Hello, ${name.value}`);
```

**Event handlers:**
```ts
input({
  // After typing oninput, Copilot suggests the full handler:
  oninput: (e) => name.value = e.target.value,
});
```

**Conditional rendering:**
```ts
// After typing when(, Copilot picks up the pattern:
when(() => isLoading.value, () => p("Loading..."));
```

## Patterns That Need Attention

Copilot occasionally generates React-style code in Whisq projects. Watch for these:

:::danger[Common Mistake]
```ts
// ❌ Copilot might generate JSX syntax
return <div>{count}</div>;

// ✅ Correct Whisq
return div(() => count.value);
```
:::

:::danger[Common Mistake]
```ts
// ❌ Copilot might suggest useState
const [count, setCount] = useState(0);

// ✅ Correct Whisq
const count = signal(0);
```
:::

## Tips

1. **Keep 2-3 Whisq files open** — Copilot uses open tabs as context. Having good examples visible improves suggestions.

2. **Accept and correct** — when Copilot generates almost-right code, accept it and fix the small issues. It learns from your corrections within the session.

3. **Use line-by-line completion** — rather than expecting Copilot to generate entire components, let it complete one line at a time. It's more accurate this way.

4. **Start with the import** — typing `import { signal, computed, component, div` sets the context. Copilot understands you're writing Whisq.

5. **Use Copilot Chat** — paste the content of `CLAUDE.md` into a Copilot Chat session for better results on complex components.

## Next Steps

- [Claude Code](https://whisq.dev/ai/claude-code/) — Deeper AI integration with CLAUDE.md
- [Cursor](https://whisq.dev/ai/cursor/) — AI-first editor with .cursorrules support
- [LLM Reference](https://whisq.dev/ai/llm-reference/) — Complete API for pasting into any AI

---
# Cursor
URL: https://whisq.dev/ai/cursor/
---

Cursor reads `.cursorrules` from your project root to understand framework conventions. Whisq projects include this file automatically.

## Setup

Create a new project — `.cursorrules` is included:

```bash
npm create whisq@latest my-app
cd my-app
# .cursorrules is already at the project root
```

Open the project in Cursor and start prompting. Cursor will follow Whisq patterns automatically.

## What .cursorrules Contains

The file teaches Cursor:

- **Import patterns** — always import from `@whisq/core`
- **Reactive children** — use `() => value` not `value` directly
- **Event handling** — `onclick`, `oninput` with standard DOM events
- **Component structure** — `component()` function wrapping signals and a return statement
- **Anti-patterns to avoid** — no JSX, no `this`, no class components

## Example Workflow

In Cursor, use Cmd+K (or Ctrl+K) to open the AI prompt and describe what you need:

```
Create a search component with:
- A text input bound to a signal
- A filtered list that updates as you type
- Use computed() for the filter logic
```

Cursor generates:

```ts

const Search = component(() => {
  const query = signal("");
  const items = signal(["Apple", "Banana", "Cherry", "Date", "Elderberry"]);
  const filtered = computed(() =>
    items.value.filter(i =>
      i.toLowerCase().includes(query.value.toLowerCase())
    )
  );

  return div(
    input({
      placeholder: "Search...",
      value: () => query.value,
      oninput: (e) => query.value = e.target.value,
    }),
    ul(each(() => filtered.value, (item) => li(item))),
  );
});
```

## Tips for Cursor

1. **Use Cmd+K in a file** — Cursor generates inline code that respects the `.cursorrules` context.

2. **Tab completion works well** — Cursor's autocomplete picks up Whisq patterns from your existing code and the rules file.

3. **Chat mode for larger features** — use Cursor's chat panel for multi-file features like stores + components.

4. **Edit selections** — select existing code, press Cmd+K, and describe the change. Cursor will modify the code following Whisq conventions.

## Customizing .cursorrules

You can extend the rules file with project-specific conventions:

```
# .cursorrules (append to existing content)

## Project Conventions
- Use stores/ directory for shared state
- Component files use PascalCase: UserCard.ts
- Store files use camelCase: cartStore.ts
- All API calls go through stores, not components
```

## Next Steps

- [Claude Code](https://whisq.dev/ai/claude-code/) — Using Whisq with Claude Code
- [GitHub Copilot](https://whisq.dev/ai/copilot/) — Tips for Copilot users
- [LLM Reference](https://whisq.dev/ai/llm-reference/) — Complete API reference for any AI tool

---
# LLM Reference
URL: https://whisq.dev/ai/llm-reference/
---

This page contains the Whisq API in a format optimized for AI context windows. Copy and paste it into any AI assistant to get accurate Whisq code generation.

Hit an error the reference block didn't prevent? Check [Common Mistakes](https://whisq.dev/common-mistakes/) — it's the symptom-first debugging reference. For the positive complement ("what's the right way to do this?"), see [Canonical Patterns](https://whisq.dev/canonical-patterns/).

## How to Use

1. Pick a tier below based on your model's free context.
2. Copy that block (use the copy button in the top-right).
3. Paste it at the start of your AI conversation.
4. Describe the component you want to build.

This works with any LLM — ChatGPT, Claude, Gemini, Llama, Mistral, or local models.

## Current version

**The npm registry is authoritative.** If your AI tool or scaffolder needs to know the current Whisq release, hit the registry first and pin everything downstream to that exact version — don't resolve "what's current?" through a CDN `@latest` alias.

```bash
# 1. Resolve the current version from the registry (authoritative).
version=$(curl -s https://registry.npmjs.org/@whisq/core/latest | jq -r .version)

# 2. Fetch version-pinned artefacts at that exact version — NOT at @latest.
curl -s "https://unpkg.com/@whisq/core@${version}/dist/public-api.json" > public-api.json
```

:::caution[CDN `@latest` aliases can lag npm]
`https://unpkg.com/@whisq/core@latest/...` typically lags the npm registry by **minutes to hours** after a publish while the CDN's edge caches warm up. The alias can still point at the previous release even after the npm registry has fully propagated, so never use a CDN `@latest` URL to answer "what's the current version?". Pin by exact version once you've resolved it from the registry.

Codex's alpha.9 review ran into exactly this: the CDN-lag window caused the generated feedback to initially resolve `0.1.0-alpha.8` even after npm had published `0.1.0-alpha.9`, and only npm-registry verification corrected it.
:::

The `whisqCoreVersion` field in this repo's `package.json` — rendered at the bottom of every docs page — is the version these docs describe. It's kept in lockstep with the npm `@latest` tag by the release process; if a doc example diverges from what the registry reports, the docs are lagging, not the registry.

## Which tier?

- **Minimum** (≤2 K tokens) — `signal`, `computed`, `effect`, `batch`, elements, events, conditional and list rendering, components, basic async data, store pattern, anti-patterns. Pick this for small-context models (4 K / 8 K windows) or when the conversation already fills most of the window.
- **Complete** (≤5 K tokens) — everything in Minimum **plus** class composition (`cx`, `rcx`), scoped CSS and design tokens (`sheet`, `styles`, `theme`), context (`createContext` / `provide` / `inject`), error boundaries, keyed lists, and `resource().refetch()`. Pick this for frontier models or whenever you have headroom.

If you're not sure, paste the **Complete** block — it's still well under any modern model's context window.

## Reactive shapes — pick the right one

Four shapes cover every reactive position. Decision flow: *"single signal you own → `bind()`; field inside an item inside a signal-held array → `bindField()`; field that is itself a `Signal` (per-item nested signals) → `bind(item().field)`."*

| Shape | Example | Use when |
|---|---|---|
| Getter child | `span(() => count.value)` | Signal → inline text |
| Getter prop | `{ class: () => active.value ? "on" : "off" }` | Signal → single attribute / style |
| `class:` array (alpha.8) | `{ class: ["btn", () => loading.value && "btn-loading"] }` | Composing class names from a mix of static + reactive sources — eliminates the cx-vs-rcx decision |
| `bind()` spread | `input({ ...bind(email) })` | Two-way bind one signal into one form input |
| `bindField()` spread | `input({ ...bindField(todos, todo, "done", { as: "checkbox" }) })` | Field inside an item inside a signal-held array |

Inside keyed `each(..., { key })`, the callback's `item` is an **accessor function** — call `todo()` to read the current item. Getters that close over `todo` directly go stale when the array is replaced. Use `bindField(source, item, key)` for two-way binding inside the loop — it identifies the right item via `keyBy` (default `t => t.id`) and produces immutable array writes.

The pre-`bindField` "manual event pair" pattern (`{ checked: () => todo().done, onchange: () => toggle(todo().id) }`) is still valid as an escape hatch when your store holds nested signals per-item or when `bindField` doesn't fit (custom write logic, derived fields, etc.).

For nested-record paths inside a single signal (`user.profile.email`, `settings.billing.plan`), use [`bindPath()`](https://whisq.dev/api/bindpath/) from `@whisq/core/forms` — sub-path import, same discriminator surface as `bind()` / `bindField()`. Three primitives cover every two-way binding shape: `bind()` for one signal, `bindField()` for an array's item field, `bindPath()` for a record's nested-object field.

Decision matrix for the three per-row editing shapes (plain immutable / nested signal / extracted child component): [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/). For the broader "which primitive when" tables (binding, list rendering, persistence, conditional, reactive class), see [Choosing Patterns](https://whisq.dev/core-concepts/choosing-patterns/).

Full taxonomy + common mistakes: [`packages/core/docs/reactive-shapes.md`](https://github.com/whisqjs/whisq/blob/main/packages/core/docs/reactive-shapes.md).

**Capture trap.** Never hoist `.value.field` (or `.value`, or `accessor.value.field`) out of a reactive getter — you capture the *value*, not the *reactivity*. Read inside the `() =>` every time. See [Hoisting `.value.field` out of a reactive getter](https://whisq.dev/common-mistakes/#hoisting-valuefield-out-of-a-reactive-getter).

## Project structure

One-line rule: **one component per file; `main.ts` is for mounting, nothing else.**

```text
src/
  main.ts          # entrypoint — mounts App to #app, nothing else
  App.ts           # top-level component — routing, layout, error boundaries
  styles.ts        # sheet() definitions at module scope
  components/      # reusable UI — one PascalCase file per component, named export
  pages/           # route targets (if using @whisq/router)
  stores/          # shared state — one domain per file
  lib/             # pure utilities, NO Whisq imports
```

Anti-patterns to avoid:

- Everything in `main.ts` — AI rewrites the whole file to change anything.
- `src/lib/index.ts` utility soup — kills tree-shaking, invites circular imports.
- Default exports — don't compose in stack traces or auto-imports.
- Lowercase or mismatched component filenames (`button.ts` exporting `Button`) — breaks auto-import heuristics.
- `stores/store.ts` holding every domain — importing one drags in all.
- Top-level network calls in a store — breaks SSR and tests; use `resource()` or a user action. `localStorage` is the one blessed exception — see the [persistence pattern](https://whisq.dev/guides/state-management/#persistence-localstorage).

Full conventions + when-to-split guidance: [`packages/core/docs/project-structure.md`](https://github.com/whisqjs/whisq/blob/main/packages/core/docs/project-structure.md). A worked multi-file scaffold with prose walking each file: [Multi-file App Scaffold](https://whisq.dev/getting-started/multi-file-app/).

**Intra-file decision** — sub-renderer as a plain factory vs `component()`: use a plain factory `(props) => element(...)` for stateless markup; promote to `component()` when it adds `signal()` / `effect()` / lifecycle / `inject()` / cross-file reuse. See [Components → "Is this a component or just a function?"](https://whisq.dev/core-concepts/components/#is-this-a-component-or-just-a-function).

## Minimum

## Complete

Complete = everything in Minimum, plus: class composition (`cx`, `rcx`), scoped CSS and design tokens (`sheet`, `styles`, `theme`, `sx`), context (`createContext` / `provide` / `inject`), error boundaries, `bind()` two-way binding, tri-state rendering (`match`), DOM refs (`ref`), keyed lists, reactive collections (`signalMap`, `signalSet`), typed event handlers (`EventHandler`, `WhisqEvent`), portals, transitions, head management, `resource().refetch()`. The block below is the **combined** Minimum + extras, ready to copy in one paste.

## Why this works

The reference above stays within its advertised tier budgets — under 2 K tokens for Minimum and under 5 K for Complete — so it fits any model's context window with room for a real conversation. It covers:

- All reactive primitives (signal, computed, effect, batch)
- All element functions
- Event handling patterns
- Conditional and list rendering (with keyed reconciliation in Complete)
- Components with lifecycle
- Class-name composition (Complete: cx, rcx)
- Scoped CSS and design tokens (Complete: sheet, styles, theme)
- Context for prop-drill-free state (Complete: createContext, provide, inject)
- Error boundaries (Complete)
- Async data fetching (with refetch in Complete)
- Shared state pattern
- Common anti-patterns

Because Whisq uses plain JavaScript functions with no special syntax, AI models generate correct code with high accuracy. There's no JSX to misformat, no hook ordering to violate, and no template DSL to hallucinate.

## Next Steps

- [Claude Code](https://whisq.dev/ai/claude-code/) — Set up for Claude Code with CLAUDE.md
- [Cursor](https://whisq.dev/ai/cursor/) — Set up .cursorrules for Cursor
- [MCP Server](https://whisq.dev/ai/mcp-server/) — AI tooling with component scaffolding
- [Common Mistakes](https://whisq.dev/common-mistakes/) — Symptom-first debugging when a snippet from the block above doesn't work
- [How Reactivity Works](https://whisq.dev/core-concepts/reactivity-model/) — Diagram + 5 questions for when the snippet works but you want to know why
- [Testing](https://whisq.dev/guides/testing/) — Render components into JSDOM, query elements, assert on the DOM — the canonical test recipe using `@whisq/testing`

---
# MCP Server
URL: https://whisq.dev/ai/mcp-server/
---

`@whisq/mcp-server` provides AI coding assistants with two tools: **scaffold_component** for generating components from descriptions, and **validate_code** for checking Whisq code against common anti-patterns.

## Installation

```bash
npm install -D @whisq/mcp-server
```

The package includes a binary `whisq-mcp` that runs as a stdio-based MCP server.

## Configuration

### Claude Code

Add the server to your Claude Code MCP configuration:

```json
{
  "mcpServers": {
    "Whisq": {
      "command": "npx",
      "args": ["whisq-mcp"]
    }
  }
}
```

### Cursor

In Cursor settings, add:

```json
{
  "mcp.servers": {
    "Whisq": {
      "command": "npx",
      "args": ["whisq-mcp"]
    }
  }
}
```

### Other MCP Clients

Any MCP-compatible client can connect using the stdio transport:

```bash
npx whisq-mcp
```

The server communicates over stdin/stdout using the Model Context Protocol.

## Tools

### scaffold_component

Generates a Whisq component from a natural language description.

**Parameters:**
| Param | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Component name in PascalCase |
| `description` | string | Yes | What the component does |
| `props` | string[] | No | Optional prop names |

**Example prompt:**
```
Use the scaffold_component tool to create a UserCard component
that displays a user's name and email, with props for name and email.
```

**Generated output:**
```ts

/**
 * UserCard — Displays a user's name and email.
 */
const UserCard = component((props: { name: string; email: string }) => {
  return div({ class: "user-card" },
    h3(props.name),
    p(props.email),
  );
});

```

### validate_code

Checks Whisq code for common mistakes and anti-patterns.

**Parameters:**
| Param | Type | Required | Description |
|---|---|---|---|
| `code` | string | Yes | TypeScript/JavaScript code to validate |

**What it checks:**
- Static signal values used as children (should be wrapped in `() =>`)
- Direct array mutation (`.push()` instead of spread)
- Missing `preventDefault` on form submissions
- Import from wrong package paths

**Example prompt:**
```
Use validate_code to check this component:

const App = component(() => {
  const count = signal(0);
  return div(count.value);
});
```

**Response:**
```
Line 3: Signal value used directly as child — wrap in () => for reactivity
  Found: div(count.value)
  Fix: div(() => count.value)
```

## How It Works

The MCP server runs as a local process alongside your editor. When you (or the AI) invokes a tool:

1. The AI sends a tool call request over the MCP protocol
2. The server processes the request (scaffolding or validation)
3. The result is returned to the AI for use in its response

No data leaves your machine. The server runs entirely locally.

:::tip[🐱 Whisker Tip]
The MCP server complements `CLAUDE.md` — the context file teaches the AI the API, while the MCP server gives it active tools to generate and validate code.
:::

## Next Steps

- [Claude Code](https://whisq.dev/ai/claude-code/) — Using the MCP server with Claude Code
- [LLM Reference](https://whisq.dev/ai/llm-reference/) — The complete API reference
- [AI Integration Guide](https://whisq.dev/guides/ai-integration/) — Prompt patterns and workflows

---
# Link()
URL: https://whisq.dev/api/Link/
---

`Link(props, ...children)` renders an `<a>` that dispatches `router.navigate(href)` on plain left-clicks, preserving modified clicks (⌘-click, middle-click, etc.) for native browser behaviour — "open in new tab" works without special handling.

## Signature

```ts

function Link(
  props: {
    href: string;
    router: Router;
    class?: string | (() => string);
  },
  ...children: (string | number | WhisqNode)[]
): WhisqNode;
```

| Prop | Type | Description |
|---|---|---|
| `href` | `string` | Destination path — pushed via `router.navigate(href)` on plain left-click. |
| `router` | `Router` | The router instance to dispatch against. Pass the same `createRouter()` return value used by the enclosing `RouterView`. |
| `class` | `string \| (() => string)` (optional) | Same reactive-class shape as every other element prop — pass a function to recompute on route change (e.g. for active styling). |

## Basic link

```ts
Link({ href: "/about", router }, "About Us")
```

## Active-link styling

There's no dedicated `active` / `activeClass` prop — the reactive `class` getter is the pattern. Read `router.current.value.path` inside a getter:

```ts
Link({
  href: "/about",
  router,
  class: () => router.current.value.path === "/about" ? "active" : "",
}, "About")
```

For a navigation bar where many links share the same rule, factor the active-class function:

```ts
const isActive = (href: string) =>
  router.current.value.path === href ? "active" : "";

nav(
  Link({ href: "/",      router, class: () => isActive("/") },      "Home"),
  Link({ href: "/about", router, class: () => isActive("/about") }, "About"),
  Link({ href: "/blog",  router, class: () => isActive("/blog") },  "Blog"),
)
```

For **prefix-matching active styling** (e.g. `/blog` stays active on `/blog/my-post`), compare with `startsWith`:

```ts
class: () => router.current.value.path.startsWith("/blog") ? "active" : ""
```

## Modified-click pass-through

`Link` checks the click event and skips its own navigation if any of the following are true — the browser handles the click as a plain anchor:

- `event.button !== 0` (middle or right-click)
- `event.metaKey`, `event.ctrlKey`, `event.shiftKey`, `event.altKey`

So ⌘-click (or Ctrl-click on Windows) opens in a new tab, Shift-click opens in a new window, etc. — all native browser behaviours are preserved.

## Semantics

- **Plain `<a>` under the hood.** Renders via [`a(...)`](https://whisq.dev/api/elements/) and accepts the same reactive class getter pattern.
- **No prefetch, no active class prop.** Both are deliberately absent in the current router — if you need them, compose on top: wrap `Link` in your own component that adds a prefetch hook, or extract an `isActive` helper as shown above.
- **`href` is a plain string.** It's not reactive — if you need a dynamic destination, recompose: render a different `Link` or compute the href at call time.

## See also

- [`/api/createrouter/`](https://whisq.dev/api/createrouter/) — the router you pass into every `Link`.
- [`/api/routerview/`](https://whisq.dev/api/routerview/) — where clicks ultimately render.
- [`/api/elements/#class-array-form-since-alpha8`](https://whisq.dev/api/elements/#class-array-form-since-alpha8) — the class-array form also works inside `Link` when you pass it as the `class` getter's return (a single string).

---
# RouterView()
URL: https://whisq.dev/api/RouterView/
---

`RouterView(router, depth?)` subscribes to `router.current` and renders the component whose matched route sits at `depth` in the match chain. Lazy components (`() => import(...)`) are resolved on first match; swaps between routes call the previous component's `dispose()`.

## Signature

```ts

function RouterView(router: Router, depth?: number): WhisqNode;
```

| Param | Type | Description |
|---|---|---|
| `router` | `Router` | The router returned by [`createRouter`](https://whisq.dev/api/createrouter/). |
| `depth` | `number` (optional, default `0`) | Which level of the match chain to render. `0` = the top-level route; `1` = its child; etc. |

## Mounting the top-level view

Most apps have exactly one top-level `RouterView` at the app root:

```ts

const router = createRouter({
  routes: [
    { path: "/", component: Home },
    { path: "/about", component: About },
  ],
});

mount(RouterView(router), document.getElementById("app")!);
```

## Nested routes

A parent route declares `children`, and its component renders a `RouterView` at the next `depth`:

```ts
// App.ts
mount(RouterView(router), document.getElementById("app")!);
```

```ts
// routes.ts
const routes: RouteConfig[] = [
  {
    path: "/users",
    component: UsersLayout,     // renders at depth 0
    children: [
      { path: "",        component: UsersList },   // /users       → depth 1
      { path: ":id",     component: UserDetail },  // /users/:id   → depth 1
      { path: ":id/edit", component: UserEdit },   // /users/:id/edit → depth 1
    ],
  },
];
```

```ts
// UsersLayout.ts

```

Each nested route's params are available to its component via the render callback (via the first argument, which is `Record<string, string>`). `router.current.value.params` aggregates all params from every matched route.

## Transition interop

`RouterView` returns a `WhisqNode`, so it composes with [`transition()`](https://whisq.dev/api/transition/) like any other element:

```ts

transition(
  RouterView(router),
  {
    enter: { opacity: [0, 1], duration: 150 },
    exit:  { opacity: [1, 0], duration: 150 },
  },
)
```

Because the underlying DOM node is a single `<div data-whisq-router-view>` whose children swap on route change, outer transitions animate the container and not individual routes. For per-route animations, wrap each matched component in its own `transition()` call.

## Lifecycle

- **Mount.** `RouterView` attaches an effect on `router.current`. First render resolves the matched component (awaits the `import(...)` if lazy) and appends its DOM node.
- **Route change.** The previous component's `dispose()` is called, the container is cleared, the new component is resolved and mounted.
- **Stale resolutions are discarded.** If a route changes while a lazy component is still resolving, the resolution's output is dropped (identity check against `router.current.value`).
- **Unmount.** Call `node.dispose()` on the returned `WhisqNode` to tear down the effect and the current component. In practice you'd do this alongside `router.dispose()` during HMR or test teardown.

## See also

- [`/api/createrouter/`](https://whisq.dev/api/createrouter/) — the router that drives the view.
- [`/api/link/`](https://whisq.dev/api/link/) — navigation links.
- [`/api/route-state/`](https://whisq.dev/api/route-state/) — reading the current route inside a rendered component.

---
# batch()
URL: https://whisq.dev/api/batch/
---

Batch multiple signal updates so effects only run once. See [How Reactivity Works → batch()](https://whisq.dev/core-concepts/reactivity-model/#4-when-does-batch-matter) for when this matters in practice.

## Signature

```ts
function batch(fn: () => void): void
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fn` | `() => void` | Function containing multiple signal writes |

## Examples

```ts

const x = signal(0);
const y = signal(0);

effect(() => console.log(x.value, y.value));
// Logs: 0, 0

batch(() => {
  x.value = 1;
  y.value = 2;
});
// Logs: 1, 2 — only ONCE
```

:::tip[🐱 Whisker Tip]
Use `batch()` when updating multiple signals at once. Without it, each write triggers a separate effect re-run.
:::

## Guarantees

These four behaviors are pinned by tests in `@whisq/core` and won't change without a version bump. The full rationale — including which lines of `reactive.ts` implement each — lives in [`packages/core/docs/batch-semantics.md`](https://github.com/whisqjs/whisq/blob/develop/packages/core/docs/batch-semantics.md) in the framework repo.

The snippets below assume `import { signal, computed, effect, batch } from "@whisq/core";` at the top of the file (same as the Examples section above).

### Computeds don't recompute mid-batch

A `computed()` whose dependency is written inside a batch stays **stale** for the remainder of the batch. It recomputes exactly once after the batch exits, no matter how many times its dependencies were written.

```ts
const a = signal(1);
const b = signal(2);
const sum = computed(() => a.value + b.value);

sum.value; // 3 (primes the cache)

batch(() => {
  a.value = 10;
  b.value = 20;
  sum.value; // 3 — STALE, still the cached value
});

sum.value; // 30 (fresh)
```

### Nested batches are reference-counted

Effects flush only at the **outermost** boundary. Inner `batch()` calls exit without running effects.

```ts
batch(() => {
  a.value = 1;
  batch(() => {
    b.value = 2;
    // no flush here
  });
  // no flush here either
});
// one flush here — effects see a=1, b=2
```

### `await` closes the batch

`batch(fn)` is **synchronous**. Writes after the first `await` in an async function run **outside** the batch — the `finally` block flushes effects the instant `fn()` returns its pending Promise.

```ts
batch(async () => {
  a.value = 1;        // inside the batch — deferred
  await fetch("/x");
  b.value = 2;        // OUTSIDE — runs its effect immediately
});
```

For async "transactions," do the async work first and batch only the synchronous write cluster (assume the snippet runs inside an `async` function):

```ts
const data = await fetch("/x").then((r) => r.json());
batch(() => {
  user.value = data.user;
  settings.value = data.settings;
  status.value = "ready";
});
```

### A throw commits the writes so far

Signal writes inside `batch()` are **eager** — only the effect runs are deferred. If code throws mid-batch, prior writes stay committed, effects flush in `finally` for those writes, and the error propagates out.

```ts
try {
  batch(() => {
    a.value = 10; // committed
    throw new Error("oops");
    b.value = 20; // unreachable
  });
} catch {}

a.value; // 10 (committed)
b.value; // unchanged (assignment never ran)
// The effect reading `a` ran once after the throw, with a.value === 10.
```

There's no rollback — don't use `batch()` as a transaction.

## Not guaranteed

These are implementation details that work today but may change without a version bump:

- **Effect execution order within a flush.** Effects are enqueued in a `Set` and iterated in insertion order per today's ES spec, but this may change as the runtime evolves (priority queues, component-boundary batching).
- **Optimizations beyond dedup.** A single effect queued multiple times inside a batch runs exactly once at flush — that's guaranteed. Beyond that (e.g., skipping effects whose deps ended the batch with their original values), no promises.

---
# bind()
URL: https://whisq.dev/api/bind/
---

Spread `bind(signal, options?)` into a form control to wire it to a signal in one line. Covers text inputs (including `textarea` and `select`), numbers, checkboxes, and radio groups.

## Signature

```ts
function bind(signal: Signal<string>): TextBind;
function bind(
  signal: Signal<number>,
  options: { as: "number" },
): NumberBind;
function bind(
  signal: Signal<boolean>,
  options: { as: "checkbox" },
): CheckboxBind;
function bind<V extends string>(
  signal: Signal<V>,
  options: { as: "radio"; value: V },
): RadioBind<V>;
```

## Parameters

| Param     | Type                                      | Description                                                     |
| --------- | ----------------------------------------- | --------------------------------------------------------------- |
| `signal`  | `Signal<string \| number \| boolean>`     | The signal to read from and write to                            |
| `options` | `{ as: "number" \| "checkbox" \| "radio"; value?: V }` | Kind of input; `radio` also needs the per-radio `value` |

## Returns

A plain props object matching the input kind:

| Kind       | Return type    | Props                                                          |
| ---------- | -------------- | -------------------------------------------------------------- |
| default    | `TextBind`     | `{ value: () => string, oninput: (e) => void }`                |
| `number`   | `NumberBind`   | `{ value: () => string, oninput: (e) => void }` (coerces)      |
| `checkbox` | `CheckboxBind` | `{ checked: () => boolean, onchange: (e) => void }`            |
| `radio`    | `RadioBind<V>` | `{ value: V, checked: () => boolean, onchange: (e) => void }`  |

## Examples

```ts

const name = signal("");
input({ ...bind(name) });                                            // text

const age = signal(0);
input({ type: "number", ...bind(age, { as: "number" }) });

const agreed = signal(false);
input({ type: "checkbox", ...bind(agreed, { as: "checkbox" }) });

const role = signal<"admin" | "user">("user");
input({ type: "radio", name: "role", ...bind(role, { as: "radio", value: "admin" }) });
input({ type: "radio", name: "role", ...bind(role, { as: "radio", value: "user"  }) });

const bio = signal("");
textarea({ ...bind(bio) });

const tier = signal("free");
select({ ...bind(tier) }, option({ value: "free" }, "Free"), option({ value: "pro" }, "Pro"));
```

See [Forms guide](https://whisq.dev/guides/forms/) for the full pattern including validation and reset.

## Handler collision (dev warning since alpha.9)

Spreading `bind(...)` and then overwriting one of its declared handlers silently drops the binding. Alpha.9+ catches it with a `console.warn` in dev (zero cost in production).

```ts
// ❌ Direction 1 — spread-first, user-handler-second. Dev: console.warn fires.
input({
  ...bind(draft),
  oninput: (e) => track(e),    // overwrites bind's oninput
});

// ✅ Canonical — put the custom handler BEFORE the bind spread
input({
  oninput: (e) => track(e),    // user handler first...
  ...bind(draft),              // ...bind wins visibly; this is what you want
});
```

**Why "spread bind last" is the convention.** The framework can only detect the collision in **direction 1** — when `bind()` sets the handler and the user later overwrites. The reverse case (user handler first, then `...bind()`) destroys the user's handler without trace — by the time the element builder sees the props, the user's handler is already gone. The warning steers you toward the safe convention: **spread bind last** so if there *is* a collision, your own handler visibly "wins" and the absence of the expected bind behaviour is loud instead of silent.

### If you deliberately want to augment bind

Chain your handler after reading `bind()`'s output — that's a transparent composition that dodges the collision entirely:

```ts
const draftBinding = bind(draft);
input({
  ...draftBinding,
  oninput: (e) => {
    draftBinding.oninput(e);  // run bind's handler first
    track(e);                  // then your own
  },
});
```

The warning fires on symbol-keyed-manifest check in the element builder; the three bind helpers (`bind`, `bindField`, `bindPath`) attach the manifest identically, so the rule is the same on all of them.

## Related primitives

- [`bindField()`](https://whisq.dev/api/bindfield/) — bind a field on an item inside a signal-held array (per-row inputs in lists).
- [`bindPath()`](https://whisq.dev/api/bindpath/) — bind a field at a nested object path inside a signal-held record (multi-step forms, settings panels).
- [Event types](https://whisq.dev/api/event-types/) — `WhisqEvent` and `EventHandler` for typed custom handlers when the spread isn't enough.

---
# bindField()
URL: https://whisq.dev/api/bindField/
---

Spread `bindField(source, item, key, options?)` into a form control to wire it to one field of one item inside a signal-held array. Sibling to [`bind()`](https://whisq.dev/api/bind/) — same discriminator shapes — but reaches into the per-item-per-field shape that `bind()` doesn't.

The realistic case: a checkbox per row in a list of todos, where the source array holds plain objects (no nested signals).

```ts
each(() => todos.value, (todo) =>
  input({
    type: "checkbox",
    ...bindField(todos, todo, "done", { as: "checkbox" }),
  }),
  { key: (t) => t.id },
)
```

## Signature

```ts
function bindField<T, K extends keyof T>(
  source: Signal<T[]>,
  item: () => T,
  key: K,
): TextBind;
function bindField<T, K extends keyof T>(
  source: Signal<T[]>,
  item: () => T,
  key: K,
  options: { as: "number" } & Common<T>,
): NumberBind;
function bindField<T, K extends keyof T>(
  source: Signal<T[]>,
  item: () => T,
  key: K,
  options: { as: "checkbox" } & Common<T>,
): CheckboxBind;
function bindField<T, K extends keyof T, V extends string>(
  source: Signal<T[]>,
  item: () => T,
  key: K,
  options: { as: "radio"; value: V } & Common<T>,
): RadioBind<V>;
```

Where `Common<T>` is `{ keyBy?: (item: T) => unknown }`. The exported public type alias is `BindFieldOptions<T>` — import it from `@whisq/core` when you need to type an `options` object explicitly.

## Parameters

| Param     | Type                                              | Description                                                                  |
| --------- | ------------------------------------------------- | ---------------------------------------------------------------------------- |
| `source`  | `Signal<T[]>`                                     | The array signal that holds the items                                        |
| `item`    | `() => T`                                         | Accessor for the current item — typically the keyed-`each()` callback's first arg |
| `key`     | `K extends keyof T`                               | The field on `T` to bind                                                     |
| `options.as`   | `"number" \| "checkbox" \| "radio"` (optional) | Kind of input — same discriminator as `bind()`                              |
| `options.value` | `V` (radio only, required)                   | The per-radio value, same as `bind()`                                       |
| `options.keyBy` | `(item: T) => unknown` (optional)            | Identifies which item to rewrite. Default: `t => t.id`                       |
| `options.strict` | `boolean` (optional, since alpha.8)         | Pin no-match write behaviour. `true` = throw `WhisqKeyByError` in both envs; `false` = warn-and-discard in both envs. Default: `true` in dev (`process.env.NODE_ENV !== "production"`), `false` in production. |

## Returns

A plain props object matching the input kind — identical to `bind()`'s return shapes:

| Kind       | Return type    | Props                                                         |
| ---------- | -------------- | ------------------------------------------------------------- |
| default    | `TextBind`     | `{ value: () => string, oninput: (e) => void }`               |
| `number`   | `NumberBind`   | `{ value: () => string, oninput: (e) => void }` (coerces)     |
| `checkbox` | `CheckboxBind` | `{ checked: () => boolean, onchange: (e) => void }`           |
| `radio`    | `RadioBind<V>` | `{ value: V, checked: () => boolean, onchange: (e) => void }` |

## Examples

### Checkbox per item

```ts

interface Todo { id: number; text: string; done: boolean }

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: false },
  { id: 2, text: "Build an app", done: false },
]);

ul(
  each(() => todos.value, (todo) =>
    li(
      input({ type: "checkbox", ...bindField(todos, todo, "done", { as: "checkbox" }) }),
      todo().text,
    ),
    { key: (t) => t.id },
  ),
)
```

### Editable text field per item

```ts
ul(
  each(() => todos.value, (todo) =>
    li(input({ ...bindField(todos, todo, "text") })),
    { key: (t) => t.id },
  ),
)
```

### Number input per item

```ts
interface CartItem { id: string; sku: string; qty: number }
const cart = signal<CartItem[]>([/* ... */]);

each(() => cart.value, (item) =>
  input({
    type: "number",
    min: 0,
    ...bindField(cart, item, "qty", { as: "number" }),
  }),
  { key: (i) => i.id },
)
```

### Radio per item (e.g. priority picker)

```ts
type Priority = "low" | "med" | "high";
interface Task { id: number; priority: Priority }
const tasks = signal<Task[]>([/* ... */]);

each(() => tasks.value, (task) =>
  div(
    (["low", "med", "high"] as const).map((p) =>
      input({
        type: "radio",
        name: `priority-${task().id}`,
        ...bindField(tasks, task, "priority", { as: "radio", value: p }),
      }),
    ),
  ),
  { key: (t) => t.id },
)
```

### Custom `keyBy`

When your item identifier isn't called `id`:

```ts
interface User { uuid: string; name: string }
const users = signal<User[]>([/* ... */]);

each(() => users.value, (user) =>
  input({
    ...bindField(users, user, "name", { keyBy: (u) => u.uuid }),
  }),
  { key: (u) => u.uuid },
)
```

## Semantics

- **Immutable array updates.** Writes produce a new array via `source.value.map(...)` — downstream `computed`, `effect`, and keyed `each()` re-reconcile correctly. No in-place mutation, no surprises for code that depends on referential change.
- **No-match writes throw `WhisqKeyByError` in dev** (since alpha.8), or warn-and-discard in production. See the dedicated section below.
- **Lives across component boundaries.** Pass `todo: () => Todo` as a prop to a child component and call `bindField(todos, props.todo, "done")` inside — works the same as inline. The accessor stays live; the source signal is captured once and identifies items by `keyBy`. See [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component).
- **Type narrowing.** TypeScript checks that `key` is a valid field of `T` and that the discriminator (`as: "checkbox"` etc.) matches the field's expected runtime type. Misuse compiles to clear errors.
- **Runtime guards.** Throws `TypeError: bindField: source must be Signal` if you pass an unwrapped value (e.g. `bindField(todos.value, ...)` instead of `bindField(todos, ...)`), and `TypeError: bindField: item must be a function` if you pass a plain object instead of the keyed-`each()` accessor.

## Dev-mode behaviour and the `strict` option

Since alpha.8, a write that can't find an item in the source array whose `keyBy(...)` matches the accessor's key throws `WhisqKeyByError` in dev (was: `console.warn` + discard). The typical cause is a stale accessor (the item was removed from the source after the accessor was created) or a broken `keyBy` function.

```ts
// Default in vite dev: throws WhisqKeyByError on no-match writes
input({ ...bindField(todos, todo, "done", { as: "checkbox" }) });

// Opt out for a test that deliberately exercises the no-match path:
input({
  ...bindField(todos, todo, "done", { as: "checkbox", strict: false }),
});
```

| `strict`        | Dev (`NODE_ENV !== "production"`) | Production |
|-----------------|-----------------------------------|------------|
| (omitted, default) | **throws `WhisqKeyByError`**   | warn-and-discard |
| `true`          | throws `WhisqKeyByError`          | **throws `WhisqKeyByError`** |
| `false`         | warn-and-discard                  | warn-and-discard |

`WhisqKeyByError` extends `Error` and carries:

| Field | Type | Description |
|---|---|---|
| `sourceKeys` | `unknown[]` | All keys present in the source array at write time, in source order |
| `targetKey` | `unknown` | The key the write was trying to match against |
| `field` | `string` | The field name being written (from `bindField`'s `key` argument) |

Both the class and its `WhisqKeyByErrorFields` shape are exported from `@whisq/core` ([`/api/imports/`](https://whisq.dev/api/imports/#-main-entry)). Catch it in an [`errorBoundary`](https://whisq.dev/api/errorboundary/) to render a friendly UI for stale-row edits, or let it bubble in tests to surface integration issues.

## Writing through filtered / partitioned views

A common shape: iterate a **filtered** view of a list (from `partition()` or a `computed`), but let the per-row input edit the **source**.

:::caution[The rule]
Pass the **source** signal to `bindField`, not the filtered signal. The accessor's `keyBy` lookup runs against whichever signal you pass, so passing the source is what makes the write target the real array.
:::

Why this works: the render callback's accessor (`todo`) just carries a reference to a `Todo` object. That same `Todo` also lives in the source array, so looking it up there by `keyBy(todo())` (default `t => t.id`) matches. `bindField` doesn't care which signal produced the accessor — it rewrites whichever array you hand it.

### Worked example

```ts
// stores/todos.ts

const [pending, completed] = partition(() => todos.value, (t) => !t.done);

    case "done":   return completed.value;
    default:       return todos.value;
  }
});
```

```ts
// components/TodoList.ts

const TodoList = component(() =>
  ul(
    each(() => filtered.value, (todo) =>
      li(
        // ✅ Iterate the filtered view, but bind against the SOURCE signal.
        // bindField's keyBy lookup runs against `todos`, which is where the
        // item actually lives — the write lands on the real array.
        input({ type: "checkbox", ...bindField(todos, todo, "done", { as: "checkbox" }) }),
        () => todo.value.text,
      ),
      { key: (t) => t.id },
    ),
  ),
);
```

The same rule applies when you split the row into its own component — pass both the source signal and the accessor as props, then call `bindField(props.source, props.todo, ...)` inside. The source signal's identity is captured once; the accessor stays live.

### Why not just pass `filtered` to `bindField`?

Two shapes of this mistake — one caught by the type system, one not.

**Shape 1 — type-prevented.** `partition()` and `computed()` both return `ReadonlySignal<T[]>`, and `bindField`'s first parameter is `Signal<T[]>`. Passing `pending`, `completed`, or a `computed()` result directly is a TypeScript error at the call site. The types catch the most common form of the mistake before runtime.

**Shape 2 — type-evaded (the real footgun).** A hand-rolled **writable** shadow signal that mirrors the filtered view typechecks but still fails:

```ts
// ❌ ANTI-PATTERN — hand-rolled writable filter view
const filteredCopy = signal<Todo[]>([]);
effect(() => {
  filteredCopy.value = todos.value.filter((t) =>
    filter.value === "all" ? true : filter.value === "active" ? !t.done : t.done,
  );
});

each(() => filteredCopy.value, (todo) =>
  input({
    type: "checkbox",
    // Writes update filteredCopy, not todos — the real source never sees the
    // edit, and the next effect beat overwrites filteredCopy.value anyway.
    // When the toggled item transitions out of the filter, its id is no
    // longer in filteredCopy → WhisqKeyByError on the next write in dev.
    ...bindField(filteredCopy, todo, "done", { as: "checkbox" }),
  }),
  { key: (t) => t.id },
);
```

Two failures at once: writes target the shadow array (which is about to be overwritten by the effect), and once the item stops matching the filter, its accessor can no longer find itself in `filteredCopy` and the write is discarded (or throws `WhisqKeyByError` in dev). The fix is `bindField(todos, todo, ...)` — nothing else changes.

## When to use which

| Shape | Helper | When |
|---|---|---|
| Single signal you own | [`bind(signal)`](https://whisq.dev/api/bind/) | One input ↔ one signal |
| Field inside an item inside a signal-held array | `bindField(source, item, key)` | Per-row inputs in lists, CRUD grids, editable tables |
| Field inside an item where the field is a `Signal` | [`bind(item().done)`](https://whisq.dev/api/bind/) | When you intentionally want per-item reactive isolation — toggling one checkbox re-evaluates only that item's signal, not the array. The array signal stays still on toggle, so dependent `computed`/`effect` don't re-fire. See [todo-app example](https://whisq.dev/examples/todo-app/) for the canonical use. |

The third shape (nested-signal store + `bind()`) is fine and idiomatic. `bindField()` exists so apps that prefer plain-object item shapes don't have to reach for the manual event-pair escape hatch.

See also: [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one), [Forms guide → list of items](https://whisq.dev/guides/forms/#binding-fields-inside-list-items), [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/) — which pattern to pick when (plain immutable / nested signal / extracted child), [Handler collision dev warning](https://whisq.dev/api/bind/#handler-collision-dev-warning-since-alpha9) — applies to `bindField()` spreads the same way as `bind()`.

---
# bindPath()
URL: https://whisq.dev/api/bindPath/
---

Spread `bindPath(source, path, options?)` into a form control to wire it to a field nested inside a signal-held record. Sibling to [`bind()`](https://whisq.dev/api/bind/) and [`bindField()`](https://whisq.dev/api/bindfield/) — same discriminator surface — but reaches into deep object paths that those primitives don't.

The realistic case: a multi-step user-profile form on a `Signal<User>` where fields live at `user.profile.email`, `user.prefs.dark`, etc.

```ts

interface User {
  id: string;
  profile: { name: string; email: string; age: number };
  prefs: { dark: boolean };
}

const user = signal<User>({
  id: "u1",
  profile: { name: "", email: "", age: 0 },
  prefs: { dark: false },
});

form(
  input({ ...bindPath(user, ["profile", "name"]) }),
  input({ type: "email", ...bindPath(user, ["profile", "email"]) }),
  input({ type: "number", ...bindPath(user, ["profile", "age"], { as: "number" }) }),
  input({ type: "checkbox", ...bindPath(user, ["prefs", "dark"], { as: "checkbox" }) }),
)
```

## Import

`bindPath()` lives on the `@whisq/core/forms` sub-path so apps that only need `bind()` and `bindField()` (the 80% case) pay no bundle cost. See [`/api/imports/`](https://whisq.dev/api/imports/#whisqcoreforms) for the full sub-path reference.

```ts
```

## Signature

```ts
// Typed overloads for depths 1–4 (TypeScript checks each path key against the
// parent shape). Default-discriminator returns TextBind only when the field
// resolves to `string`; misuse on a non-string field is a type error.

function bindPath<T, K1 extends keyof T>(
  source: Signal<T>,
  path: readonly [K1],
): T[K1] extends string ? TextBind : never;

function bindPath<T, K1 extends keyof T, K2 extends keyof T[K1]>(
  source: Signal<T>,
  path: readonly [K1, K2],
): T[K1][K2] extends string ? TextBind : never;

// ... and so on for depth 3 and 4 (same shape, more keys).

// Loose signature — works at any depth, less TS inference.
function bindPath<T>(
  source: Signal<T>,
  path: readonly PropertyKey[],
  options: { as: "number" },
): NumberBind;

function bindPath<T>(
  source: Signal<T>,
  path: readonly PropertyKey[],
  options: { as: "checkbox" },
): CheckboxBind;

function bindPath<T, V extends string>(
  source: Signal<T>,
  path: readonly PropertyKey[],
  options: { as: "radio"; value: V },
): RadioBind<V>;

function bindPath<T>(
  source: Signal<T>,
  path: readonly PropertyKey[],
  options?: PathOptions,
): TextBind;
```

## Parameters

| Param           | Type                                            | Description                                                                                  |
| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `source`        | `Signal<T>`                                     | The signal holding the root record                                                           |
| `path`          | `readonly PropertyKey[]`                        | A non-empty array of keys describing the field's path. **Object keys only — no array indexes.** |
| `options.as`    | `"number" \| "checkbox" \| "radio"` (optional)  | Kind of input — same discriminator as `bind()` and `bindField()`                             |
| `options.value` | `V` (radio only, required)                      | The per-radio value, same as `bind()`                                                        |

## Returns

A plain props object matching the input kind — identical to `bind()`'s return shapes:

| Kind       | Return type    | Props                                                         |
| ---------- | -------------- | ------------------------------------------------------------- |
| default    | `TextBind`     | `{ value: () => string, oninput: (e) => void }`               |
| `number`   | `NumberBind`   | `{ value: () => string, oninput: (e) => void }` (coerces)     |
| `checkbox` | `CheckboxBind` | `{ checked: () => boolean, onchange: (e) => void }`           |
| `radio`    | `RadioBind<V>` | `{ value: V, checked: () => boolean, onchange: (e) => void }` |

## Examples

### Profile form (text + email + number + checkbox)

```ts

interface User {
  id: string;
  profile: { name: string; email: string; age: number };
  prefs: { dark: boolean };
}

const user = signal<User>({
  id: "u1",
  profile: { name: "", email: "", age: 0 },
  prefs: { dark: false },
});

form(
  label("Name", input({ ...bindPath(user, ["profile", "name"]) })),
  label("Email", input({ type: "email", ...bindPath(user, ["profile", "email"]) })),
  label("Age", input({ type: "number", ...bindPath(user, ["profile", "age"], { as: "number" }) })),
  label("Dark mode", input({ type: "checkbox", ...bindPath(user, ["prefs", "dark"], { as: "checkbox" }) })),
)
```

### Settings with a radio group

```ts
interface Settings {
  billing: { plan: "free" | "pro" | "team" };
}

const settings = signal<Settings>({ billing: { plan: "free" } });

div(
  (["free", "pro", "team"] as const).map((plan) =>
    label(
      input({
        type: "radio",
        name: "plan",
        ...bindPath(settings, ["billing", "plan"], { as: "radio", value: plan }),
      }),
      plan,
    ),
  ),
)
```

### Composing with `bindField()` for arrays inside the path

`bindPath` does **not** traverse arrays — `["items", 0, "done"]` would walk `items[0]` as if `0` were an object key on whatever the array exposes. And `bindPath` requires a `Signal<T>` (a single record), not a `Signal<T[]>` — calling `bindPath(orders, [...])` on an array signal is a `TypeError` at the path-walk level.

For per-item fields inside an array, use `bindField()` at the array level. For nested-object fields **on a single record**, use `bindPath` at that record. To combine both — a CRUD grid where each row is a record with nested fields — factor the per-row render into its own component that owns a per-row `Signal<T>`:

```ts

interface Order {
  id: string;
  items: Array<{ id: string; sku: string; qty: number }>;
  shipping: { address: { line1: string; city: string } };
}

const orders = signal<Order[]>([/* … */]);

// Per-row component with its own Signal<Order> derived from the parent.
// Two-way sync back to the parent array isn't free — wire an effect or
// expose an `onChange(updated)` prop. This snippet shows the binding
// shape only; pick a sync strategy for your store.
const OrderRow = component((props: { initial: Order }) => {
  const order = signal(props.initial);

  return div(
    // bindField — per-cell input on the row's nested items array.
    each(() => order.value.items, (item) =>
      input({
        type: "number",
        ...bindField(
          // Bind against a derived Signal<items[]>; in practice you
          // expose a sub-signal or use a setter helper here.
          signal(order.value.items),
          item,
          "qty",
          { as: "number" },
        ),
      }),
      { key: (i) => i.id },
    ),
    // bindPath — nested-object field on the row's single record.
    input({ ...bindPath(order, ["shipping", "address", "city"]) }),
  );
});
```

For most apps a simpler split works: keep deeply nested fields out of array elements, or use one `Signal<Record>` per top-level entity instead of one `Signal<Record[]>`. `bindPath` is sharpest when paired with single-record state — settings panels, profile forms, single-document editors.

## Semantics

- **Structural sharing on writes.** Writes produce a new root and new objects at every level on the path; **sibling branches preserve referential identity**. Downstream `computed` / `effect` that depend on unaffected branches don't re-run.
- **Missing intermediates.** Reading through a missing intermediate returns `undefined`. Writing **creates** the object structure as needed — `bindPath(empty, ["a", "b", "c"])` writes through `{ a: { b: { c: value } } }`. If an intermediate is `null`, `undefined`, or any non-object value (string, number, boolean), the write replaces it with a fresh object. Intentional: lets you wire forms before optional records exist, but be aware that writing into a path whose ancestor is currently a primitive will clobber that primitive.
- **Object keys only.** Array traversal is not supported in the path. `["items", 0]` would treat `0` as an object key, not an array index — usually not what you want. Use `bindField()` for array-element fields. This keeps `bindPath` predictable and its implementation small.
- **Typed overloads for depths 1–4.** TypeScript checks each path key against the parent shape, giving you autocomplete + misuse detection through 4 levels. Deeper paths fall through to the loose signature (same runtime, less TS inference) — split into a sub-record signal if you find yourself nesting further.
- **TypeError throws.** `bindPath: source must be a Signal` if you pass an unwrapped value (e.g. `bindPath(user.value, …)` instead of `bindPath(user, …)`). `bindPath: path must be a non-empty array of keys` if `path` is empty or not an array.

## When to use which

| Shape | Helper | When |
|---|---|---|
| Single signal you own | [`bind(signal)`](https://whisq.dev/api/bind/) | One input ↔ one signal |
| Field inside an item inside a signal-held array | [`bindField(source, item, key)`](https://whisq.dev/api/bindfield/) | Per-row inputs in lists, CRUD grids, editable tables |
| Field at a nested object path inside a signal-held record | `bindPath(source, path)` | Multi-step forms, settings panels, `user.profile.email` shapes |

The three helpers compose: a CRUD grid where each row is a record with nested fields uses `bindField` at the array level and (after factoring the row into a component with a per-row signal) `bindPath` for the inner-object cells.

See also: [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one), [Forms guide → binding into nested records](https://whisq.dev/guides/forms/#binding-into-nested-records), [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/) — when an array row hosts a nested record, the guide's pattern 3 covers the row-as-component split. [Persisted settings recipe](https://whisq.dev/guides/state-management/#recipe--persisted-settings-single-record--bindpath) — `bindPath` + `persistedSignal<Settings>` for nested-field writes on a persisted single record. [Handler collision dev warning](https://whisq.dev/api/bind/#handler-collision-dev-warning-since-alpha9) — applies to `bindPath()` spreads the same way as `bind()`.

---
# component()
URL: https://whisq.dev/api/component/
---

Define a component with a setup function.

## Signature

```ts
function component<P extends Record<string, any>>(
  setup: (props: P) => ComponentSetupReturn,
): ComponentDef<P>

// Since alpha.9 — setup can return a WhisqNode OR a function child
type ComponentSetupReturn = WhisqNode | (() => unknown);
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `setup` | `(props: P) => ComponentSetupReturn` | Setup function — runs once. Returns either a `WhisqNode` (element-shaped — the canonical form) or a `() => unknown` function child (since alpha.9 — for branching components). |

:::caution
`setup` runs **once** and props are captured at that moment — they are not reactive by default. Pass [getter functions](https://whisq.dev/core-concepts/signals/#getters-and-accessors) (`() => signal.value`) when a parent needs to update a child's value over time. See [Components → Props and reactivity](https://whisq.dev/core-concepts/components/#props-and-reactivity).
:::

## Returns

`ComponentDef<P>` — a callable that accepts props and returns a `WhisqNode`.

## Examples

```ts

const Counter = component((props: { initial?: number }) => {
  const count = signal(props.initial ?? 0);

  return div(
    button({ onclick: () => count.value-- }, "-"),
    span(() => ` ${count.value} `),
    button({ onclick: () => count.value++ }, "+"),
  );
});

mount(Counter({ initial: 10 }), document.getElementById("app")!);
```

## Function-child root (since alpha.9)

When a component's entire job is to branch — render loading / error / data, or swap between views — setup can return the function directly. No wrapper element required.

```ts

const Screen = component(() =>
  match(
    [() => view.value === "loading", () => p("loading")],
    [() => view.value === "data", () => DataView({})],
    () => p("empty"),
  ),
);
```

Works for any zero-arg function return — `when()`, `match()`, `each()` result, or a plain `() => someNode`. Under the hood, `component()` wraps the function in a fragment bounded by start/end markers (the same pattern `errorBoundary` and keyed `each` already use). Branch switches dispose the previous `WhisqNode` before inserting the next — no node leaks.

Pick the shape by what the component *is*:

- **Element root** (`div`, `section`, custom semantic element) — use when you need to attach class / style / events to the root. This is the canonical form.
- **Function-child root** — use when the component *is* the branch. No wrapper DOM, no sacrificial `div`.

`onMount` / `onCleanup` hooks registered inside setup fire normally in both shapes.

**Before alpha.9**, the function-child form threw `WhisqStructureError` at mount; you had to wrap in a neutral element. See the [Using match() as a component root](https://whisq.dev/api/match/#using-match-as-a-component-root) section for migration notes.

---
# computed()
URL: https://whisq.dev/api/computed/
---

Create a read-only signal that auto-updates when dependencies change.

## Signature

```ts
function computed<T>(fn: () => T): ReadonlySignal<T>
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fn` | `() => T` | Computation function — reads other signals |

## Returns

`ReadonlySignal<T>` — same as Signal but read-only (no `.set()`, `.update()`, or `.value =`).

## Examples

```ts

const count = signal(3);
const double = computed(() => count.value * 2);

double.value; // 6
count.value = 5;
double.value; // 10 — auto-updated
```

:::tip[🐱 Whisker Tip]
Computed values are lazy and cached — they don't recompute until read, and reading twice without changes returns the cached value.
:::

## Related primitives

- [`signal()`](https://whisq.dev/api/signal/) — the mutable primitive `computed()` reads from.
- [`effect()`](https://whisq.dev/api/effect/) — side effects triggered by signal/computed changes.
- [`batch()`](https://whisq.dev/api/batch/) — group writes so dependent computeds re-read only once.
- [`partition()`](https://whisq.dev/api/partition/) — convenience helper that returns two computeds splitting an array signal by a predicate.

---
# createContext()
URL: https://whisq.dev/api/createContext/
---

Create a context object that components can `provide()` and descendants can `inject()`.

## Signature

```ts
function createContext<T>(defaultValue: T): Context<T>
```

## Parameters

| Param          | Type | Description                                                  |
| -------------- | ---- | ------------------------------------------------------------ |
| `defaultValue` | `T`  | Returned by `inject()` when no ancestor has called `provide()` |

## Returns

`Context<T>` — pass to [`provide()`](https://whisq.dev/api/provide/) and [`inject()`](https://whisq.dev/api/inject/).

## Examples

```ts

const ThemeCtx = createContext("light");

const Parent = component(() => {
  provide(ThemeCtx, "dark");
  return div(Child({}));
});

const Child = component(() => {
  const theme = inject(ThemeCtx); // "dark"
  return p(`Theme: ${theme}`);
});
```

See [Components → Context](https://whisq.dev/core-concepts/components/#context-provideinject) for the full pattern.

---
# createRouter()
URL: https://whisq.dev/api/createRouter/
---

`createRouter(config)` builds a router around a single `current` signal. Subscribing to that signal is how every other piece of router-aware UI (`RouterView`, `Link`, components that read `params` / `query`) stays reactive.

Ships from the separate package `@whisq/router`, versioned lockstep with `@whisq/core`:

```bash
npm install @whisq/router
```

## Signature

```ts

function createRouter(config: RouterConfig): Router;
```

## Quick start

```ts

const router = createRouter({
  routes: [
    { path: "/", component: Home },
    { path: "/users/:id", component: UserDetail },
    { path: "*", component: NotFound },
  ],
});

mount(RouterView(router), document.getElementById("app")!);
```

## `RouterConfig`

| Field | Type | Description |
|---|---|---|
| `routes` | `RouteConfig[]` | Route table. First match wins; order matters. |
| `beforeEach` | `NavigationGuard` (optional) | Runs before every navigation. Return `false` to cancel, a string to redirect, or `void` / `true` to proceed. |
| `afterEach` | `AfterGuard` (optional) | Runs after every successful navigation. Side-effect only — return value is ignored. |
| `scrollBehavior` | `ScrollBehaviorOption` (optional, default `"top"`) | `"top"` scrolls to 0,0; `"restore"` remembers and restores per-path scroll on back/forward; `"auto"` and `false` leave scroll untouched. |

## `RouteConfig`

| Field | Type | Description |
|---|---|---|
| `path` | `string` | Pattern: static (`/about`), param (`/users/:id`), or wildcard (`*`). `:name` extracts into `params.name`. |
| `component` | `RouteComponent` | Either a sync `(params) => WhisqNode` or a lazy `() => import("./X")` whose default export is the component. |
| `children` | `RouteConfig[]` (optional) | Nested routes. When a route has children, the parent matches as a prefix; children render into a depth-1 `RouterView`. |
| `meta` | `Record<string, unknown>` (optional) | Arbitrary per-route metadata. Merged into the resolved `RouteState.meta` in matched order. |
| `beforeEnter` | `NavigationGuard` (optional) | Per-route guard. Runs after the global `beforeEach` for every matched route in the chain. |

Lazy components work by returning a promise:

```ts
{ path: "/admin", component: () => import("./routes/Admin") }
// ./routes/Admin.ts must `export default` the component.
```

## Guards — `NavigationGuard` and `AfterGuard`

```ts
type NavigationGuard = (
  to: RouteState,
  from: RouteState | null,
) => boolean | string | void;

type AfterGuard = (to: RouteState, from: RouteState | null) => void;
```

**Return-value semantics for `NavigationGuard`:**

| Returned value | Effect |
|---|---|
| `true` / `undefined` | Proceed |
| `false` | Cancel navigation; URL is reverted on push-navigations (back/forward keep the new URL) |
| `string` | Redirect to that path; the redirect itself is pushed as a replacement of the current history entry |

Guards run in order: global `beforeEach` first, then each matched route's `beforeEnter` top-down. The first `false` or string short-circuits the chain.

```ts
createRouter({
  routes: [...],
  beforeEach: (to) => {
    if (to.meta.requiresAuth && !isLoggedIn()) return "/login";
  },
});
```

## `Router` interface

```ts
interface Router {
  current: ReadonlySignal<RouteState>;
  navigate(path: string): void;
  back(): void;
  forward(): void;
  dispose(): void;
}
```

| Member | Description |
|---|---|
| `current` | The reactive `RouteState` signal. Read as `router.current.value` (or pass `() => router.current.value` to `computed` / effects). |
| `navigate(path)` | Push-state navigation. Runs guards. Equivalent to what `Link` dispatches on click. |
| `back()` | Calls `window.history.back()`. `popstate` re-runs guards. |
| `forward()` | Calls `window.history.forward()`. |
| `dispose()` | Detaches the internal `popstate` listener. Call when hot-reloading or tearing down tests — without this the listener leaks across module re-loads. |

`current` is a `ReadonlySignal<RouteState>` — you cannot write to it directly. Navigation is the only way to change the route.

## `ScrollBehaviorOption`

| Value | Behaviour |
|---|---|
| `"top"` (default) | Scroll to `(0, 0)` on every navigation |
| `"restore"` | Save scroll on leave; restore on back/forward. Forward navigations still scroll to top |
| `"auto"` | Leave scroll untouched (browser default on `popstate` — useful with native anchor scrolling) |
| `false` | Same as `"auto"` — never touches `window.scrollTo` |

Scroll actions (both the `"top"` scrollTo and `"restore"`'s saved-position restore) are deferred to `requestAnimationFrame` so the new route has mounted before the scroll lands.

## Semantics

- **Single signal per router.** `router.current` is the only reactive input — everything downstream (`RouterView`, `Link`'s active class, components reading `params`) derives from it.
- **Guards are synchronous.** There's no async-guard ceremony — if you need async (e.g. auth check), gate the redirect on a cached signal instead of awaiting inside the guard.
- **Wildcards are terminal.** A `{ path: "*" }` route matches everything and should come last in the table.
- **Per-route params merge up.** Nested routes see their own params plus all ancestors' params in `RouteState.params`, in matched order.

## See also

- [`/api/routerview/`](https://whisq.dev/api/routerview/) — rendering the matched component (and nested routes).
- [`/api/link/`](https://whisq.dev/api/link/) — push-state navigation anchors.
- [`/api/route-state/`](https://whisq.dev/api/route-state/) — reading the current route reactively.
- [`/guides/routing/`](https://whisq.dev/guides/routing/) — routing patterns and end-to-end examples.
- [`/examples/router-basics/`](https://whisq.dev/examples/router-basics/) — small multi-page example with params, nested routes, and a guard.

---
# cx()
URL: https://whisq.dev/api/cx/
---

Compose class names with conditional logic (static).

:::tip[Since alpha.8]
For class composition directly on an element prop, prefer the **array form on `class:`** — it accepts strings, falsy shorthands, and reactive getters in one place, with no separate `cx` / `rcx` decision. See [`/api/elements/#class-array-form-since-alpha8`](https://whisq.dev/api/elements/#class-array-form-since-alpha8). Reach for `cx()` when you need to compose class strings outside an element prop (utility helpers, returning a string from a function, etc.).
:::

## Signature

```ts
function cx(...args: ClassValue[]): string
```

## Parameters

Accepts strings, falsy values, or objects with boolean values.

## Examples

```ts

div({ class: cx("btn", isPrimary && "btn-primary", isLarge && "btn-lg") })
div({ class: cx("card", { active: true, disabled: false }) })
// Result: "card active"
```

---
# DevTools
URL: https://whisq.dev/api/devtools/
---

`@whisq/devtools` is a runtime hook that attaches a read-only inspection surface to `globalThis.__WHISQ_DEVTOOLS__`. A browser extension or a console script can read the hook to inspect signals, components, and a logged event stream. Apps opt in by calling register / log functions themselves — **there is no auto-instrumentation**.

Ships as a separate package, versioned lockstep with `@whisq/core`:

```bash
npm install --save-dev @whisq/devtools
```

## Signature

```ts

function connectDevTools(): void;
function disconnectDevTools(): void;
```

## Quick start

Wire the hook once, guarded by the dev flag, before `mount()`:

```ts
// src/main.ts

if (import.meta.env.DEV) connectDevTools();

mount(App({}), document.getElementById("app")!);
```

Then register the signals and components you want to inspect. No magic — you pick what's interesting:

```ts
// stores/todos.ts

if (import.meta.env.DEV) {
  // Safe: globalThis.__WHISQ_DEVTOOLS__ exists after connectDevTools().
  globalThis.__WHISQ_DEVTOOLS__?.registerSignal("todos", todos);
}
```

## Runtime hook (`window.__WHISQ_DEVTOOLS__`)

After `connectDevTools()`, the hook lives on the global object under `__WHISQ_DEVTOOLS__` and implements the `DevToolsHook` interface:

```ts
interface DevToolsHook {
  version: string;

  // Signals
  registerSignal(name: string, signal: ReadonlySignal<unknown>): void;
  unregisterSignal(name: string): void;
  getSignals(): SignalInfo[];

  // Components
  registerComponent(name: string): void;
  unregisterComponent(name: string): void;
  getComponents(): string[];

  // Event log
  logEvent(type: string, data: Record<string, unknown>): void;
  getEvents(): DevToolsEvent[];
  clearEvents(): void;
}

interface SignalInfo {
  name: string;
  value: unknown;
}

interface DevToolsEvent {
  type: string;
  data: Record<string, unknown>;
  timestamp: number;
}
```

| Method | Use |
|---|---|
| `registerSignal(name, signal)` | Add a named signal to the hook's ledger. |
| `unregisterSignal(name)` | Remove a named signal — useful in HMR boundaries or component unmount. |
| `getSignals()` | Snapshot of all registered signals. Reads via `signal.peek()`, so inspection does **not** subscribe the reader. |
| `registerComponent(name)` | Mark a component as active. |
| `unregisterComponent(name)` | Remove an active component. |
| `getComponents()` | Snapshot of active component names. |
| `logEvent(type, data)` | Append a timestamped event to the log (type + free-form data). |
| `getEvents()` | Snapshot of the event log (copy; mutating the return doesn't touch the hook). |
| `clearEvents()` | Empty the event log. |

Note on `version`: the hook reports its own internal protocol version (currently `"0.0.1-alpha.0"`), independent of the `@whisq/devtools` package version. That string is what browser extensions check for compatibility.

## `disconnectDevTools()`

Removes `globalThis.__WHISQ_DEVTOOLS__`. Useful when an HMR or test run re-initialises the app:

```ts

// Register teardown BEFORE connecting — the dispose hook runs on every HMR
// cycle, and we want it ready for the first hot update after this module load.
if (import.meta.hot) {
  import.meta.hot.dispose(() => disconnectDevTools());
}
if (import.meta.env.DEV) connectDevTools();
```

Without teardown, a hot reload can leave a stale hook pointing at disposed signals — `getSignals()` would then `.peek()` values that no longer fire subscribers.

## When to call `connectDevTools()`

- **Dev builds only.** Guard with `import.meta.env.DEV` (or your bundler's equivalent) so the hook doesn't ship to production.
- **Before `mount()`.** Component setup functions can then call `registerComponent(...)` / `registerSignal(...)` during first render.
- **Once, at module scope.** Calling it again overwrites the hook — idempotent in practice but wasteful.

## Browser extension

There is no official Whisq browser extension yet. The hook is designed to be forward-compatible with one — the `version` field and the shape of `DevToolsHook` are the contract a future extension will consume. Until then, the hook is inspectable from the browser console:

```js
// In the browser console, on a running dev build:
__WHISQ_DEVTOOLS__?.getSignals();
__WHISQ_DEVTOOLS__?.getComponents();
__WHISQ_DEVTOOLS__?.getEvents();
```

## Semantics

- **Passive surface.** `connectDevTools()` only exposes the hook object. It does not monkey-patch `signal()`, wrap `component()`, or intercept effects. What the hook knows is exactly what you've told it.
- **No subscriptions.** `getSignals()` reads via `.peek()`, so nothing in the hook tracks dependencies — inspecting from the console won't re-run effects.
- **No-op on double-register.** `registerSignal(name, …)` with an existing name replaces the previous entry via `Map.set` — no throw, no warn. Same for `registerComponent` (`Set.add` ignores duplicates).
- **`getSignals()` / `getEvents()` return copies.** `getEvents()` spreads into a new array, so mutating the return doesn't touch the hook's internal log. Registered signals are held by reference, but the `SignalInfo` snapshot is fresh on every call.

## See also

- [`/api/imports/#whisqdevtools`](https://whisq.dev/api/imports/#whisqdevtools) — sub-path imports for DevTools.
- [Performance guide → Profiling with DevTools](https://whisq.dev/advanced/performance/#profiling-with-devtools) — where the hook fits in a performance-investigation workflow.
- [`signal()`](https://whisq.dev/api/signal/) — `peek()` (untracked read) is what `getSignals()` uses to snapshot values without subscribing.

---
# each()
URL: https://whisq.dev/api/each/
---

Render a reactive list with optional keyed DOM reconciliation. Two overloads — non-keyed (fresh nodes on every change) and keyed (LIS-based diffing with **hybrid accessors** for per-item reactivity — see the `ItemAccessor<T>` interface below).

## Signature

```ts
// Non-keyed — item is a plain T, nodes are recreated on every source change.
function each<T>(
  items: () => T[],
  render: (item: T, index: number) => WhisqNode,
): () => Child[];

// Keyed — item / index are HYBRID accessors (callable + signal-shaped).
// DOM nodes are reused across source changes.
function each<T>(
  items: () => T[],
  render: (item: ItemAccessor<T>, index: ItemAccessor<number>) => WhisqNode,
  options: { key: (item: T) => unknown },
): WhisqNode;

// since alpha.8 — `ItemAccessor<T>` is exported from "@whisq/core"
interface ItemAccessor<T> {
  (): T;                  // call form — what existed pre-alpha.8
  readonly value: T;      // .value form — canonical for new code
  peek(): T;              // peek form — read without subscribing
}
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `items` | `() => T[]` | Reactive array of items |
| `render` (non-keyed) | `(item: T, index: number) => WhisqNode` | Receives plain values; called on every source change |
| `render` (keyed) | `(item: ItemAccessor<T>, index: ItemAccessor<number>) => WhisqNode` | Receives hybrid accessors — read via `item.value` (canonical), `item()`, or `item.peek()` |
| `options.key` | `(item: T) => unknown` | Key function. Presence switches to the keyed overload. **Receives the value, not an accessor.** |

## Example — keyed

```ts

const todos = signal([
  { id: 1, text: "Learn Whisq" },
  { id: 2, text: "Build an app" },
]);

ul(
  each(
    () => todos.value,
    (todo) => li(() => todo.value.text),    // .value — canonical since alpha.8
    { key: (t /* value, not accessor */) => t.id },
  ),
)
```

The `todo()` call form (pre-alpha.8) still works and is structurally compatible with helpers typed as `() => T` — `bindField(todos, todo, "done", { as: "checkbox" })` and similar accept either form unchanged. New code should prefer the `.value` shape for consistency with the rest of the reactive-access rule.

:::tip[🐱 Whisker Tip]
Use the `key` option when items have stable identities. LIS-based diffing only moves, inserts, or removes changed DOM nodes, and the per-entry signals keep reactive getters fresh when a same-keyed item is replaced.
:::

## Reactive fields inside keyed `each()`

The keyed callback's `item` is `() => T` — not a plain `T`. When to call `todo()` and when to wrap it in a getter isn't about whether the field "changes" — it's about whether the **position** you're using it in needs to re-evaluate.

Four archetypes, from a `Todo = { id: string, text: string, done: Signal<boolean> }`:

| Position | Shape (alpha.8 canonical) | Why |
|---|---|---|
| Static text child | `todo.value.text` (or legacy `todo().text`) | Text renders once; `text` is a plain string. Reading at render time gives the current item. |
| `bind()` on a per-item signal | `bind(todo.value.done, { as: "checkbox" })` | `bind()` receives a **signal reference**, and the `Signal` drives its own reactivity. Reading `.value` once captures the stable signal object. |
| Re-evaluated position reading a signal's value | `() => todo.value.done.value && s.doneText` (inside `rcx` or a prop getter) | `rcx()` / prop getters *re-run* when dependencies change. The getter closes over `todo`, so on re-run it sees the current entry and reads `.done.value` from the stable signal. |
| Event handler | `onchange: () => toggle(todo.value.id)` | Fires on user interaction — re-reads the current item at click time, even if the array was reshuffled since render. |

```ts
each(
  () => todos.value,
  (todo) =>
    li(
      input({
        type: "checkbox",
        checked: () => todo.value.done.value,     // reactive: getter re-runs, reads .value
        onchange: () => toggle(todo.value.id),    // fresh read at click time
      }),
      todo.value.text,                            // static snapshot — plain string field
    ),
  { key: (t /* value, not accessor */) => t.id },
)
```

**When `bind(todo.value.done, ...)` is safe:** the signal object at `todo.value.done` has stable identity — the store creates each todo's `done` signal once and never replaces it. If your store swaps signal objects under a same key (e.g. `todos.value = todos.value.map(t => t.id === x ? { ...t, done: newSignal } : t)`), the snapshot goes stale; use the re-evaluated shape (pass `rcx`/prop-getters or re-build the binding).

The legacy `todo()` form continues to work everywhere `.value` works (the accessor is structurally `() => T`), so existing call sites do not need to migrate. Mix-and-match within a single render is fine but discouraged for readability — pick one form per file.

## Splitting into a component

For lists past about a dozen lines of per-item render, factor the render into its own component. The accessor passes through the boundary as a prop typed as `ItemAccessor<T>` — read inside the component the same way:

```ts
// src/components/TodoItem.ts

type Todo = { id: number; text: string; done: Signal<boolean> };

type TodoItemProps = {
  todo: ItemAccessor<Todo>;               // hybrid accessor — read via .value (or call form)
  onRemove: (id: number) => void;
};

```

If your store **does** swap item objects under a same key (e.g. `todos.value = todos.value.map(t => t.id === id ? { ...t, text: newText } : t)`), wrap the text read in a getter — `() => props.todo.value.text` — so the reconciler's per-entry signal drives a re-read. The todo-app example's store keeps object identity per key, which is why the snapshot form is safe there.

Call site:

```ts
ul({ class: s.list },
  each(
    () => todos.value,
    (todo) => TodoItem({ todo, onRemove: removeTodo }),
    { key: (t) => t.id },
  ),
)
```

### Why it works

- **The accessor is a hybrid object.** Passing `todo` into `TodoItem({ todo })` copies the reference. Inside the component, `props.todo.value` (or `props.todo()`) calls into the same accessor that the reconciler owns — the reconciler writes fresh values into the per-entry signal, so reads always return the current item.
- **Destructuring at the prop boundary is safe.** `(props)` or `({ todo, onRemove })` both work: you're copying the accessor reference, not reading through it. The footgun is destructuring the *result*: `const { done } = props.todo.value` captures at setup time and won't update when the reconciler swaps entries.
- **The same four-archetype rule applies** — snapshot reads (`props.todo.value.text`), `bind()` on a stable signal (`bind(props.todo.value.done, ...)`), re-evaluated getters (`() => props.todo.value.done.value && ...`), event handlers (`() => props.onRemove(props.todo.value.id)`). Same shapes, just inside a component.

The pre-alpha.8 call form (`props.todo: () => Todo`, read as `props.todo()`) still works unchanged — `ItemAccessor<T>` is structurally assignable to `() => T`. Migrate at your own pace.

See the [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) for the full four-shape taxonomy. For the decision matrix on which per-item-editing pattern to reach for (plain immutable / nested signal / extracted child), see the [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/). For the canonical wrong/why/right pairings on `ItemAccessor<T>` reads, see [Keyed `each()` mistakes in `/common-mistakes/`](https://whisq.dev/common-mistakes/#keyed-each-mistakes) and [Hoisting `.value.field` out of a reactive getter](https://whisq.dev/common-mistakes/#hoisting-valuefield-out-of-a-reactive-getter) for the general stale-capture trap.

## Related primitives

- [`when()`](https://whisq.dev/api/when/), [`match()`](https://whisq.dev/api/match/) — pair with `each()` for empty-state messaging around a list.
- [`bindField()`](https://whisq.dev/api/bindfield/) — two-way bind a field on the items `each()` iterates.
- [`partition()`](https://whisq.dev/api/partition/) — split the source array into two derived signals before rendering (e.g. active vs done).
- [`signalMap()`](https://whisq.dev/api/signalmap/), [`signalSet()`](https://whisq.dev/api/signalset/) — iterate reactive collections whose membership changes.

---
# effect()
URL: https://whisq.dev/api/effect/
---

Run a side effect that re-executes when its signal dependencies change. See [How Reactivity Works](https://whisq.dev/core-concepts/reactivity-model/) for the underlying mental model.

## Signature

```ts
function effect(fn: () => void | (() => void)): () => void
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fn` | `() => void \| (() => void)` | Effect function. Can return a cleanup function. |

## Returns

`() => void` — dispose function that stops the effect.

## Examples

```ts

const count = signal(0);

const dispose = effect(() => {
  console.log(`Count: ${count.value}`);
});
// Logs: "Count: 0"

count.value = 1; // Logs: "Count: 1"
dispose();       // Stop watching
count.value = 2; // No log
```

### With cleanup

```ts
effect(() => {
  const timer = setInterval(() => tick(), 1000);
  return () => clearInterval(timer);
});
```

## Related primitives

- [`signal()`](https://whisq.dev/api/signal/) — the mutable primitive; `effect()` re-runs when a tracked signal changes.
- [`computed()`](https://whisq.dev/api/computed/) — derived values; prefer over `effect()` when you need a readable result.
- [`onCleanup()`](https://whisq.dev/api/oncleanup/) — component-scoped cleanup for effects started inside a component.
- [`batch()`](https://whisq.dev/api/batch/) — batch multiple writes into one effect re-run.

---
# Element Functions
URL: https://whisq.dev/api/elements/
---

Every HTML element is a typed function.

## Signature

```ts
function div(props?: CommonProps | Child, ...children: Child[]): WhisqNode
function span(props?: CommonProps | Child, ...children: Child[]): WhisqNode
function button(props?: ButtonProps | Child, ...children: Child[]): WhisqNode
function input(props?: InputProps): WhisqNode
// ... and 30+ more
```

## Two Call Signatures

```ts
// With props + children
div({ class: "card", id: "main" }, h1("Title"), p("Content"))

// Without props — just children
div(h1("Title"), p("Content"))

// Single text child
h1("Hello Whisq")
```

## Available Elements

**Layout:** `div`, `span`, `main`, `section`, `article`, `aside`, `header`, `footer`, `nav`
**Text:** `h1`–`h6`, `p`, `strong`, `em`, `small`, `pre`, `code`
**Interactive:** `button`, `a`
**Forms:** `form`, `input`, `textarea`, `select`, `option`, `label`
**Lists:** `ul`, `ol`, `li`
**Table:** `table`, `thead`, `tbody`, `tr`, `th`, `td`
**Media:** `img`, `video`, `audio`
**Misc:** `br`, `hr`, `iframe`

## Reactive Props

Pass a function for any prop to make it reactive:

```ts
div({ class: () => active.value ? "on" : "off" })
div({ style: () => `color: ${color.value}` })
div({ hidden: () => !visible.value })
```

### `class:` array form (since alpha.8)

`class:` also accepts an **array** of sources. Strings are class names; falsy values (`false | null | undefined | 0 | ""`) are filtered out; functions are reactive (re-run when tracked signals change). If any element is a function, the whole array is applied reactively; otherwise it's applied once at mount.

```ts
div({
  class: [
    "btn",                                    // static
    () => `btn-${variant.value}`,             // reactive
    loading.value && "btn-loading",           // static conditional shorthand
    () => isDisabled.value && "disabled",     // reactive conditional
  ],
});
```

Eliminates the [`cx`](https://whisq.dev/api/cx/) vs [`rcx`](https://whisq.dev/api/rcx/) decision for the common case — reach for those only when composing class strings outside an element prop.

#### Rules

The runtime walks the array once and joins the kept sources with a single space. Exact behaviour:

- **Skipped (filtered out):** `false`, `null`, `undefined`, `0`, `""`. This is what makes the `cond && "active"` shorthand work — a false `cond` short-circuits to the falsy boolean and is dropped.
- **Strings are kept as-is.** They are not parsed, trimmed, or split on spaces — `"btn primary"` is added verbatim, so you can still pack multiple class names into a single string if you want.
- **Truthy non-strings (not functions) are silently dropped.** Numbers other than `0`, plain objects, arrays, and `true` are not coerced via `String()` — they fall through the loop and are not added. The TypeScript type (`ClassArraySource`) refuses them at the boundary; this rule is the runtime contract for cases that slip through (e.g. `any`, untyped data).
- **Nested arrays are NOT flattened.** A nested array is a non-string non-function value, so it's dropped rather than recursed into:

  ```ts
  // ❌ "btn" only — the inner array is dropped
  div({ class: ["btn", ["primary", "lg"]] });

  // ✅ Spread the inner array, or flatten it yourself
  div({ class: ["btn", ...["primary", "lg"]] });
  ```

- **Functions are called in a reactive getter**, and their **return value follows the same rules**: a truthy string is kept, a falsy value (`false | null | undefined | 0 | ""`) is skipped. A function that returns an array is not flattened — the array ends up joined via its default `.toString()` (comma-joined), which is almost certainly a bug. Return a pre-joined string instead:

  ```ts
  // ❌ Produces `class="btn a,b"` — Array.toString runs
  div({ class: ["btn", () => active.value ? ["a", "b"] : ""] });

  // ✅ Return a string with spaces — or use separate entries
  div({ class: ["btn", () => active.value && "a b"] });
  div({ class: ["btn", () => active.value && "a", () => active.value && "b"] });
  ```

### ARIA attributes (since alpha.9)

For guide-level treatment (focus management, semantic HTML choices, escape hatch), see the [Accessibility guide](https://whisq.dev/guides/accessibility/). The reference below is the prop surface and serialisation rules.

Every element accepts typed `aria-*` props. Mirrors the `data-*` pattern but with a wider value type, because ARIA uses both enum-strings (`aria-live: "polite"`) and predicate-booleans (`aria-expanded`, `aria-hidden`, `aria-pressed`). Types are `ReactiveProp<string | boolean | undefined>` — static values, reactive getters, or `undefined` to remove the attribute.

```ts
// Static
button({ "aria-label": "Remove" }, "×");

// Reactive
button({ "aria-expanded": () => menuOpen.value }, "Menu");
div({ "aria-live": "polite", "aria-atomic": true }, () => status.value);

// Conditional removal
div({ "aria-hidden": () => visible.value ? undefined : true });
```

Serialisation rules:

| Value | Serialised as |
|---|---|
| `"polite"` / string | `"polite"` |
| `true` | `"true"` (per ARIA spec — fixed in alpha.9) |
| `false` | `"false"` |
| `undefined` / `null` | attribute removed |

**Note**: pre-alpha.9, `true` serialised to the empty string `aria-expanded=""`, which is **invalid** per the ARIA spec (not equivalent to `aria-expanded="true"`). Alpha.9 routes `aria-*` through a dedicated branch in the prop applier to produce the correct string forms.

## Events

```ts
button({ onclick: () => count.value++ }, "Click")
input({ oninput: (e) => name.value = e.target.value })
```

---
# errorBoundary()
URL: https://whisq.dev/api/errorBoundary/
---

Wrap a subtree with a fallback that renders when something inside throws. Prefer this over a hand-rolled `try`/`catch` in a component setup.

## Signature

```ts
function errorBoundary(
  fallback: (error: Error, retry: () => void) => WhisqNode,
  child: () => WhisqNode,
): WhisqNode
```

## Parameters

| Param      | Type                                                | Description                                                              |
| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
| `fallback` | `(error: Error, retry: () => void) => WhisqNode`    | Rendered when the wrapped subtree throws. `retry` re-runs `child`        |
| `child`    | `() => WhisqNode`                                   | The protected subtree, wrapped in a thunk so `retry` can re-invoke it    |

## Examples

```ts

errorBoundary(
  (error, retry) =>
    div({ class: "error-boundary" },
      p(`Something went wrong: ${error.message}`),
      button({ onclick: retry }, "Try again"),
    ),
  () => RiskyComponent({}),
);
```

See [Advanced → Error Boundaries](https://whisq.dev/advanced/error-boundaries/) for granular wrapping, error reporting, and how the primitive composes with [`resource()`](https://whisq.dev/api/resource/).

---
# Event types
URL: https://whisq.dev/api/event-types/
---

The framework's exported types for typed event handlers and accessor / error shapes. Type-only imports (no runtime cost) — use them when you want a named handler whose `currentTarget` narrows to the element it's attached to, or when you're typing a prop that receives a keyed-`each()` accessor.

```ts
```

## `EventHandler<E, T>`

The handler signature for a typed DOM event with a narrowed `currentTarget`.

```ts
type EventHandler<E extends Event = Event, T extends Element = Element> = (
  event: E & { currentTarget: T },
) => void;
```

Use when you want to extract a named handler from a component setup — types stay correct, `currentTarget` narrows to the right element type, and the return type stays `void` (handlers never need to return).

```ts

const onSubmit: EventHandler<SubmitEvent, HTMLFormElement> = (e) => {
  e.preventDefault();
  e.currentTarget.reset();
};

form({ onsubmit: onSubmit }, /* ... */);
```

## `WhisqEvent<K, T>`

Look up the event type from a DOM event name (as used in `HTMLElementEventMap`) and narrow the `currentTarget` to a target element.

```ts
type WhisqEvent<
  K extends keyof HTMLElementEventMap,
  T extends Element = Element,
> = HTMLElementEventMap[K] & { currentTarget: T };
```

Use when you want to name the exact event, instead of writing `KeyboardEvent & { currentTarget: HTMLInputElement }` by hand:

```ts

function onSearchKey(e: WhisqEvent<"keydown", HTMLInputElement>) {
  if (e.key === "Enter") submit(e.currentTarget.value);
}

input({ onkeydown: onSearchKey });
```

## When to use which

| If you have... | Reach for... | Example |
|---|---|---|
| The event class (`SubmitEvent`, `MouseEvent`) | `EventHandler<E, T>` | `EventHandler<SubmitEvent, HTMLFormElement>` |
| The event name (`"keydown"`, `"input"`) | `WhisqEvent<K, T>` | `WhisqEvent<"keydown", HTMLInputElement>` |

Both are interchangeable in practice; pick by which name you already have in your head.

## `ItemAccessor<T>` (since alpha.8)

The hybrid accessor passed to a keyed `each()`'s render callback.

```ts
interface ItemAccessor<T> {
  (): T;                  // call form — pre-alpha.8 backwards-compat
  readonly value: T;      // .value form — canonical for new code
  peek(): T;              // peek form — read without subscribing
}
```

Use when typing a prop that receives a keyed-`each()` accessor — typically when extracting per-row markup into a child component:

```ts

type TodoItemProps = { todo: ItemAccessor<Todo>; onRemove: (id: string) => void };

const TodoItem = component((props: TodoItemProps) =>
  li({ onclick: () => props.onRemove(props.todo.value.id) }, () => props.todo.value.text),
);
```

`ItemAccessor<T>` is structurally assignable to `() => T`, so it works unchanged with helpers typed as `() => T` (e.g. `bindField`). See [`/api/each/`](https://whisq.dev/api/each/) and [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/).

## Dev-mode error classes

Both error classes are runtime exports (not pure types) — you can `instanceof` them, but production builds strip the throw sites in most cases.

### `WhisqKeyByError` (since alpha.8)

Thrown by `bindField()` in dev mode (or with `strict: true` in any env) when a write can't find an item in the source array whose `keyBy(...)` matches the accessor's key. Carries `sourceKeys`, `targetKey`, and `field` for debugging.

```ts
interface WhisqKeyByErrorFields {
  sourceKeys: unknown[];   // keys present in the source at write time
  targetKey: unknown;      // the key the write was looking for
  field: string;           // the field bindField was writing
}

class WhisqKeyByError extends Error implements WhisqKeyByErrorFields { /* ... */ }
```

Full reference and the `strict` matrix: [`/api/bindfield/#dev-mode-behaviour-and-the-strict-option`](https://whisq.dev/api/bindfield/#dev-mode-behaviour-and-the-strict-option).

### `WhisqStructureError`

Thrown by element / `each()` / `match()` / `component()` in dev mode when an API receives a value it can't render. Carries `expected`, `received`, `element`, and an optional `hint`.

```ts
interface WhisqStructureErrorFields {
  expected: string;
  received: string;
  element: string;
  hint?: string;
  callsite?: string;
}

class WhisqStructureError extends Error implements WhisqStructureErrorFields { /* ... */ }
```

Full coverage of every dev-mode error message and its fix: [`/common-mistakes/#about-whisqstructureerror`](https://whisq.dev/common-mistakes/#about-whisqstructureerror).

## See also

- [`bindField()`](https://whisq.dev/api/bindfield/) — uses `WhisqKeyByError` and `EventHandler` shapes.
- [`each()`](https://whisq.dev/api/each/) — origin of `ItemAccessor<T>`.
- [Forms guide](https://whisq.dev/guides/forms/) — typed handler patterns in action.
- [LLM reference — Typed Event Handlers](https://whisq.dev/ai/llm-reference/) — canonical snippet.

---
# h()
URL: https://whisq.dev/api/h/
---

Create an element by tag name. Use `h()` for web components, SVG, custom tags, or any element not covered by the named element functions (`div()`, `button()`, etc.).

## Signature

```ts
function h(
  tag: string,
  props?: Props,
  ...children: Child[]
): WhisqNode
```

## Parameters

| Param      | Type        | Description                                       |
| ---------- | ----------- | ------------------------------------------------- |
| `tag`      | `string`    | Tag name (`"div"`, `"my-component"`, `"circle"`)  |
| `props`    | `Props`     | Optional props object — same shape as named elements |
| `children` | `Child[]`   | Child nodes, strings, or reactive getters         |

## Examples

```ts

// Web component
h("color-picker", {
  value: () => selectedColor.value,
  onchange: (e) => (selectedColor.value = e.target.value),
});

// SVG
h("svg", { viewBox: "0 0 24 24", width: "24", height: "24" },
  h("circle", { cx: "12", cy: "12", r: "10", fill: "currentColor" }),
);

// Dynamic tag name
const tagName = "section";
h(tagName, { class: "card" }, "Hello");
```

See [Custom Elements](https://whisq.dev/advanced/custom-elements/) for web-component, SVG, and wrapper patterns.

---
# Imports
URL: https://whisq.dev/api/imports/
---

Every public `@whisq/*` package and entry point, verified against the published `package.json` `exports` field. Use this page to confirm where a given symbol lives before writing an import line.

If a symbol isn't listed here, it either hasn't been published yet or it's internal (not part of the public API).

## `@whisq/core`

The primary package. Most application imports come from here.

### `.` (main entry)

```ts
```

**Reactive primitives:** `signal`, `computed`, `effect`, `batch` · types: `Signal`, `ReadonlySignal`

**Element helpers** (every HTML element is exported): `div`, `span`, `a`, `img`, `button`, `input`, `textarea`, `select`, `option`, `label`, `form`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `strong`, `em`, `small`, `pre`, `code`, `ul`, `ol`, `li`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `header`, `footer`, `nav`, `main`, `section`, `article`, `aside`, `audio`, `video`, `iframe`, `br`, `hr` · type: `WhisqNode`

**Hyperscript helper:** `h` (for tags not pre-exported), `raw` (inject HTML strings)

**Rendering:** `mount`, `each`, `match`, `when`, `errorBoundary`, `portal`, `transition`

**Components & lifecycle:** `component`, `onMount`, `onCleanup`, `resource`, `createContext`, `provide`, `inject`, `useHead` · types: `ComponentDef`, `Resource`, `ResourceOptions`, `ResourceSourceOptions`, `InjectionKey`

**Refs:** `ref` · types: `ElementRef<T>`, `Ref<T>`

**Event types:** `EventHandler<E, T>`, `WhisqEvent<K, T>` (types only)

**Bind:** [`bind`](https://whisq.dev/api/bind/) (single-signal two-way binding with `as: "text" | "number" | "checkbox" | "radio"` options), [`bindField`](https://whisq.dev/api/bindfield/) (field-inside-signal-array binding for list items, with `keyBy` defaulting to `t => t.id`) · types: `BindOptions`, `TextBind`, `NumberBind`, `CheckboxBind`, `RadioBind`, `BindFieldOptions`

**Styling:** `sheet`, `theme`, `styles`, `sx`, `cx`, `rcx` · types: `StyleObject`, `ThemeOptions`

**Dev diagnostics:** `WhisqStructureError` (runtime class for dev-mode structure violations), `WhisqKeyByError` (runtime class thrown by `bindField` on no-match writes in dev mode — see [`/api/bindfield/`](https://whisq.dev/api/bindfield/#dev-mode-behaviour-and-the-strict-option)) · types: `WhisqStructureErrorFields`, `WhisqKeyByErrorFields`

### `./collections`

Reactive collections with per-key / per-value subscriptions, plus collection helpers. Lives on a sub-path so the main entry stays under 5 KB.

```ts
```

**Exports:** `signalMap<K, V>()`, `signalSet<T>()`, [`partition<T>()`](https://whisq.dev/api/partition/) (since alpha.8 — split a signal-held array into matching / not-matching derived signals)

### `./persistence`

localStorage-backed signals. The [State Management guide](https://whisq.dev/guides/state-management/#persistence-localstorage) covers the full option surface (`storage`, `serialize`/`deserialize`, `schema`) and the SSR/quota/schema-validation behaviors the helper handles internally.

```ts

const todos = persistedSignal("whisq.todos", []);
```

**Exports:** `persistedSignal<T>()` — creates a `Signal<T>` that loads from localStorage on module init and writes on every change. See [`PersistedSignalOptions`](https://github.com/whisqjs/whisq/blob/main/packages/core/src/persistence.ts) in the framework source for configuration options (serializer, skip-initial-write, etc.).

### `./forms`

Deep-path form bindings. Sub-path so apps that only need `bind()` and `bindField()` (the 80% case) pay no bundle cost — the default `bind` / `bindField` exports stay on the main entry.

```ts

form(
  input({ ...bindPath(user, ["profile", "name"]) }),
  input({ type: "checkbox", ...bindPath(user, ["prefs", "dark"], { as: "checkbox" }) }),
);
```

**Exports:** [`bindPath()`](https://whisq.dev/api/bindpath/) — two-way binding for a field at an arbitrary object path inside a signal-held record. Mirrors `bind()` / `bindField()` discriminator shapes (text / number / checkbox / radio). See [`/api/bindpath/`](https://whisq.dev/api/bindpath/) for the full reference.

### `./ids`

Random-id generation. Sub-path so apps that don't need client-side id generation (e.g. SSR apps where the server hands out ids) pay no bundle cost. Since alpha.8.

```ts

const todo = { id: randomId(), text: "Learn Whisq", done: false };
```

**Exports:** [`randomId()`](https://whisq.dev/api/randomid/) — returns a UUID-v4-shaped string. Prefers native `crypto.randomUUID()` when available; falls back to a `Math.random` synthesis with the same v4 shape for older targets. Suitable for UI row keys and `each({ key })` ids — **not** a security primitive.

## `@whisq/router`

Signal-based router for Whisq applications — a single `router.current` signal, push-state navigation, nested routes, guards, and scroll restoration.

```ts
```

API reference:

| Export | Page |
|---|---|
| `createRouter()` | [`/api/createrouter/`](https://whisq.dev/api/createrouter/) |
| `RouterView()` | [`/api/routerview/`](https://whisq.dev/api/routerview/) |
| `Link()` | [`/api/link/`](https://whisq.dev/api/link/) |
| Reading route state | [`/api/route-state/`](https://whisq.dev/api/route-state/) |

End-to-end walkthrough: [Router basics example](https://whisq.dev/examples/router-basics/). Patterns: [Routing guide](https://whisq.dev/guides/routing/).

## `@whisq/ssr`

Server-side rendering for Whisq applications.

```ts
```

Used from a server framework (Vite SSR, Node HTTP, etc.) to produce initial HTML. Pairs with `@whisq/vite-plugin` for the build-side plumbing.

## `@whisq/vite-plugin`

Vite plugin for Whisq — file-based routing, HMR, optimized builds.

```ts
// vite.config.ts

```

## `@whisq/testing`

Testing utilities for Whisq components — `render`, `screen` queries, `fireEvent`.

```ts
```

See [`/guides/testing/`](https://whisq.dev/guides/testing/) for the patterns the docs use.

## `@whisq/devtools`

DevTools runtime hook — signal inspection, component tree, effect tracking.

```ts
if (import.meta.env.DEV) connectDevTools();
```

Installs `globalThis.__WHISQ_DEVTOOLS__` — a passive surface a browser extension or console script can read. Apps opt in by calling `registerSignal` / `registerComponent` / `logEvent` themselves; there's no auto-instrumentation. Full API: [`/api/devtools/`](https://whisq.dev/api/devtools/).

## `@whisq/sandbox`

Sandboxed code execution — isolated environment with configurable limits. Used internally by the whisq.dev playground.

```ts
```

Primarily for tooling that needs to run untrusted Whisq code (playgrounds, snippet runners, MDX live examples). End-user app code doesn't typically import this.

## Versioning

All packages release in lockstep under the same `0.x.y-alpha.N` tag. The `whisqCoreVersion` field in this repo's `package.json` pins the version these docs describe — currently the version at the bottom of every docs page.

The drift-check script (`scripts/check-llm-reference-sync.mjs`) verifies the LLM reference card stays in sync with `@whisq/core`'s published public-api manifest. There's no equivalent check for the other packages yet — if a secondary-package example on this site doesn't compile against a fresh install, the package probably moved faster than the docs did.

**For AI/scaffolder workflows:** resolve the current version from the npm registry, never from a CDN `@latest` alias — see [LLM Reference → Current version](https://whisq.dev/ai/llm-reference/#current-version).

---
# inject()
URL: https://whisq.dev/api/inject/
---

Read the value of a context provided by an ancestor. Call from inside a `component()` setup. Returns the context's `defaultValue` when no ancestor has called [`provide()`](https://whisq.dev/api/provide/).

## Signature

```ts
function inject<T>(context: Context<T>): T
```

## Parameters

| Param     | Type         | Description                                       |
| --------- | ------------ | ------------------------------------------------- |
| `context` | `Context<T>` | The context object returned by `createContext()`  |

## Returns

`T` — the nearest ancestor's provided value, or the context's default if none.

## Examples

```ts

const ThemeCtx = createContext("light");

const Child = component(() => {
  const theme = inject(ThemeCtx);
  return p(`Theme: ${theme}`);
});
```

See [`provide()`](https://whisq.dev/api/provide/) for the producer side and [Components → Context](https://whisq.dev/core-concepts/components/#context-provideinject) for the full pattern.

---
# match()
URL: https://whisq.dev/api/match/
---

Render one of several UI branches based on which predicate is true. Use `match()` when `when()` would chain three or more times — the canonical example is the `resource()` loading/error/data tri-state.

For the "when, match, or inline ternary?" decision, see [Choosing Patterns → Conditional rendering](https://whisq.dev/core-concepts/choosing-patterns/#conditional-rendering--when-match-or-inline-ternary).

## Signature

```ts
type MatchRender = () => WhisqNode | string | null;
type MatchBranch = readonly [() => boolean, MatchRender];

function match(...branches: MatchBranch[]): () => Child;
function match(...args: [...MatchBranch[], MatchRender]): () => Child;
```

## Parameters

Each branch is a tuple `[predicate, render]`. An optional trailing bare render function (not wrapped in a tuple) acts as a fallback when no predicate matches.

| Param       | Type                                                | Description                                      |
| ----------- | --------------------------------------------------- | ------------------------------------------------ |
| `branches`  | `MatchBranch[]`                                     | `[() => boolean, () => WhisqNode \| string \| null]` tuples |
| `fallback`  | `MatchRender` (trailing, optional)                  | Rendered when no branch predicate is truthy      |

## Returns

`() => Child` — a reactive child that re-evaluates its branches on every read. Pass it as a child to any element.

## Semantics

- **First-true-wins.** Branches are evaluated top-to-bottom; the first with a truthy predicate renders. Later branches are skipped.
- **Fallback is optional.** Without one, `match()` renders `null` when no branch matches.
- **Reactive.** Like any function child, `match()` re-evaluates whenever any signal it touches changes.

## What `match()` isn't

`match()` is a **predicate chain**, not pattern matching or value dispatch. It does not accept an object map of values to branches.

```ts
// ❌ Object form — not supported. Renders nothing and throws at render time.
match({
  loading: () => p("Loading…"),
  error:   () => p("Failed"),
  data:    () => ul(/* ... */),
});

// ✅ Predicate chain — first-true-wins.
match(
  [() => state.value === "loading", () => p("Loading…")],
  [() => state.value === "error",   () => p("Failed")],
  [() => state.value === "data",    () => ul(/* ... */)],
);
```

If you actually need value dispatch (one signal, many discrete cases) and the predicates are noisy to write, use a `switch` inside a getter child:

```ts
const state = signal<"loading" | "error" | "data">("loading");

div(() => {
  switch (state.value) {
    case "loading": return p("Loading…");
    case "error":   return p("Failed");
    case "data":    return ul(/* ... */);
  }
});
```

The `switch`-in-a-getter form re-evaluates whenever `state` changes (the getter is a reactive position). Use it when every branch maps cleanly to one value of one signal; reach for `match()` when branches mix predicates against different signals (the canonical example: `loading()` / `error()` / `data()` accessors on `resource()`).

:::caution[If you hit `WhisqStructureError: match: expected a branch tuple…`]
You passed an object literal (or other non-tuple) where the framework expected `[() => boolean, () => WhisqNode]` tuples. The dev-mode validator catches this at the call site so you don't fall through to a confusing native error. Convert each entry to a tuple — see the `state.value === "loading"` example above. Full debugging entry: [Common Mistakes → match() given an object](https://whisq.dev/common-mistakes/#match-given-an-object-instead-of-tuples). The validator is stripped from production bundles via `process.env.NODE_ENV` guards — see [About `WhisqStructureError`](https://whisq.dev/common-mistakes/#about-whisqstructureerror) for the wider story.
:::

## Examples

```ts

const users = resource(() => fetch("/api/users").then((r) => r.json()));

div(
  match(
    [() => users.loading(),  () => p("Loading…")],
    [() => !!users.error(),  () => div(
      p(() => `Error: ${users.error()!.message}`),
      button({ onclick: () => users.refetch() }, "Retry"),
    )],
    [() => !!users.data(),   () => ul(each(() => users.data()!, (u) => li(u.name)))],
  ),
);
```

Ordering matters — put the most specific predicate first:

```ts

const count = signal(0);

match(
  [() => count.value > 10,  () => p("More than ten")],
  [() => count.value > 0,   () => p("Some")],    // skipped when count > 10
  () => p("None"),                               // fallback
);
```

See [Conditional Rendering](https://whisq.dev/core-concepts/conditional-rendering/#match--three-or-more-branches) for the full narrative arc.

## Using `match()` as a component root

When a component's job is to branch — render loading / error / data, or swap between views — `match()` can be the component root directly since alpha.9. No wrapper element required.

```ts

const StatusView = component(() =>
  match(
    [() => loading.value, () => Spinner({})],
    [() => !!error.value, () => ErrorPanel({ err: error.value })],
    () => DataView({}),
  ),
);
```

This works because alpha.9 widened `component()`'s setup return to accept a `() => unknown` function in addition to a `WhisqNode` — the framework wraps the function in a fragment bounded by start/end markers internally. See [`/api/component/#function-child-root-since-alpha9`](https://whisq.dev/api/component/#function-child-root-since-alpha9) for the mechanism.

### When to wrap in an element anyway

If you need the component root to carry class / style / events, wrap in an element:

```ts
// Wrapping the branch in a semantic element when the root needs class / style / events.
```

Pick the shape by intent: function-child root when the component *is* the branch, element root when the component is "a branch wearing class / aria attributes".

### Pre-alpha.9 behaviour

Before alpha.9, `component(() => match(...))` threw `WhisqStructureError` at mount — the framework required a `WhisqNode` return, and `match()` returns a function. The wrapping-element pattern above was the only option. Migrating to alpha.9+ is zero-diff for that shape (the wrapper still works); dropping the wrapper is opt-in.

---
# mount()
URL: https://whisq.dev/api/mount/
---

Attach a WhisqNode to a DOM element.

## Signature

```ts
function mount(node: WhisqNode, container: Element): () => void
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `node` | `WhisqNode` | The node to mount |
| `container` | `Element` | Target DOM element |

## Returns

`() => void` — dispose function that unmounts and cleans up all effects.

## Examples

```ts

const dispose = mount(
  div("Hello Whisq"),
  document.getElementById("app")!,
);

// Later: unmount
dispose();
```

---
# onCleanup()
URL: https://whisq.dev/api/onCleanup/
---

Register a function that runs when the component unmounts.

## Signature

```ts
function onCleanup(fn: () => void): void
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fn` | `() => void` | Cleanup function |

## Examples

```ts

const Sub = component(() => {
  const sub = eventBus.subscribe(handler);
  onCleanup(() => sub.unsubscribe());
  return div("Listening");
});
```

---
# onMount()
URL: https://whisq.dev/api/onMount/
---

Register a callback that runs after the component is inserted into the DOM.

## Signature

```ts
function onMount(fn: () => void | (() => void)): void
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fn` | `() => void \| (() => void)` | Mount callback. Can return a cleanup function. |

## Examples

```ts

const App = component(() => {
  onMount(() => {
    console.log("mounted!");
    return () => console.log("cleanup!");
  });

  return div("Hello");
});
```

:::tip[🐱 Whisker Tip]
Must be called inside a `component()` setup function. Throws if called outside.
:::

---
# partition()
URL: https://whisq.dev/api/partition/
---

Split a signal-held array into two derived signals — **the first matches the predicate, the second doesn't**. Both sides re-compute when the source changes; source order is preserved on both sides.

Shipped from the **sub-path** `@whisq/core/collections`, not the main entry.

## Signature

```ts

function partition<T>(
  source: () => T[],
  predicate: (item: T) => boolean,
): [ReadonlySignal<T[]>, ReadonlySignal<T[]>];
```

## Parameters

| Param       | Type                  | Description                                                                  |
| ----------- | --------------------- | ---------------------------------------------------------------------------- |
| `source`    | `() => T[]`           | Reactive accessor for the source array. Typically `() => mySignal.value`. |
| `predicate` | `(item: T) => boolean` | Returns `true` to send the item to the first side (`matching`), `false` for the second side (`notMatching`). |

## Returns

A tuple `[matching, notMatching]` of `ReadonlySignal<T[]>`. Each side is an independent `computed()` — subscribing to one does **not** subscribe to the other, so an effect reading only `pending.value` doesn't re-run when only items in `done` change.

## Example — todo "active vs done"

```ts

interface Todo { id: string; text: string; done: boolean }

const todos = signal<Todo[]>([
  { id: "1", text: "Learn Whisq", done: false },
  { id: "2", text: "Ship it", done: true },
]);

const [pending, done] = partition(() => todos.value, (t) => !t.done);

// Read either side independently — subscribers don't cross-pollinate.
p(() => `${pending.value.length} left`);
p(() => `${done.value.length} done`);

button({ onclick: () => todos.value = pending.value }, "Clear completed");
```

## Why not just two `computed`s?

You could write:

```ts
const pending = computed(() => todos.value.filter((t) => !t.done));
const done    = computed(() => todos.value.filter((t) =>  t.done));
```

That works and is fine for short cases. `partition` is a one-line replacement that:

- Keeps the predicate in one place — the `notMatching` side is automatically the inverse, so there's no risk of the two predicates drifting out of sync.
- Returns a tuple destructured at the call site, matching how partitioning reads in most other languages and libraries.

Reactivity behaviour is identical to two `computed()`s — both sides use reference-equality on the produced arrays (matching `computed()` semantics). If you need structural-equality semantics, that's the caller's job — wrap the result in your own equality-checked `computed()`.

## Semantics

- **Source order preserved.** Both sides receive items in the order they appear in `source()`. No re-sorting.
- **Reference equality on output.** Re-runs only fire when the partitioned array would change in content (per `computed()`'s default equality).
- **Sub-path import.** Lives on `@whisq/core/collections` to keep the main entry under 5 KB.

See also: [`computed()`](https://whisq.dev/api/computed/), [`/api/imports/#collections`](https://whisq.dev/api/imports/#collections), [State Management guide](https://whisq.dev/guides/state-management/), [`bindField()` → Writing through filtered / partitioned views](https://whisq.dev/api/bindfield/#writing-through-filtered--partitioned-views) — pass the source signal to `bindField`, not the partitioned side, when editing per-row inside a filtered `each()`.

---
# persistedSignal()
URL: https://whisq.dev/api/persistedSignal/
---

A `Signal<T>` backed by `localStorage` (or `sessionStorage`). Loads from storage on module init, writes on every change. SSR-safe, quota-safe, schema-validated. Use for small, human-readable JSON state — settings, draft form data, todo lists, theme preferences.

Shipped from the **sub-path** `@whisq/core/persistence`, not the main entry. The "no import-time I/O" rule for `fetch()` doesn't apply here — `localStorage` reads are synchronous and local-only, so the read-once-at-module-load shape is the natural fit.

## Signature

```ts

function persistedSignal<T>(
  key: string,
  initial: T,
  options?: PersistedSignalOptions<T>,
): Signal<T>;

interface PersistedSignalOptions<T> {
  storage?: "local" | "session";
  serialize?: (value: T) => string;
  deserialize?: (raw: string) => T;
  schema?: (raw: unknown) => T;
  onSchemaFailure?: (err: unknown, raw: string) => void;  // since alpha.8
}
```

## Parameters

| Param     | Type                          | Description                                                              |
| --------- | ----------------------------- | ------------------------------------------------------------------------ |
| `key`     | `string`                      | Storage key (namespace your app's keys to avoid collisions).             |
| `initial` | `T`                           | Initial value used on first visit, on SSR, or when validation rejects.   |
| `options` | `PersistedSignalOptions<T>?`  | See **Options** below.                                                   |

## Returns

A standard [`Signal<T>`](https://whisq.dev/api/signal/) — same `.value` / `.peek()` / `.update()` / `.subscribe()` surface. The persistence is invisible to consumers; reads and writes look exactly like a plain `signal()`.

## Quick start

```ts
// stores/todos.ts

interface Todo { id: string; text: string; done: boolean }

// Mutate normally — every assignment persists.
};
```

The first read on first visit returns `[]` (the `initial`); subsequent reads return whatever was last written.

## Options

### `storage`

`"local"` (default; persists across tabs and reloads) or `"session"` (per-tab, cleared when the tab closes). Both backends share the same SSR / quota / schema-validation behaviour.

```ts
const draft = persistedSignal<string>("draft", "", { storage: "session" });
```

### `serialize` / `deserialize`

Override the default `JSON.stringify` / `JSON.parse` for non-JSON storage formats — compressed strings, custom encodings, BigInt-aware serialization.

```ts
const big = persistedSignal<bigint>("big", 0n, {
  serialize: (v) => v.toString(),
  deserialize: (raw) => BigInt(raw),
});
```

### `schema`

Validate the deserialized value before adopting it. Return `T` on success; throw to reject and fall back to `initial`. Most useful for version migrations:

```ts
const settings = persistedSignal<Settings>("settings", DEFAULT_SETTINGS, {
  schema: (raw) => {
    // alpha shape had `theme: string`; current shape has `theme: { mode, accent }`.
    if (typeof raw === "object" && raw && typeof (raw as any).theme === "string") {
      return { ...(raw as object), theme: { mode: (raw as any).theme, accent: "blue" } } as Settings;
    }
    if (typeof raw === "object" && raw && typeof (raw as any).theme === "object") {
      return raw as Settings;
    }
    throw new Error("settings: unrecognized stored shape");
  },
});
```

### `onSchemaFailure` (since alpha.8)

Diagnostic hook fired synchronously **before** the helper falls back to `initial` when `deserialize` throws (malformed stored JSON) or `schema` throws (validator rejects). Receives the thrown error and the exact raw string read from storage.

```ts
const todos = persistedSignal<Todo[]>("todos", [], {
  schema: validateTodosShape,
  onSchemaFailure: (err, raw) => {
    Sentry.captureException(err, { extra: { key: "todos", raw } });
  },
});
```

| Behaviour                         | Detail                                                                 |
| --------------------------------- | ---------------------------------------------------------------------- |
| **Not invoked** on first visit    | `raw` would be `null`, not a failure.                                  |
| **Not invoked** on storage errors | Private mode / disabled storage — environment fault, not schema fault. |
| Callback errors caught            | If the callback throws, the exception is logged via `console.warn`.    |

## Behaviors

- **SSR-safe.** On the server (`typeof window === "undefined"`), returns a plain signal initialized to `initial`, with no storage subscription. Hydration on the client picks up where the server left off.
- **Schema-validated.** If the stored JSON is malformed or `schema` throws, the signal falls back to `initial` rather than crashing at mount. Triggers `onSchemaFailure` if set.
- **Quota-safe.** If a write throws (`QuotaExceededError`, private-mode Safari), the helper logs a warning and keeps the in-memory value — the app keeps working.
- **Module-scope intent.** Call `persistedSignal` at module scope in your `stores/` file, **not inside components**. The write effect lives for the module lifetime by design — it has no disposal hook.

## When to reach for it (and when not)

| Use it for | Don't use it for |
|---|---|
| Settings, theme, draft form data | Cache for server-side data (`resource()` is the better fit) |
| Todo lists, small in-memory caches | Anything > ~5 MB (the LocalStorage quota varies by browser) |
| Per-tab UI state (`storage: "session"`) | Cross-tab synchronization (no `storage` event handling) |
| State that survives a page reload | Secrets, auth tokens (LocalStorage is readable by every script on the origin) |

For larger or structured data, reach for a dedicated IndexedDB library and wire its load/save into a regular `signal()` + `effect()` pair. The "module-scope read once, effect-write on change" shape still applies.

For server-derived state with a local cache, compose `resource()` with `persistedSignal()` — see [recipe 3 in the persistence guide](https://whisq.dev/guides/state-management/#persistence-localstorage).

## See also

- [State Management guide → Persistence](https://whisq.dev/guides/state-management/#persistence-localstorage) — the longer-form story including the inline hand-roll alternative for nested-signal stores.
- [`/api/imports/#persistence`](https://whisq.dev/api/imports/#persistence) — sub-path import reference.
- [`signal()`](https://whisq.dev/api/signal/) — the underlying primitive.
- [`resource()`](https://whisq.dev/api/resource/) — for server-derived data; can be paired with `persistedSignal` as a freshness cache.
- [Persisted settings recipe](https://whisq.dev/guides/state-management/#recipe--persisted-settings-single-record--bindpath) — compose `persistedSignal<Settings>` with `bindPath` for single-record UIs (theme, filters, notification prefs).

---
# portal()
URL: https://whisq.dev/api/portal/
---

Render a `WhisqNode` inside a different DOM target than its logical parent. Useful for modals, tooltips, and dropdowns that need to escape the parent's `overflow: hidden` or stacking context.

## Signature

```ts
function portal(target: Element, content: WhisqNode): WhisqNode;
```

## Parameters

| Param     | Type         | Description                                       |
| --------- | ------------ | ------------------------------------------------- |
| `target`  | `Element`    | DOM element to teleport `content` into            |
| `content` | `WhisqNode`  | Any element / component call — the portal payload |

## Returns

A `WhisqNode` that renders a marker comment at the logical location and the real content inside `target`. Disposing the returned node removes the teleported content.

## Examples

```ts

const open = signal(false);

div(
  button({ onclick: () => open.value = true }, "Open modal"),
  when(() => open.value, () =>
    portal(document.body, div({ class: "modal-overlay" },
      div({ class: "modal-card" }, "Hello"),
    )),
  ),
);
```

The modal renders inside `<body>` instead of nested under the logical parent, so it can span the full viewport regardless of ancestor overflow rules.

---
# provide()
URL: https://whisq.dev/api/provide/
---

Make a [`createContext()`](https://whisq.dev/api/createcontext/) value available to all descendant components. Call from inside a `component()` setup.

## Signature

```ts
function provide<T>(context: Context<T>, value: T): void
```

## Parameters

| Param     | Type         | Description                                                 |
| --------- | ------------ | ----------------------------------------------------------- |
| `context` | `Context<T>` | The context object returned by `createContext()`            |
| `value`   | `T`          | Value visible to descendant components via `inject()`       |

## Examples

```ts

const ThemeCtx = createContext("light");

const App = component(() => {
  provide(ThemeCtx, "dark");
  return div(Page({}));
});
```

See [`inject()`](https://whisq.dev/api/inject/) for the consumer side and [Components → Context](https://whisq.dev/core-concepts/components/#context-provideinject) for the full pattern.

---
# randomId()
URL: https://whisq.dev/api/randomId/
---

Generate a UUID-v4-shaped random identifier — a string like `"3f5d2c1b-9a4e-4b87-bf1a-7c2d8e3f9a01"`. The canonical default for keyed-`each` row keys, todo `id` fields, and any other "I just need a stable unique string" use case.

Shipped from the **sub-path** `@whisq/core/ids`, not the main entry. Since alpha.8.

## Signature

```ts

function randomId(): string;
```

## Example

```ts

interface Todo { id: string; text: string; done: boolean }

const todos = signal<Todo[]>([]);

const addTodo = (text: string) => {
  todos.value = [...todos.value, { id: randomId(), text, done: false }];
};
```

## How it works

- **Prefers `crypto.randomUUID()`** when the platform provides it — all modern browsers, Node 19+, Deno, Bun.
- **Falls back to a `Math.random` synthesis** for older targets (pre-19 Node, old Safari). Same v4 shape (`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` where `y ∈ {8, 9, a, b}`), but with weaker entropy.
- **Same output shape on both paths**, so callers don't have to branch on platform.

## Not a security primitive

:::caution
Suitable for UI row ids and keyed-`each` keys. **Not** suitable for security tokens, password reset codes, session ids, or anything where unpredictability matters — the fallback path is not cryptographically strong, and even native `crypto.randomUUID()` isn't intended for cryptographic secrets.

For tokens, use the platform's `crypto.getRandomValues()` (or a server-side secret generator) and don't reach for `randomId()`.
:::

## Why a sub-path?

`@whisq/core/ids` lives on its own sub-path so apps that don't generate ids client-side (e.g. an SSR app where the server hands out ids) pay no bundle cost. Same convention as `/persistence`, `/forms`, and `/collections`.

See also: [`/api/imports/#ids`](https://whisq.dev/api/imports/#ids), [Todo App example](https://whisq.dev/examples/todo-app/).

---
# raw()
URL: https://whisq.dev/api/raw/
---

Inject pre-built HTML into the DOM. Use for markdown output, third-party HTML, etc.

## Signature

```ts
function raw(htmlString: string | (() => string)): WhisqNode
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `htmlString` | `string \| (() => string)` | HTML string (static or reactive) |

## Examples

```ts

div({ class: "content" },
  h1("My Post"),
  raw(markdownToHtml(post.body)),
)
```

:::danger[Common Mistake]
`raw()` does **NOT** sanitize HTML. Never pass user input directly — always sanitize first to prevent XSS.
:::

---
# rcx()
URL: https://whisq.dev/api/rcx/
---

Compose class names reactively — returns a getter function for use with reactive `class` props.

:::tip[Since alpha.8]
For reactive class composition directly on an element prop, prefer the **array form on `class:`** — it accepts strings, falsy shorthands, and reactive getters in one place, with no separate `cx` / `rcx` decision. See [`/api/elements/#class-array-form-since-alpha8`](https://whisq.dev/api/elements/#class-array-form-since-alpha8). Reach for `rcx()` when you need to compose a reactive class string outside an element prop.
:::

## Signature

```ts
function rcx(...args: (string | (() => string | false | null | undefined) | false | null | undefined)[]): () => string
```

Any positional argument can be a plain string, a falsy value (`false` / `null` / `undefined`), or a getter function returning string-or-falsy. Falsy values and falsy getter returns are skipped; remaining classes are space-joined.

## Examples

### One static class

```ts
div({ class: rcx("btn") })
```

### Static base + reactive toggle

```ts
const loading = signal(false);

div({
  class: rcx("btn", () => loading.value && "btn-loading"),
})
```

### All reactive

```ts
const theme = signal<"light" | "dark">("light");
const size = signal<"sm" | "md" | "lg">("md");

div({
  class: rcx(
    () => `theme-${theme.value}`,
    () => `size-${size.value}`,
  ),
})
```

### Mixing with `sheet()` classes

```ts
const s = sheet({
  item:   { padding: "0.5rem" },
  active: { background: "var(--color-accent-low)" },
});

const selected = signal(false);

li({
  class: rcx(s.item, () => selected.value && s.active),
})
```

### Multiple toggles

```ts
const variant = signal<"primary" | "secondary">("primary");
const loading = signal(false);

div({
  class: rcx(
    "btn",
    () => variant.value === "primary" && "btn-primary",
    () => variant.value === "secondary" && "btn-secondary",
    () => loading.value && "btn-loading",
  ),
})
```

---
# ref()
URL: https://whisq.dev/api/ref/
---

Create an `ElementRef<T>` (a `Signal<T | null>`) that Whisq populates with a DOM element after mount and resets to `null` on unmount. Pass it as the `ref` prop on any element and read `.value` — **not `.current`** — after `onMount`.

:::caution[Not React]
Whisq refs are plain signals. Read them with `.value`, never `.current` — that's the most common mistake for developers coming from React. See [Common Mistakes → `.current` instead of `.value`](https://whisq.dev/common-mistakes/#current-instead-of-value-on-a-ref).
:::

## Signature

```ts
function ref<T extends HTMLElement = HTMLElement>(): ElementRef<T>;
```

Where `ElementRef<T>` is a named type alias exported from `@whisq/core`:

```ts
type ElementRef<T> = Signal<T | null>;
```

The alias is structurally identical to `Signal<T | null>` — its job is ergonomic. Tooltips read `ElementRef<HTMLInputElement>` instead of `Signal<HTMLInputElement | null>`, so the concept has a name.

## Returns

An `ElementRef<T>` that starts at `null` and is set to the element after mount. Read via `.value`.

## Examples

```ts

const Focus = component(() => {
  const inputEl = ref<HTMLInputElement>(); // ElementRef<HTMLInputElement>
  onMount(() => inputEl.value?.focus()); // .value — not .current
  return input({ ref: inputEl, placeholder: "Autofocused" });
});
```

Because it's a regular signal, you can also read it reactively:

```ts

const el = ref<HTMLDivElement>();
effect(() => {
  if (el.value) console.log("mounted", el.value.getBoundingClientRect());
});
div({ ref: el }, "Hello");
```

## Naming a prop or field that holds a ref

Use the `ElementRef<T>` type when you need to declare the shape of an object, prop, or collection of refs:

```ts

type FormRefs = {
  email: ElementRef<HTMLInputElement>;
  submitBtn: ElementRef<HTMLButtonElement>;
};
```

## Callback-ref form

A function that receives the element is also supported on the `ref` prop. `Ref<T>` — exported as a type from `@whisq/core` — is the union of both shapes:

```ts

type Ref<T> = ElementRef<T> | ((el: T | null) => void);
```

## Backward compatibility

`ElementRef<T>` is a type alias over `Signal<T | null>`, not a new type. Code that declared `const r: Signal<HTMLInputElement | null> = ref()` still type-checks without changes — the alias exists for readability, not for nominal typing.

---
# resource()
URL: https://whisq.dev/api/resource/
---

Fetch async data with reactive loading, error, and data states.

## Signature

```ts
function resource<T>(fetcher: () => Promise<T>): Resource<T>
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `fetcher` | `() => Promise<T>` | Async function that returns data |

## Returns

| Property | Type | Description |
|---|---|---|
| `.data()` | `T \| undefined` | Resolved data |
| `.loading()` | `boolean` | True while fetching |
| `.error()` | `Error \| undefined` | Rejection error |
| `.refetch()` | `void` | Re-execute the fetcher |

## Examples

```ts

const users = resource(() =>
  fetch("/api/users").then(r => r.json())
);

div(
  when(() => users.loading(), () => p("Loading...")),
  when(() => !!users.error(), () => p(() => users.error()!.message)),
  when(() => !!users.data(), () =>
    ul(each(() => users.data()!, (u) => li(u.name)))
  ),
)
```

---
# Reading route state
URL: https://whisq.dev/api/route-state/
---

There's no `useRoute()` hook in `@whisq/router` — reading the current route is done directly via `router.current`, a `ReadonlySignal<RouteState>`. Every other router primitive (`RouterView`, `Link`'s active-class) is built on subscribing to that signal.

This page covers the reactive-access shape: what `RouteState` exposes, how to read it inside components, and which read form (`.value` vs callable getter) to reach for in which context.

## `RouteState`

```ts
interface RouteState {
  path: string;
  params: Record<string, string>;
  query: Record<string, string>;
  matched: MatchedRoute[];
  meta: Record<string, unknown>;
}

interface MatchedRoute {
  route: RouteConfig;
  params: Record<string, string>;
}
```

| Field | Type | Description |
|---|---|---|
| `path` | `string` | Normalised pathname — leading slash, no trailing slash (except `"/"`). |
| `params` | `Record<string, string>` | All `:name` captures across the matched chain, flattened. Nested routes contribute their own params plus ancestors'. |
| `query` | `Record<string, string>` | Parsed query string. Single values only — repeated keys are overwritten. Empty object when no query. |
| `matched` | `MatchedRoute[]` | The full chain of matched routes, top-down. Length = nesting depth. Useful for breadcrumbs. |
| `meta` | `Record<string, unknown>` | Merged `meta` from every matched route, in matched order (child wins on key collision). Useful for per-route flags like `{ requiresAuth: true }`. |

## Reading inside a component

Use the callable getter form (`() => router.current.value.<field>`) anywhere Whisq expects a reactive value — text children, reactive props, inside `when()` / `match()`:

```ts

```

The render callback's `params` argument is a `Record<string, string>` aggregated from all matched routes **up to and including this view's `depth`** — sugar so shallow components don't need to import `router`:

```ts
// Reads the params passed by RouterView for this depth.
```

This is a **plain object snapshot** captured when the component mounts. It's equal to `router.current.value.params` when the component sits at the deepest matched level, but a shallower view's render sees a proper subset (its own params plus ancestors', not descendants').

`RouterView` re-mounts the component on every route change, so the snapshot is always for the current match — no stale captures across navigations. But inside an **already-mounted** component, if you need a value that reads reactively without a re-mount (uncommon — happens mostly with hash-only changes or programmatic rewrites), reach for the signal:

```ts
// Always reads the current value — works even if the framework
// short-circuits a re-mount for an identical route swap.
h1(() => `User ${router.current.value.params.id}`)
```

## Reading inside an effect

`router.current.value` establishes a subscription, so the effect re-runs on every route change:

```ts

effect(() => {
  const route = router.current.value;
  document.title = route.meta.title as string | undefined ?? "App";
});
```

If you only care about a specific field, read just that to keep the effect's dependency set tight:

```ts
effect(() => {
  const tab = router.current.value.query.tab ?? "profile";
  loadTab(tab);
});
```

The effect still re-runs on every navigation (since `router.current` is a single signal), but reading the narrow projection up front makes the intent obvious and keeps the effect body focused.

## `peek()` — read without subscribing

For one-shot reads in non-reactive contexts (event handlers, analytics calls):

```ts
button({
  onclick: () => {
    const current = router.current.peek().path;
    analytics.track("logout", { from: current });
  },
}, "Log out")
```

`.peek()` reads the current value without entering the tracking scope — the effect or component around this button won't re-render on route change just because it read the path.

## Patterns

- **Breadcrumbs** — iterate `router.current.value.matched`, reading `meta.title` (or another per-route field) on each `MatchedRoute`.
- **Per-route page title** — `effect(() => document.title = router.current.value.meta.title ?? "App")` as shown above. Prefer this over `useHead` inside per-route components when the title logic lives outside the routes.
- **Query-string-driven state** — treat `router.current.value.query.x` as the source of truth for a query-gated UI mode; write back via `router.navigate` with a rebuilt query string.

## See also

- [`/api/createrouter/`](https://whisq.dev/api/createrouter/) — creates the `Router` that owns `current`.
- [`/api/routerview/`](https://whisq.dev/api/routerview/) — renders the component matched by `current`.
- [`/guides/routing/#accessing-route-state`](https://whisq.dev/guides/routing/#accessing-route-state) — the routing guide's take on this pattern.

---
# sheet()
URL: https://whisq.dev/api/sheet/
---

Generate scoped class names from JavaScript objects. Auto-injects a `<style>` tag.

## Signature

```ts
function sheet<T extends SheetDef>(definitions: T): SheetResult<T>
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `definitions` | `T` | Object mapping class names to CSS rules |

## Returns

Object where each key is a scoped class name string. Also includes a `.cls()` helper.

## Examples

```ts

const s = sheet({
  card: {
    padding: "1.5rem",
    borderRadius: "12px",
    background: "#fff",
    "&:hover": { background: "#f5f5f5" },
  },
  title: { fontSize: "1.25rem", fontWeight: 600 },
});

div({ class: s.card }, h2({ class: s.title }, "Hello"), p("World"))
```

## Supported nested selectors

Two buckets, resolved by the leading character of the key:

- **`&`-prefixed keys** — the leading `&` is dropped and the rest of the key is appended verbatim to the scoped class name. So `"&:hover"` becomes `.wq0_card:hover`, `"& > span"` becomes `.wq0_card > span`, and so on. Anything valid as a CSS suffix works — pseudo-classes, pseudo-elements, combinators, attribute selectors, `:not()`, `:has()`, etc.
- **`@`-prefixed keys** — wrapped around the class rule. `"@media (min-width: 768px)"` becomes `@media (min-width: 768px){.wq0_card{...}}`. `@supports`, `@container`, and any other conditional at-rule work the same way.

### Pseudo-classes

```ts
sheet({
  btn: {
    background: "#333",
    color: "#fff",
    "&:hover":         { background: "#555" },
    "&:focus-visible": { outline: "2px solid var(--color-accent)" },
    "&:disabled":      { opacity: 0.5, cursor: "not-allowed" },
    "&:active":        { background: "#222" },
  },
})
```

### Pseudo-elements

```ts
sheet({
  card: {
    position: "relative",
    "&::before":      { content: '""', position: "absolute", inset: 0 },
    "&::after":       { content: '"★"', position: "absolute", top: "0.5rem", right: "0.5rem" },
  },
  field: {
    padding: "0.5rem",
    "&::placeholder": { color: "var(--color-text-muted)" },
  },
})
```

### Compound selectors

Stack pseudo-classes and pseudo-elements directly — the whole suffix is concatenated.

```ts
sheet({
  toggle: {
    "&:checked::after":       { content: '"✓"', color: "var(--color-success)" },
    "&:hover:not(:disabled)": { background: "#555" },
    "&:has(:focus-visible)":  { outline: "2px solid var(--color-accent)" },
  },
})
```

### Combinators (descendants, children, siblings)

```ts
sheet({
  list: {
    listStyle: "none",
    padding: 0,
    "& > li":       { padding: "0.5rem", borderBottom: "1px solid #eee" },
    "& a":          { color: "var(--color-accent)", textDecoration: "none" },
    "& a:hover":    { textDecoration: "underline" },
    "& > li + li":  { marginTop: "0.25rem" },
  },
})
```

### Attribute selectors and class modifiers

```ts
sheet({
  dialog: {
    display: "none",
    "&[open]":              { display: "block" },
    '&[data-state="entering"]': { animation: "fade-in 150ms" },
  },
  btn: {
    background: "#333",
    "&.primary":   { background: "var(--color-primary)" },
    "&.danger":    { background: "var(--color-danger)" },
    "&.small":     { padding: "0.25rem 0.5rem" },
  },
})
```

### At-rules (media, supports, container)

```ts
sheet({
  card: {
    padding: "1rem",
    display: "block",
    "@media (min-width: 768px)": { padding: "2rem" },
    "@supports (display: grid)": { display: "grid", gap: "1rem" },
    "@container (max-width: 400px)": { fontSize: "0.875rem" },
  },
})
```

:::caution[@container requires a containment ancestor]
`@container` queries only fire when a containing ancestor declares `container-type` (e.g. `container-type: inline-size`). `sheet()` emits the at-rule correctly, but without that ancestor the query silently never matches. `@media` and `@supports` have no such setup requirement — they always evaluate against browser state.
:::

## SSR behaviour (since alpha.8)

On the server (`typeof document === "undefined"`), `sheet()` **returns the in-memory `classMap` as usual** — server-rendered HTML can reference the correct class names for the client to hydrate against — but **skips the DOM injection step**. The styles aren't written to a `<style>` tag on the server; client-side hydration injects them on mount.

Previously threw `ReferenceError: document is not defined` at the injection line. The fix in alpha.8 is the same internal `injectCSS()` short-circuit that `theme()` and `persistedSignal()` already use.

If your SSR pipeline needs the styles inlined into server HTML (e.g. for first-paint correctness without a hydration flash), emit them yourself by walking the returned classMap and serializing the rules into a `<style>` block in your SSR template.

## Limitations

- **Single level of nesting.** Nested rules are flat `{ property: value }` objects — you cannot nest a `&`- or `@`- key inside another nested block. To express "the hover state of a descendant," combine the selectors yourself: `"&:hover > span"` rather than `"&:hover": { "& > span": { ... } }`.
- **No global / top-level selectors.** `sheet()` only emits scoped class rules. For global resets or tag-level styling, inject a `<style>` tag manually or use a separate CSS file.
- **`&` must be the first character of the key.** The engine only processes keys that start with `&` or `@`. A key like `".parent"`, `"> span"`, or `"span &"` is **silently mishandled** — it goes into the base rule and is serialized as a CSS property, producing garbage output without any error. This is the footgun to watch for: always start your nested keys with `&` or `@`.
- **No SCSS-style `&` substitution mid-selector.** The engine does not scan for `&` beyond the leading position. Writing `"&:hover & > span"` emits `.cls:hover & > span` — the second `&` stays literal and is invalid CSS.

---
# signal()
URL: https://whisq.dev/api/signal/
---

Create a reactive value that triggers updates when changed.

## Signature

```ts
function signal<T>(initialValue: T): Signal<T>
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `initialValue` | `T` | The initial value |

## Returns

`Signal<T>` with:

| Property | Type | Description |
|---|---|---|
| `.value` | `T` | Read or write (triggers reactivity) |
| `.peek()` | `T` | Read without tracking |
| `.set(value)` | `void` | Set a new value |
| `.update(fn)` | `void` | Update via function |
| `.subscribe(fn)` | `() => void` | Subscribe to changes, returns unsubscribe |

## Examples

```ts

const count = signal(0);
count.value;              // 0 (read — triggers tracking)
count.value = 5;          // (write — triggers updates)
count.update(n => n + 1); // 6
count.peek();             // 6 (read — no tracking)
```

:::tip[🐱 Whisker Tip]
Use `peek()` inside effects when you need a value without creating a dependency. This prevents infinite loops.
:::

## Related primitives

- [`computed()`](https://whisq.dev/api/computed/) — derived values (read-only signals that recompute when their inputs change).
- [`effect()`](https://whisq.dev/api/effect/) — run side effects when tracked signals change.
- [`batch()`](https://whisq.dev/api/batch/) — group multiple writes into one notification.
- [`persistedSignal()`](https://whisq.dev/api/persistedsignal/) — a `Signal<T>` backed by `localStorage` / `sessionStorage` (sub-path import).
- [`signalMap()`](https://whisq.dev/api/signalmap/), [`signalSet()`](https://whisq.dev/api/signalset/) — reactive collections with per-key / per-value subscriptions.
- [`partition()`](https://whisq.dev/api/partition/) — split a signal-held array into matching / not-matching derived signals.

---
# signalMap()
URL: https://whisq.dev/api/signalMap/
---

A reactive `Map`-shaped collection where each key has its own subscriber set. Effects that read a specific key via `.get()` or `.has()` re-run only when that key changes — effects that iterate or read `.size` re-run on any structural change.

Shipped from the **sub-path** `@whisq/core/collections`, not the main entry.

## Signature

```ts

function signalMap<K, V>(
  initial?: Iterable<readonly [K, V]>,
): SignalMap<K, V>;

interface SignalMap<K, V> {
  get(key: K): V | undefined;
  has(key: K): boolean;
  set(key: K, value: V): SignalMap<K, V>;
  delete(key: K): boolean;
  clear(): void;
  readonly size: number;
  keys(): IterableIterator<K>;
  values(): IterableIterator<V>;
  entries(): IterableIterator<[K, V]>;
  [Symbol.iterator](): IterableIterator<[K, V]>;
  forEach(fn: (value: V, key: K, map: SignalMap<K, V>) => void): void;
}
```

## Parameters

| Param     | Type                                  | Description                           |
| --------- | ------------------------------------- | ------------------------------------- |
| `initial` | `Iterable<readonly [K, V]>`           | Optional initial key/value pairs      |

## Reactivity

- `.get(key)` / `.has(key)` — subscribe **only** to `key`. Writes to other keys don't re-run your effect.
- `.size`, iteration, `.keys()` / `.values()` / `.entries()` / `.forEach()` — subscribe to **structural** changes (add/delete/clear).
- `.set(key, value)` — notifies subscribers of `key` (and `.size` subscribers if it's a new key).

## Examples

```ts

interface User { name: string }

const users = signalMap<string, User>();
users.set("u1", { name: "Alice" });

effect(() => {
  // Tracks "u1" only — other inserts don't re-run this.
  console.log(users.get("u1")?.name);
});

users.set("u2", { name: "Bob" });     // effect does NOT re-run
users.set("u1", { name: "Carol" });   // effect re-runs
```

Use `signalMap` when you keep a dictionary keyed by stable IDs and want per-ID subscriptions — it avoids the O(N) re-run cost of a single `signal<Record<K, V>>` on every mutation.

---
# signalSet()
URL: https://whisq.dev/api/signalSet/
---

A reactive `Set`-shaped collection with per-value membership signals. Effects that read `.has(x)` re-run only when `x` is added or removed, not on other changes.

Shipped from the **sub-path** `@whisq/core/collections`, not the main entry.

## Signature

```ts

function signalSet<T>(initial?: Iterable<T>): SignalSet<T>;

interface SignalSet<T> {
  has(value: T): boolean;
  add(value: T): SignalSet<T>;
  delete(value: T): boolean;
  clear(): void;
  readonly size: number;
  keys(): IterableIterator<T>;
  values(): IterableIterator<T>;
  entries(): IterableIterator<[T, T]>;
  [Symbol.iterator](): IterableIterator<T>;
  forEach(fn: (value: T, value2: T, set: SignalSet<T>) => void): void;
}
```

## Parameters

| Param     | Type             | Description                       |
| --------- | ---------------- | --------------------------------- |
| `initial` | `Iterable<T>`    | Optional initial values           |

## Reactivity

- `.has(value)` — subscribes **only** to membership of that specific `value`.
- `.size`, iteration, `.keys()` / `.values()` / `.entries()` / `.forEach()` — subscribe to **structural** changes (add/delete/clear).
- `.add(value)` / `.delete(value)` — notifies subscribers of that value and the structure signal.

## Examples

```ts

const selected = signalSet<string>();

effect(() => {
  // Tracks "admin" only — other adds/deletes don't re-run this.
  console.log("admin selected:", selected.has("admin"));
});

selected.add("user");    // effect does NOT re-run
selected.add("admin");   // effect re-runs (prints true)
selected.delete("admin"); // effect re-runs (prints false)
```

Pair with `signalMap` for patterns like "which rows are selected in a table" — each row's `has()` only re-renders when its own membership flips.

---
# styles()
URL: https://whisq.dev/api/styles/
---

Create a reactive inline style string from a JavaScript object.

## Signature

```ts
function styles(def: ReactiveStyleDef): string | (() => string)
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `def` | `ReactiveStyleDef` | Object mapping CSS properties to values or reactive functions |

## Examples

```ts

const dark = signal(false);

div({
  style: styles({
    padding: "1rem",
    background: () => dark.value ? "#111" : "#fff",
    color: () => dark.value ? "#fff" : "#111",
  }),
}, "Content")
```

---
# sx()
URL: https://whisq.dev/api/sx/
---

Merge multiple style sources into a single object to pass as the `style` prop. Function values in a source are preserved (not invoked), so the `style` prop's per-property reactivity sees them.

## Signature

```ts
function sx(...sources: SxStyleSource[]): Record<string, SxStyleValue | (() => SxStyleValue)>;
```

## How it merges

- Each `source` is either a plain style object or a falsy value. Falsy sources are skipped.
- Keys from later sources override earlier ones.
- **Merging happens at call time**, not reactively. A source that reads a signal value (`active.value && { ... }`) is evaluated once during setup — frozen after.
- For reactive conditionals, **put the function on the property**, not the source: `{ borderColor: () => active.value ? "blue" : "transparent" }`.

## Examples

```ts

const active = signal(false);
const x = signal(0);

div({
  style: sx(
    { color: "red", padding: "1rem" },                              // base
    { borderColor: () => active.value ? "blue" : "transparent" },   // reactive conditional
    { transform: () => `translateX(${x.value}px)` },                // reactive
  ),
});
```

For scoped class-based styles instead of inline, see [`sheet()`](https://whisq.dev/api/sheet/) and [`rcx()`](https://whisq.dev/api/rcx/).

---
# theme()
URL: https://whisq.dev/api/theme/
---

Define CSS custom properties at `:root` level for design tokens.

## Signature

```ts
function theme(tokens: ThemeTokens, options?: ThemeOptions): void

// Since alpha.9 — exported from "@whisq/core"
interface ThemeOptions {
  /** Suppress the dev-mode "theme() called twice" warning. */
  silent?: boolean;
}
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `tokens` | `ThemeTokens` | Object of token groups and values |
| `options.silent` | `boolean` (optional, since alpha.9) | Suppress the dev-mode duplicate-call warning. Use for legitimate second calls (theme-switching). Default: `false`. |

## Examples

```ts

theme({
  color: {
    primary: "#4386FB",
    text: "#111827",
    bg: "#ffffff",
  },
  space: { sm: "0.5rem", md: "1rem", lg: "1.5rem" },
  radius: { md: "8px", lg: "12px" },
});

// Generated CSS: --color-primary: #4386FB; --space-md: 1rem; etc.

// Use in sheet():
sheet({
  card: {
    background: "var(--color-bg)",
    padding: "var(--space-lg)",
    borderRadius: "var(--radius-lg)",
  },
});
```

## Call-site conventions

- **Call once, at module scope** in your `src/styles.ts` file. The tokens become CSS custom properties on `:root` and are available everywhere. Import `styles.ts` transitively from `App.ts` so the call runs on first import.
- **Duplicate calls = last-call-wins.** A second `theme()` call replaces the first `<style id="whisq-style-whisq-theme">` block entirely; the new tokens take effect immediately. This is intentional — it enables theme-switching (e.g., `theme(lightTokens)` → `theme(darkTokens)` in a toggle handler) without leaking old tokens.
- **Duplicate-call dev warning (since alpha.9).** Accidentally importing two `styles.ts` files silently wiping the first theme's variables was the alpha.8 feedback's top styling footgun. Alpha.9+ emits a `console.warn` in dev when a second `theme()` call would replace an existing block; use `{ silent: true }` to acknowledge intentional second calls (theme-switching). Production doesn't emit the warning regardless. See [Duplicate-call warning](#duplicate-call-warning-since-alpha9) below.
- **SSR-safe (since alpha.8).** On the server (`typeof document === "undefined"`), the call is a no-op — no `<style>` tag is written. Client-side hydration applies the theme on mount. Previously threw `ReferenceError: document is not defined`.

  CSS variables won't appear in server-rendered HTML by themselves; attach theme tokens in a `<style>` block in your SSR template until a dedicated server renderer ships.

## Duplicate-call warning (since alpha.9)

`theme()` is last-call-wins by design — the second call replaces the first `<style>` block. Useful for theme-switching; a source of silent bugs when the duplicate is accidental (e.g., two `styles.ts` files imported transitively by different parts of the app).

Alpha.9 adds a `console.warn` in dev when a second call would replace an existing block. Two modes:

```ts
// Accidental duplicate — dev warns.
// styles.ts
theme({ color: { primary: "#4386FB" } });

// another-styles.ts (imported from another branch of the graph)
theme({ color: { primary: "#ffffff" } });   // Dev: console.warn names the conflict.

// Intentional theme switch — opt out of the warning.
const toggleDark = () => {
  theme(darkTokens, { silent: true });     // No warning.
};
```

Detection is DOM-based (`getElementById("whisq-style-whisq-theme")`). Production builds strip the entire guard via the existing `NODE_ENV !== "production"` pattern, so there's no runtime cost in shipped code.

The `silent: true` option only suppresses the warning — it doesn't change injection semantics. `theme()` remains last-call-wins regardless.

See also: [`/api/sheet/`](https://whisq.dev/api/sheet/), [Styling guide](https://whisq.dev/core-concepts/styling/), [Common Mistakes → theme variables flipped unexpectedly](https://whisq.dev/common-mistakes/#theme-variables-flipped-unexpectedly-after-merge).

---
# transition()
URL: https://whisq.dev/api/transition/
---

Wrap a `WhisqNode` with enter / exit CSS animations powered by the Web Animations API. Enter fires when the node is mounted; exit fires on disposal (the node stays in the DOM until the exit animation completes).

## Signature

```ts
function transition(node: WhisqNode, options: TransitionOptions): WhisqNode;

interface TransitionOptions {
  enter?: TransitionPhase;
  exit?: TransitionPhase;
}

// A phase is duration + easing + any number of CSS property [from, to] pairs
type TransitionPhase = {
  duration?: number;   // ms, default 300
  easing?: string;     // CSS easing, default "ease"
  [prop: string]: [string | number, string | number] | number | string | undefined;
};
```

## Parameters

| Param     | Type                 | Description                                       |
| --------- | -------------------- | ------------------------------------------------- |
| `node`    | `WhisqNode`          | The node to animate                               |
| `options` | `TransitionOptions`  | `enter` and/or `exit` phase configs               |

Each phase's CSS property keys take a `[from, to]` tuple. Non-array values (numbers, strings) on a phase are reserved for `duration` / `easing`.

## Examples

```ts

transition(
  div({ class: "toast" }, "Saved"),
  {
    enter: {
      opacity: [0, 1],
      transform: ["translateY(10px)", "translateY(0)"],
      duration: 200,
      easing: "ease-out",
    },
    exit: {
      opacity: [1, 0],
      duration: 150,
    },
  },
);
```

On mount, the toast fades in and slides up over 200 ms. When the wrapping control (`when()`, `match()`, etc.) disposes it, the exit animation plays and the node is removed from the DOM when the animation settles.

---
# useHead()
URL: https://whisq.dev/api/useHead/
---

Reactively manage the document's title, meta tags, and link tags. Call from inside a `component()` setup. Tags are automatically removed when the component unmounts.

## Signature

```ts
function useHead(config: HeadConfig): void;

interface HeadConfig {
  title?: string | (() => string);
  meta?: Record<string, string | (() => string)>[];
  link?: Record<string, string>[];
}
```

## Parameters

| Field   | Type                                              | Description                                                    |
| ------- | ------------------------------------------------- | -------------------------------------------------------------- |
| `title` | `string \| (() => string)`                        | Document title. Pass a function for reactive titles            |
| `meta`  | `Record<string, string \| (() => string)>[]`      | Array of meta-tag attribute bags (values can be reactive)      |
| `link`  | `Record<string, string>[]`                        | Array of link-tag attribute bags                               |

## Cleanup

Each reactive title / meta value registers a `cleanup` that runs on component unmount, removing the tag from `<head>` and disposing the effect. No manual cleanup needed.

## Examples

```ts

const page = signal("Home");
const desc = signal("The AI-native framework");

const Page = component(() => {
  useHead({
    title: () => `${page.value} — Whisq`,
    meta: [
      { name: "description", content: () => desc.value },
      { property: "og:title",       content: () => page.value },
      { property: "og:description", content: () => desc.value },
    ],
    link: [{ rel: "canonical", href: "https://whisq.dev/" }],
  });

  return div(h1(() => page.value));
});
```

Updating `page.value` or `desc.value` flips `<title>` and the reactive meta attributes in place — no DOM rewiring, just an `effect()` per reactive value.

## Constraint

Must be called during a component's synchronous setup. Calling it outside `component()` (top-level, inside an effect, after an `await`) throws.

---
# when()
URL: https://whisq.dev/api/when/
---

Render content conditionally based on a reactive condition.

## Signature

```ts
function when(
  condition: () => boolean,
  then: () => WhisqNode | string | null,
  otherwise?: () => WhisqNode | string | null,
): () => Child
```

## Parameters

| Param | Type | Description |
|---|---|---|
| `condition` | `() => boolean` | Reactive condition |
| `then` | `() => WhisqNode \| string \| null` | Rendered when true |
| `otherwise` | `() => WhisqNode \| string \| null` | Rendered when false (optional) |

## Examples

```ts

const loggedIn = signal(false);

div(
  when(() => loggedIn.value,
    () => p("Welcome back!"),
    () => button({ onclick: login }, "Sign In"),
  ),
)
```

## Related primitives

- [`match()`](https://whisq.dev/api/match/) — multi-branch conditional for 3+ cases with a fallback.
- [`each()`](https://whisq.dev/api/each/) — iterate a reactive array (use together for list-plus-empty-state shapes).
- [Conditional Rendering guide](https://whisq.dev/core-concepts/conditional-rendering/) — narrative arc of `when` → `match` → inline ternary.

---
# Canonical Patterns
URL: https://whisq.dev/canonical-patterns/
---

A situation-keyed catalogue of recommended patterns. Sister page to [Common Mistakes](https://whisq.dev/common-mistakes/): that page answers "why isn't this working?" symptom-first; this page answers "what's the right way to do this?" situation-first.

Each entry is one recommended pattern with a short code block, a one-sentence "why," and a cross-link. For deeper decision-tables across multiple primitives, see [Choosing Patterns](https://whisq.dev/core-concepts/choosing-patterns/).

## Two-way bind a checkbox in a list

**Recommended pattern.**

```ts
each(() => todos.value, (todo) =>
  input({ type: "checkbox", ...bindField(todos, todo, "done", { as: "checkbox" }) }),
  { key: (t) => t.id },
)
```

**Why.** `bindField` handles the keyed-`each()` accessor, writes immutably, and identifies the right item via `keyBy` (default `t => t.id`).

**See also.** [`/api/bindfield/`](https://whisq.dev/api/bindfield/), [Nested Item Editing → Pattern 1](https://whisq.dev/guides/nested-item-editing/).

## Read a per-item field reactively inside keyed `each()`

**Recommended pattern.**

```ts
each(() => todos.value, (todo) =>
  li({ class: () => todo.value.done ? "done" : "" }, () => todo.value.text),
  { key: (t) => t.id },
)
```

**Why.** In alpha.8+, the render callback's `todo` is `ItemAccessor<T>` — read via `todo.value.<field>`. Wrap reactive reads in a getter (`() => todo.value.text`) so the reconciler keeps them fresh across entry swaps. The `key:` callback receives the value.

**See also.** [`/api/each/`](https://whisq.dev/api/each/), [Common Mistakes → Keyed each() mistakes](https://whisq.dev/common-mistakes/#keyed-each-mistakes).

## Persist plain-object state to localStorage

**Recommended pattern.**

```ts

interface Todo { id: string; text: string; done: boolean }
```

**Why.** The helper handles SSR, quotas, schema validation, and JSON round-tripping. Use at module scope in `stores/`.

**See also.** [`/api/persistedsignal/`](https://whisq.dev/api/persistedsignal/), [Persistence Recipes](https://whisq.dev/guides/state-management/#recipes-by-data-shape).

## Two-way bind a deeply-nested object field

**Recommended pattern.**

```ts

form(
  input({ ...bindPath(user, ["profile", "name"]) }),
  input({ type: "email", ...bindPath(user, ["profile", "email"]) }),
)
```

**Why.** `bindPath` walks deep paths on a single record signal — the third primitive alongside `bind` (single signal) and `bindField` (array field).

**See also.** [`/api/bindpath/`](https://whisq.dev/api/bindpath/), [Forms guide → binding into nested records](https://whisq.dev/guides/forms/#binding-into-nested-records).

## Conditionally render with 3+ branches

**Recommended pattern.**

```ts
match(
  [() => users.loading(), () => p("Loading…")],
  [() => !!users.error(), () => p(() => `Error: ${users.error()!.message}`)],
  [() => !!users.data(),  () => ul(each(() => users.data()!, (u) => li(() => u.value.name)))],
  () => p("No data yet."),   // fallback
)
```

**Why.** `match()` is first-true-wins with a trailing fallback — reach for it at 3+ branches where chained `when()`s would become unreadable.

**See also.** [`/api/match/`](https://whisq.dev/api/match/), [Choosing Patterns → Conditional rendering](https://whisq.dev/core-concepts/choosing-patterns/#conditional-rendering--when-match-or-inline-ternary).

## Toggle a CSS class based on a signal

**Recommended pattern** (since alpha.8).

```ts
div({
  class: ["btn", () => loading.value && "btn-loading", () => active.value && "active"],
})
```

**Why.** The array form on `class:` accepts strings, falsy shorthands, and reactive getters in one prop — no separate `cx` / `rcx` helper. If any element is a function, the whole array is reactive.

**See also.** [`/api/elements/#class-array-form-since-alpha8`](https://whisq.dev/api/elements/#class-array-form-since-alpha8), [Choosing Patterns → Reactive class composition](https://whisq.dev/core-concepts/choosing-patterns/#reactive-class-composition--array-form-cx-or-rcx).

## Flatten a pre-computed class list into `class:`

**Recommended pattern.**

```ts
const base = ["btn", size === "lg" && "btn-lg"];
const extras = isPrimary ? ["btn-primary", "btn-shadow"] : [];
div({ class: [...base, ...extras, () => loading.value && "btn-loading"] });
```

**Why.** `class:` arrays are **not** flattened recursively — a nested array like `class: ["btn", ["primary", "lg"]]` silently drops the inner array. Spread the parts at the call site instead. A function that returns an array has the same trap and produces a comma-joined string; return a space-joined string or spread into separate entries. Full rules: [`/api/elements/#rules`](https://whisq.dev/api/elements/#rules).

**See also.** [`/api/elements/#class-array-form-since-alpha8`](https://whisq.dev/api/elements/#class-array-form-since-alpha8).

## Compose static class names outside an element prop

**Recommended pattern.**

```ts
const cardClass = cx("card", isPrimary && "card-primary", { active: true });
```

**Why.** `cx()` is the right tool when you need to compose a class string as a utility return value — but on an element prop, prefer the array form above.

**See also.** [`/api/cx/`](https://whisq.dev/api/cx/).

## Set up theme tokens

**Recommended pattern.**

```ts
// src/styles.ts

theme({
  color: { primary: "#4386FB", text: "#111827", bg: "#ffffff" },
  space: { sm: "0.5rem", md: "1rem", lg: "1.5rem" },
});
```

**Why.** Call once, at module scope, in `src/styles.ts`. Import that file transitively from `App.ts`. Duplicate calls replace the previous tokens (last-call-wins — useful for theme-switching). SSR-safe since alpha.8.

**See also.** [`/api/theme/`](https://whisq.dev/api/theme/), [Styling guide → Lifecycle](https://whisq.dev/core-concepts/styling/#lifecycle-where-to-call-theme-and-sheet).

## Pass a child component an accessor for cross-boundary reactivity

**Recommended pattern.**

```ts

type TodoItemProps = { todo: ItemAccessor<Todo>; onRemove: (id: string) => void };

const TodoItem = component((props: TodoItemProps) =>
  li(
    input({ type: "checkbox", ...bindField(todos, props.todo, "done", { as: "checkbox" }) }),
    () => props.todo.value.text,
    button({ onclick: () => props.onRemove(props.todo.value.id) }, "×"),
  ),
);

each(() => todos.value, (todo) => TodoItem({ todo, onRemove: removeTodo }), { key: (t) => t.id })
```

**Why.** Pass the accessor reference itself (not `props.todo.value`) so the child reads current values across reconciler swaps. Type with `ItemAccessor<T>` so helpers typed as `() => T` still accept it.

**See also.** [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component), [Nested Item Editing → Pattern 3](https://whisq.dev/guides/nested-item-editing/).

## Update an array signal immutably

**Recommended pattern.**

```ts
todos.value = [...todos.value, { id: randomId(), text, done: false }];
// or:
todos.value = todos.value.filter(t => !t.done);
// or:
todos.value = todos.value.map(t => t.id === id ? { ...t, done: !t.done } : t);
```

**Why.** Reactivity triggers on the signal's `.value` being **reassigned**, not on the array being mutated in place. `push()` / `splice()` / direct index writes don't fire subscribers.

**See also.** [Common Mistakes → Array mutation instead of reassignment](https://whisq.dev/common-mistakes/#array-mutation-instead-of-reassignment).

## Generate a row id

**Recommended pattern** (since alpha.8).

```ts

const newTodo = { id: randomId(), text, done: false };
```

**Why.** UUID-v4 shape; native `crypto.randomUUID()` when available, `Math.random` fallback for older targets. Suitable for UI keys — **not** for security tokens.

**See also.** [`/api/randomid/`](https://whisq.dev/api/randomid/).

## Split a list by predicate

**Recommended pattern** (since alpha.8).

```ts

const [pending, done] = partition(() => todos.value, (t) => !t.done);
p(() => `${pending.value.length} left`);
button({ onclick: () => todos.value = pending.value }, "Clear completed");
```

**Why.** One call produces two independently-subscribable `ReadonlySignal<T[]>` sides — subscribing to `pending` doesn't churn when only `done` changes.

**See also.** [`/api/partition/`](https://whisq.dev/api/partition/).

## See also

- [Common Mistakes](https://whisq.dev/common-mistakes/) — sister page: symptom-first debugging.
- [Choosing Patterns](https://whisq.dev/core-concepts/choosing-patterns/) — decision tables for which primitive to reach for.
- [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) — the four-shape taxonomy for where signals go.

---
# Common Mistakes
URL: https://whisq.dev/common-mistakes/
---

Symptom-first debugging reference. If you've hit a runtime error, a silent UI-doesn't-update bug, or a TypeScript complaint that doesn't match your mental model, scan this page for the symptom.

Sister page: [Canonical Patterns](https://whisq.dev/canonical-patterns/) — the positive complement, answering "what's the right way to do this?" situation-first.

Most entries are short — a one-line diagnosis plus a minimal before/after. A few of the dev-mode-error entries cover multiple sub-cases the framework's own `Hint:` text distinguishes; treat those as a checklist rather than a single rule.

## About `WhisqStructureError`

Most structural mistakes (bad children, malformed `each()` items, malformed `match()` arguments) throw a `WhisqStructureError` in dev mode. The message has a consistent shape:

```
<element>: expected <X>, received <Y>. Hint: <how to fix>
```

The throw sites are wrapped in `process.env.NODE_ENV !== "production"` guards, so production bundles strip the validation entirely — zero size cost on shipped code, helpful messages while you're building.

:::note[Playground caveat]
The `/playground` on this site runs a production build of `@whisq/core` (the bundle is minified for size), so dev-mode `WhisqStructureError` throws are stripped there. Bugs in playground snippets will silently drop unrecognized children or no-op rather than throw — debug from a real `pnpm dev` workspace to see the helpful error text.
:::

Catch them in dev to render friendly error UI:

```ts

errorBoundary(
  (err) => err instanceof WhisqStructureError
    ? div({ class: "dev-error" }, p(err.message), p({ class: "hint" }, err.hint))
    : div({ class: "error" }, "Something went wrong"),
  () => MyApp({}),
)
```

Each entry below names the exact `WhisqStructureError` text where applicable, so symptom-search by the error string lands on the right diagnosis.

## Child renders nothing / dev throws `WhisqStructureError` on unrecognized children

**Symptom.** In dev, a `WhisqStructureError` thrown by the parent element:

```text
<tagname>: expected WhisqNode | string | number | boolean | null | undefined | function | array,
  received plain object.
  Hint: Plain objects can't be rendered as children.
  Did you forget to call a component (`MyComponent({})` not `MyComponent`),
  or wrap a signal read in `() => signal.value`?
```

In production builds (validation stripped) the symptom regresses to a silent drop — the position where the child should render is empty with no error.

**Why.** Element functions handle a specific set of child types: strings, numbers, `WhisqNode`s, arrays of those, getter functions returning those, and `when()` / `match()` / `each()` results. Plain objects, raw Promises, component **definitions** (not invocations), and other un-handled shapes are not renderable.

**Fix.** Pass a handled shape — usually invoke a component (`MyComponent({})` not `MyComponent`), wrap a signal read in a getter (`() => signal.value`), or use `resource()` for async.

```ts
// ❌ component definition, not invocation
div(MyComponent)

// ✅ invoke the component
div(MyComponent({}))

// ❌ raw signal read at setup — captures once, never updates
div(name.value)

// ✅ getter — re-evaluates on change
div(() => name.value)

// ❌ raw promise
div(fetch("/api/data"))

// ✅ resource() for async
const data = resource(() => fetch("/api/data").then((r) => r.json()));
div(() => data.loading() ? "Loading…" : data.data()?.name)
```

The `Hint:` line in the error message names the specific cause — read it before reaching for the docs.

## Signal read without a getter in a reactive position

**Symptom.** Value renders once at mount, then never updates when the signal changes.

**Why.** Reactive props and children need a **function** so Whisq knows to re-evaluate them. A bare `.value` read is evaluated once at setup time — the reactive graph never sees the dependency.

**Fix.** Wrap the read in `() => ...`.

```ts
// ❌ evaluated once at setup — never updates
div({ hidden: visible.value }, `Count: ${count.value}`)

// ✅ getter re-runs on every change
div({ hidden: () => visible.value }, () => `Count: ${count.value}`)
```

See the [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) for which positions need getters.

## Array mutation instead of reassignment

**Symptom.** Calling `.push()`, `.splice()`, etc. on a signal's array value — no re-render.

**Why.** Signals use `Object.is` equality. Mutating the array doesn't change its reference, so the signal doesn't detect a change and subscribers don't re-run.

**Fix.** Assign a new array.

```ts
// ❌ mutation — reference unchanged, no update
items.value.push(newItem);

// ✅ new array — reference changes, subscribers fire
items.value = [...items.value, newItem];
items.value = items.value.filter((i) => i.id !== id);
items.value = items.value.map((i) => i.id === id ? { ...i, done: true } : i);
```

## `.current` instead of `.value` on a ref

**Symptom.** `inputEl.current` is `undefined`. TypeScript may or may not catch it depending on config.

**Why.** Whisq refs are plain signals — not React-shaped. The populated element lives on `.value`, not `.current`. The `ElementRef<T>` type alias (from `@whisq/core`) is structurally `Signal<T | null>`.

**Fix.** Use `.value`.

```ts
// ❌ React prior
onMount(() => inputEl.current?.focus());

// ✅ Whisq refs are signals
onMount(() => inputEl.value?.focus());
```

See [`/api/ref/`](https://whisq.dev/api/ref/) for the full pattern including the `ElementRef<T>` alias.

## Keyed `each()` mistakes

When you pass `{ key }` to `each()`, the render callback's `item` parameter is an **`ItemAccessor<T>`** (since alpha.8) — callable (`item()`), signal-shaped (`item.value`), and with `.peek()`. The same shape that's friction-prone enough to deserve its own collected section. Five entries below cover the patterns reviewers and AI tools have hit most often.

Non-keyed `each()` (no `{ key }`) passes plain values — the accessor shape only applies in keyed mode.

### Reading `item.field` directly (without `.value` or call)

**Symptom.** TypeScript error: `Property 'field' does not exist on type 'ItemAccessor<T>'`. Or — silent stale-data bug if you cast around it.

**Why.** `ItemAccessor<T>` is the accessor object; you have to read through `.value` (alpha.8 canonical) or call it (`()` legacy form) to get the entry.

**Fix.**

```ts
// ❌ accessing .text on the accessor
each(() => todos.value, (todo) => li(todo.text), { key: (t) => t.id })

// ✅ read via .value (alpha.8 canonical)
each(() => todos.value, (todo) => li(todo.value.text), { key: (t) => t.id })

// ✅ call form (still works pre/post-alpha.8)
each(() => todos.value, (todo) => li(todo().text), { key: (t) => t.id })
```

### Destructuring the accessor's result at setup

**Symptom.** First render is fine; after the source array is replaced (sort, filter, item swap), the destructured locals stay frozen at their initial value.

**Why.** Destructuring captures the read at setup time — `const { text, done } = todo.value` is a one-shot snapshot, not a live reference. The reconciler swaps the entry behind the same key, but your destructured locals don't see it.

**Fix.** Read through the accessor inside reactive positions, not at setup.

```ts
// ❌ destructuring at setup — captures initial entry, never updates
each(() => todos.value, (todo) => {
  const { text, done } = todo.value;          // frozen!
  return li({ class: done && "done" }, text);
}, { key: (t) => t.id })

// ✅ read inside reactive positions
each(() => todos.value, (todo) =>
  li({ class: () => todo.value.done && "done" }, () => todo.value.text),
  { key: (t) => t.id })
```

### Passing the accessor's value (snapshot) into a child component

**Symptom.** Child renders the right item once, then never reflects updates when the reconciler swaps the entry.

**Why.** Passing `todo.value` (or `todo()`) into a component snapshots the current entry. The child receives a frozen `T`, not a live accessor — same root cause as the destructuring case, just across a component boundary.

**Fix.** Pass the accessor itself, type the prop as `ItemAccessor<T>`, and read through it inside the child.

```ts
// ❌ passes a frozen snapshot — child stops updating after a swap
each(() => todos.value, (todo) =>
  TodoItem({ todo: todo.value, onRemove: removeTodo }),
  { key: (t) => t.id })

// ✅ pass the accessor; declare the prop as ItemAccessor<Todo>
type TodoItemProps = { todo: ItemAccessor<Todo>; onRemove: (id: string) => void };
const TodoItem = component((props: TodoItemProps) =>
  li({ onclick: () => props.onRemove(props.todo.value.id) }, () => props.todo.value.text)
);

each(() => todos.value, (todo) =>
  TodoItem({ todo, onRemove: removeTodo }),
  { key: (t) => t.id })
```

See [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component) for the full child-component pattern.

### Inline `.map()` where keyed `each()` is correct

**Symptom.** Re-rendering a list — even on a single-item edit — recreates every `<li>` from scratch. Focus loss, scroll jump, animation flicker, slow updates on long lists.

**Why.** `() => arr.value.map(t => li(t.text))` re-runs the whole getter on any change to `arr.value`, throwing away every existing DOM node. `each(() => arr.value, render, { key })` does LIS-based diffing — only changed nodes move, insert, or remove.

**Fix.** Use `each({ key })` whenever items have stable identities.

```ts
// ❌ inline map — full re-render on every change
ul(() => todos.value.map((t) => li(t.text)))

// ✅ keyed each — DOM is reused across reorders/edits
ul(each(() => todos.value, (t) => li(() => t.value.text), { key: (t) => t.id }))
```

### `.value` flagged as unknown by TypeScript

**Symptom.** TypeScript error like `Property 'value' does not exist on type 'never'` or `Property 'value' does not exist on type 'Function'` when reading `todo.value.<field>`.

**Why.** The hybrid accessor shape (since alpha.8) is `ItemAccessor<T>`, which is callable AND has `.value`. TypeScript only sees both shapes when `T` infers correctly — typically because the source signal is typed.

**Fix.** Type the source signal explicitly. The render callback's `todo` will then infer as `ItemAccessor<Todo>`.

```ts
// ❌ untyped — TS may infer todos.value as `any[]` and lose the shape
const todos = signal([{ id: "1", text: "Learn", done: false }]);
each(() => todos.value, (todo) => li(todo.value.text), { key: (t) => t.id })
//                                  ^^^^^^^^^^^ may not type-check

// ✅ typed source — todo infers as ItemAccessor<Todo>
interface Todo { id: string; text: string; done: boolean }
const todos = signal<Todo[]>([{ id: "1", text: "Learn", done: false }]);
each(() => todos.value, (todo) => li(todo.value.text), { key: (t) => t.id })
```

See [`/api/each/`](https://whisq.dev/api/each/) for the full `ItemAccessor<T>` interface and the four-archetype rule on when to use `.value` (snapshot) vs a getter (`() => todo.value.field` — re-evaluates) vs `.peek()` (untracked read).

## Hoisting `.value.field` out of a reactive getter

**Symptom.** A class / style / text that depended on a signal field stops updating after the first render. No dev error — the read just captures the snapshot at setup time, and subsequent `signal.value =` writes appear to have no effect in that component.

**Why.** `.value` *looks* like a plain property read, so the natural refactor for readability — "extract the expression into a local, use the local in the getter" — captures the value at setup time. The `() => …` wrapper runs once and closes over the frozen local instead of re-reading the signal on every evaluation. The signal drives its own reactivity, but only if the getter's body actually reads `.value` each time it runs.

**Fix.** Read `.value` (or `.value.field`) **inside** the getter, not outside it. If you need a local for readability, make it an accessor function (`() => signal.value.field`) and call it inside the getter.

```ts
// ❌ stale — captured at setup time, frozen after first render
const done = props.todo.value.done;
li({ class: [s.item, () => done && s.itemDone] }, props.todo.value.text);

// ✅ reads on every getter invocation
li({ class: [s.item, () => props.todo.value.done && s.itemDone] }, () => props.todo.value.text);

// ✅ if you want a readable local, make it an accessor (still re-reads)
const done = () => props.todo.value.done;
li({ class: [s.item, () => done() && s.itemDone] }, () => props.todo.value.text);
```

The trap generalises beyond keyed `each()` accessors. Plain signals have the same shape:

```ts
const user = signal({ name: "Alice", role: "admin" });

// ❌ stale — `role` captures "admin" at setup; later writes don't update the class
const role = user.value.role;
div({ class: [s.card, () => role === "admin" && s.adminCard] }, "…");

// ✅ keep the .value.field read inside the getter
div({ class: [s.card, () => user.value.role === "admin" && s.adminCard] }, "…");
```

**Rule:** never hoist `.value.field` (or `.value`, or `accessor.value.field`) out of a reactive position. You've captured the *value*, not the *reactivity*. If you want the local, make it a getter function.

See also: [`/api/each/` → Reactive fields inside keyed each()](https://whisq.dev/api/each/#reactive-fields-inside-keyed-each), [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one).

## `bind(signal.value)` instead of `bind(signal)`

**Symptom.** `TypeError: bind() expects a Signal as its first argument`. Or — the binding doesn't write back: typing into the input doesn't update the signal.

**Why.** `bind()` needs the **signal reference**, not the current value. Passing `.value` unwraps the signal into a plain value, which `bind()` can't subscribe to.

**Fix.** Pass the signal itself.

```ts
// ❌ passing the unwrapped value
input({ ...bind(name.value) })

// ✅ pass the signal reference
input({ ...bind(name) })

// ✅ inside keyed each, call the accessor then pass the signal field
// (bind receives the stable Signal<boolean>, not its value)
input({ type: "checkbox", ...bind(todo().done, { as: "checkbox" }) })
```

## `bind()` spread followed by a handler that silently drops it

**Symptom.** You added an `oninput` / `onchange` next to a `bind()` (or `bindField` / `bindPath`) spread to track user input, and the signal stopped updating. Dev since alpha.9 also prints a `console.warn` naming the overwritten handler.

**Why.** Object spread copies keys left-to-right; the later handler wins. `bind()` returns `{ value: ..., oninput: ... }` — if your spread-order reads `{ ...bind(draft), oninput: (e) => track(e) }`, your `oninput` overwrites `bind`'s and the binding stops writing back.

**Fix.** **Spread `bind()` last** so your own handler lives in the props before the spread; if there's still a collision, it's `bind`'s handler that wins (visibly), not yours — silent drops never happen on your code:

```ts
// ❌ silent drop pre-alpha.9; warns in alpha.9+ dev
input({
  ...bind(draft),
  oninput: (e) => track(e),
});

// ✅ spread bind last — bind wins, user handler has to be composed explicitly
input({
  oninput: (e) => track(e),
  ...bind(draft),
});

// ✅ or compose transparently: read bind() into a local then chain
const draftBinding = bind(draft);
input({
  ...draftBinding,
  oninput: (e) => {
    draftBinding.oninput(e);  // run bind's handler first
    track(e);
  },
});
```

**Detection caveat.** The framework's warning only catches direction 1 — spread-first, user-handler-second. If you write the *other* direction (user handler first, then `...bind(sig)`), your handler is destroyed without a trace — the warning can't fire because the evidence is gone by the time the element builder looks. That's exactly why the convention is "spread bind last" — it makes direction 2 the safe shape.

See [`/api/bind/#handler-collision-dev-warning-since-alpha9`](https://whisq.dev/api/bind/#handler-collision-dev-warning-since-alpha9) for the framework-side mechanism.

## Destructuring `props` at component setup

**Symptom.** Props from a parent update, but the child never reflects the change.

**Why.** `component()` setup runs **once**. Destructuring at the signature (`({ value })`) copies the prop's value at setup time — you lose the live reference. If the parent passed a getter prop, destructuring its result likewise captures a snapshot.

**Fix.** Access `props.value` inside the render body — or, if the prop is a getter, call it at read time.

```ts
// ❌ destructured at setup — captures the initial value forever
const Display = component(({ value }: { value: number }) =>
  p(`Count: ${value}`)  // never updates
);

// ✅ read through props on every re-evaluation
const Display = component((props: { value: () => number }) =>
  p(() => `Count: ${props.value()}`)
);
```

The footgun is destructuring the **result** of calling a getter — `const { value } = props.getter()` captures a snapshot that never updates. Destructuring the getter *function* itself (`({ getter }: { getter: () => number }) => ...`) is safe because you're copying the function reference, but `props.getter()` at the call site is the clearer pattern and the one the docs recommend consistently.

## `match()` given an object instead of tuples

**Symptom.** In dev, a `WhisqStructureError` thrown at the `match()` call site:

```text
match: expected a branch tuple `[() => boolean, () => WhisqNode]`, received plain object.
  Hint: `match()` is a predicate chain, not a value-dispatch table.
  Plain objects like `{ loading: ..., error: ... }` aren't accepted —
  write tuples: `[() => state.value === 'loading', () => ...]`.
```

**Why.** `match()` is a **predicate chain** — variadic `[predicate, render]` tuples evaluated top-to-bottom, first-truthy wins. It is not pattern matching or value dispatch. The validator catches object literals at the boundary so you don't fall through to a confusing `TypeError` (the alpha.6 symptom) or silent fallthrough (the worst case).

**Fix.** Convert each `key: value` entry to a `[predicate, render]` tuple.

```ts
// ❌ object form — WhisqStructureError in dev
match({
  loading: () => p("Loading…"),
  error:   () => p("Failed"),
  data:    () => ul(/* … */),
});

// ✅ tuples
match(
  [() => state.value === "loading", () => p("Loading…")],
  [() => state.value === "error",   () => p("Failed")],
  [() => state.value === "data",    () => ul(/* … */)],
);
```

If your branches all dispatch on the same signal's value and writing the predicates is tedious, a `switch` inside a getter child is the better fit — see [What `match()` isn't](https://whisq.dev/api/match/#what-match-isnt) for when each form applies.

## `match()` at a component's root (pre-alpha.9 only)

**Symptom** *(pre-alpha.9 only)*. A component whose entire job was to branch wouldn't mount — `WhisqStructureError` thrown at first render, or a TypeScript complaint that the `component()` setup return type didn't match `WhisqNode`.

**Status.** **Fixed in alpha.9** (release-note `e6d59c4`). `component()`'s setup return type was widened from `WhisqNode` to `WhisqNode | (() => unknown)`, so `component(() => match(...))` works directly — no wrapper element needed. See [`/api/component/#function-child-root-since-alpha9`](https://whisq.dev/api/component/#function-child-root-since-alpha9) for the canonical new shape.

```ts
// alpha.9+ — function-child root is the component root, no wrapper needed
const StatusView = component(() =>
  match(
    [() => loading.value, () => Spinner({})],
    [() => !!error.value, () => ErrorPanel({ err: error.value })],
    () => DataView({}),
  ),
);
```

If you're on **alpha.8 or earlier**, the fix is still to wrap in a neutral element:

```ts
// pre-alpha.9 workaround — wrap in an element
const StatusView = component(() =>
  div(
    match(
      [() => loading.value, () => Spinner({})],
      [() => !!error.value, () => ErrorPanel({ err: error.value })],
      () => DataView({}),
    ),
  ),
);
```

The wrapping-element shape remains valid in alpha.9+ too — reach for it when the root needs class / style / events attached. See [Using `match()` as a component root](https://whisq.dev/api/match/#using-match-as-a-component-root) for the decision.

## `bindField` write throws `WhisqKeyByError` on a removed item

**Symptom.** In dev (since alpha.8), a `WhisqKeyByError` thrown after the user clicks a checkbox or edits a field on a row that was just removed from the source array — or whose `keyBy` returns a different value at write time than at read time:

```
WhisqKeyByError: bindField: no item in source matched key … for write to "done"
  sourceKeys: [...]   // what was actually present at write time
  targetKey: ...      // what bindField was looking for
  field: "done"
```

**Why.** `bindField` identifies which item to rewrite via `keyBy` (default `t => t.id`). If the item was removed from `source` between render and the user's interaction, or `keyBy` returns inconsistent results (e.g. mutates the read key), the write has nothing to rewrite. Pre-alpha.8 silently warned and discarded the write; alpha.8 surfaces it as a `WhisqKeyByError` so the bug is visible at the first failed click instead of drowning in the console.

**Fix.** Two paths:

- **Real bug** — make sure the row removal also clears any references that hold the stale accessor (avoid retained closures pointing at the removed `todo`). Make `keyBy` deterministic: read the same field both ways.
- **Deliberate test path** — pass `strict: false` on the call to suppress the throw and keep the legacy warn-and-discard behaviour:

```ts
input({
  ...bindField(todos, todo, "done", { as: "checkbox", strict: false }),
});
```

See [`/api/bindfield/#dev-mode-behaviour-and-the-strict-option`](https://whisq.dev/api/bindfield/#dev-mode-behaviour-and-the-strict-option) for the full `strict` matrix and the `WhisqKeyByError` field reference.

---

## Inline `signal()` creation inside a reactive render

**Symptom.** Local state resets to its initial value on every change. Effects seem to run too often.

**Why.** Creating a signal inside a getter, element callback, or `each()` render callback means a new signal instance is constructed each time the surrounding function re-evaluates. The old signal's subscribers are dropped, and the new signal has no history.

**Fix.** Hoist signal creation to module scope or component setup.

```ts
// ❌ new signal every time the getter re-evaluates
div(() => {
  const hovered = signal(false);  // reset on every re-evaluation!
  return span({ onmouseenter: () => hovered.value = true }, "Hello");
})

// ✅ signal lives in component setup — stable across re-evaluations
const Tooltip = component(() => {
  const hovered = signal(false);
  return div(span({ onmouseenter: () => hovered.value = true }, "Hello"));
});
```

## Theme variables flipped unexpectedly after merge

**Symptom.** CSS custom properties (`--color-primary`, `--space-md`, etc.) stopped matching the theme you set in `src/styles.ts`. Dev since alpha.9 prints a `console.warn` naming the duplicate `theme()` call.

**Why.** `theme()` is last-call-wins — the second call replaces the first `<style>` block entirely. This is intentional for theme-switching, but if a second `styles.ts` sneaks into the import graph (a new `components/styles.ts`, an accidentally-imported stylesheet from a dependency, a duplicate file after a merge), it silently wipes the original tokens.

**Fix.** Search for all `theme(` call sites:

```bash
rg "theme\(" src/
```

Keep **one** call at module scope in your canonical `src/styles.ts`. Delete duplicates (or merge them into the canonical file). If a duplicate *is* intentional (a theme-switching toggle), pass `{ silent: true }` to opt out of the warning:

```ts
// Intentional runtime theme switch
const enableDark = () => theme(darkTokens, { silent: true });
```

Production builds strip the whole duplicate-detection guard, so this is a dev-time safety net with zero shipped cost. See [`/api/theme/#duplicate-call-warning-since-alpha9`](https://whisq.dev/api/theme/#duplicate-call-warning-since-alpha9) for the framework-side mechanism.

---

## See also

- [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) — four positions × which shape applies.
- [Getters and accessors](https://whisq.dev/core-concepts/signals/#getters-and-accessors) — glossary definitions.
- [`/api/each/#reactive-fields-inside-keyed-each`](https://whisq.dev/api/each/#reactive-fields-inside-keyed-each) — the position-based rule for snapshot vs getter in lists.
- [`/core-concepts/signals/`](https://whisq.dev/core-concepts/signals/) — how reactivity tracks and re-runs.

---
# Choosing Patterns
URL: https://whisq.dev/core-concepts/choosing-patterns/
---

Each table answers one "which primitive should I reach for?" question. Each row is one paragraph at most — depth lives in the linked API pages.

For the four-shape **reactive-position** taxonomy (getter child / getter prop / `bind()` spread / `bindField()` spread), see the [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one). The tables below cover everything else.

## Two-way binding — which helper?

The default decision when you wire an input to state.

| Situation | Helper | Why |
|---|---|---|
| One signal, one input | [`bind(signal)`](https://whisq.dev/api/bind/) | The dedicated primitive. Same discriminator (`as`) for text / number / checkbox / radio. |
| A field of an item inside a keyed `each()` | [`bindField(source, item, key, …)`](https://whisq.dev/api/bindfield/) | Accepts the keyed-`each()` accessor; produces immutable array writes; no manual event pair. |
| A field at a nested path inside a single record signal | [`bindPath(source, ['a', 'b'], …)`](https://whisq.dev/api/bindpath/) (sub-path: `@whisq/core/forms`) | Reaches deep object paths that `bind()` can't address. |
| The item field is itself a `Signal` (per-item nested signals) | `bind(item.value.field, …)` | The signal drives its own reactivity; treat it as the "one signal" case. |
| Custom write logic / derived field / debouncing | Manual `value`/`oninput` (or `checked`/`onchange`) pair | Escape hatch. Reach for it only when none of the above fit. |

For the deeper "plain object vs nested signals vs extracted child component" decision, see the [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/) — that's a thicker pedagogical page.

## List rendering — when to split into a child component?

| Situation | Reach for | Why |
|---|---|---|
| Per-row render is ≤ 12 lines, used in one place | Inline `each(() => arr.value, (todo) => li(…), { key })` | Don't pay for a file boundary you don't need. |
| Per-row render is > 12 lines, or reused in two places | Extracted child component with `todo: ItemAccessor<T>` typed prop | Shorter parent file; reusable. See [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component). |
| Items have stable identities | `each(…, { key: (t) => t.id })` | LIS-based diffing; preserves DOM state across reorders. |
| Items have no stable identity (computed on the fly) | Non-keyed `each(…, render)` | Re-creates DOM nodes on every change. Fine for short lists. |
| Items are `< ~20`, rarely change | Inline `() => arr.value.map(t => li(t))` | Cheapest shape; `.map()` re-renders the whole list but at this size that's invisible. |

## Persistence — which shape?

Three patterns by data shape. Full code lives in [Persistence Recipes](https://whisq.dev/guides/state-management/#recipes-by-data-shape).

| What you have | Reach for | Quick reason |
|---|---|---|
| Plain JSON-serializable items | [`persistedSignal<T[]>("key", [])`](https://whisq.dev/api/persistedsignal/) | One import, no helper. Default. |
| Items with nested per-field `Signal`s (`done: Signal<boolean>`) | Hand-rolled `loadTodos()` + `effect()` + `signal<Todo[]>` | `JSON.stringify` can't round-trip `Signal`s. |
| Server-derived data with a freshness cache | `resource()` + `persistedSignal()` (initialValue: cache.value) | Server owns truth; cache warms first paint. |
| State > a few MB | Custom IndexedDB integration with `signal()` + `effect()` | LocalStorage quotas vary; reach for IndexedDB. |

## Conditional rendering — `when()`, `match()`, or inline ternary?

| Situation | Reach for | Why |
|---|---|---|
| One reactive condition, one branch (show/hide) | [`when(() => cond, () => Block)`](https://whisq.dev/api/when/) | Simplest. Falsy branch renders nothing. |
| Two distinct branches | `when(() => cond, () => A, () => B)` | Two-arg form is fine. Don't escalate to `match()` for two cases. |
| 3+ mutually-exclusive branches (loading / error / data, etc.) | [`match([pred, render], …, fallback)`](https://whisq.dev/api/match/) | First-true-wins; trailing fn is the fallback. |
| A switch on a discriminator value | `match([() => state.kind === 'a', …], …)` | One predicate per kind. |
| Inline text-vs-text ternary (`a > b ? "yes" : "no"`) | Plain getter — `() => a.value > b.value ? "yes" : "no"` | `when()` / `match()` are for nodes, not values. |

## Reactive class composition — array form, `cx`, or `rcx`?

Since alpha.8, the array form on `class:` covers most cases. `cx` / `rcx` are escape hatches.

| Situation | Reach for | Why |
|---|---|---|
| Mix of static class + reactive toggles on an element | Array form: `class: ["btn", () => loading.value && "btn-loading"]` (alpha.8) | Strings, falsy shorthands, reactive getters in one prop. No separate helper. |
| Composing class names outside an element prop (e.g. returning a string from a utility) | [`cx("a", b && "c", { d: true })`](https://whisq.dev/api/cx/) | Static composition; returns `string`. |
| Composing reactive class names outside an element prop | [`rcx("a", () => b.value && "c")`](https://whisq.dev/api/rcx/) | Reactive composition; returns `() => string`. |
| Single class that depends on one signal | `class: () => active.value ? "on" : "off"` | Plain getter. Simplest. |

## Sub-renderer — plain factory or `component()`?

Within a file, the micro-decision: is this tiny sub-renderer a component or just a function?

| The sub-renderer has… | Reach for | Why |
|---|---|---|
| No state, no lifecycle, ≤ ~10 lines | **Plain factory** `const FilterBtn = (...) => button(...)` | A function returning element markup is first-class. No fragment, no setup scope. |
| Local `signal()` or any `effect()` | [`component()`](https://whisq.dev/api/component/) | A factory runs once per call site; setup scope requires `component()`. |
| `onMount` / `onCleanup` / `inject()` | [`component()`](https://whisq.dev/api/component/) | Lifecycle hooks and context reads only fire in `component()` setup. |
| Reused across files (PascalCase export) | [`component()`](https://whisq.dev/api/component/) | Named boundaries deserve a definition, not an inline factory. |

The promotion rule: **add `signal()` / `effect()` / lifecycle → promote to `component()`**. See [Components → "Is this a component or just a function?"](https://whisq.dev/core-concepts/components/#is-this-a-component-or-just-a-function) for worked examples.

## See also

- [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) — the four-shape "where does the signal go" taxonomy.
- [Nested Item Editing](https://whisq.dev/guides/nested-item-editing/) — deeper decision tree for editing a field inside a keyed list.
- [Persistence Recipes](https://whisq.dev/guides/state-management/#recipes-by-data-shape) — full code for the three persistence shapes.
- [Common Mistakes](https://whisq.dev/common-mistakes/) — symptom-first debugging when a pattern doesn't behave.

---
# Components
URL: https://whisq.dev/core-concepts/components/
---

Components encapsulate state, logic, and UI into reusable units.

## Defining a Component

```ts

const Counter = component((props: { initial?: number }) => {
  const count = signal(props.initial ?? 0);

  return div({ class: "counter" },
    button({ onclick: () => count.value-- }, "-"),
    span(() => ` ${count.value} `),
    button({ onclick: () => count.value++ }, "+"),
  );
});
```

The setup function runs **once**. It receives props and returns a WhisqNode.

## Using Components

```ts
Counter({ initial: 10 })

mount(Counter({ initial: 0 }), document.getElementById("app")!);
```

## Composition

```ts
const App = component(() => {
  return div(
    header(h1("My App")),
    main(
      Counter({ initial: 0 }),
      Counter({ initial: 100 }),
    ),
  );
});
```

## Props and reactivity

Setup runs **once** per component instance. Whatever props the component receives at that moment are captured for the rest of its lifetime — they are **not** reactive by default.

If you come from React, Vue, or Svelte, this is the most important rule to internalise: passing a plain `signal.value` from a parent does **not** make the child re-read it later.

### Wrong vs. right

Given a shared signal in a store file:

```ts
// stores/counter.ts
```

```ts
// ❌ Wrong — reads count.value once at the call site;
// Display shows the initial number forever

const Display = component((props: { value: number }) => {
  return p(() => `Count: ${props.value}`);  // never updates
});

Display({ value: count.value });
```

```ts
// ✅ Right — pass a getter; the child re-reads on every change

const Display = component((props: { value: () => number }) => {
  return p(() => `Count: ${props.value()}`);  // updates on every change
});

Display({ value: () => count.value });
```

The rule of thumb:

> **If the value can change after setup, pass a [getter](https://whisq.dev/core-concepts/signals/#getters-and-accessors) (`() => signal.value`) and call it in the child.**

### When static props are fine

Plain (non-getter) props are the right choice when the value will never change for the life of this component instance:

- **Initial values** — `Counter({ initial: 10 })`. The child seeds a signal from this once.
- **Stable callbacks** — `Button({ onclick: handleClick })` when `handleClick` is defined at module scope or in an outer closure that the parent never needs to swap. If the parent ever needs to change which function the child uses (e.g. permission-gated handlers), pass a getter.
- **Identifiers** — `User({ id: "u_123" })`, `Form({ name: "signup" })`.
- **Type / variant flags chosen at construction time** — `Card({ variant: "compact" })` when the variant is decided when the parent renders the child and never reassigned.

When in doubt: if a parent might want to change the value later and have the child reflect it, use a getter. If the value is set at instantiation and forgotten, pass it plain.

### Why it works this way

- The setup function runs once and never re-runs — there is no "render lifecycle" to re-feed props into.
- Reactivity flows through signals, computeds, and effects you create in setup. Wrapping a prop access in a getter (`() => props.value`) makes that read participate in the same reactive graph as everything else.
- `onMount` fires once, after the component is attached. There is no per-update hook because the setup body is the only "render."

## Context (provide/inject)

Pass data deeply without prop drilling:

```ts

const ThemeCtx = createContext("light");

const Parent = component(() => {
  provide(ThemeCtx, "dark");
  return div(Child({}));
});

const Child = component(() => {
  const theme = inject(ThemeCtx); // "dark"
  return p(`Theme: ${theme}`);
});
```

## Error Boundaries

Catch errors in child rendering:

```ts

errorBoundary(
  (error, retry) => div(
    p(`Error: ${error.message}`),
    button({ onclick: retry }, "Retry"),
  ),
  () => RiskyComponent({}),
)
```

See [Advanced → Error Boundaries](https://whisq.dev/advanced/error-boundaries/) for what the primitive catches, granular wrapping, error reporting, and how it composes with `resource()`.

## Is this a component or just a function?

Once a file grows past a single view, you hit a micro-decision several times per file: *"this tiny sub-renderer — do I wrap it in `component(() => ...)`, or just write a plain function that returns element markup?"* The rule:

> Use `component()` when the thing has setup logic, lifecycle hooks, context reads, or is a named reusable boundary. Otherwise write a plain factory — a function that returns element markup.

### Decision table

| Is the sub-renderer… | Reach for | Example |
|---|---|---|
| Pure markup with props, no state, used locally | Plain factory | `const FilterBtn = (value: string, label: string) => button({ onclick: () => filter.value = value }, label)` |
| Has own local `signal()` / `effect()` / refs | `component()` | `component(() => { const open = signal(false); return details({ open: () => open.value }, ...) })` |
| Needs `onMount` / `onCleanup` | `component()` | Anything subscribing to an external source, timer, observer |
| Reads `inject()` from context | `component()` | Components that consume a `ThemeCtx` / `AuthCtx` |
| Reused across files (PascalCase export) | `component()` | The canonical "one component per file" case |
| Reused on the same page only, ≤ 10 lines | Plain factory | Filter buttons, footer rows, trivial sub-views |

### Worked examples

**Plain factory** — stateless, structural, no lifecycle:

```ts
// components/Footer.ts — four filter buttons, each 3 lines of structure
const FilterBtn = (value: "all" | "active" | "done", label: string) =>
  button(
    { class: [s.filterBtn, () => filter.value === value && s.filterActive],
      onclick: () => (filter.value = value) },
    label,
  );

```

No `component()` wrapper on `FilterBtn` — it's structured markup with props, no setup. Wrapping would add noise and a fragment boundary you don't need.

**Promoted to `component()`** — same sub-renderer grows local state:

```ts
// Now FilterBtn tracks hover state locally — promote to component()
const FilterBtn = component((props: { value: "all" | "active" | "done"; label: string }) => {
  const hover = signal(false);
  return button(
    {
      class: [
        s.filterBtn,
        () => filter.value === props.value && s.filterActive,
        () => hover.value && s.filterHover,
      ],
      onmouseenter: () => (hover.value = true),
      onmouseleave: () => (hover.value = false),
      onclick: () => (filter.value = props.value),
    },
    props.label,
  );
});
```

The moment `hover` enters the picture, the factory form can't express it — a plain function runs once per call, so a `signal()` inside would reset on every render. `component()` gives each call its own setup scope. This is the promotion rule: **add `signal()` → promote to `component()`**.

**Cross-file named component** — the top-of-file-split shape:

```ts
// components/TodoItem.ts — reused from multiple parents, deserves its own file

type Props = { todo: ItemAccessor<Todo>; onRemove: (id: string) => void };

```

When a reviewer asks *"is this a component?"* the answer is: yes if it has setup / lifecycle / context / reuse-across-files; no otherwise. A plain factory is a first-class citizen — don't reach for `component()` reflexively.

See also: [Choosing Patterns → List rendering](https://whisq.dev/core-concepts/choosing-patterns/#list-rendering--when-to-split-into-a-child-component) for the split-to-own-file decision at the file level, and [Nested Item Editing guide](https://whisq.dev/guides/nested-item-editing/) for the per-row decision.

## Next Steps

- [Styling](https://whisq.dev/core-concepts/styling/) — Scoped CSS-in-JS
- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — onMount, onCleanup, resource

---
# Conditional Rendering
URL: https://whisq.dev/core-concepts/conditional-rendering/
---

Whisq has two primitives for conditional rendering:

- **`when()`** — for a single two-branch decision: show this, or show that.
- **`match()`** — for three or more branches picked by predicate.

Function children (a bare `() => ...` returning a node or `null`) remain available for inline one-offs, but for the common three-way shapes (loading / error / data, idle / invalid / valid, empty / filtered-empty / list), reach for `match()`.

## `when()` — two-branch conditional

```ts

const loggedIn = signal(false);

div(
  when(() => loggedIn.value,
    () => p("Welcome back!"),
    () => button({ onclick: login }, "Sign In"),
  ),
);
```

The third argument (`otherwise`) is optional — omit it to render nothing on the false branch:

```ts
when(() => showBanner.value,
  () => div({ class: "banner" }, "Notice!"),
);
```

## `match()` — three or more branches

`match()` evaluates branches in order and renders the first whose predicate returns truthy. An optional trailing fallback (a bare render function, not wrapped in a tuple) renders when no branch matches. Re-evaluates reactively like any other child.

```ts

const users = resource(() => fetch("/api/users").then((r) => r.json()));

div(
  match(
    [() => users.loading(),   () => p("Loading…")],
    [() => !!users.error(),   () => div(
      p(() => `Error: ${users.error()!.message}`),
      button({ onclick: () => users.refetch() }, "Retry"),
    )],
    [() => !!users.data(),    () => ul(each(() => users.data()!, (u) => li(u.name)))],
    () => p("No data yet."),  // fallback
  ),
);
```

The loading/error/data tri-state on a `resource()` is the canonical case — it's what `match()` was added for, and it's the pattern `/guides/data-fetching/` leads with. Any time you find yourself chaining three or more `when()`s against states of the same thing, reach for `match()`.

### First-true-wins

If two predicates are both true at the same time, only the earlier branch renders:

```ts
match(
  [() => count.value > 10,  () => p("More than ten")],
  [() => count.value > 0,   () => p("Some")],     // skipped when count > 10
  () => p("None"),
);
```

Order your branches from most-specific to most-general.

### Fallback

A trailing bare render function (no tuple) fires when no predicate matches:

```ts
match(
  [() => status.value === "ok",     () => p("All good")],
  [() => status.value === "warn",   () => p({ class: "warn" }, "Heads up")],
  () => p("Unknown status"),  // fires when status is anything else
);
```

Omit the fallback to render nothing when no branch matches — like `when()` without its `otherwise`.

## Inline — function child

For a one-off inline branch where a named variable or a full `when()` call would be overkill, a bare function child returning a node or `null` is still idiomatic:

```ts
div(
  () => isError.value
    ? p({ class: "error" }, "Something broke")
    : null,
);
```

Use this when the predicate is trivial and the rendered branch is a one-liner. For anything beyond that — especially three or more outcomes — use `match()`.

## Rendering nothing

Return `null` from any render function to render nothing:

```ts
div(
  () => showMessage.value ? p("Visible!") : null,
);
```

Both `when()` and `match()` already handle this for you — if the matching branch returns `null`, nothing is rendered.

## Next Steps

- [List Rendering](https://whisq.dev/core-concepts/list-rendering/) — `each()` for arrays, with keyed reconciliation.
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — `resource()` and the canonical `match()` tri-state.
- [API — when()](https://whisq.dev/api/when/) — reference.

---
# Elements
URL: https://whisq.dev/core-concepts/elements/
---

In Whisq, every HTML element is a function. No JSX, no templates — just function calls with full TypeScript support.

## Basic Usage

```ts

// With props + children
div({ class: "card", id: "main" },
  h1("Title"),
  p("Content"),
)

// Without props — just children
div(
  h1("Title"),
  p("Content"),
)

// Single text child
h1("Hello Whisq")
button("Click me")
```

The first argument is either a **props object** or a **child**. Whisq detects which automatically.

## Available Elements

Every standard HTML tag has a function:

**Layout:** `div`, `span`, `main`, `section`, `article`, `aside`, `header`, `footer`, `nav`

**Text:** `h1`–`h6`, `p`, `strong`, `em`, `small`, `pre`, `code`

**Interactive:** `button`, `a`

**Forms:** `form`, `input`, `textarea`, `select`, `option`, `label`

**Lists:** `ul`, `ol`, `li`

**Table:** `table`, `thead`, `tbody`, `tr`, `th`, `td`

**Media:** `img`, `video`, `audio`

**Misc:** `br`, `hr`, `iframe`

## Reactive Props

Pass a function for any prop to make it reactive:

```ts

const active = signal(false);
const color = signal("blue");
const visible = signal(true);

// Reactive class — single getter form
div({ class: () => active.value ? "card active" : "card" },
  span("Content"),
)

// Reactive style
div({ style: () => `color: ${color.value}` }, "Styled text")

// Reactive visibility
div({ hidden: () => !visible.value }, "Now you see me")
```

### `class:` array form (since alpha.8)

For composing class names from a mix of static strings, conditional shorthands, and reactive getters, pass an **array** to `class:`. Strings are kept; falsy values (`false | null | undefined | 0 | ""`) are filtered out; functions are reactive — each one re-runs when its tracked signals change.

```ts

const variant = signal<"primary" | "secondary">("primary");
const loading = signal(false);
const isDisabled = signal(false);

div({
  class: [
    "btn",                                          // static
    () => `btn-${variant.value}`,                   // reactive
    loading.value && "btn-loading",                 // static conditional shorthand
    () => isDisabled.value && "disabled",           // reactive conditional
  ],
});
```

If any array element is a function, the whole array is applied reactively; otherwise it's applied once at mount. This eliminates the cx-vs-rcx decision for most cases — reach for [`cx`](https://whisq.dev/api/cx/) / [`rcx`](https://whisq.dev/api/rcx/) only when you need to compose class strings outside an element prop.

### ARIA attributes (since alpha.9)

Typed `aria-*` props on every element. Like `data-*`, but with a wider type — ARIA mixes enum-string attrs (`aria-live: "polite"`) with predicate-boolean attrs (`aria-expanded`, `aria-hidden`, `aria-pressed`).

```ts

const menuOpen = signal(false);
const status = signal("Ready");

// Static
button({ "aria-label": "Remove" }, "×");

// Reactive
button({ "aria-expanded": () => menuOpen.value }, "Menu");
div({ "aria-live": "polite", "aria-atomic": true }, () => status.value);
```

`true` / `false` serialise to the strings `"true"` / `"false"` (correct per ARIA spec); `undefined` / `null` removes the attribute. See [`/api/elements/#aria-attributes-since-alpha9`](https://whisq.dev/api/elements/#aria-attributes-since-alpha9) for the full table and the pre-alpha.9 boolean-serialisation fix.

## Events

Events use `on*` props with function handlers:

```ts
button({ onclick: () => count.value++ }, "Click me")
input({ oninput: (e) => name.value = e.target.value })
form({ onsubmit: (e) => { e.preventDefault(); save(); } },
  // form children
)
```

All standard DOM events are supported: `onclick`, `oninput`, `onchange`, `onsubmit`, `onkeydown`, `onmouseenter`, `onfocus`, `onblur`, etc.

:::danger[Common Mistake]
```ts
// ❌ WRONG — string event handlers are blocked (XSS vector)
button({ onclick: "doSomething()" })

// ✅ RIGHT — use a function
button({ onclick: () => doSomething() })
```
:::

## Reactive Children

Pass a function as a child to make it reactive:

```ts
const name = signal("World");

div(
  // Static child — never changes
  h1("Hello"),
  // Reactive child — updates when `name` changes
  p(() => `Welcome, ${name.value}!`),
)
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — static value, never updates
span(count.value)

// ✅ RIGHT — function wrapper, updates reactively
span(() => count.value)
```
:::

## h() — Low-Level Element Creation

For dynamic tag names or custom elements:

```ts

h("custom-element", { class: "foo" }, "content")
h("details", { open: true }, h("summary", {}, "Click"), "Hidden content")
```

## ref — Direct DOM Access

Access the underlying DOM element via the `ref` prop:

```ts

const inputRef = signal<HTMLInputElement | null>(null);

input({ ref: inputRef, type: "text" })

// Later: inputRef.value?.focus()
```

Or with a callback:

```ts
input({
  ref: (el) => el?.focus(),
  type: "text",
})
```

## mount() — Attach to DOM

Mount a WhisqNode into a DOM container:

```ts

const dispose = mount(
  div("Hello Whisq"),
  document.getElementById("app")!,
);

// Later: dispose() to unmount and clean up
```

## Next Steps

- [Components](https://whisq.dev/core-concepts/components/) — Encapsulate elements in reusable components
- [Styling](https://whisq.dev/core-concepts/styling/) — Scoped CSS with `sheet()` and `styles()`

---
# Lifecycle
URL: https://whisq.dev/core-concepts/lifecycle/
---

## onMount() — After DOM Insertion

Runs after the component mounts. Return a cleanup function:

```ts

const Timer = component(() => {
  onMount(() => {
    const id = setInterval(() => tick(), 1000);
    return () => clearInterval(id);
  });

  return div("Timer running...");
});
```

## onCleanup() — Before Unmount

Register cleanup that runs when the component is removed:

```ts

const Sub = component(() => {
  const sub = eventBus.subscribe(handler);
  onCleanup(() => sub.unsubscribe());
  return div("Listening...");
});
```

## resource() — Async Data

```ts

const users = resource(() =>
  fetch("/api/users").then(r => r.json())
);

div(
  when(() => users.loading(), () => p("Loading...")),
  when(() => !!users.error(), () =>
    p(() => `Error: ${users.error()!.message}`),
  ),
  when(() => !!users.data(), () =>
    ul(each(() => users.data()!, (u) => li(u.name)))
  ),
)
```

**API:** `r.data()`, `r.loading()`, `r.error()`, `r.refetch()`

## useHead() — Document Head

Reactively manage title and meta tags:

```ts

const App = component(() => {
  const page = signal("Home");
  useHead({
    title: () => `${page.value} — My App`,
    meta: [{ name: "description", content: "A Whisq app" }],
  });
  return div("Content");
});
```

Tags auto-remove on unmount.

## Summary

| Hook | When | Use For |
|------|------|---------|
| `onMount()` | After DOM insert | Timers, DOM access, subscriptions |
| `onCleanup()` | Before unmount | Unsubscribe, clear timers |
| `resource()` | Immediately (async) | Data fetching |
| `useHead()` | During setup | Document title, meta tags |

## Next Steps

- [API Reference](https://whisq.dev/api/signal/) — Complete API documentation
- [Guides](https://whisq.dev/guides/forms/) — Practical how-to guides

---
# List Rendering
URL: https://whisq.dev/core-concepts/list-rendering/
---

## Simple Lists with .map()

```ts

const items = signal(["Apple", "Banana", "Cherry"]);

ul(
  () => items.value.map(item => li(item))
)
```

## each() — Efficient Keyed Lists

For large or frequently-changing lists, `each()` with a key function reuses DOM nodes. In keyed mode the render callback receives **hybrid accessors** (`ItemAccessor<T>`) — read via `todo.value` (canonical since alpha.8), `todo()` (legacy call form), or `todo.peek()` (read without subscribing). All three return the current item. See [`/api/each/`](https://whisq.dev/api/each/) for the full type and four-archetype reactivity rule.

```ts

const todos = signal([
  { id: 1, text: "Learn Whisq" },
  { id: 2, text: "Build an app" },
]);

ul(
  each(
    () => todos.value,
    (todo) =>
      li(
        span(todo.value.text),                                 // snapshot read
        button({ onclick: () => remove(todo.value.id) }, "x"), // fresh read at click
      ),
    { key: (t /* value, not accessor */) => t.id },
  ),
)
```

Non-keyed `each()` is unchanged: the callback still receives `(item: T, index: number)`. The accessor shape only applies when you pass `{ key }`. The `key:` callback receives the **value** (not the accessor) — same in both shapes.

## When to Use Which

| Approach | Use When |
|----------|----------|
| `.map()` | Small lists, rarely changing |
| `each()` without key | Medium lists, index identity |
| `each()` with key | Large lists, reorderable items |

:::tip[🐱 Whisker Tip]
Always use `each()` with a key when items have a stable identity. This preserves DOM state (focus, scroll, animations) across updates.
:::

:::danger[Common Mistake]
```ts
// ❌ WRONG — mutating won't trigger updates
items.value.push(newItem);

// ✅ RIGHT — create a new array
items.value = [...items.value, newItem];
```

See [Common Mistakes](https://whisq.dev/common-mistakes/) for the full debugging reference.
:::

## Next Steps

- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — Hooks for mount, cleanup, async data
- [Nested Item Editing](https://whisq.dev/guides/nested-item-editing/) — three canonical patterns for editing a field on one row (decision matrix + worked examples)

---
# How Reactivity Works
URL: https://whisq.dev/core-concepts/reactivity-model/
---

A picture and five questions for the chain that turns a `count.value = x` write into a repainted `<span>`. Read this once and the rest of the docs snap into place.

## The signal-flow diagram

```text
                        ┌──────────────────────────────┐
                        │   signal.value = newValue    │
                        └─────────────┬────────────────┘
                                      ▼
                          ┌───────────────────┐
                          │ Object.is(old,new)?│
                          └────┬─────────┬────┘
                          equal│         │different
                               ▼         ▼
                          (no-op)   ┌─────────────────┐
                                    │ notify subscribers │
                                    └─┬──────┬──────┬─┘
                                      │      │      │
                            ┌─────────┘      │      └────────────┐
                            ▼                ▼                   ▼
                  ┌──────────────────┐ ┌──────────────┐ ┌────────────────────┐
                  │  effect re-runs  │ │  computed    │ │  getter (child or  │
                  │  side effects    │ │  marks stale │ │  prop) re-runs;    │
                  │  fire            │ │  → recomputes│ │  patches that one  │
                  │                  │ │  on next read│ │  DOM position only │
                  └──────────────────┘ └──────────────┘ └────────────────────┘
```

**No top-down re-render.** Whisq doesn't diff a virtual tree. Each subscriber is wired directly to the signals it read, and only those subscribers fire when their signals change. A keystroke that updates one signal patches one DOM position — the rest of the tree is untouched.

## Five questions

### 1. What triggers tracking?

Reading `.value` (or calling an [accessor](https://whisq.dev/core-concepts/signals/#getters-and-accessors) like `users.data()`) **inside a reactive scope** registers a subscription. The signal stores a reference to the active subscriber; the subscriber stores a reference back to the signal so it can clean up.

Reading outside any reactive scope is just a value read — no subscription, no re-evaluation. Use `signal.peek()` to read inside a reactive scope without registering as a dependency.

### 2. What's a "reactive scope"?

The currently-running effect, computed body, or getter passed as a child / prop. Whisq maintains an active-subscriber stack while these run; tracked reads add the signal → current subscriber link.

The four positions that establish reactive scope:

| Position | Form | Notes |
|---|---|---|
| Effect body | `effect(() => { ... })` | Re-runs when any read signal changes |
| Computed body | `computed(() => ...)` | Lazy — only re-runs on read after a dependency changed |
| Getter child | `span(() => count.value)` | Re-runs and patches the text node |
| Getter prop | `div({ class: () => ... })` | Re-runs and patches that one prop |

Non-keyed `each()` render callbacks are **builder functions** invoked fresh on every source change — they run inside the same reactive scope as the `each()` itself, not in a per-item effect. Only getters you explicitly write inside the returned nodes establish reactive positions. (Keyed `each()` is different — see Question 5.)

### 3. What triggers re-execution?

Only **signals that changed**, and only **their subscribers**. There's no top-down render pass. Each subscriber re-runs once in response to its dependency change; if `batch()` is active, the re-runs queue and flush at the end of the batch.

### 4. When does `batch()` matter?

Multiple synchronous writes to different signals — without `batch()`, each write triggers its subscribers immediately. Subscribers that read more than one of the writes will run more times than necessary.

```ts
// ❌ effect runs twice
firstName.value = "Grace";  // effect runs (sees "Grace" + old lastName)
lastName.value = "Hopper";  // effect runs again (sees "Grace" + "Hopper")

// ✅ effect runs once
batch(() => {
  firstName.value = "Grace";
  lastName.value = "Hopper";
});                         // effect runs once at flush (sees "Grace" + "Hopper")
```

Single writes don't need `batch()`. When an event handler writes to multiple signals, **each write notifies its subscribers immediately** — Whisq does not auto-batch event handlers. Wrap all the writes in `batch()` if you want them to flush as a group.

### 5. How does keyed `each()` fit?

The reconciler maintains per-entry signals (`itemSig`, `indexSig`). Replacing the source array doesn't re-mount items with the same key — the reconciler writes the new item value into `itemSig.value`, which fires any reactive getter that closed over `() => item()`.

```text
                        ┌──────────────────────────┐
                        │ todos.value = newArray   │
                        └────────────┬─────────────┘
                                     ▼
                        ┌──────────────────────────┐
                        │ each() reconciler runs:   │
                        │  - same keys → reuse node │
                        │  - new keys → mount       │
                        │  - missing → unmount      │
                        └────────────┬─────────────┘
                                     ▼
                        ┌──────────────────────────┐
                        │ for each reused entry:    │
                        │   itemSig.value = newItem │
                        └────────────┬─────────────┘
                                     ▼
                        ┌──────────────────────────┐
                        │ getters that closed over  │
                        │ () => todo() see fresh    │
                        │ values — DOM patches      │
                        │ where they are read       │
                        └──────────────────────────┘
```

This is why `() => todo().done` stays live across array replacement — the getter re-reads `todo()`, which calls into the reconciler's `itemSig`, which now holds the new value.

## Component lifecycle

Component setup runs **once**. Reactivity flows through the signals and getters you create in setup, not through re-running setup.

```text
                  ┌────────────────────────────┐
                  │ component(() => { ... })   │
                  │ called as Component({...}) │
                  └─────────────┬──────────────┘
                                ▼
                  ┌────────────────────────────┐
                  │ setup function runs ONCE   │
                  │  - props captured          │
                  │  - signals created         │
                  │  - root element returned   │
                  └─────────────┬──────────────┘
                                ▼
                  ┌────────────────────────────┐
                  │ mounted to DOM             │
                  │  → onMount() callbacks fire│
                  └─────────────┬──────────────┘
                                ▼
                  ┌────────────────────────────┐
                  │ runtime: signal writes →   │
                  │  targeted re-evaluation of │
                  │  effects/computeds/getters │
                  │  that read those signals   │
                  │  (setup does NOT re-run)   │
                  └─────────────┬──────────────┘
                                ▼
                  ┌────────────────────────────┐
                  │ unmounted                  │
                  │  → onCleanup() fires       │
                  │  → effects auto-disposed   │
                  └────────────────────────────┘
```

The "setup runs once" rule is the source of two patterns elsewhere in the docs:

- **Pass getters for changing prop values.** A parent that wants the child to reflect a changing value passes `() => signal.value`, not `signal.value`. The child reads `props.value()` inside a reactive position — `props` is captured at setup, but the function call returns the current value.
- **Don't create signals inside reactive callbacks.** A `signal()` call inside an effect body or element-callback body constructs a new signal every time the callback re-runs, dropping the old one's subscribers. Hoist signal creation to setup or module scope.

## See also

- [Signals](https://whisq.dev/core-concepts/signals/) — the primitives the diagrams refer to.
- [`/api/effect/`](https://whisq.dev/api/effect/) — the effect API. Note: `effect()` runs once on creation, then re-runs when its tracked dependencies change.
- [`/api/batch/`](https://whisq.dev/api/batch/) — when to wrap multiple writes.
- [`/api/each/`](https://whisq.dev/api/each/#reactive-fields-inside-keyed-each) — the keyed-each reconciler in practice.
- [Common Mistakes](https://whisq.dev/common-mistakes/) — what goes wrong when this model is applied incorrectly.

---
# Signals
URL: https://whisq.dev/core-concepts/signals/
---

Signals are Whisq's reactive primitives. They hold values that automatically track dependencies and trigger updates when changed.

## signal() — Reactive State

```ts

const count = signal(0);

count.value;              // 0 — read (triggers dependency tracking)
count.value = 5;          // write (triggers updates)
count.update(n => n + 1); // 6 — update via function
count.peek();             // 6 — read WITHOUT tracking
count.set(10);            // 10 — alias for direct assignment
```

### When to use `peek()`

Use `peek()` inside effects when you need to read a value without creating a dependency:

```ts
effect(() => {
  // Re-runs when `trigger` changes, but NOT when `config` changes
  console.log(trigger.value, config.peek());
});
```

:::tip[🐱 Whisker Tip]
Signals are cheap. Create many small signals rather than one big object signal. This gives you fine-grained reactivity — only the parts that changed re-render.
:::

## computed() — Derived Values

`computed()` creates a read-only signal that auto-updates when its dependencies change:

```ts

const firstName = signal("Ada");
const lastName = signal("Lovelace");
const fullName = computed(() => `${firstName.value} ${lastName.value}`);

fullName.value; // "Ada Lovelace"

firstName.value = "Grace";
fullName.value; // "Grace Lovelace" — auto-updated
```

Computed values are **lazy** — they don't recompute until read. They also **cache** — reading twice without dependency changes returns the cached value.

## effect() — Side Effects

`effect()` runs a function immediately and re-runs it whenever its dependencies change:

```ts

const count = signal(0);

const dispose = effect(() => {
  console.log(`Count is: ${count.value}`);
});
// Logs: "Count is: 0"

count.value = 1;
// Logs: "Count is: 1"

dispose(); // Stop watching
count.value = 2; // No log — effect is disposed
```

### Cleanup Functions

Return a function from an effect to run cleanup before each re-execution:

```ts
effect(() => {
  const timer = setInterval(() => tick(), 1000);
  return () => clearInterval(timer); // cleanup
});
```

### Conditional Dependencies

Effects only track signals read in the current execution:

```ts
const flag = signal(true);
const a = signal("A");
const b = signal("B");

effect(() => {
  // When flag is true, tracks `a` only
  // When flag is false, tracks `b` only
  console.log(flag.value ? a.value : b.value);
});
```

## batch() — Grouped Updates

`batch()` defers effect re-runs until all updates complete:

```ts

const x = signal(0);
const y = signal(0);

effect(() => {
  console.log(`${x.value}, ${y.value}`);
});
// Logs: "0, 0"

batch(() => {
  x.value = 1;
  y.value = 2;
});
// Logs: "1, 2" — only ONCE, not twice
```

Without `batch()`, the effect would run once for `x` and again for `y`.

## subscribe() — Manual Subscriptions

For integrating with external systems:

```ts
const count = signal(0);

const unsub = count.subscribe(value => {
  // Called immediately with current value, then on every change
  externalSystem.update(value);
});

unsub(); // Stop subscribing
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — Object.is equality means same reference = no update
const items = signal([1, 2, 3]);
items.value.push(4); // Mutates array, but reference unchanged — no update!

// ✅ RIGHT — create new array
items.value = [...items.value, 4];
```
:::

## Getters and accessors

Two `() => T` shapes come up constantly in Whisq prose and code. They look structurally identical but fill different roles — which matters because it controls whether *you* need to write the function or whether the framework hands it to you:

- **Getter** — a `() => value` closure **you write** around a read to make it reactive. Whisq evaluates it lazily whenever the surrounding position needs to re-render. You'll see getters in reactive element children, reactive props, computed bodies, effect bodies, `rcx()` args, and anywhere the docs say "pass a getter."

  ```ts
  span(() => count.value)                              // getter child
  div({ class: () => active.value ? "on" : "off" })    // getter prop
  rcx("btn", () => loading.value && "btn-loading")     // getter arg
  ```

- **Accessor** — a `() => T` function **the framework hands to you**. You call it (with parentheses) to read the current value. The framework owns a backing signal; when it updates, anything that reads the accessor inside a getter or reactive position sees the fresh value. You'll see accessors on keyed `each()` callbacks (`todo()`, `index()`) and on `resource()` fields (`users.data()`, `users.loading()`, `users.error()`).

  ```ts
  each(() => todos.value, (todo) => li(todo().text), { key: (t) => t.id })
  //                        ↑ `todo` is an accessor — call it to read the current entry
  //                                                 `key` receives plain T, not an accessor

  const users = resource(() => fetch("/api/users").then(r => r.json()));
  users.data()      // accessor — returns current data or undefined
  users.loading()   // accessor — true while fetching
  ```

**Rule of thumb:** "who wrote the function?" User-written → getter. Framework-supplied → accessor. When you hear "wrap it in a getter" it means you're writing a closure; when you hear "call the accessor" it means the framework gave you the function and you call it.

**Edge case — `rcx()`.** `rcx()` is framework-supplied and returns a `() => string` that lives in a reactive `class` position. Its return value is passed to a getter-shaped slot, so the docs describe it as a "getter function" at the call site even though the framework produced it. The distinction only matters when the framework gives you a function and tells you to *call it to read a value* — that's the accessor pattern. If the framework gives you a function that *the framework itself invokes* at a reactive position, it behaves as a getter.

Signals (`.value`) and plain values are the other two shapes that show up in reactive positions. See the [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) for all four.

## Next Steps

- [How Reactivity Works](https://whisq.dev/core-concepts/reactivity-model/) — The diagram + five questions for the signal → subscriber → DOM update flow.
- [Elements](https://whisq.dev/core-concepts/elements/) — Use signals in reactive UI elements
- [Components](https://whisq.dev/core-concepts/components/) — Encapsulate signals in components

---
# Styling
URL: https://whisq.dev/core-concepts/styling/
---

Four styling tools — all functions, no build step required.

## sheet() — Scoped CSS Classes

```ts

const s = sheet({
  card: {
    padding: "1.5rem",
    borderRadius: "12px",
    background: "#fff",
    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
    "&:hover": { background: "#f5f5f5" },
  },
  title: { fontSize: "1.25rem", fontWeight: 600 },
});

div({ class: s.card },
  h2({ class: s.title }, "Hello"),
  p("World"),
)
```

Classes are auto-scoped (e.g., `wq0_card`). A `<style>` tag is injected automatically.

Nested selectors beyond `&:hover` — pseudo-elements (`&::before`), compound selectors (`&:checked::after`), combinators (`& > span`), attribute selectors (`&[open]`), `@media` / `@supports` / `@container` at-rules — all work. See [`/api/sheet/#supported-nested-selectors`](https://whisq.dev/api/sheet/#supported-nested-selectors) for the full reference with one example per category and documented limitations.

## styles() — Reactive Inline Styles

```ts

const dark = signal(false);

div({
  style: styles({
    padding: "1rem",
    background: () => dark.value ? "#111" : "#fff",
    color: () => dark.value ? "#fff" : "#111",
  }),
}, "Content")
```

## cx() — Static Class Composition

```ts

div({ class: cx("btn", isPrimary && "btn-primary", isLarge && "btn-lg") })
div({ class: cx("card", { active: true, disabled: false }) })
```

## rcx() — Reactive Class Composition

```ts

const variant = signal("primary");

div({
  class: rcx(
    "btn",
    () => variant.value === "primary" && "btn-primary",
    () => loading.value && "btn-loading",
  ),
})
```

## theme() — Design Tokens

```ts

theme({
  color: { primary: "#4386FB", text: "#111827", bg: "#ffffff" },
  space: { sm: "0.5rem", md: "1rem", lg: "1.5rem" },
  radius: { md: "8px", lg: "12px" },
});

// Use in sheet():
const s = sheet({
  card: {
    background: "var(--color-bg)",
    padding: "var(--space-lg)",
    borderRadius: "var(--radius-lg)",
  },
});
```

### Lifecycle: where to call `theme()` and `sheet()`

- **Call `theme()` once, at module scope** in `src/styles.ts`. Import `styles.ts` transitively from `App.ts` so the call runs on first import. The tokens become CSS custom properties on `:root` and stay available everywhere.
- **Duplicate `theme()` calls = last-call-wins.** A second call replaces the first `<style>` block entirely. This is intentional — it enables theme-switching (`theme(lightTokens)` → `theme(darkTokens)` in a toggle handler) without leaking old tokens. **Since alpha.9, dev mode warns on duplicate calls** to catch accidental double-imports; pass `{ silent: true }` on intentional theme-switch calls. See [`/api/theme/#duplicate-call-warning-since-alpha9`](https://whisq.dev/api/theme/#duplicate-call-warning-since-alpha9).
- **`sheet()` can be called per-module** wherever you want scoped styles. Each call returns its own `classMap` and injects its own `<style>` block; calling at module scope (e.g. `const s = sheet({...})` at the top of a component file) keeps the call once-per-module.
- **SSR-safe (since alpha.8).** On the server (`typeof document === "undefined"`):
  - `theme()` is a no-op — no `<style>` tag is written; client hydration applies the theme on mount.
  - `sheet()` returns the in-memory `classMap` so server-rendered HTML can reference correct class names — but skips the DOM injection step. Hydration injects on mount.

  Pre-alpha.8 both threw `ReferenceError: document is not defined`. If your SSR pipeline needs styles inlined into server HTML for first-paint, emit them yourself by walking the returned `classMap` into a `<style>` block in your SSR template.

See [`/api/theme/`](https://whisq.dev/api/theme/) and [`/api/sheet/`](https://whisq.dev/api/sheet/) for the full per-API reference.

## Using External CSS Frameworks

Whisq renders real DOM elements — `div()` produces an actual `<div>`, `button()` produces a `<button>`. Any CSS framework that works with HTML works with Whisq.

### Tailwind CSS

```ts

const count = signal(0);

div({ class: "flex items-center gap-4 p-8 bg-gray-900 rounded-xl" },
  button({
    class: "w-10 h-10 rounded-lg bg-indigo-600 hover:bg-indigo-500 text-white font-bold",
    onclick: () => count.value--,
  }, "-"),
  span({ class: "text-3xl font-mono text-cyan-400" }, () => `${count.value}`),
  button({
    class: "w-10 h-10 rounded-lg bg-indigo-600 hover:bg-indigo-500 text-white font-bold",
    onclick: () => count.value++,
  }, "+"),
);
```

Reactive classes work naturally:

```ts
div({
  class: () => count.value > 0
    ? "text-green-400 font-bold"
    : "text-red-400 font-bold",
}, () => `${count.value}`);
```

### Plain CSS / CSS Modules

Import a CSS file in your entry point and use class names directly:

```ts
// main.ts

div({ class: "card" },
  p({ class: "card-title" }, "Hello"),
);
```

### When to Use What

| Approach | Best for |
|---|---|
| `sheet()` | Component-scoped styles, no external deps |
| `styles()` | Reactive inline styles |
| Tailwind / UnoCSS | Utility-first, rapid prototyping |
| Plain CSS | Existing stylesheets, CSS variables |

You can mix approaches — use `sheet()` for component logic and Tailwind for layout utilities in the same project.

:::tip[🐱 Whisker Tip]
Whisq's `sheet()` and external CSS frameworks are not mutually exclusive. Use `cx()` to combine them: `cx(s.card, "p-4 mx-auto")`.
:::

## Next Steps

- [Conditional Rendering](https://whisq.dev/core-concepts/conditional-rendering/) — Show/hide UI reactively

---
# Counter
URL: https://whisq.dev/examples/counter/
---

The counter is the "hello world" of UI frameworks. In Whisq, it's 12 lines of code.

## What You'll Build

A counter with increment, decrement, and reset buttons. The count updates reactively — no manual DOM manipulation.

## Full Source

```ts

const Counter = component((props: { initial?: number }) => {
  const count = signal(props.initial ?? 0);

  return div({ class: "counter" },
    button({ onclick: () => count.value-- }, "-"),
    span({ class: "count" }, () => ` ${count.value} `),
    button({ onclick: () => count.value++ }, "+"),
    button({ onclick: () => count.value = 0 }, "Reset"),
  );
});

mount(Counter({ initial: 0 }), document.getElementById("app")!);
```

## How It Works

**1. Create reactive state**

```ts
const count = signal(props.initial ?? 0);
```

`signal(0)` creates a reactive value. Reading `count.value` tracks the dependency. Writing to it triggers UI updates.

**2. Build the UI with element functions**

```ts
div({ class: "counter" },
  button({ onclick: () => count.value-- }, "-"),
  span({ class: "count" }, () => ` ${count.value} `),
  button({ onclick: () => count.value++ }, "+"),
);
```

Each HTML element is a function. The first argument is an optional props object, the rest are children. The `span` child is a function `() => count.value` — this is what makes it reactive.

**3. Mount to the DOM**

```ts
mount(Counter({ initial: 0 }), document.getElementById("app")!);
```

`mount()` attaches the component tree to a DOM element.

## Key Concepts

- **signal()** — reactive state that triggers updates when written to
- **Element functions** — `div()`, `button()`, `span()` — typed functions for every HTML element
- **Reactive children** — pass a function `() => value` to make text update automatically
- **component()** — wraps a function that returns UI, accepts props

:::tip[🐱 Whisker Tip]
Notice there's no `useState`, no `setState`, no re-render cycle. Write to `count.value` and the DOM updates. That's it.
:::

## Next Steps

- [Todo App](https://whisq.dev/examples/todo-app/) — A more complete example with lists and state
- [Signals](https://whisq.dev/core-concepts/signals/) — Deep dive into reactive state
- [Elements](https://whisq.dev/core-concepts/elements/) — All element functions and props

---
# Dashboard
URL: https://whisq.dev/examples/dashboard/
---

A dashboard that fetches data from APIs, displays stats, and updates in real time. Demonstrates `resource()`, multiple components sharing state, and composing widgets.

## What You'll Build

- Stats overview with key metrics
- A list of recent orders fetched from an API
- A revenue summary widget
- Refresh button to reload all data

## Data Layer

```ts
// stores/dashboard.ts

  customer: string;
  amount: number;
  status: "pending" | "shipped" | "delivered";
}

  return {
    pending: list.filter(o => o.status === "pending").length,
    shipped: list.filter(o => o.status === "shipped").length,
    delivered: list.filter(o => o.status === "delivered").length,
  };
});

};
```

## Stat Card Widget

```ts
// components/StatCard.ts

interface StatCardProps {
  label: string;
  value: () => string;
  color?: string;
}

const StatCard = component((props: StatCardProps) =>
  div({ class: "stat-card" },
    h3(props.label),
    span({ class: "stat-value", style: () => props.color ? `color: ${props.color}` : "" },
      props.value,
    ),
  )
);

```

## Orders Table

```ts
// components/OrdersTable.ts

const OrdersTable = component(() =>
  div({ class: "orders-table" },
    when(() => orders.loading(), () => p("Loading orders...")),
    when(() => !!orders.error(), () => p({ class: "error" }, "Failed to load orders")),
    when(() => !!orders.data(), () =>
      table(
        thead(
          tr(
            th("ID"),
            th("Customer"),
            th("Amount"),
            th("Status"),
          ),
        ),
        tbody(
          each(() => orders.data()!, (order) =>
            tr(
              td(`#${order.id}`),
              td(order.customer),
              td(`$${order.amount.toFixed(2)}`),
              td({ class: () => `status-${order.status}` }, order.status),
            )
          ),
        ),
      )
    ),
  )
);

```

## Dashboard Layout

```ts
// components/Dashboard.ts

const Dashboard = component(() =>
  div({ class: "dashboard" },
    div({ class: "header" },
      h1("Dashboard"),
      button({ onclick: refreshAll }, "Refresh"),
    ),

    div({ class: "stats-grid" },
      StatCard({
        label: "Total Revenue",
        value: () => `$${totalRevenue.value.toFixed(2)}`,
        color: "#10b981",
      }),
      StatCard({
        label: "Total Orders",
        value: () => `${(orders.data() ?? []).length}`,
      }),
      StatCard({
        label: "Pending",
        value: () => `${ordersByStatus.value.pending}`,
        color: "#f59e0b",
      }),
      StatCard({
        label: "Delivered",
        value: () => `${ordersByStatus.value.delivered}`,
        color: "#5ce0f2",
      }),
    ),

    OrdersTable({}),
  )
);

```

## Entry Point

```ts
// main.ts

mount(Dashboard({}), document.getElementById("app")!);
```

## Key Concepts

- **resource()** — fetches data and exposes reactive `loading()`, `error()`, `data()` states
- **computed()** — `totalRevenue` and `ordersByStatus` derive from fetched data automatically
- **Component composition** — `StatCard` is reused with different props for each metric
- **refetch()** — the refresh button triggers a new API call, UI updates automatically
- **when() + each()** — conditional loading/error states with list rendering for table rows

:::tip[🐱 Whisker Tip]
Passing `value` as a function `() => string` to `StatCard` keeps the stat reactive. If the data changes (e.g., after refetch), every card updates automatically.
:::

## Next Steps

- [Data Fetching](https://whisq.dev/guides/data-fetching/) — More on resource() patterns
- [Real-time Data](https://whisq.dev/examples/real-time-data/) — WebSocket-based live updates
- [State Management](https://whisq.dev/guides/state-management/) — Composing stores

---
# Form Validation
URL: https://whisq.dev/examples/form-validation/
---

A registration form with email, password, and confirm password fields. Validation runs reactively — errors appear as the user types, and the submit button enables only when everything is valid.

## What You'll Build

- Email validation (must contain @)
- Password validation (minimum 8 characters, must contain a number)
- Confirm password (must match)
- Per-field error messages that appear after the user starts typing
- Submit button that's disabled until all fields are valid

## Full Source

```ts

const RegistrationForm = component(() => {
  const email = signal("");
  const password = signal("");
  const confirm = signal("");
  const submitted = signal(false);

  // Validation rules
  const emailValid = computed(() => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value));
  const passwordLong = computed(() => password.value.length >= 8);
  const passwordHasNumber = computed(() => /\d/.test(password.value));
  const passwordValid = computed(() => passwordLong.value && passwordHasNumber.value);
  const confirmValid = computed(() => confirm.value === password.value);
  const formValid = computed(() => emailValid.value && passwordValid.value && confirmValid.value);

  // Only show errors after user has typed something
  const emailTouched = computed(() => email.value.length > 0);
  const passwordTouched = computed(() => password.value.length > 0);
  const confirmTouched = computed(() => confirm.value.length > 0);

  const handleSubmit = (e: Event) => {
    e.preventDefault();
    if (!formValid.value) return;
    submitted.value = true;
    console.log({ email: email.value, password: password.value });
  };

  return form({ onsubmit: handleSubmit },
    // Email
    div({ class: "field" },
      label("Email"),
      input({
        type: "email",
        placeholder: "you@example.com",
        value: () => email.value,
        oninput: (e) => email.value = e.target.value,
      }),
      when(() => emailTouched.value && !emailValid.value,
        () => p({ class: "error" }, "Enter a valid email address"),
      ),
    ),

    // Password
    div({ class: "field" },
      label("Password"),
      input({
        type: "password",
        placeholder: "At least 8 characters with a number",
        value: () => password.value,
        oninput: (e) => password.value = e.target.value,
      }),
      when(() => passwordTouched.value && !passwordLong.value,
        () => p({ class: "error" }, "Password must be at least 8 characters"),
      ),
      when(() => passwordTouched.value && passwordLong.value && !passwordHasNumber.value,
        () => p({ class: "error" }, "Password must contain at least one number"),
      ),
    ),

    // Confirm Password
    div({ class: "field" },
      label("Confirm Password"),
      input({
        type: "password",
        placeholder: "Repeat your password",
        value: () => confirm.value,
        oninput: (e) => confirm.value = e.target.value,
      }),
      when(() => confirmTouched.value && !confirmValid.value,
        () => p({ class: "error" }, "Passwords do not match"),
      ),
    ),

    // Submit
    button({
      disabled: () => !formValid.value,
    }, "Create Account"),

    when(() => submitted.value,
      () => p({ class: "success" }, "Account created!"),
    ),
  );
});

mount(RegistrationForm({}), document.getElementById("app")!);
```

## How It Works

**1. Validation rules as computed values**

```ts
const emailValid = computed(() => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value));
const passwordValid = computed(() => passwordLong.value && passwordHasNumber.value);
const formValid = computed(() => emailValid.value && passwordValid.value && confirmValid.value);
```

Each rule is a `computed()` that re-evaluates automatically when its dependencies change. `formValid` composes all individual rules.

**2. Touched state for UX**

```ts
const emailTouched = computed(() => email.value.length > 0);
```

Errors only appear after the user starts typing. This prevents a wall of error messages on initial load.

**3. Conditional error display**

```ts
when(() => emailTouched.value && !emailValid.value,
  () => p({ class: "error" }, "Enter a valid email address"),
),
```

`when()` renders the error only when both conditions are true: the field has been touched AND the value is invalid.

**4. Reactive button state**

```ts
button({ disabled: () => !formValid.value }, "Create Account")
```

The button enables automatically when all validation passes.

## Key Concepts

- **computed()** — derive validation state reactively from signals
- **Composable validation** — small rules combine into `formValid`
- **Touched state** — track whether the user has interacted with a field
- **when()** — show/hide error messages based on reactive conditions
- **Reactive disabled** — button enables itself when form becomes valid

:::tip[🐱 Whisker Tip]
Keep validation rules as separate `computed()` values rather than one big function. This makes them individually reusable and testable.
:::

## Next Steps

- [Forms Guide](https://whisq.dev/guides/forms/) — More form patterns
- [Todo App](https://whisq.dev/examples/todo-app/) — Full CRUD example
- [Testing](https://whisq.dev/guides/testing/) — Test form components

---
# Real-time Data
URL: https://whisq.dev/examples/real-time-data/
---

A live stock ticker that receives price updates over a WebSocket connection and renders them reactively. Demonstrates signals with external data sources and lifecycle cleanup.

## What You'll Build

- Connect to a WebSocket for live price updates
- Display a table of stock prices that update in real time
- Show connection status (connected/disconnected)
- Color-code price changes (green for up, red for down)
- Clean up the WebSocket connection when the component unmounts

## Data Store

```ts
// stores/ticker.ts

  price: number;
  change: number;
}

  const change = current ? price - current.price : 0;
  const updated = new Map(stocks.value);
  updated.set(symbol, { symbol, price, change });
  stocks.value = updated;
};
```

## WebSocket Hook

```ts
// hooks/useWebSocket.ts

    ws.onopen = () => {
      connected.value = true;
    };

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      updateStock(data.symbol, data.price);
    };

    ws.onclose = () => {
      connected.value = false;
    };

    onCleanup(() => {
      ws.close();
    });
  });
}
```

## Ticker Component

```ts
// components/Ticker.ts

const Ticker = component(() => {
  useTickerSocket("wss://example.com/stocks");

  return div({ class: "ticker" },
    div({ class: "header" },
      h1("Live Prices"),
      span({
        class: () => connected.value ? "status connected" : "status disconnected",
      }, () => connected.value ? "Connected" : "Disconnected"),
    ),

    table(
      thead(
        tr(
          th("Symbol"),
          th("Price"),
          th("Change"),
        ),
      ),
      tbody(
        each(() => stockList.value, (stock) =>
          tr(
            td({ class: "symbol" }, stock.symbol),
            td(() => `$${stock.price.toFixed(2)}`),
            td({
              class: () => stock.change > 0 ? "up" : stock.change < 0 ? "down" : "",
            }, () => {
              const sign = stock.change > 0 ? "+" : "";
              return `${sign}${stock.change.toFixed(2)}`;
            }),
          )
        ),
      ),
    ),
  );
});

```

## Entry Point

```ts
// main.ts

mount(Ticker({}), document.getElementById("app")!);
```

## How It Works

**1. External data feeds into signals**

```ts
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  updateStock(data.symbol, data.price);
};
```

WebSocket messages update a signal. Every component reading that signal updates automatically — no event bus, no pubsub, no manual DOM updates.

**2. Immutable Map updates**

```ts
const updated = new Map(stocks.value);
updated.set(symbol, { symbol, price, change });
stocks.value = updated;
```

Creating a new `Map` triggers reactivity. Mutating the existing Map would not.

**3. Lifecycle cleanup**

```ts
onMount(() => {
  const ws = new WebSocket(url);
  // ...
  onCleanup(() => {
    ws.close();
  });
});
```

`onCleanup` runs when the component unmounts, closing the WebSocket connection.

**4. Reactive CSS classes**

```ts
td({
  class: () => stock.change > 0 ? "up" : stock.change < 0 ? "down" : "",
})
```

The class changes reactively based on the price change direction.

## Key Concepts

- **Signals with external data** — WebSocket messages write to signals, UI reads them
- **onMount + onCleanup** — connect on mount, disconnect on unmount
- **Immutable collections** — `new Map(old)` for reactive updates
- **computed()** — `stockList` derives a sorted array from the Map signal
- **Reactive classes** — CSS classes that change based on signal values

:::tip[🐱 Whisker Tip]
The `useTickerSocket` function isn't a "hook" in the React sense — it's just a regular function that calls `onMount` and `onCleanup`. There are no hook rules. Call it conditionally, in loops, or from helper functions.
:::

## Next Steps

- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — Deep dive into onMount and onCleanup
- [Dashboard](https://whisq.dev/examples/dashboard/) — Data fetching with resource()
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — HTTP-based data loading

---
# Router basics
URL: https://whisq.dev/examples/router-basics/
---

A minimal routed app that exercises the parts of `@whisq/router` you reach for on day one: dynamic params, nested routes, a `beforeEach` guard for auth-gating, and reactive active-link styling via `router.current`.

## What You'll Build

- Public routes: `/` (home), `/users`, `/users/:id`, `/users/:id/edit`
- A protected `/admin` route gated by a `beforeEach` guard
- Nested routes under `/users` — a shared layout with its own sub-nav
- A `nav` with active-link styling that highlights the current top-level route
- A wildcard `*` fallback

## Install

```bash
npm install @whisq/core @whisq/router
```

## The router

```ts
// src/router.ts

    }
  },

  scrollBehavior: "restore",
});
```

## The app shell

```ts
// src/App.ts

const isActive = (prefix: string) => () =>
  router.current.value.path.startsWith(prefix) ? "active" : "";

```

```ts
// src/main.ts

mount(App({}), document.getElementById("app")!);
```

## The nested `/users` layout

```ts
// src/routes/UsersLayout.ts

```

Each child route gets its own component; `RouterView(router, 1)` swaps between them as the child path changes.

## A dynamic-param route

```ts
// src/routes/UserDetail.ts
// Snapshot pattern: `id` comes from the render callback's params argument.
// RouterView re-mounts this component on every route change, so `id` is
// always fresh for the current match — no reactive wrapper needed.

```

```ts
// src/routes/UserEdit.ts
// Reactive pattern: read the current id from router.current inside a getter.
// Equivalent to the snapshot form above when RouterView re-mounts per match,
// but explicit about the reactive source if you're extending this later.

```

## A session store + guard target

```ts
// src/stores/session.ts

const loggedIn = signal(false);

```

The `beforeEach` guard calls `isLoggedIn()` at navigation time — `.peek()` is used so the guard doesn't subscribe the navigation to the signal. The login route flips the signal, then programmatically navigates:

```ts
// src/routes/Login.ts

        router.navigate("/admin");
      },
    }, "Log in and go to /admin"),
  ),
);
```

## `Admin`, `Home`, `UsersList`, `NotFound`

```ts
// src/routes/Home.ts

// src/routes/Admin.ts

// src/routes/UsersList.ts

// src/routes/NotFound.ts
```

## Key concepts

- **Single `router.current` signal.** Every reactive router read — `RouterView`'s mounted component, `Link`'s active class, any component reading `params` / `query` — ultimately subscribes to this one signal.
- **Nested `RouterView(router, depth)`.** Matching nests under children; `RouterView` at `depth = 1` renders the matched child. Further nesting can go `depth = 2`, etc.
- **Guard return values.** `beforeEach` returning a string redirects; returning `false` cancels; returning `void` (or `true`) proceeds. The guard is synchronous — for async auth checks, read a cached signal (via `.peek()`) instead of awaiting.
- **`meta` is how guards find routes.** Setting `meta: { requiresAuth: true }` lets a single `beforeEach` handle every protected route without enumerating paths.
- **Active links.** No dedicated `active` prop — use a reactive `class` getter reading `router.current.value.path`. Exact match with `===`, prefix match with `.startsWith()`.

## Next Steps

- [Routing guide](https://whisq.dev/guides/routing/) — patterns and walkthroughs.
- [`/api/createrouter/`](https://whisq.dev/api/createrouter/) — config reference.
- [`/api/routerview/`](https://whisq.dev/api/routerview/) — the mounting component.
- [`/api/link/`](https://whisq.dev/api/link/) — navigation anchors.
- [`/api/route-state/`](https://whisq.dev/api/route-state/) — reactive reads.

---
# Todo App
URL: https://whisq.dev/examples/todo-app/
---

A full-featured todo app demonstrating the modern Whisq idioms: `bind()` for two-way input binding, `match()` for empty states, keyed `each()` for efficient list reconciliation, `sheet()` for scoped class names, and the alpha.8 array `class:` form for reactive class toggles.

:::tip[Two persistence patterns — pick by item shape]
This example uses **nested signals** (`done: Signal<boolean>` per todo) for narrow per-item reactivity — toggling one checkbox doesn't re-run computeds that read the array's length. The persistence story is hand-rolled (`loadTodos()` + `effect()`) because `JSON.stringify` can't round-trip a `Signal`.

If your store can hold plain booleans (most apps), prefer the simpler **plain-object + helper** shape: [`persistedSignal<Todo[]>("todos", [])`](https://whisq.dev/api/persistedsignal/) + [`bindField(todos, todo, "done", { as: "checkbox" })`](https://whisq.dev/api/bindfield/). One import, no helper to write. See [Persistence Recipe 1 — plain-object state](https://whisq.dev/guides/state-management/#recipe--plain-object-state) and [Nested Item Editing — Pattern 1](https://whisq.dev/guides/nested-item-editing/) for the full plain-object alternative.
:::

## What You'll Build

- Add new todos from a text input (`bind()`)
- Toggle todos as done/not done (`bind()` on a per-todo `Signal<boolean>`)
- Remove individual todos
- Filter by all, active, or completed
- Display count of remaining items
- Empty-state messaging that distinguishes "no todos yet" from "none match the filter"

## The Store

Separate state logic from UI. Each todo holds a nested `done: Signal<boolean>` so toggling a single checkbox doesn't churn the whole array — only the one checkbox re-renders.

```ts
// stores/todos.ts

  text: string;
  done: Signal<boolean>; // nested signal — per-todo reactivity
}

// ── Persistence ────────────────────────────────────────────────
// Stored shape is plain JSON: { id, text, done: boolean }.
// `done` is hydrated back into a signal on load, re-serialized on save.
// For plain-object stores, prefer the framework helper:
//   import { persistedSignal } from "@whisq/core/persistence";
//   export const todos = persistedSignal<Todo[]>("todos", []);
// We hand-roll loadTodos+effect here because Todo.done is a Signal<boolean>
// (nested-signals pattern) — JSON.stringify can't round-trip that without a
// custom { serialize, deserialize } pair, and at that point the inline form
// reads more clearly than the option spread.
// See /guides/state-management/#persistence-localstorage for the helper.

const STORAGE_KEY = "whisq.todos";

interface StoredTodo { id: string; text: string; done: boolean; }

function loadTodos(): Todo[] {
  if (typeof localStorage === "undefined") return [];
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    if (!raw) return [];
    const parsed = JSON.parse(raw) as StoredTodo[];
    return parsed.map((t) => ({ id: t.id, text: t.text, done: signal(t.done) }));
  } catch {
    return []; // corrupt payload — start fresh
  }
}

// ── Store ──────────────────────────────────────────────────────

// Write on every change. The effect reads todos.value AND every done.value
// via map(), so toggling any checkbox re-runs this effect and persists.
// Skip the eager first run so we don't rewrite the value we just loaded.
let persistInitialized = false;
effect(() => {
  const list = todos.value; // establish subscription
  if (!persistInitialized) { persistInitialized = true; return; }
  if (typeof localStorage === "undefined") return;
  try {
    const serializable: StoredTodo[] = list.map((t) => ({
      id: t.id, text: t.text, done: t.done.value,
    }));
    localStorage.setItem(STORAGE_KEY, JSON.stringify(serializable));
  } catch {
    // Quota exceeded or serialization failure — degrade silently.
  }
});

  switch (filter.value) {
    case "active": return list.filter((t) => !t.done.value);
    case "done":   return list.filter((t) =>  t.done.value);
    default:       return list;
  }
});

  todos.value = [
    ...todos.value,
    { id: randomId(), text: text.trim(), done: signal(false) },
  ];
};

};

};
```

No `toggleTodo()` needed — each checkbox uses `bind(todo.value.done, { as: "checkbox" })` (keyed `each()` gives an `ItemAccessor<Todo>` — read via `.value` for the alpha.8 canonical shape; the legacy `todo()` call form still works) and flips the per-todo signal directly.

:::tip[Persistence pattern]
The `loadTodos()` / persist-`effect()` pair here is the inline shape of `persistedSignal()`. For state without nested signals — the common case — use [`persistedSignal()` from `@whisq/core/persistence`](https://whisq.dev/guides/state-management/#persistence-localstorage) directly: one import, no helper to write. This store hand-rolls the pattern because each `Todo.done` is itself a `Signal<boolean>` and `JSON.stringify` can't round-trip that without a custom `{ serialize, deserialize }` pair — at that point the inline form reads more clearly than the option spread.
:::

## Styles

Use `sheet()` for scoped class names (no global collisions); reactive toggles use the [array `class:` form](https://whisq.dev/api/elements/#class-array-form-since-alpha8) on each element:

```ts
// styles/todo-app.ts

```

## The Component

```ts
// components/TodoApp.ts

const TodoApp = component(() => {
  const newText = signal("");

  const handleAdd = (e: Event) => {
    e.preventDefault();
    addTodo(newText.value);
    newText.value = "";
  };

  return div({ class: s.app },
    h1("Todos"),

    // Add form — bind(newText) spreads value + oninput onto the input
    div({ class: s.addForm },
      input({
        ...bind(newText),
        placeholder: "What needs to be done?",
        class: s.addInput,
        onkeydown: (e) => e.key === "Enter" && handleAdd(e),
      }),
      button({ onclick: handleAdd }, "Add"),
    ),

    // Empty states (two of them) + the list — match() picks first-true branch,
    // with the list as the trailing fallback.
    match(
      [() => todos.value.length === 0,
        () => p({ class: s.empty }, "No todos yet. Add one above.")],
      [() => filtered.value.length === 0,
        () => p({ class: s.empty }, `No ${filter.value} todos.`)],
      () => ul({ class: s.list },
        each(
          () => filtered.value,
          // Keyed render — `todo` is `() => Todo`; call it to read the current entry.
          (todo) => li({ class: s.item },
            // bind() receives the signal REFERENCE — captured once at render is fine
            // because each todo's `done: Signal<boolean>` has stable identity.
            input({ type: "checkbox", ...bind(todo.value.done, { as: "checkbox" }) }),
            // Array `class:` form — reactive getter re-reads todo.value so a
            // reconciler-swapped entry still resolves to the right .done.value.
            span({ class: [() => todo.value.done.value && s.doneText] }, todo.value.text),
            // Event handler: todo.value is read at click time, not at render time.
            button({ class: s.remove, onclick: () => removeTodo(todo.value.id) }, "×"),
          ),
          { key: (t /* value, not accessor */) => t.id }, // keyed each — reuses DOM on reorder/toggle
        ),
      ),
    ),

    // Footer
    div({ class: s.footer },
      span(() => `${remaining.value} items left`),
      div({ class: s.filters },
        button({
          class: [s.filterBtn, () => filter.value === "all" && s.filterActive],
          onclick: () => filter.value = "all",
        }, "All"),
        button({
          class: [s.filterBtn, () => filter.value === "active" && s.filterActive],
          onclick: () => filter.value = "active",
        }, "Active"),
        button({
          class: [s.filterBtn, () => filter.value === "done" && s.filterActive],
          onclick: () => filter.value = "done",
        }, "Done"),
      ),
      when(() => todos.value.some((t) => t.done.value),
        () => button({ onclick: clearCompleted }, "Clear completed"),
      ),
    ),
  );
});

```

## Entry Point

```ts
// main.ts

mount(TodoApp({}), document.getElementById("app")!);
```

## Key Concepts

- **Store pattern** — state lives in a separate module; UI imports what it needs. The example uses `filter.value = "all"` inline in onclick handlers for readability. For apps larger than a single screen, factor mutations into named actions like `setFilter("all")` — see [State Management → Mutations as named actions](https://whisq.dev/guides/state-management/#mutations-as-named-actions).
- **Nested signals** — each todo holds its own `done: Signal<boolean>`. Toggling one checkbox updates only that `<li>`; the array signal only changes on add/remove. The `filtered`/`remaining` computeds still see every `.done.value` change because they read the signals during filtering.
- **`bind()`** — spreads `value + oninput` (text) or `checked + onchange` (checkbox) in one shot. Works on the add-form input and every per-todo checkbox. **Note:** `bind(todo.value.done, …)` works here because `done` is a `Signal<boolean>` (the nested-signals pattern). If your store holds plain booleans instead — `done: boolean` — use [`bindField(todos, todo, "done", { as: "checkbox" })`](https://whisq.dev/api/bindfield/), which mutates the source array immutably and identifies the right item via `keyBy`. Both patterns are valid; `bindField` is the choice when you don't want per-item signals.
- **Keyed `each()`** — `{ key: (t /* value, not accessor */) => t.id }` enables LIS-based diffing, so reordering or filter-toggling moves existing DOM nodes instead of recreating them. The render callback receives `todo: ItemAccessor<Todo>` — read via `todo.value.<field>` (alpha.8 canonical), `todo()` (legacy call form), or `todo.peek()` (untracked). The rule isn't "does the field change" — it's whether the **position** re-evaluates. `bind(todo.value.done, ...)` takes a snapshot because `bind()` consumes a signal reference and the signal drives its own reactivity. The `class: [() => todo.value.done.value && s.doneText]` array form re-evaluates its function elements on change — the getter re-reads `todo.value` every time, so a reconciler-swapped entry still resolves correctly. See [`/api/each/`](https://whisq.dev/api/each/#reactive-fields-inside-keyed-each) for the full breakdown. For real apps, the per-item render usually lives in its own component — see [Splitting into a component](https://whisq.dev/api/each/#splitting-into-a-component) for the accessor-prop pattern.
- **`match()`** — first-true-wins branching with a trailing fallback. Here: "no todos at all" → a prompt, "filtered to empty" → a specific message, otherwise render the list.
- **`when()`** — the two-state "Clear completed" button. Two branches are fine for `when()`; reach for `match()` at three.
- **`sheet()` + array `class:` form** — scoped class names (no global CSS collisions) with reactive toggles. `class: [s.item, () => flag && s.active]` is the canonical alpha.8 shape; [`rcx()`](https://whisq.dev/api/rcx/) continues to work and is the right tool when you need a reactive class string *outside* an element prop.
- **Immutable updates** — `todos.value = [...todos.value, newTodo]` on add/remove. Mutating in place wouldn't trigger reactivity.
- **Keyboard events** — `onkeydown` with `e.key === "Enter"` for form-less submit.

:::danger[Common Mistake: mutation instead of new array]
```ts
// ❌ WRONG — mutation won't trigger updates
todos.value.push(newTodo);

// ✅ RIGHT — new array triggers reactivity
todos.value = [...todos.value, newTodo];
```
:::

:::danger[Common Mistake: static class instead of reactive]
```ts
// ❌ WRONG — class is set once at render, never updates
button({ class: filter.value === "all" ? "active" : "" }, "All")

// ❌ WORKS but awkward — hand-rolled ternary getter
button({ class: () => filter.value === "all" ? "active" : "" }, "All")

// ✅ RIGHT — array class: form (alpha.8) — strings + reactive getters in one prop
button({ class: [s.filterBtn, () => filter.value === "all" && s.filterActive] }, "All")
```
:::

## Next Steps

- [Forms guide](https://whisq.dev/guides/forms/) — deep dive on `bind()` for every input type.
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — `resource()` and `match()` for loading/error/data.
- [List Rendering](https://whisq.dev/core-concepts/list-rendering/) — when keyed vs. unkeyed `each()` matters.
- [State Management](https://whisq.dev/guides/state-management/) — more on the store pattern + nested signals.

---
# Installation
URL: https://whisq.dev/getting-started/installation/
---

## Scaffolding (Recommended)

The fastest way to start:

```bash
# npm
npm create whisq@latest my-app

# pnpm
pnpm create whisq my-app

# bun
bun create Whisq my-app
```

This creates a project with Vite, TypeScript, and a counter example.

## Adding to an Existing Project

### Package Manager

```bash
# npm
npm install @whisq/core

# pnpm
pnpm add @whisq/core

# yarn
yarn add @whisq/core

# bun
bun add @whisq/core
```

### With Vite

If you already have a Vite project, just install the package — no plugin needed for basic usage:

```bash
npm install @whisq/core
```

```ts
// src/main.ts

const count = signal(0);

mount(
  div(
    button({ onclick: () => count.value++ }, "Click me"),
    span(() => `Count: ${count.value}`),
  ),
  document.getElementById("app")!,
);
```

For file-based routing, add the Vite plugin:

```bash
npm install @whisq/vite-plugin
```

```ts
// vite.config.ts

```

## TypeScript Configuration

Whisq is written in TypeScript and ships with types. Recommended `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "isolatedModules": true
  },
  "include": ["src"]
}
```

## CDN (No Build)

For prototyping or small projects, use Whisq directly via CDN:

```html
<!DOCTYPE html>
<html>
  <body>
    <div id="app"></div>
    <script type="module">
      import {
        signal, div, button, span, mount
      } from "https://esm.sh/@whisq/core";

      const count = signal(0);

      mount(
        div(
          button({ onclick: () => count.value++ }, "+"),
          span(() => ` ${count.value} `),
        ),
        document.getElementById("app"),
      );
    </script>
  </body>
</html>
```

:::tip[🐱 Whisker Tip]
The CDN approach is great for CodePen, JSFiddle, or quick experiments. For real apps, use the Vite setup — you get HMR, TypeScript, and optimized builds.
:::

## Optional Packages

| Package | Purpose | Install |
|---------|---------|---------|
| `@whisq/router` | Client-side routing | `npm i @whisq/router` |
| `@whisq/ssr` | Server-side rendering | `npm i @whisq/ssr` |
| `@whisq/testing` | Component testing | `npm i -D @whisq/testing` |
| `@whisq/vite-plugin` | File routing, HMR | `npm i -D @whisq/vite-plugin` |
| `@whisq/devtools` | Runtime debugging | `npm i -D @whisq/devtools` |

## Next Steps

- [Your First Component](https://whisq.dev/getting-started/your-first-component/) — Build something real
- [Signals](https://whisq.dev/core-concepts/signals/) — Understand reactive state

---
# Introduction
URL: https://whisq.dev/getting-started/introduction/
---

## What is Whisq?

Whisq is a reactive JavaScript/TypeScript framework for building web UIs. It uses **signals** for state, **hyperscript functions** for elements, and **function components** for composition.

```ts

const Counter = component(() => {
  const count = signal(0);
  return div(
    button({ onclick: () => count.value-- }, "-"),
    span(() => ` ${count.value} `),
    button({ onclick: () => count.value++ }, "+"),
  );
});

mount(Counter({}), document.getElementById("app")!);
```

No JSX. No build step. No compilation. Just function calls.

## Who is Whisq for?

- **AI-assisted developers** — Whisq's API is designed so AI generates correct code on the first attempt. The entire API fits in &lt;5K tokens.
- **Developers who want simplicity** — No hooks rules, no virtual DOM, no template syntax to learn. Everything is a function.
- **Teams shipping fast** — Zero build configuration. `<script type="module">` and you're running.

## Design Philosophy

### Everything is a function

Every HTML element is a typed function. `div()`, `button()`, `input()` — no template strings, no JSX transpilation. TypeScript gives you autocomplete for props and events.

### Signals, not hooks

Reactive state is a first-class primitive, not a framework-specific hook pattern. Signals are standalone values that track dependencies automatically.

```ts
const count = signal(0);   // create
count.value;               // read (tracks)
count.value = 5;           // write (triggers updates)
```

### AI-native

Whisq was designed from day one for AI code generation:

- **Function calls** — AI generates function calls more accurately than JSX/templates
- **No special syntax** — No `<template>`, no `@click`, no `{#each}`. Just JavaScript.
- **Small API surface** — The complete API fits in a single CLAUDE.md file (&lt;5K tokens)
- **Typed everything** — TypeScript catches AI mistakes at compile time

### Zero build

Whisq runs directly in the browser via ES modules. No bundler required for development. Add Vite when you need production optimization.

## How Whisq Compares

| Feature | React | Vue | Svelte | **Whisq** |
|---------|-------|-----|--------|-----------|
| Reactivity | `useState` + rules | `ref()` + `.value` | `$state` rune | `signal()` — no rules |
| Templates | JSX (needs build) | SFC templates | Svelte syntax | Function calls — no build |
| Bundle size | ~45KB | ~33KB | ~2KB | **&lt;5KB** |
| AI accuracy | Medium | Medium | Low | **High** — function calls |
| Learning curve | Moderate | Moderate | Low | **Minimal** — just functions |

## Next Steps

Ready to build something? Head to the [Quick Start](https://whisq.dev/getting-started/quick-start/) to create your first Whisq app in 5 minutes.

---
# Multi-file App Scaffold
URL: https://whisq.dev/getting-started/multi-file-app/
---

A worked example of the project-structure rules from the [LLM reference](https://whisq.dev/ai/llm-reference/#project-structure). If you've read the rules but want to see them applied end-to-end, this is that page. Use it as the starting point for a new app, or as a reference when you're adding the first component past `main.ts`.

## Scaffold a new project

The fastest path is [`create-whisq`](https://www.npmjs.com/package/create-whisq), which produces this scaffold (plus `package.json`, `vite.config.ts`, `tsconfig.json`, `index.html`, and a starter component):

```bash
npm create whisq@latest my-app
cd my-app
npm install
npm run dev
```

The CLI prompts for a template (`full-app` matches the structure below; `minimal` gives you a single-file starting point; `ssr` includes server-rendering wiring). Skip the rest of this page if the scaffold is enough — come back when you want to understand *why* each file exists.

## The file layout

```text
src/
  main.ts                  # entrypoint — mounts App, nothing else
  App.ts                   # top-level shell component
  styles.ts                # theme() + root sheet() definitions
  components/
    TodoList.ts            # one component per file, named export
    TodoItem.ts
  stores/
    todos.ts               # shared state — one domain per file
  lib/
    format.ts              # pure utilities, NO Whisq imports
```

Seven files. Each one has one job. Together they implement a minimal persisted todo app — the code below is copy-paste-runnable against `@whisq/core@0.1.0-alpha.8`.

## `src/main.ts` — entrypoint

```ts

mount(App({}), document.getElementById("app")!);
```

**Why one line.** `main.ts` exists to wire the DOM target to the top-level component. Anything more — state, styling, routing — belongs elsewhere. If an AI rewrites `main.ts` to change behaviour, your git history becomes hard to read. Keep it boring.

## `src/App.ts` — shell

```ts

```

**Why a shell.** The shell is where layout lives. State lives in `stores/`, per-row UI lives in `components/`, styles live in `styles.ts`. The shell composes them. Keep it narrow — if it grows past ~30 lines, split a subsection into its own component.

## `src/stores/todos.ts` — shared state

```ts

  if (!trimmed) return;
  todos.value = [...todos.value, { id: randomId(), text: trimmed, done: false }];
};

};
```

**Why a store.** Module-scope signals + exported action functions. Anything that needs the state imports from this file; reactivity propagates automatically. `persistedSignal` handles localStorage serialization, SSR safety, and quota errors. `randomId` is UUID-v4-shaped for stable keys. One domain per file; a cart app would have `stores/cart.ts`, auth would have `stores/auth.ts`, and so on.

## `src/components/TodoList.ts` — per-row render

```ts

const TodoItem = component((props: { todo: ItemAccessor<Todo> }) =>
  li({ class: s.item },
    input({ type: "checkbox", ...bindField(todos, props.todo, "done", { as: "checkbox" }) }),
    () => props.todo.value.text,
    button({ class: s.remove, onclick: () => removeTodo(props.todo.value.id) }, "×"),
  ),
);
```

**Why a typed prop.** `ItemAccessor<T>` is what keyed `each()` hands to the render callback in alpha.8+. Passing it across a component boundary preserves reactivity — the child reads `props.todo.value.<field>` for current values without needing its own signal. `bindField` writes back to the `todos` array immutably; the `keyBy` default (`t => t.id`) handles row identification.

## `src/components/AddTodo.ts` — input + submit

```ts

  const submit = (e: Event) => {
    e.preventDefault();
    addTodo(draft.value);
    draft.value = "";
  };

  return form({ class: s.addForm, onsubmit: submit },
    input({ ...bind(draft), placeholder: "What needs to be done?", class: s.input }),
    button({ type: "submit" }, "Add"),
  );
});
```

**Why a local signal.** `draft` is UI state scoped to this one component — no other module needs it, so it lives here. If three components needed the draft, it'd move to `stores/`. The rule isn't "always stores" or "always local"; it's **"where's the smallest scope that includes every reader?"**

## `src/lib/format.ts` — pure utilities

```ts
// NO Whisq imports. Pure functions only.

}

}
```

**Why pure.** No Whisq imports means these functions are testable in isolation and reusable in a non-Whisq context (tests, CLI, another project). If you find yourself reaching for `signal()` in `lib/`, the function belongs in `stores/` instead.

## `src/styles.ts` — theme + root styles

```ts

theme({
  color: { primary: "#4386FB", text: "#111827", bg: "#ffffff" },
  space: { sm: "0.5rem", md: "1rem", lg: "1.5rem" },
});

```

**Why module scope.** `theme()` injects CSS variables into `:root` once; calling it at module scope ensures it runs on first import (which happens transitively via `App.ts`). `sheet()` returns a `classMap` whose class names are stable for the module lifetime. Both are SSR-safe since alpha.8.

## Expanding the scaffold

When the app grows past this skeleton, here's the rule of thumb for where new code goes:

- **New UI surface that's reusable** → new file in `components/`.
- **New shared state domain** → new file in `stores/` (e.g. `stores/auth.ts` for login state).
- **New pure helper** (no Whisq imports) → new file in `lib/`.
- **New route** (if you've added `@whisq/router`) → new file in `pages/`.
- **One-off component that's only used once** — keep inline in the parent component file until you need it twice.

The skeleton scales linearly: adding a 10th component adds one file, not a refactor of the existing nine.

## See also

- [Project structure rules](https://whisq.dev/ai/llm-reference/#project-structure) — the one-line rules this page demonstrates.
- [LLM reference](https://whisq.dev/ai/llm-reference/) — the AI-facing condensed version includes a "Project Structure (worked)" block matching the scaffold above.
- [State Management](https://whisq.dev/guides/state-management/) — deeper coverage of the `stores/` pattern.
- [Todo App example](https://whisq.dev/examples/todo-app/) — a richer variant of this same scaffold with filters, empty states, and nested-signal persistence.
- [Your First Component](https://whisq.dev/getting-started/your-first-component/) — the single-file starting point. Read this page next when you're ready to split.

---
# Quick Start
URL: https://whisq.dev/getting-started/quick-start/
---

Build a working Whisq app in under 5 minutes.

## 1. Create a Project

```bash
npm create whisq@latest my-app
cd my-app
npm install
npm run dev
```

Open `http://localhost:5173` — you should see a counter app.

## 2. Understand the Code

Open `src/main.ts`:

```ts

const Counter = component((props: { initial?: number }) => {
  const count = signal(props.initial ?? 0);

  return div({ class: "counter" },
    h1("Whisq Counter"),
    button({ onclick: () => count.value-- }, "-"),
    span({ class: "count" }, () => ` ${count.value} `),
    button({ onclick: () => count.value++ }, "+"),
  );
});

const App = component(() => {
  return div({ class: "app" },
    Counter({ initial: 0 }),
  );
});

mount(App({}), document.getElementById("app")!);
```

Let's break this down:

### Signals — reactive state

```ts
const count = signal(0);  // create a reactive value
count.value++;            // write — triggers updates everywhere
```

### Elements — typed HTML functions

```ts
div({ class: "counter" },  // props object (optional)
  h1("Whisq Counter"),      // text child
  button({ onclick: fn }),  // event handler
  span(() => count.value),  // reactive child (function)
)
```

Every HTML tag is a function: `div()`, `span()`, `button()`, `input()`, `h1()`, etc.

### Components — setup functions

```ts
const Counter = component((props) => {
  // setup code runs once
  const count = signal(0);

  // return a WhisqNode
  return div(/* ... */);
});

// use it — it's a function call
Counter({ initial: 10 })
```

## 3. Make a Change

Try editing `src/main.ts`:

```ts
// Change the title
h1("My First Whisq App"),

// Add a computed display
const doubled = computed(() => count.value * 2);

// Show it
p(() => `Doubled: ${doubled.value}`),
```

Don't forget to import `computed` and `p`:

```ts
```

Save — Vite hot-reloads instantly.

## 4. Key Rules

:::tip[🐱 Whisker Tip]
These three rules cover 90% of Whisq development:
:::

**Rule 1: Wrap reactive values in functions**
```ts
// ❌ WRONG — static, never updates
span(count.value)

// ✅ RIGHT — reactive, updates automatically
span(() => count.value)
```

**Rule 2: Don't mutate arrays in-place**
```ts
// ❌ WRONG — won't trigger updates
items.value.push(newItem)

// ✅ RIGHT — creates new array, triggers updates
items.value = [...items.value, newItem]
```

**Rule 3: Events are `on*` props with functions**
```ts
// ❌ WRONG — string handler
button({ onclick: "doSomething()" })

// ✅ RIGHT — function handler
button({ onclick: () => doSomething() })
```

## Next Steps

- [Installation](https://whisq.dev/getting-started/installation/) — All the ways to add Whisq to a project
- [Your First Component](https://whisq.dev/getting-started/your-first-component/) — Build a real component step by step
- [Signals](https://whisq.dev/core-concepts/signals/) — Deep dive into reactive state

---
# Your First Component
URL: https://whisq.dev/getting-started/your-first-component/
---

Let's build a real component: a **todo list** with add, toggle, and delete.

## Step 1: The Data Model

Start with the state. A todo has an `id`, `text`, and `done` flag:

```ts

interface Todo {
  id: number;
  text: string;
  done: boolean;
}

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: false },
  { id: 2, text: "Build something", done: false },
]);

let nextId = 3;
```

## Step 2: The Todo Item

Each todo is a `li` with a checkbox, text, and delete button:

```ts

function TodoItem(todo: Todo) {
  return li({ class: () => todo.done ? "done" : "" },
    input({
      type: "checkbox",
      checked: todo.done,
      onchange: () => toggleTodo(todo.id),
    }),
    span(todo.text),
    button({ onclick: () => removeTodo(todo.id) }, "✕"),
  );
}
```

:::tip[🐱 Whisker Tip]
Notice `TodoItem` is a plain function, not `component()`. For simple presentational pieces that don't need lifecycle hooks, plain functions work fine. Use `component()` when you need `onMount`, `onCleanup`, or `provide`/`inject`.
:::

## Step 3: Actions

Functions that update the signal:

```ts
function addTodo(text: string) {
  todos.value = [...todos.value, { id: nextId++, text, done: false }];
}

function toggleTodo(id: number) {
  todos.value = todos.value.map(t =>
    t.id === id ? { ...t, done: !t.done } : t
  );
}

function removeTodo(id: number) {
  todos.value = todos.value.filter(t => t.id !== id);
}
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — mutating the array won't trigger updates
todos.value.push({ id: 3, text: "new", done: false });

// ✅ RIGHT — create a new array
todos.value = [...todos.value, { id: 3, text: "new", done: false }];
```
:::

## Step 4: The Add Form

An input with an "Add" button:

```ts

function AddTodo() {
  const text = signal("");

  return form({
    onsubmit: (e) => {
      e.preventDefault();
      if (text.value.trim()) {
        addTodo(text.value.trim());
        text.value = "";
      }
    },
  },
    input({
      type: "text",
      placeholder: "What needs doing?",
      value: () => text.value,
      oninput: (e) => text.value = (e.target as HTMLInputElement).value,
    }),
    button({ type: "submit" }, "Add"),
  );
}
```

## Step 5: The Full App

Put it all together:

```ts

interface Todo {
  id: number;
  text: string;
  done: boolean;
}

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: false },
  { id: 2, text: "Build something", done: false },
]);
let nextId = 3;

const remaining = computed(() =>
  todos.value.filter(t => !t.done).length
);

function addTodo(text: string) {
  todos.value = [...todos.value, { id: nextId++, text, done: false }];
}

function toggleTodo(id: number) {
  todos.value = todos.value.map(t =>
    t.id === id ? { ...t, done: !t.done } : t
  );
}

function removeTodo(id: number) {
  todos.value = todos.value.filter(t => t.id !== id);
}

const App = component(() => {
  const text = signal("");

  return div({ class: "app" },
    h1("Whisq Todos"),
    form({
      onsubmit: (e) => {
        e.preventDefault();
        if (text.value.trim()) {
          addTodo(text.value.trim());
          text.value = "";
        }
      },
    },
      input({
        type: "text",
        placeholder: "What needs doing?",
        value: () => text.value,
        oninput: (e) => text.value = (e.target as HTMLInputElement).value,
      }),
      button({ type: "submit" }, "Add"),
    ),
    ul(
      () => todos.value.map(todo =>
        li({ class: () => todo.done ? "done" : "" },
          input({
            type: "checkbox",
            checked: todo.done,
            onchange: () => toggleTodo(todo.id),
          }),
          span(todo.text),
          button({ onclick: () => removeTodo(todo.id) }, "✕"),
        )
      ),
    ),
    p(() => `${remaining.value} item${remaining.value !== 1 ? "s" : ""} remaining`),
  );
});

mount(App({}), document.getElementById("app")!);
```

## What You Learned

In this tutorial you used:

- **`signal()`** — reactive state for the todo list and input text
- **`computed()`** — derived value (remaining count)
- **`component()`** — the root app component
- **Element functions** — `div`, `h1`, `ul`, `li`, `form`, `input`, `button`, `span`, `p`
- **Reactive children** — `() => todos.value.map(...)` for dynamic lists
- **Reactive props** — `class: () => ...` for conditional styling
- **Events** — `onclick`, `onsubmit`, `oninput`, `onchange`

## Next Steps

- [Multi-file App Scaffold](https://whisq.dev/getting-started/multi-file-app/) — Split this single-file example into the canonical `main.ts` / `App.ts` / `stores/` / `components/` / `lib/` / `styles.ts` shape.
- [Signals](https://whisq.dev/core-concepts/signals/) — Deep dive into `signal()`, `computed()`, `effect()`
- [Elements](https://whisq.dev/core-concepts/elements/) — All the element functions and props
- [Components](https://whisq.dev/core-concepts/components/) — Lifecycle, context, error boundaries

---
# Accessibility
URL: https://whisq.dev/guides/accessibility/
---

Accessibility in Whisq comes from four decisions that compose: reach for the **right semantic element** first, let the **typed `aria-*` surface** fill the gap when semantics aren't enough, use `ref()` + `onMount` for **focus management**, and drop to `h(tag, { … })` when you need an attribute the typed props don't cover.

## Typed `aria-*` props (since alpha.9)

Every element accepts typed `aria-*` props via an indexed signature on `BaseProps`:

```ts
// The type on every element's props:
[key: `aria-${string}`]: ReactiveProp<string | boolean | undefined>;
```

That means all three of these typecheck, on every element:

```ts
button({ "aria-label": "Close dialog" }, "×");
button({ "aria-expanded": true }, "Menu");
button({ "aria-expanded": () => menuOpen.value }, "Menu");
```

No need to pick between "known ARIA names" and the untyped `data-*` escape hatch — the typed surface covers every attribute whose name starts with `aria-`.

### Serialisation rules

| Value | Serialised as | Notes |
|---|---|---|
| `"polite"` / any string | `"polite"` | Strings pass through verbatim — use these for enum-shaped attrs (`aria-live`, `aria-sort`, etc.). |
| `true` | `"true"` | Correct per ARIA spec — alpha.9 fix. |
| `false` | `"false"` | Correct per ARIA spec — `"false"` is **not** equivalent to "missing" for predicate attrs. |
| `undefined` / `null` | attribute removed | Useful for conditional removal — see "Dynamic ARIA" below. |

**Pre-alpha.9 note:** `true` used to serialise to the empty string `aria-expanded=""`, which is **invalid** per the ARIA spec — it's *not* equivalent to `aria-expanded="true"`. Alpha.9 routes `aria-*` through a dedicated branch in the prop applier that produces the correct string form ([whisqjs/whisq#128](https://github.com/whisqjs/whisq/issues/128), [whisqjs/whisq#129](https://github.com/whisqjs/whisq/issues/129)). If you're seeing the wrong shape in DOM, check you're on alpha.9+.

## Dynamic ARIA

Pass a function to make any `aria-*` prop reactive — `ReactiveProp<T>` is `T | (() => T)`, so a getter fits anywhere a static value fits:

```ts
const menuOpen = signal(false);
const status = signal<"loading" | "ready" | "error">("loading");

button({
  "aria-expanded": () => menuOpen.value,
  "aria-controls": "main-menu",
  onclick: () => menuOpen.value = !menuOpen.value,
}, "Menu");

div({ role: "status", "aria-live": "polite" }, () => status.value);
```

### Removing an attribute reactively

Return `undefined` (or `null`) from the getter to drop the attribute. This is the idiomatic way to express "this attribute doesn't apply right now":

```ts
// Visible elements don't need aria-hidden at all; set it only when hiding.
div({ "aria-hidden": () => visible.value ? undefined : true });
```

Don't try to "remove" an attribute by setting it to `false` — that serialises to `"false"`, which is a **different** accessibility meaning for most predicate-shaped ARIA attrs (e.g. `aria-hidden="false"` is explicit "not hidden", which is distinct from the default of no attribute at all).

## Focus management with `ref()`

A `ref()` gives you a reactive handle to the DOM node. For focus work, pair it with `onMount` so the node exists before you call `.focus()`:

```ts

const AutoFocusInput = component(() => {
  const el = ref<HTMLInputElement>();

  // Focus inside onMount — the node is guaranteed to be attached to the DOM
  // by the time this callback runs, so `.focus()` has something to focus.
  onMount(() => {
    el.value?.focus();
  });

  return input({ ref: el, placeholder: "Search…" });
});
```

`el.value` — **not** `.current`. Whisq refs are plain signals; React's `.current` naming doesn't apply. See [Common Mistakes → `.current` instead of `.value`](https://whisq.dev/common-mistakes/#current-instead-of-value-on-a-ref) for the spelling trap.

### Focus management across navigations

For a multi-view app, set focus from the component that owns the newly-mounted view:

```ts

const DialogTitle = component((props: { children: string }) => {
  const heading = ref<HTMLHeadingElement>();
  onMount(() => heading.value?.focus());
  // tabindex="-1" makes the element programmatically focusable without
  // adding it to the tab order.
  return h2({ ref: heading, tabindex: -1 }, props.children);
});
```

Same shape for routed pages — the top-of-route component takes a ref on its heading (or a skip-link target) and focuses it on mount.

### Reading a ref in an event handler (untracked)

When an event handler needs the element but shouldn't re-run on ref changes (e.g. you just want to blur on Escape), read with `.peek()`:

```ts
input({
  ref: el,
  onkeydown: (e) => {
    if (e.key === "Escape") el.peek()?.blur();
  },
});
```

Inside effects or reactive getters, read with `.value` — that's what subscribes the consumer.

## Semantic HTML + ARIA together

**Prefer a real semantic element over a `role=`-annotated generic element.** `button()` already carries role, keyboard handling (`Enter` and `Space` fire `onclick`), focusability, and the correct disabled semantics — a `div({ role: "button" })` has none of those for free and needs a full keyboard handler, explicit `tabindex`, and a visual focus style to reach parity.

| When you need… | Reach for… | Not… |
|---|---|---|
| Click or keyboard-activated control | `button({ onclick: … }, label)` | `div({ role: "button", tabindex: 0, onkeydown: … })` |
| Navigation | `a({ href: … }, label)` | `span({ role: "link", onclick: () => navigate(…) })` |
| Named form region | `form({ …, "aria-labelledby": "form-title" })` | `div({ role: "form" })` |
| Accessible heading landmark | `h1()` – `h6()` | `div({ role: "heading", "aria-level": 2 })` |
| Live status text | `div({ role: "status", "aria-live": "polite" }, …)` | `div({}, …)` + DOM poking |

The `role`-on-`div` patterns on the right *do* work with the typed ARIA surface, but you'd be re-implementing semantics the browser gives you for free with the left-hand shapes. Use `role` when there isn't a semantic element for the job (tablists, trees, listboxes) and pair it with the full ARIA surface the pattern requires.

### When you DO need `role` + full ARIA

Building a custom widget (e.g. a tablist, a combobox) means `role` plus several `aria-*` attributes in concert. The typed surface handles all of them:

```ts
// A minimal tab control — role on the container, aria-selected on each tab,
// all using the typed surface.
const selected = signal<"overview" | "billing">("overview");

div({ role: "tablist" },
  button({
    role: "tab",
    "aria-selected": () => selected.value === "overview",
    "aria-controls": "panel-overview",
    onclick: () => selected.value = "overview",
  }, "Overview"),
  button({
    role: "tab",
    "aria-selected": () => selected.value === "billing",
    "aria-controls": "panel-billing",
    onclick: () => selected.value = "billing",
  }, "Billing"),
);
```

Follow the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) patterns for which `aria-*` attributes a given `role` needs — the typed surface will accept any of them.

## Escape hatch — `h(tag, { "custom-attr": … })`

When an attribute isn't in the typed surface at all — a custom data attribute beyond `data-*`, a non-ARIA accessibility attribute added to a new spec, or a web-component property — drop to `h()`. It accepts any prop key with the **same runtime semantics** as the typed element functions: function values become reactive getters, `on*` keys become event listeners, everything else sets an attribute. The only difference from `button()`, `div()`, etc. is that TypeScript imposes no constraint on the key name.

```ts

// A new accessibility attribute not yet on BaseProps.
h("button", { "aria-description": "Saves and closes the dialog" }, "Save");

// A web-component attribute.
h("my-widget", { "data-track": "pricing-cta", "theme-variant": "dark" });

// Reactive shape on a non-standard attribute — treated as a reactive getter,
// not stringified via setAttribute.
h("my-widget", { "selection-index": () => currentIndex.value });
```

The typed element functions (`button`, `div`, `input`, …) are thin wrappers around `h()` that add TypeScript coverage for the well-known prop shapes. Dropping to `h()` gives you the same runtime behaviour with a looser type — use it when TypeScript's strictness is getting in your way, not as a default.

See [`/api/h/`](https://whisq.dev/api/h/) for the full signature and semantics.

## Further reading

- [`/api/elements/#aria-attributes-since-alpha9`](https://whisq.dev/api/elements/#aria-attributes-since-alpha9) — the reference for the ARIA surface, including the serialisation table.
- [`/api/ref/`](https://whisq.dev/api/ref/) — ref shapes, callback form, and the `.value` vs `.current` trap.
- [`/api/h/`](https://whisq.dev/api/h/) — the untyped escape-hatch element factory.
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) — upstream pattern reference for ARIA + keyboard behaviour by widget type.
- [MDN ARIA reference](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) — attribute-by-attribute semantics and serialisation rules.

---
# AI Integration
URL: https://whisq.dev/guides/ai-integration/
---

Whisq is designed for AI-assisted development. The entire API fits in under 5,000 tokens, which means any AI coding assistant can hold the complete framework reference in its context window.

## CLAUDE.md

Every Whisq project includes a `CLAUDE.md` file at the root. This file contains the complete API reference in a format optimized for AI context windows.

To use it with any AI assistant, copy the contents of `CLAUDE.md` and paste it into your conversation. The AI will then generate correct Whisq code.

```bash
# Create a new project — CLAUDE.md is included automatically
npm create whisq@latest my-app
```

The file covers:
- All reactive primitives (`signal`, `computed`, `effect`, `batch`)
- All element functions (`div`, `button`, `input`, etc.)
- Component creation, lifecycle, and rendering
- Conditional rendering (`when`) and list rendering (`each`)
- Common patterns and anti-patterns

## .cursorrules

For Cursor IDE users, Whisq includes a `.cursorrules` file that teaches Cursor how to write idiomatic Whisq code. Place it in your project root:

```
my-app/
  .cursorrules     # Cursor reads this automatically
  CLAUDE.md        # For other AI assistants
  src/
    main.ts
```

## MCP Server

`@whisq/mcp-server` provides deep AI integration through the Model Context Protocol. It enables AI assistants to scaffold components and validate code.

Install it:

```bash
npm install -D @whisq/mcp-server
```

The MCP server provides tools for:
- **Component scaffolding** — generate component boilerplate from a description
- **Code validation** — check that generated code follows Whisq patterns
- **API lookup** — query the API reference programmatically

## Effective Prompts

When asking an AI to write Whisq code, be specific about what you need:

**Good prompts:**

```
Create a Whisq component that shows a list of users fetched from /api/users.
Show a loading state while fetching and an error message if it fails.
Use resource() for data fetching and each() for the list.
```

```
Build a Whisq login form with email and password fields.
Use computed() to validate that email contains @ and password is 8+ chars.
Disable the submit button until the form is valid.
```

```
Create a Whisq store in stores/cart.ts with:
- items signal (array of {id, name, price, qty})
- total computed (sum of price * qty)
- addItem and removeItem functions
```

**What makes these work:** they mention specific Whisq APIs (`resource()`, `computed()`, `signal()`), which guides the AI to use the right patterns.

## Common Patterns AI Generates Well

:::note[Version sourcing]
Scaffolders and codegen tools: resolve the current version from the npm registry, never from a CDN `@latest` alias — see [LLM Reference → Current version](https://whisq.dev/ai/llm-reference/#current-version).
:::

Whisq's function-based API is straightforward for AI to generate correctly:

| Pattern | AI Accuracy | Why |
|---|---|---|
| Signal + reactive text | Very high | `signal()` + `() => value` is simple |
| Event handlers | Very high | Standard DOM events, no special syntax |
| Conditional rendering | High | `when()` has a clear signature |
| List rendering | High | `each()` maps directly to array iteration |
| Form validation | High | `computed()` for derived boolean state |
| Data fetching | High | `resource()` wraps a single promise |

## Tips for Working with AI

1. **Include CLAUDE.md in your context** — paste it at the start of your conversation for the best results.
2. **Name specific APIs** — saying "use `resource()`" is better than "fetch some data."
3. **Show the anti-patterns** — if AI generates `div(count.value)`, point out it should be `div(() => count.value)`. The AI will learn the pattern for the rest of the conversation.
4. **Use stores for shared state** — tell the AI to "create a store in stores/cart.ts" and it will export signals and functions correctly.

:::tip[🐱 Whisker Tip]
The smaller the API, the more accurate AI code generation becomes. Whisq's under-5K-token API surface is a deliberate design choice for this reason.
:::

## Next Steps

- [Quick Start](https://whisq.dev/getting-started/quick-start/) — Set up your first project with AI context files
- [Components](https://whisq.dev/core-concepts/components/) — Understand what AI generates
- [State Management](https://whisq.dev/guides/state-management/) — The store pattern AI handles well

---
# Data Fetching
URL: https://whisq.dev/guides/data-fetching/
---

Whisq's `resource()` wraps a promise and exposes reactive `loading()`, `error()`, and `data()` [accessors](https://whisq.dev/core-concepts/signals/#getters-and-accessors). The canonical way to render its three-way state is `match()` — **prefer `match()` over chained `when()` calls** for any loading/error/data UI.

See [Conditional Rendering — match()](https://whisq.dev/core-concepts/conditional-rendering/#match--three-or-more-branches) for the primitive itself.

## Basic Fetch

```ts

const users = resource(() =>
  fetch("/api/users").then((r) => r.json()),
);

div(
  match(
    [() => users.loading(),  () => p("Loading…")],
    [() => !!users.error(),  () => div(
      p(() => `Error: ${users.error()!.message}`),
      button({ onclick: () => users.refetch() }, "Retry"),
    )],
    [() => !!users.data(),   () => ul(each(() => users.data()!, (u) => li(u.name)))],
  ),
);
```

`resource()` starts fetching immediately, so the three branches cover every state: `loading()` is true in flight, `error()` holds the rejection on failure, `data()` holds the value on success. `match()` picks the first truthy branch. Bundling the retry button into the **error branch** is the canonical retry pattern — users only see it when they need it.

No `match()` fallback is needed here: for an eager `resource()`, at least one of the three predicates is always true, so a trailing bare function would be unreachable. Reach for a fallback only with resources that can start in a non-loading idle state (for example, lazy resources created but not yet triggered).

## Resource Accessors

```ts
const posts = resource(() =>
  fetch("/api/posts").then((r) => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);
    return r.json();
  }),
);

posts.loading();   // boolean — true while fetching
posts.error();     // Error | undefined — rejection reason if failed
posts.data();      // T | undefined — resolved value if successful
posts.refetch();   // re-run the fetcher
```

Inside the error branch of `match()`, the non-null assertion on `resource.error()!` is safe: the branch only runs when the predicate `!!resource.error()` was true, so the accessor is guaranteed to return an `Error`.

:::tip[🐱 Whisker Tip]
Always check `r.ok` in your fetch call. `fetch()` doesn't throw on 404 or 500 responses — only on network failures. Without the check, `match()`'s error branch never fires and the data branch receives an error-shaped body.
:::

## Refetching on User Action

`refetch()` re-runs the original fetcher. The canonical place to surface it is the error branch (as in Basic Fetch above), but you can also expose it as a "refresh" affordance:

```ts

const todos = resource(() =>
  fetch("/api/todos").then((r) => r.json()),
);

div(
  button({ onclick: () => todos.refetch() }, "Refresh"),
  match(
    [() => todos.loading(),  () => p("Loading…")],
    [() => !!todos.error(),  () => p(() => `Error: ${todos.error()!.message}`)],
    [() => !!todos.data(),   () => ul(each(() => todos.data()!, (t) => li(t.title)))],
  ),
);
```

When `refetch()` fires, the resource briefly returns `loading()` → true; `match()` re-evaluates and renders the loading branch until the new response lands.

## Dependent Fetches

Refetch when a signal changes by calling `refetch()` from an `effect()`:

```ts

const category = signal("all");

const products = resource(() =>
  fetch(`/api/products?category=${category.value}`).then((r) => r.json()),
);

effect(() => {
  category.value;   // track the dependency
  products.refetch();
});

div(
  select({ ...bind(category) },
    option({ value: "all" }, "All"),
    option({ value: "books" }, "Books"),
    option({ value: "electronics" }, "Electronics"),
  ),
  match(
    [() => products.loading(),  () => p("Loading…")],
    [() => !!products.error(),  () => p(() => `Error: ${products.error()!.message}`)],
    [() => !!products.data(),   () => ul(each(() => products.data()!, (item) => li(item.name)))],
  ),
);
```

The `select` uses `bind(category)` for two-way binding; when the user picks a new value, `category` updates, the `effect()` re-runs, `refetch()` kicks off a new request, and `match()` swaps back to the loading branch until it lands.

:::danger[Common Mistake: static fetcher]
```ts
// ❌ WRONG — resource fetcher runs once at creation time with the
// initial category.value; later changes never trigger a new fetch.
const products = resource(() =>
  fetch(`/api/products?cat=${category.value}`),
);

// ✅ RIGHT — use effect() to refetch on dependency change
effect(() => {
  category.value;
  products.refetch();
});
```
:::

## Posting Data

`resource()` is for reading. For mutations (POST, PUT, DELETE), use regular signals and an async function:

```ts

const saving = signal(false);
const error = signal<string | null>(null);

const saveUser = async (payload: { name: string }) => {
  saving.value = true;
  error.value = null;
  try {
    const res = await fetch("/api/users", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    });
    if (!res.ok) throw new Error("Save failed");
  } catch (e) {
    error.value = e instanceof Error ? e.message : "Unknown error";
  } finally {
    saving.value = false;
  }
};

div(
  button({
    onclick: () => saveUser({ name: "Alice" }),
    disabled: () => saving.value,
  }, () => (saving.value ? "Saving…" : "Save")),
  when(() => !!error.value, () =>
    p({ class: "error" }, () => error.value),
  ),
);
```

Mutation flows are usually single-outcome (succeed or show an error), so a plain `when()` on the error signal is appropriate. Reach for `match()` only when the UI has three or more distinct states.

:::tip[🐱 Whisker Tip]
`resource()` is for reading data. For writes, use regular async functions with signals for `saving` and `error` state.
:::

## Next Steps

- [Conditional Rendering](https://whisq.dev/core-concepts/conditional-rendering/) — `when()`, `match()`, and when to reach for each.
- [State Management](https://whisq.dev/guides/state-management/) — share fetched data across components.
- [Persistence recipe — remote source of truth + local cache](https://whisq.dev/guides/state-management/#recipe--remote-source-of-truth--local-cache) — pair `resource()` with `persistedSignal()` for instant first-paint from cached data.
- [Forms](https://whisq.dev/guides/forms/) — `bind()` for two-way input binding, covered end-to-end.
- [Lifecycle](https://whisq.dev/core-concepts/lifecycle/) — clean up subscriptions with `onCleanup`.

---
# Forms
URL: https://whisq.dev/guides/forms/
---

Forms in Whisq work with standard DOM events and reactive signals. There's no special form library — just `signal()` for state, `computed()` for validation, element functions for the UI, and **`bind()`** to wire an input to a signal in one line.

See [all `@whisq/*` entry points](https://whisq.dev/api/imports/) for the complete sub-path list (`/forms` for `bindPath`, plus the other helpers used elsewhere in the docs).

:::tip[Convention: spread `bind()` last]
When mixing `bind(...)` with your own event handlers (e.g. `oninput` for analytics, `onchange` for form-dirty tracking), **spread `bind()` LAST** in the props object. Your handler appears first, so if the two collide it's `bind`'s that visibly wins. Pre-alpha.9 the reverse order silently dropped `bind`'s handler; alpha.9+ dev warns on it, but only direction 1 is detectable — the convention makes direction 2 safe by construction. See [`/api/bind/#handler-collision-dev-warning-since-alpha9`](https://whisq.dev/api/bind/#handler-collision-dev-warning-since-alpha9).
:::

## Basic Input Binding

Spread `bind(signal)` into an input to get two-way binding:

```ts

const name = signal("");

div(
  input({ placeholder: "Your name", ...bind(name) }),
  p(() => `Hello, ${name.value || "stranger"}!`),
);
```

That's it. The signal holds the latest value at all times; `name.value` always reflects what's typed.

## Input Types

`bind()` covers every common input type. Pass the right signal type and (for non-text types) an `as:` option:

```ts

const email = signal("");
const age = signal(0);
const bio = signal("");
const role = signal("dev");
const tier = signal<"free" | "pro">("free");
const agreed = signal(false);

div(
  label("Email"),
  input({ type: "email", ...bind(email) }),

  label("Age"),
  input({ type: "number", ...bind(age, { as: "number" }) }),

  label("Bio"),
  textarea({ ...bind(bio) }),

  label("Role"),
  select({ ...bind(role) },
    option({ value: "dev" }, "Developer"),
    option({ value: "design" }, "Designer"),
    option({ value: "pm" }, "Product Manager"),
  ),

  label(
    input({ type: "radio", name: "tier", ...bind(tier, { as: "radio", value: "free" }) }),
    " Free",
  ),
  label(
    input({ type: "radio", name: "tier", ...bind(tier, { as: "radio", value: "pro" }) }),
    " Pro",
  ),

  label(
    input({ type: "checkbox", ...bind(agreed, { as: "checkbox" }) }),
    " I agree to the terms",
  ),
);
```

:::tip[🐱 Whisker Tip]
- Text / email / tel / url / password / search inputs, `textarea`, and `select` all take the default form: `bind(signal)` expecting `Signal<string>`.
- Numbers need `{ as: "number" }` so the helper coerces between the input's string value and your `Signal<number>`.
- Checkboxes need `{ as: "checkbox" }` (uses `checked` + `onchange` under the hood).
- Radios share one signal across a radio group — pass `{ as: "radio", value: "..." }` once per radio.
:::

## Form Submission

Handle submission with `onsubmit` and `preventDefault`:

```ts

const ContactForm = component(() => {
  const email = signal("");
  const message = signal("");
  const submitted = signal(false);

  const handleSubmit = (e: Event) => {
    e.preventDefault();
    console.log({ email: email.value, message: message.value });
    submitted.value = true;
  };

  return form({ onsubmit: handleSubmit },
    label("Email"),
    input({ type: "email", ...bind(email) }),
    label("Message"),
    input({ ...bind(message) }),
    button("Send"),
    p(() => (submitted.value ? "Sent!" : "")),
  );
});
```

## Validation

Derive validation state with `computed()` over the bound signals:

```ts

const SignupForm = component(() => {
  const email = signal("");
  const password = signal("");

  const emailValid = computed(() => email.value.includes("@"));
  const passwordValid = computed(() => password.value.length >= 8);
  const formValid = computed(() => emailValid.value && passwordValid.value);

  return form({ onsubmit: (e) => { e.preventDefault(); } },
    label("Email"),
    input({ type: "email", ...bind(email) }),
    when(() => email.value && !emailValid.value,
      () => p({ class: "error" }, "Enter a valid email address"),
    ),

    label("Password"),
    input({ type: "password", ...bind(password) }),
    when(() => password.value && !passwordValid.value,
      () => p({ class: "error" }, "Password must be at least 8 characters"),
    ),

    button({ disabled: () => !formValid.value }, "Sign Up"),
  );
});
```

Validation messages only appear after the user starts typing — `email.value && !emailValid.value` keeps the error hidden when the field is empty.

:::danger[Common Mistake]
```ts
// ❌ WRONG — disabled is static, never updates
button({ disabled: !formValid.value }, "Sign Up")

// ✅ RIGHT — disabled is reactive
button({ disabled: () => !formValid.value }, "Sign Up")
```
:::

## Form Reset

Reset all signals to their initial values:

```ts
const email = signal("");
const password = signal("");

const reset = () => {
  email.value = "";
  password.value = "";
};

form({ onsubmit: handleSubmit },
  // ... fields using ...bind(email), ...bind(password)
  button({ type: "button", onclick: reset }, "Reset"),
  button("Submit"),
);
```

Because `bind()` reads from the signal reactively, clearing the signal clears the input — no extra wiring needed.

:::tip[🐱 Whisker Tip]
Use `type: "button"` on the reset button to prevent it from submitting the form.
:::

## Binding fields inside list items

`bind()` covers "one input, one signal." For per-row inputs in a list — checkboxes per todo, quantity inputs in a cart, edit fields in a CRUD grid — reach for `bindField(source, item, key, options?)`. It's the same discriminator surface (text / number / checkbox / radio) but reaches into a field on an item inside a signal-held array.

```ts

interface Todo { id: number; text: string; done: boolean }

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: false },
  { id: 2, text: "Build an app", done: false },
]);

ul(
  each(() => todos.value, (todo) =>
    li(
      input({ type: "checkbox", ...bindField(todos, todo, "done", { as: "checkbox" }) }),
      input({ ...bindField(todos, todo, "text") }),
    ),
    { key: (t) => t.id },
  ),
)
```

Three things to notice:

- `todo` is the keyed-`each()` accessor — `bindField`'s second argument expects exactly that shape.
- Writes produce **immutable array updates** — the array is reassigned, not mutated. Downstream `computed`, `effect`, and other keyed-`each()` blocks reconcile correctly.
- If the item is removed from `source` between render and the user's edit, the write **logs a console warning and is discarded** rather than silently corrupting state. Custom item shapes can override the default `t => t.id` lookup with `{ keyBy: (t) => t.uuid }`.

See [`/api/bindfield/`](https://whisq.dev/api/bindfield/) for every variant.

## Binding into nested records

For the third common case — fields nested inside an object held by a single signal (`user.profile.email`, `settings.billing.plan`) — reach for `bindPath(source, path, options?)` from `@whisq/core/forms`. It lives on a sub-path so apps that don't need it pay no bundle cost.

```ts

interface User {
  profile: { name: string; email: string; age: number };
  prefs: { dark: boolean };
}

const user = signal<User>({
  profile: { name: "", email: "", age: 0 },
  prefs: { dark: false },
});

form(
  label("Name", input({ ...bindPath(user, ["profile", "name"]) })),
  label("Email", input({ type: "email", ...bindPath(user, ["profile", "email"]) })),
  label("Age", input({ type: "number", ...bindPath(user, ["profile", "age"], { as: "number" }) })),
  label("Dark mode", input({ type: "checkbox", ...bindPath(user, ["prefs", "dark"], { as: "checkbox" }) })),
)
```

Three things to know:

- **Structural sharing on writes.** Each write produces a new root and new objects at every level on the path; sibling branches keep their reference identity. Downstream `computed` / `effect` that depend on unaffected branches don't re-run.
- **Object keys only — no array traversal.** `["items", 0]` would treat `0` as an object key. For per-item fields inside an array, use `bindField()` at the array level (see the section above) and compose with `bindPath` for nested-object cells.
- **TypeScript checks paths through depth 4** — autocomplete + misuse detection on `path` keys against the parent shape. Deeper paths fall through to a loose signature.

See [`/api/bindpath/`](https://whisq.dev/api/bindpath/) for every variant and the full semantics.

## Why `bind()` exists

Under the hood, `bind(signal)` on a text input expands to the same prop pair you'd write by hand:

```ts
// What ...bind(name) expands to for a text input, textarea, or select:
input({
  value: () => name.value,
  oninput: (e) =>
    name.value = (
      e.target as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
    ).value,
})
```

`<select>` fires the `input` event on change too (HTML5 behaviour), which is why the same `bind()` spread works for selects and textareas without a separate overload.

Reach for the manual form only when you genuinely need something `bind()` doesn't cover:

- **Custom event names** — e.g. a web component that emits `value-changed` instead of `input`.
- **Debounced or throttled input** — wrap your own `oninput` around a debounce helper before writing to the signal.
- **Transforms on write** — e.g. trimming whitespace, uppercasing, normalising before assigning.
- **Derived values** — when the input and signal shapes differ enough that coercion via `{ as: "..." }` isn't the right abstraction.

For everything else, use `bind()`.

## Next Steps

- [Signals](https://whisq.dev/core-concepts/signals/) — Deep dive into reactive state.
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — Submit forms to APIs with `resource()`.
- [State Management](https://whisq.dev/guides/state-management/) — Share form state across components.
- [Event types reference](https://whisq.dev/api/event-types/) — `WhisqEvent`, `EventHandler`, and the dev-mode error classes for typed-handler patterns.

---
# Nested Item Editing
URL: https://whisq.dev/guides/nested-item-editing/
---

You have a list of items and want to edit one field on one row — toggle a checkbox, change a number, edit text. There are three idiomatic shapes for this. Pick by your **item shape** (plain object vs. nested signal) and **per-item churn** (how often a single field changes).

Each shape is already documented in depth on its canonical API page. This guide is the decision matrix that points you at the right one.

## Decision matrix

| Pattern | Item shape | Reach for it when | Canonical reference |
|---|---|---|---|
| **1 · Plain immutable update via [`bindField`](https://whisq.dev/api/bindfield/)** | `{ id, text, done: boolean }` — plain JSON values | The default. JSON-serializable items, simple stores, persistence is straightforward. | [`/api/bindfield/`](https://whisq.dev/api/bindfield/) |
| **2 · Nested signal per item via [`bind`](https://whisq.dev/api/bind/)** | `{ id, text, done: Signal<boolean> }` — fields are signals | Per-item field changes are frequent and you want the array signal to stay quiet on toggle (so dependent `computed` / `effect` don't re-run on every keystroke). | [`/examples/todo-app/#the-store`](https://whisq.dev/examples/todo-app/#the-store) |
| **3 · Extracted child component with accessor prop** | Either of the above, but the per-row render is more than ~12 lines | The render is large enough to deserve its own file, or the same row markup is reused in two places. Composes with patterns 1 and 2 — pick one of those for the binding shape, then move it inside the component. | [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component) |

The three shapes compose. A real app frequently uses pattern 3 with pattern 1 inside (CRUD grid: plain JSON items, child component owns the per-row markup) — or pattern 3 with pattern 2 inside (todo-app: nested signals for narrow reactivity, child component to keep `TodoApp.ts` short).

## Pattern 1 — Plain immutable update via `bindField`

Item shape: plain JSON. `bindField` mutates the array immutably (`source.value = source.value.map(...)`) and identifies the item via `keyBy` (defaults to `t => t.id`).

```ts

interface Todo { id: number; text: string; done: boolean }

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: false },
  { id: 2, text: "Build an app", done: false },
]);

ul(
  each(() => todos.value, (todo) =>
    li(
      input({ type: "checkbox", ...bindField(todos, todo, "done", { as: "checkbox" }) }),
      todo.value.text,
    ),
    { key: (t) => t.id },
  ),
)
```

`bindField`'s second argument is typed as `() => T` — the hybrid accessor `todo` (an `ItemAccessor<Todo>`) is structurally compatible, so this works unchanged across alpha.7 → alpha.8.

**Cost:** every toggle creates a new array (cheap for hundreds of items, measurable for tens of thousands). Downstream `computed` / `effect` that depend on `todos.value` re-run on every change. Fine for most apps.

**See also:** the full discriminator table (text / number / checkbox / radio), `keyBy` for non-`id` identifiers, and per-item radio groups on [`/api/bindfield/`](https://whisq.dev/api/bindfield/).

## Pattern 2 — Nested signal per item via `bind`

Item shape: each item holds its own per-field `Signal`. `bind()` consumes a signal reference, so toggling one checkbox flips just that signal — the array signal stays still, and dependent computeds only re-run when they read the changed field.

```ts

interface Todo { id: number; text: string; done: Signal<boolean> }

const todos = signal<Todo[]>([
  { id: 1, text: "Learn Whisq", done: signal(false) },
  { id: 2, text: "Build an app", done: signal(false) },
]);

ul(
  each(() => todos.value, (todo) =>
    li(
      input({ type: "checkbox", ...bind(todo.value.done, { as: "checkbox" }) }),
      todo.value.text,
    ),
    { key: (t) => t.id },
  ),
)
```

**Cost:** items aren't trivially `JSON.stringify`-able — persistence needs a hand-rolled `serialize` / `deserialize` pair, or `persistedSignal` with custom options. The todo-app example shows the inline shape ([`/examples/todo-app/`](https://whisq.dev/examples/todo-app/)).

**Why this shape exists:** the array signal doesn't churn on a single-field edit. If you have a derived `computed(() => todos.value.length)` and many other readers of `todos.value` itself, this keeps them quiet on per-row toggles. Worth the persistence overhead when per-item edits are frequent.

## Pattern 3 — Extracted child component with accessor prop

Same binding shapes as patterns 1 or 2, but the per-row render lives in its own component. The reconciler's accessor passes through the prop boundary as a function reference — call it inside the child the same way as inline.

```ts
// src/components/TodoItem.ts

type Todo = { id: number; text: string; done: Signal<boolean> };

type TodoItemProps = {
  todo: ItemAccessor<Todo>;               // hybrid accessor — read via .value
  onRemove: (id: number) => void;
};

```

Call site:

```ts
each(() => todos.value, (todo) => TodoItem({ todo, onRemove: removeTodo }), { key: (t) => t.id })
```

Swap `bind(props.todo.value.done, { as: "checkbox" })` for `bindField(todos, props.todo, "done", { as: "checkbox" })` if your store holds plain booleans (pattern 1 inside pattern 3) — same row component, different binding shape. (`bindField` accepts the accessor itself, not `.value` — its second argument is typed as `() => T` and the hybrid accessor is structurally compatible.)

**Cost:** one extra file per row type. Pays back when the per-row markup grows past ~12 lines, when the same row is reused in two places, or when the row owns local state of its own.

**Footgun to avoid:** destructure the prop, never the accessor result. `({ todo, onRemove })` works because `todo` is the accessor reference. `const { done } = props.todo.value` (or `const { done } = props.todo()`) captures one entry's `done` at setup time and doesn't update when the reconciler swaps the entry.

**See also:** the full pattern, the four-archetype rule for `todo()` reads, and the same-key swap edge case on [`/api/each/#splitting-into-a-component`](https://whisq.dev/api/each/#splitting-into-a-component).

## Why three patterns and not one

The three patterns trade off the same three things differently:

- **Reactive granularity** — does the array signal churn on every per-row edit (patterns 1 & 3-with-1) or stay still (patterns 2 & 3-with-2)?
- **Persistence ergonomics** — plain JSON shapes round-trip through `JSON.stringify` for free (patterns 1 & 3-with-1); nested-signal shapes need a custom round-trip (patterns 2 & 3-with-2).
- **File-level structure** — inline render keeps related code together (patterns 1 & 2); extracted component pays one extra import for reusability and shorter parent files (pattern 3).

If you only learn one: **default to pattern 1**. Reach for pattern 2 when you measure churn from per-row edits hurting other parts of the app. Reach for pattern 3 when the per-row render outgrows its inline home.

## Next Steps

- [`bindField`](https://whisq.dev/api/bindfield/) — full discriminator surface for pattern 1
- [`bind`](https://whisq.dev/api/bind/) — for pattern 2's per-item signal binding
- [`each`](https://whisq.dev/api/each/#splitting-into-a-component) — accessor-prop pattern for pattern 3
- [Reactive shapes cheat sheet](https://whisq.dev/ai/llm-reference/#reactive-shapes--pick-the-right-one) — the full four-shape taxonomy across the framework
- [Todo App example](https://whisq.dev/examples/todo-app/) — pattern 2 + pattern 3 composed in a real app
- [Components → "Is this a component or just a function?"](https://whisq.dev/core-concepts/components/#is-this-a-component-or-just-a-function) — decision rule for when the per-row markup deserves `component()` vs a plain factory

---
# Routing
URL: https://whisq.dev/guides/routing/
---

`@whisq/router` provides client-side routing built on signals. Routes are reactive — when the URL changes, the matched component renders automatically.

## Setup

Install the router package:

```bash
npm install @whisq/router
```

Create a router with your route configuration:

```ts

const Home = () => div(h1("Home"), p("Welcome to Whisq"));
const About = () => div(h1("About"), p("Learn more about Whisq"));

const router = createRouter({
  routes: [
    { path: "/", component: Home },
    { path: "/about", component: About },
  ],
});

mount(
  div(
    div(
      Link({ href: "/", router }, "Home"),
      Link({ href: "/about", router }, "About"),
    ),
    RouterView(router),
  ),
  document.getElementById("app"),
);
```

`RouterView` renders the component that matches the current URL. `Link` handles navigation without a full page reload.

## Dynamic Routes

Use `:param` syntax for URL parameters:

```ts

const UserPage = component((props: { params: { id: string } }) =>
  div(
    h1(() => `User ${props.params.id}`),
    p("User profile page"),
  )
);

const router = createRouter({
  routes: [
    { path: "/users/:id", component: UserPage },
  ],
});
```

Multiple params work too: `/users/:userId/posts/:postId`.

## Accessing Route State

The router exposes a reactive `current` signal:

```ts
const router = createRouter({ routes: [...] });

// Current route state (reactive)
router.current.value.path;    // "/users/42"
router.current.value.params;  // { id: "42" }
router.current.value.query;   // { sort: "name" } from ?sort=name
```

Use it in your UI:

```ts

div(
  span(() => `Current path: ${router.current.value.path}`),
);
```

## Programmatic Navigation

Navigate from code using `router.navigate()`:

```ts

button({
  onclick: () => router.navigate("/dashboard"),
}, "Go to Dashboard");
```

## Wildcard Routes

Catch unmatched URLs with a wildcard `*` route:

```ts

const NotFound = () =>
  div(h1("404"), p("Page not found"));

const router = createRouter({
  routes: [
    { path: "/", component: Home },
    { path: "/about", component: About },
    { path: "*", component: NotFound },
  ],
});
```

:::tip[🐱 Whisker Tip]
Always put the wildcard route last. Routes are matched in order — the first match wins.
:::

## Active Link Styling

Check `router.current` to style the active link:

```ts

Link({
  href: "/about",
  router,
  class: () =>
    router.current.value.path === "/about" ? "nav-link active" : "nav-link",
}, "About");
```

## Query Parameters

Query strings are automatically parsed and available on the route state:

```ts
// URL: /search?q=Whisq&page=2
router.current.value.query;  // { q: "Whisq", page: "2" }
```

Navigate with query params:

```ts
router.navigate("/search?q=signals&page=1");
```

## Next Steps

- [Components](https://whisq.dev/core-concepts/components/) — Building the page components
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — Load data based on route params
- [SSR](https://whisq.dev/guides/ssr/) — Server-render routed pages

---
# Server-Side Rendering
URL: https://whisq.dev/guides/ssr/
---

`@whisq/ssr` lets you render Whisq components to HTML strings on the server. The browser receives pre-rendered HTML, then Whisq hydrates it into an interactive app on the client.

## Setup

Install the SSR package:

```bash
npm install @whisq/ssr
```

## Basic Server Rendering

Use `renderToString()` to convert a component tree to HTML:

```ts

const Page = () =>
  div(
    h1("Welcome"),
    p("This page was rendered on the server."),
    ul(
      li("Fast initial load"),
      li("SEO friendly"),
      li("Works without JavaScript"),
    ),
  );

const html = renderToString(Page());
// <div><h1>Welcome</h1><p>This page was rendered on the server.</p>...</div>
```

## Express Server Example

Serve a Whisq app from an Express server:

```ts

const App = component(() =>
  div(
    h1("My App"),
    p("Server-rendered with Whisq"),
  )
);

const app = express();

app.get("*", (req, res) => {
  const content = renderToString(App({}));
  res.send(`
    <!DOCTYPE html>
    <html>
      <head><title>My App</title></head>
      <body>
        <div id="app">${content}</div>
        <script src="/client.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);
```

## Hydration

On the client, call `mount()` on the same root element. Whisq attaches event handlers to the existing HTML:

```ts
// client.ts

mount(App({}), document.getElementById("app"));
```

The user sees the server-rendered content immediately, and interactivity kicks in once the client JavaScript loads.

## How It Works

- **Reactive values are evaluated once** — signals are read at render time and their current value is used in the HTML output.
- **Event handlers are stripped** — `onclick`, `oninput`, etc. don't appear in the server HTML. They're attached during hydration.
- **HTML is properly escaped** — attribute values and text content are escaped to prevent XSS.

:::tip[🐱 Whisker Tip]
`renderToString()` produces a static snapshot. For interactive features, the client-side `mount()` call is required.
:::

## When to Use SSR

| Use SSR when... | Use client-only when... |
|---|---|
| SEO matters (public pages, blogs) | App is behind a login |
| Fast first paint is critical | Content is fully dynamic |
| Users have slow connections | App is a dashboard or tool |
| Content doesn't change per-user | Real-time data is the focus |

## Rendering with Data

Fetch data on the server before rendering:

```ts
app.get("/users", async (req, res) => {
  const users = await fetch("https://api.example.com/users")
    .then(r => r.json());

  const Page = () =>
    div(
      h1("Users"),
      ul(users.map(u => li(u.name))),
    );

  const html = renderToString(Page());
  res.send(wrapInShell(html));
});
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — resource() is for client-side fetching
const users = resource(() => fetch("/api/users"));
const html = renderToString(div(when(() => users.data(), ...)));
// resource hasn't resolved yet — HTML will show loading state

// ✅ RIGHT — fetch data before rendering on the server
const users = await fetch("/api/users").then(r => r.json());
const html = renderToString(ul(users.map(u => li(u.name))));
```
:::

## Next Steps

- [Routing](https://whisq.dev/guides/routing/) — Server-render different pages based on URL
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — Client-side data loading after hydration
- [Testing](https://whisq.dev/guides/testing/) — Test server-rendered output

---
# State Management
URL: https://whisq.dev/guides/state-management/
---

Whisq doesn't need a state management library. Shared state is just signals and functions exported from a module. Any component that imports them stays in sync automatically.

## The Store Pattern

Create a file that exports signals and functions:

```ts
// stores/counter.ts

```

Use it in any component:

```ts

const Display = component(() =>
  div(
    span(() => `Count: ${count.value}`),
    span(() => ` (doubled: ${doubled.value})`),
  )
);

const Controls = component(() =>
  div(
    button({ onclick: decrement }, "-"),
    button({ onclick: increment }, "+"),
  )
);
```

Both components share the same state. When `increment()` is called in Controls, the Display updates automatically.

## A Real-World Store

A todo store with add, remove, toggle, and derived state:

```ts
// stores/todos.ts

interface Todo {
  id: string;
  text: string;
  done: boolean;
}

};

};

};
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — mutation doesn't trigger updates
todos.value.push({ id: randomId(), text: "New", done: false });

// ✅ RIGHT — new array triggers reactivity
todos.value = [...todos.value, { id: randomId(), text: "New", done: false }];
```
:::

## Local vs Shared State

**Local state** lives inside a component. Use it for UI state that only that component needs:

```ts

const Accordion = component(() => {
  const open = signal(false);

  return div(
    button({ onclick: () => open.value = !open.value }, "Toggle"),
    when(() => open.value, () => div("Content here")),
  );
});
```

**Shared state** lives in a store module. Use it when multiple components need the same data:

```ts
// stores/auth.ts

```

:::tip[🐱 Whisker Tip]
Keep signals small and focused. Prefer many small signals over one big object. Fine-grained signals mean only the UI that uses a specific value will update when it changes.
:::

## Mutations as named actions

Nothing in the framework forces this — `filter.value = "all"` works exactly the same from any call site. But past the single-screen threshold, **write every mutation as an exported helper function from the store file**, and import both signals and actions from the same module. The rule:

> Store files export (a) the signals and computeds that describe state, (b) the action functions that change it. Consumers import both; mutation happens only inside the store module.

```ts
// ❌ inline mutation at the call site — fine for a single-screen demo,
//    trouble once state is owned by more than one component
button({ onclick: () => (filter.value = "all") }, "All");

// ✅ named action — single place where this mutation can originate
// stores/filters.ts
};

// call site
button({ onclick: () => setFilter("all") }, "All");
```

**Why it matters past the single-screen threshold:**

- **Auditable.** The set of ways state can change is the set of exported action functions. A newcomer reading `stores/filters.ts` sees the full API.
- **One place to hook.** Instrumentation, logging, undo/redo, server sync — all plug into the named action, not into N scattered `signal.value =` sites.
- **Validation / invariants.** `addTodo(text)` can trim, validate, reject empty — a direct `todos.value.push(...)` has no place for that.
- **Refactoring.** Changing the underlying signal shape (plain boolean → nested signal, scalar → `persistedSignal`, etc.) touches one file.

The todo-app example keeps mutations inline (`filter.value = "all"` in `onclick`) for readability — a beginner can trace the state change without tab-switching between files. For anything larger, the named-action pattern saves every team from re-deriving it.

Cross-reference: [`packages/core/docs/project-structure.md`](https://github.com/whisqjs/whisq/blob/main/packages/core/docs/project-structure.md) section on store-file layout states the same rule from the file-structure angle ("each file exports the signals plus the mutation helpers that operate on them").

## Persistence (localStorage)

The project-structure rules say **no import-time network calls** — they break SSR, tests, and first-paint. `localStorage` is different: reads are synchronous, there's no network, and the "read once at module load, write on every change" shape is the natural fit for Whisq's reactive model.

`@whisq/core` ships `persistedSignal(key, initial, options?)` on the `@whisq/core/persistence` sub-path — a `Signal<T>` backed by `localStorage` (or `sessionStorage`). All the SSR / quota / corrupt-JSON guards are handled inside the helper. See [`/api/persistedsignal/`](https://whisq.dev/api/persistedsignal/) for the full options surface and behaviour reference.

See [all `@whisq/*` entry points](https://whisq.dev/api/imports/) for the complete sub-path list.

```ts
// stores/todos.ts

// Mutate normally — every assignment persists.
};
```

Lives on a sub-path so apps that don't need it pay no bundle cost.

### Recipes by data shape

Three patterns cover the persistence story end-to-end. Pick by what your data looks like.

#### Recipe — plain-object state

The default. Use when items are JSON-serializable end-to-end (plain booleans, numbers, strings, nested plain objects). Most apps want this.

```ts

interface Todo { id: string; text: string; done: boolean }

// Optional: validate stored shape and surface diagnostics on bad payloads.
  },
});
```

Add new entries with `randomId()` from `@whisq/core/ids` (UUID-v4 shape, native crypto preferred). The `schema` + `onSchemaFailure` pair is the canonical "validate or fall back to initial, log to Sentry" shape — see [`/api/persistedsignal/`](https://whisq.dev/api/persistedsignal/#options) for the full option surface.

#### Recipe — nested signals (per-item reactive isolation)

When per-item field changes are frequent and you want the array signal to stay quiet on toggle, hold each per-row state in its own `Signal`. `JSON.stringify` can't round-trip a `Signal`, so use a hand-rolled `loadTodos()` + persist-`effect()` pair.

```ts
// stores/todos.ts

function loadTodos(): Todo[] {
  if (typeof localStorage === "undefined") return [];
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    if (!raw) return [];
    const parsed = JSON.parse(raw) as StoredTodo[];
    return parsed.map((t) => ({ id: t.id, text: t.text, done: signal(t.done) }));
  } catch {
    return []; // corrupt payload — start fresh
  }
}

// Re-runs whenever todos.value OR any per-item .done.value changes.
effect(() => {
  const list = todos.value;
  if (typeof localStorage === "undefined") return;
  try {
    const serializable = list.map((t) => ({ id: t.id, text: t.text, done: t.done.value }));
    localStorage.setItem(STORAGE_KEY, JSON.stringify(serializable));
  } catch {
    // Quota exceeded or serialization failure — degrade silently.
  }
});
```

This is the shape the [Todo App example](https://whisq.dev/examples/todo-app/) uses. Pay the boilerplate when narrow per-item reactivity is worth more than the helper-driven 3-liner.

#### Recipe — remote source of truth + local cache

When the data lives on a server and `localStorage` is a freshness cache. `resource()` owns the fetch lifecycle; `persistedSignal` warms the next page-load.

```ts

interface User { id: string; name: string }

const cache = persistedSignal<User[]>("users.cache", []);
  cache.value = fresh;             // warm the cache for next page-load
  return fresh;
}, { initialValue: cache.value }); // hydrate immediately from cache
```

The `initialValue: cache.value` line is what makes first-paint instant — the page renders cached data before the network round-trip finishes, then re-renders when fresh data arrives. See [Data Fetching](https://whisq.dev/guides/data-fetching/) for `resource()`'s full lifecycle.

#### Recipe — persisted settings (single-record + bindPath)

When the data is a single settings record with nested fields — theme, filter, notification prefs — and your UI binds directly into those fields. Compose `persistedSignal<Settings>` for the storage half with [`bindPath`](https://whisq.dev/api/bindpath/) from `@whisq/core/forms` for the per-field binding.

```ts
// stores/settings.ts

interface Settings {
  filter: "all" | "active" | "done";
  theme: { mode: "light" | "dark"; accent: "blue" | "purple" | "green" };
  notifications: { email: boolean; push: boolean };
}

const DEFAULT: Settings = {
  filter: "all",
  theme: { mode: "light", accent: "blue" },
  notifications: { email: true, push: false },
};

```

Call sites use `bindPath` to write into specific leaves — each `bindPath` write produces a new root and new objects along the path only, so unchanged branches keep their reference identity:

```ts
// components/SettingsPanel.ts

form(
  label("Filter",
    select({ ...bindPath(settings, ["filter"]) },
      option({ value: "all" }, "All"),
      option({ value: "active" }, "Active"),
      option({ value: "done" }, "Done"),
    ),
  ),
  label("Theme",
    select({ ...bindPath(settings, ["theme", "mode"]) },
      option({ value: "light" }, "Light"),
      option({ value: "dark" }, "Dark"),
    ),
  ),
  label("Email notifications",
    input({ type: "checkbox", ...bindPath(settings, ["notifications", "email"], { as: "checkbox" }) }),
  ),
);
```

Closes the three-primitive binding story: `bind` for one signal, [`bindField`](https://whisq.dev/api/bindfield/) for a field in an array, `bindPath` for a nested object field — now in a persisted shape. `persistedSignal` handles serialization; the per-path writes preserve reference identity on unchanged branches so dependent `computed` / `effect` only re-run when their branch changed.

### Options

```ts
interface PersistedSignalOptions<T> {
  storage?: "local" | "session";
  serialize?: (value: T) => string;
  deserialize?: (raw: string) => T;
  schema?: (raw: unknown) => T;
  onSchemaFailure?: (err: unknown, raw: string) => void;  // since alpha.8
}
```

- **`storage`** — `"local"` (default; persists across tabs and reloads) or `"session"` (per-tab, cleared when the tab closes).
- **`serialize` / `deserialize`** — override the default `JSON.stringify` / `JSON.parse` for non-JSON storage formats (compressed strings, custom encodings).
- **`onSchemaFailure`** *(since alpha.8)* — diagnostic hook fired synchronously **before** the helper falls back to `initial` when `deserialize` throws (malformed stored JSON) or `schema` throws (validator rejects). Receives the thrown error and the exact raw string read from storage. Use it to log to Sentry, show a recovery UI, or decide between migrate-vs-reset:

  ```ts
  const todos = persistedSignal<Todo[]>("todos", [], {
    schema: validateTodosShape,
    onSchemaFailure: (err, raw) => {
      Sentry.captureException(err, { extra: { key: "todos", raw } });
    },
  });
  ```

  Behaviour notes:

  - **Not invoked on first-visit** — `raw` would be `null`, not a failure.
  - **Not invoked on storage-access errors** (private mode, disabled storage) — those are environment faults, not schema faults; the existing quota-safe path handles them.
  - **Callback errors are caught.** If the callback itself throws, the exception is caught and logged via `console.warn` so a broken diagnostic pipeline can't prevent signal construction.

- **`schema`** — validate the deserialized value before adopting it. Throw to reject and fall back to `initial` (and trigger `onSchemaFailure` if set). Most useful for version migrations:

  ```ts
  const settings = persistedSignal<Settings>("settings", DEFAULT_SETTINGS, {
    schema: (raw) => {
      // alpha shape had `theme: string`; current shape has `theme: { mode, accent }`.
      if (typeof raw === "object" && raw && typeof (raw as any).theme === "string") {
        return { ...(raw as object), theme: { mode: (raw as any).theme, accent: "blue" } } as Settings;
      }
      // Already-current shape: validate, then accept.
      if (typeof raw === "object" && raw && typeof (raw as any).theme === "object") {
        return raw as Settings;
      }
      // Unrecognized shape (a stray string from a buggy build, primitives,
      // anything else) — throw so the helper falls back to DEFAULT_SETTINGS.
      throw new Error("settings: unrecognized stored shape");
    },
  });
  ```

### Documented behaviors

- **SSR-safe.** On the server (`typeof window === "undefined"`) returns a plain signal initialized to `initial`, with no storage subscription.
- **Schema-validated.** If the stored JSON is malformed or `schema` throws, the signal falls back to `initial` rather than crashing at mount.
- **Quota-safe.** If a write throws (`QuotaExceededError`, private-mode Safari), the helper logs a warning and keeps the in-memory value — the app keeps working.
- **Module-scope intent.** Call `persistedSignal` at module scope in your `stores/` file, not inside components. The write effect lives for the module lifetime by design — it has no disposal hook.

### What's still forbidden

The "no import-time I/O" rule still applies to anything network-shaped. Keep `fetch()`, WebSocket connections, and analytics boot calls **out** of module scope — use `resource()` or a user-triggered action. `localStorage` is the specific, blessed exception because it's local and synchronous.

### IndexedDB and larger stores

`persistedSignal` is sized for small, human-readable JSON state. For larger or structured data, reach for a dedicated IndexedDB library and wire its load/save into a regular `signal()` + `effect()` pair. The "module-scope read once, effect-write on change" shape still applies.

## Batch Updates

When updating multiple signals at once, wrap them in `batch()` to avoid intermediate renders:

```ts

const firstName = signal("");
const lastName = signal("");
const age = signal(0);

const loadProfile = (profile: { first: string; last: string; age: number }) => {
  batch(() => {
    firstName.value = profile.first;
    lastName.value = profile.last;
    age.value = profile.age;
  });
  // UI updates once, not three times
};
```

## Composing Stores

Stores can import from other stores:

```ts
// stores/cart.ts

```

## Next Steps

- [Signals](https://whisq.dev/core-concepts/signals/) — How reactivity works under the hood
- [Components](https://whisq.dev/core-concepts/components/) — Building component trees
- [Data Fetching](https://whisq.dev/guides/data-fetching/) — Loading server data into stores

---
# Testing
URL: https://whisq.dev/guides/testing/
---

`@whisq/testing` provides utilities for mounting components in a test environment, querying the DOM, and simulating user interactions. It works with any test runner — Vitest, Jest, or Node's built-in test runner.

## Setup

Install the testing package:

```bash
npm install -D @whisq/testing
```

## Your First Test

```ts

afterEach(cleanup);

const Counter = component((props: { initial?: number }) => {
  const count = signal(props.initial ?? 0);
  return div(
    button({ onclick: () => count.value-- }, "-"),
    span(() => `${count.value}`),
    button({ onclick: () => count.value++ }, "+"),
  );
});

describe("Counter", () => {
  it("renders initial value", () => {
    render(Counter({ initial: 5 }));
    expect(screen.getByText("5")).toBeTruthy();
  });
});
```

`render()` mounts the component into the document. `cleanup()` removes it after each test. `screen` provides query methods to find elements.

## Querying Elements

### By Text

```ts
screen.getByText("Submit");        // throws if not found
screen.queryByText("Submit");      // returns null if not found
```

### By Role

Role queries use implicit ARIA roles — a `<button>` has role `"button"`, an `<input>` has role `"textbox"`:

```ts
screen.getByRole("button");        // finds <button>
screen.getByRole("textbox");       // finds <input>
```

:::tip[🐱 Whisker Tip]
Prefer role queries over text queries. They test what assistive technology sees, and they're less brittle when text changes.
:::

## Simulating Events

Use `fireEvent` to simulate user interactions:

```ts

it("increments on click", () => {
  render(Counter({ initial: 0 }));

  const plus = screen.getByText("+");
  fireEvent.click(plus);

  expect(screen.getByText("1")).toBeTruthy();
});
```

### Available Events

```ts
fireEvent.click(element);
fireEvent.input(element, { target: { value: "hello" } });
fireEvent.change(element, { target: { value: "new value" } });
fireEvent.submit(element);
fireEvent.keydown(element, { key: "Enter" });
fireEvent.keyup(element, { key: "Escape" });
fireEvent.focus(element);
fireEvent.blur(element);
```

## Testing Forms

```ts

const LoginForm = component(() => {
  const email = signal("");
  const valid = computed(() => email.value.includes("@"));

  return form(
    input({
      type: "email",
      placeholder: "Email",
      value: () => email.value,
      oninput: (e) => email.value = e.target.value,
    }),
    button({ disabled: () => !valid.value }, "Sign In"),
  );
});

describe("LoginForm", () => {
  afterEach(cleanup);

  it("disables submit when email is invalid", () => {
    render(LoginForm({}));
    const btn = screen.getByText("Sign In");
    expect(btn.disabled).toBe(true);
  });

  it("enables submit when email is valid", () => {
    render(LoginForm({}));
    const input = screen.getByRole("textbox");
    fireEvent.input(input, { target: { value: "user@example.com" } });
    const btn = screen.getByText("Sign In");
    expect(btn.disabled).toBe(false);
  });
});
```

## Testing Conditional Rendering

```ts

const Alert = component((props: { show: boolean }) => {
  const visible = signal(props.show);
  return div(
    when(() => visible.value, () => p("Alert is visible")),
  );
});

it("shows alert when visible", () => {
  render(Alert({ show: true }));
  expect(screen.queryByText("Alert is visible")).toBeTruthy();
});

it("hides alert when not visible", () => {
  render(Alert({ show: false }));
  expect(screen.queryByText("Alert is visible")).toBeNull();
});
```

:::danger[Common Mistake]
```ts
// ❌ WRONG — getByText throws if element doesn't exist
expect(screen.getByText("Missing")).toBeNull();

// ✅ RIGHT — queryByText returns null safely
expect(screen.queryByText("Missing")).toBeNull();
```
:::

## Test Structure

A recommended file structure for tests:

```
src/
  components/
    Counter.ts
    Counter.test.ts    # test file next to component
  stores/
    todos.ts
    todos.test.ts      # test store logic directly
```

:::tip[🐱 Whisker Tip]
Store tests don't need `render()` — just import the signals and functions, call them, and assert on `.value`. Only test components through the DOM.
:::

## Next Steps

- [Components](https://whisq.dev/core-concepts/components/) — Building the components you'll test
- [Forms](https://whisq.dev/guides/forms/) — Form patterns that need testing
- [State Management](https://whisq.dev/guides/state-management/) — Testing shared stores

---
# Welcome to Whisq
URL: https://whisq.dev/
---

Whisq is a reactive UI framework for JavaScript and TypeScript. Signals for state, functions for UI, and a complete ecosystem — all under 5KB gzipped.

```ts

const count = signal(0);

mount(
  div(
    button({ onclick: () => count.value++ },
      span(() => `Clicked ${count.value} times`),
    ),
  ),
  document.getElementById("app")!,
);
```

## What makes Whisq different

- **AI-native** — the entire API fits in under 5,000 tokens. AI coding assistants generate correct Whisq code on the first attempt.
- **Zero build step** — no JSX, no compiler, no bundler required. Works as plain JavaScript or with any build tool.
- **Signals** — fine-grained reactivity without virtual DOM diffing. Only the DOM nodes that read a signal update when it changes.

## Get started

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin-top: 8px;">

<a href="/getting-started/introduction/" style="display: block; padding: 16px; border: 1px solid var(--sl-color-gray-4); border-radius: 8px; text-decoration: none;">
**Introduction** — What Whisq is and who it's for
</a>

<a href="/getting-started/quick-start/" style="display: block; padding: 16px; border: 1px solid var(--sl-color-gray-4); border-radius: 8px; text-decoration: none;">
**Quick Start** — From zero to running app in 5 minutes
</a>

</div>

## Learn

- **[Core Concepts](https://whisq.dev/core-concepts/signals/)** — Signals, elements, components, styling, rendering
- **[Guides](https://whisq.dev/guides/forms/)** — Forms, data fetching, routing, SSR, testing, AI integration
- **[API Reference](https://whisq.dev/api/signal/)** — Every function documented with examples
- **[Examples](https://whisq.dev/examples/counter/)** — Counter, todo app, dashboard, form validation, real-time data

## Ecosystem

Whisq ships 9 packages that work together:

| Package | What it does |
|---------|-------------|
| `@whisq/core` | Signals, elements, components, lifecycle, styling |
| `@whisq/router` | Client-side routing |
| `@whisq/ssr` | Server-side rendering |
| `@whisq/testing` | Component testing utilities |
| `@whisq/devtools` | Signal inspector and component tree |
| `@whisq/vite-plugin` | File-based routing and HMR |
| `@whisq/mcp-server` | AI tool integration (MCP) |
| `@whisq/sandbox` | Sandboxed code execution |
| `create-whisq` | Project scaffolding |

## AI tools

Whisq is designed for AI-assisted development:

- **[Claude Code](https://whisq.dev/ai/claude-code/)** — CLAUDE.md setup and workflow
- **[Cursor](https://whisq.dev/ai/cursor/)** — .cursorrules configuration
- **[GitHub Copilot](https://whisq.dev/ai/copilot/)** — Tips for accurate completions
- **[MCP Server](https://whisq.dev/ai/mcp-server/)** — Component scaffolding and code validation
- **[LLM Reference](https://whisq.dev/ai/llm-reference/)** — Paste-ready API for any AI assistant