---
url: https://sigx.dev/server/packages/ssr-islands/registry-and-code-splitting/
title: Registry & code splitting
description: Register island components eagerly or lazily, and split each island into its own chunk
---

# Registry & code splitting

<p class="lede">On the client, the islands runtime needs a way to find the component behind each `client:*` marker. The registry maps component names to factories — eagerly, or lazily for per-island code splitting.</p>

## Eager registration

The simplest setup: import the components and register them by name before calling
`hydrateIslands()`.

```ts
import { registerComponent, hydrateIslands } from '@sigx/ssr-islands';
import { Counter } from './components/Counter';

registerComponent('Counter', Counter);
hydrateIslands();
```

Register several at once with `registerComponents` — keys become the names:

```ts
import { registerComponents } from '@sigx/ssr-islands';
import * as Components from './components';

registerComponents(Components); // { Counter, Chart, … }
```

The name you register **must** match the component name the server serialized into
the island data.

> **Trade-off:** eager registration imports every island's code up front, so it is
> all in the initial bundle — simple, but no code splitting.

## Lazy registration & per-island chunks

To download an island's code only when its strategy fires, register a **loader**
instead of a component. The loader's `import()` runs on demand:

```ts
import { registerComponentChunk } from '@sigx/ssr-islands/client';

registerComponentChunk('Counter', () => import('./Counter').then((m) => m.Counter));
```

A `client:visible` island registered this way downloads its chunk only when it
scrolls into view.

> **You rarely write this by hand.** The `sigxIslandsPlugin` Vite transform
> generates these `registerComponentChunk` calls automatically from your islands,
> keyed by a stable file-path id. Hand-write loaders only for components the
> transform doesn't cover.

### Resolution order

When an island needs its component, the runtime resolves it in order:

1. **Eager registry** — already loaded via `registerComponent`.
2. **Lazy registry** — registered via `registerComponentChunk`.
3. **Direct chunk URL** — from the SSR manifest (`IslandInfo.chunkUrl`), see
   [Plugin setup](/server/packages/ssr-islands/plugin-setup).

`loadIslandComponent(info)` runs this full resolution (with in-flight dedup);
`resolveComponent(name)` checks the eager then lazy registries and caches the
result for instant subsequent lookups.

## Prefetching

For deferred islands, warm the browser cache early with
`<link rel="modulepreload">` so the chunk is ready before the strategy fires:

```ts
import { prefetchIslandChunks, getIslandData } from '@sigx/ssr-islands';

// On DOMContentLoaded — prefetch all deferred islands' chunks
prefetchIslandChunks(getIslandData());
```

Pass a list of strategies to limit which islands are prefetched (default: all
deferred strategies).

## The registry class

For advanced cases, `HydrationRegistry` is the class behind the module-level
helpers — useful when you want an isolated registry instance:

```ts
import { HydrationRegistry } from '@sigx/ssr-islands';
import { Counter } from './components/Counter';

const registry = new HydrationRegistry()
    .register('Counter', Counter)
    .registerLazy('Chart', () => import('./Chart').then((m) => m.Chart));

await registry.resolve('Chart'); // ComponentFactory | undefined
```

## Next steps

- [Plugin setup](/server/packages/ssr-islands/plugin-setup) — manifests, options, and signal-state transfer.
- [Client directives](/server/packages/ssr-islands/client-directives) — pair lazy chunks with `client:visible`.
- [API reference](/server/packages/ssr-islands/api)

---
url: https://sigx.dev/terminal/packages/runtime-terminal/installation/
title: Installation
description: Install and configure @sigx/runtime-terminal, the Runtime Terminal package for SignalX Terminal.
---

# Installation

<p class="lede">Add `@sigx/runtime-terminal` to your project.</p>

## Install the package

```bash
pnpm add @sigx/runtime-terminal
```

## Verify

```tsx
import * as RuntimeTerminal from '@sigx/runtime-terminal';

console.log(Object.keys(RuntimeTerminal));
```

---
url: https://sigx.dev/server/packages/server-renderer/request-lifecycle/
title: The request lifecycle
description: Set status codes and redirects from a component with useResponse, catch render failures with one error seam, and the WinterCG-clean ./node entry split
---

# The request lifecycle

<p class="lede">SSR is a request/response cycle, and a component sometimes needs to shape the response — a 404, a redirect, a header — or to fail gracefully. This is the seam for that, plus the runtime split that keeps the renderer edge-portable.</p>

## Shaping the response from a component

`useResponse()` returns a recorder you call synchronously during setup — the same timing rule as `useHead`:

```tsx
import { component } from 'sigx';
import { useResponse } from '@sigx/server-renderer';

const NotFound = component(() => {
    useResponse().status(404);
    return () => <h1>Not found</h1>;
});

const Guard = component(() => {
    if (!loggedIn()) useResponse().redirect('/login');
    return () => <Dashboard />;
});
```

The recorder has three methods:

```ts
interface ResponseRecorder {
    status(code: number): ResponseRecorder;                        // last write wins
    redirect(location: string, status?: number): ResponseRecorder; // default 302
    header(name: string, value: string): ResponseRecorder;         // last write per name; names lowercased
}
```

Two properties make it safe to call from components you also render on the client:

- **Inert off the server.** On the client, and anywhere outside a server render, the calls are no-ops — so a shared component needs no `typeof window` branching.
- **Concurrency-safe.** There's no module-level state; the recorder lives on the per-request context, so parallel requests never collide.

A redirect short-circuits a streaming document: the shell promise resolves with the redirect and **no body bytes are produced**.

The resolved response is what the document shell promise gives you:

```ts
interface SSRResponse {
    status: number;                     // explicit status, else redirect status, else 200
    headers: Record<string, string>;
    redirect?: { location: string; status: number };
}
```

## One error seam

Render failures — a component throwing during the synchronous shell, or during a streamed deferred render, or a request-level shell/stream failure — all arrive at a single pair of callbacks on `SSRContextOptions` (and so on `DocumentOptions`):

```ts
interface SSRContextOptions {
    streaming?: boolean;                                    // default true
    onError?: (error: Error, info: SSRErrorInfo) => void;
    renderError?: (error: Error, info: SSRErrorInfo) => string;
}

interface SSRErrorInfo {
    phase: 'shell' | 'stream';   // 'shell' = before the first byte could flush
    componentId?: number;
    componentName?: string;
    boundaryId?: number;
}
```

`onError` is your reporting hook; `renderError` lets you substitute the markup emitted in place of a failed component. The default `renderError` emits a stable `<!--ssr-error:ID-->` boundary comment plus a visible dev diagnostic.

## Server error scopes

`errorScope` works on the server the same way it does in the browser — but with a rewind. A throw below a scope bubbles to the owning frame, which **rewinds everything its subtree produced** (buffered bytes, pending async, head config, boundary records, the id stack) and renders the scope's `fallback(err, retry)` in its place. Scoped subtrees suppress mid-subtree flushing precisely so this rewind is always possible.

The caught boundary is marked in `__SIGX_BOUNDARIES__` with an `errorScope: { message }`. On hydration the client seeds that scope already-errored, so the fallback hydrates cleanly and `retry()` performs a real remount. A scope-caught error fires that **scope's** `onError`, not the request-level one — nearest scope wins.

## The `./node` entry

The renderer's main entries — `@sigx/server-renderer` and `@sigx/server-renderer/server` — are WinterCG-clean: they import no Node built-ins, so they run on edge runtimes (a CI job enforces this by streaming a document through the production build with every Node import forbidden). Anything that touches `node:stream` lives in a separate entry:

```ts
import {
    renderToNodeStream,
    renderDocumentToNodeStream,
    toNodeStream,
    createRequestHandler,
} from '@sigx/server-renderer/node';
```

Reach for `@sigx/server-renderer/node` when you're on Node and want a `Readable`; stay on the root/`/server` entries for edge and Web-stream targets. See the [API reference](/server/packages/server-renderer/api) for each signature.

## The document head, upgraded

`useHead` (from `sigx`) gained document-level controls for SSR, applied by `@sigx/server-renderer`'s head renderer:

- **`base`** — one `<base>` per document; last config wins.
- **`noscript`** / **`style`** — raw markup, opt-in per entry via an explicit `innerHTML` field.
- **`priority`** — server-render ordering, ascending (default `0`, ties in call order, lower = earlier). Client-side SPA application stays per-call and does not reorder the live head.

`htmlAttrs` / `bodyAttrs` now patch the document template's `<html>` / `<body>` tags server-side, and raw content has closing-tag sequences neutralized.

## Where to go next

- [The boundary model](/server/packages/server-renderer/boundaries) — flush and hydrate axes
- [Building a full SSR app](/server/packages/server-renderer/full-app) — entry-server, entry-client and the request handler
- [The fetch handler](/server/packages/server-renderer/fetch-handler) — the WinterCG production handler these entries make possible
- [Vite SSR mode](/vite/docs/ssr) — the build and dev-server side

---
url: https://sigx.dev/actors/packages/actors-cloudflare/installation/
title: Installation
description: wrangler.jsonc bindings and migrations, the __DEV__ define, and the three settings that are easy to get wrong
---

# Installation

<p class="lede">One binding, one migration line, and one <code>define</code> — each of which
fails in a way that is hard to diagnose if you miss it.</p>

## Install

```bash
pnpm add @sigx/actors-cloudflare
pnpm add -D wrangler
```

## `wrangler.jsonc`

```jsonc
{
    "main": "src/worker.ts",
    // Pinned, never floating: a compatibility date is how Workers versions
    // runtime behaviour, so bumping it is a deliberate change to test.
    "compatibility_date": "2026-07-01",
    "compatibility_flags": ["nodejs_compat"],

    "durable_objects": {
        "bindings": [{ "name": "ACTORS", "class_name": "ActorHost" }]
    },

    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ActorHost"] }],

    "define": { "__DEV__": "false" },

    "observability": { "enabled": true }
}
```

## The three that bite

> **`new_sqlite_classes`, not `new_classes` — a one-way door.** `new_classes` creates the
> legacy key-value backed storage, which **cannot be migrated to SQLite in place**; the class
> is stuck with it forever, and it carries a far smaller per-value limit. This is the single
> most consequential irreversible line in the file.

> **`__DEV__` must be defined by your bundler.** The published package ships both a dev and a
> production dist and expects the flag to be defined. Without it the host throws
> `__DEV__ is not defined` on the first request. `pnpm dev` should override it to `true` for
> local warnings.

> **`nodejs_compat` is required.** [Interleaving](/actors/docs/reentrancy) needs
> `AsyncLocalStorage`.

## The entry

```ts
export class ActorHost extends createHostDurableObject<Env>({
    actors, namespace: (env) => env.ACTORS, app: createApp,
}) {}

export default createWorkerHandler<Env>({
    actors, namespace: (env) => env.ACTORS, app: createApp,
    fetch: { origin: false, fallback: servePage },
});
```

Pass an app **factory**, not an app — building at module scope binds whichever object
constructed it first. And set `origin` explicitly: the public mount defaults to refusing a
request with no `Origin`, and Workers callers send none.

Both are explained in [Cloudflare Workers](/actors/docs/cloudflare-workers).

## Types

`Env` is worth declaring by hand rather than generating with `wrangler types` — one binding is
not worth a generated file that has to be committed, kept in step with `wrangler.jsonc` and
excluded from lint.

```ts
export interface Env { ACTORS: DurableObjectNamespace }
```

## Verify

```bash
pnpm wrangler dev
```

Local `wrangler dev` numbers describe the local harness, not Cloudflare — do not read
performance conclusions from them.

## Next steps

- [API reference](/actors/packages/actors-cloudflare/api) — exports.
- [Cloudflare Workers](/actors/docs/cloudflare-workers) — placement, eviction and alarms.
- [Tasks](/actors/docs/tasks) — the checkpoint posture under eviction.

---
url: https://sigx.dev/server/packages/ssr-islands/client-directives/
title: Client directives
description: The six client:* selective-hydration strategies — load, idle, visible, media, interaction, only
---

# Client directives

<p class="lede">A `client:*` directive on a component tells the islands plugin to hydrate it — and <em>when</em>. Components without a `client:*` directive render to static HTML and ship no client JavaScript.</p>

The attributes need no import to type-check — installing the pack is enough. See
[Installation](/server/packages/ssr-islands/installation).

## The strategies

```tsx
<Counter client:load />                       {/* hydrate immediately */}
<Sidebar client:idle />                       {/* hydrate when the browser is idle */}
<Chart client:visible />                      {/* hydrate when scrolled into view */}
<Menu client:media="(min-width: 768px)" />    {/* hydrate when the query matches */}
<Search client:interaction />                 {/* hydrate on the first interaction */}
<LiveFeed client:only />                       {/* skip SSR, mount fresh on the client */}
```

### client:load

Hydrates as soon as `hydrateIslands()` runs. Use for above-the-fold interactivity
that must be live immediately (primary nav, a hero CTA).

### client:idle

Defers hydration to browser idle time (`requestIdleCallback`, with a timeout
fallback). Good for secondary widgets that should not compete with first paint.

### client:visible

Hydrates when the element scrolls into the viewport, via `IntersectionObserver`.
Ideal for below-the-fold islands — charts, comment threads, carousels — so their
JS only loads when the user reaches them. Pairs naturally with lazy registration
for [per-island code splitting](/server/packages/ssr-islands/registry-and-code-splitting).

### client:media

Hydrates when a CSS media query matches. Pass the query as the value:

```tsx
<MobileMenu client:media="(max-width: 767px)" />
<DesktopNav client:media="(min-width: 768px)" />
```

The component stays static until (and unless) the query matches — so a desktop
visitor never pays for the mobile menu's JavaScript, and vice versa.

### client:interaction

Hydrates on the **first interaction** with the element — the first `pointerdown`,
`keydown`, `touchstart`, or `focusin`. It fires once, and the triggering event is
**not** replayed, so the island wakes and the user's next action lands on the live
component. Ideal for controls that are visible but only matter once touched — a
search box, a "reply" affordance, a menu that opens on click — where you want the
static HTML immediately and the JavaScript only when the user commits.

### client:only

**Genuinely skips server rendering.** The component is **not** run on the server:
its `setup`/render never execute, and the server emits an empty
`<div data-boundary>` placeholder in its place — no server HTML for the component
itself. The island still gets a boundary record in `__SIGX_BOUNDARIES__` (so the
client knows to mount it), but with **no captured signal `state`**, since nothing
ran server-side. On the client it mounts **fresh**.

Use it for components that cannot render on the server — ones that read `window`,
`localStorage`, or other browser-only globals during setup.

Contrast with `client:load`, which **does** render on the server (you get the SSR
HTML immediately) and then hydrates that existing DOM, resuming from the captured
signal state. Reach for `client:only` only when server rendering is impossible or
unwanted; otherwise a server-rendered strategy gives a faster first paint.

## The strategy type

The six strategies are the `HydrationStrategy` union, and the directives are the
`ClientDirectives` interface that augments component attributes:

```ts
type HydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'interaction' | 'only';

interface ClientDirectives {
    'client:load'?: boolean;
    'client:idle'?: boolean;
    'client:visible'?: boolean;
    'client:media'?: string;   // the media query
    'client:interaction'?: boolean;
    'client:only'?: boolean;
}
```

### Directives vs. boundary axes

These directives are the islands pack's friendly surface over the two [boundary
axes](/server/packages/server-renderer/boundaries). The two vocabularies don't
line up one-to-one, and it's worth knowing why: `client:only` is a **flush**
concern — it maps to `{ flush: 'skip', hydrate: 'load' }` — while the boundary
model's `hydrate: 'never'` (server HTML, no client component) has no directive of
its own. So don't read the directive list and the `hydrate` axis as the same enum.

## Cleaning up on SPA navigation

Deferred strategies register observers and listeners (`IntersectionObserver`,
`matchMedia`) for islands that have not triggered yet. When you navigate away in
an SPA before they fire, call `cleanupPendingHydrations()` to tear those down and
avoid leaks:

```ts
import { cleanupPendingHydrations } from '@sigx/ssr-islands';

router.beforeEach(() => {
    cleanupPendingHydrations();
});
```

## Next steps

- [Registry & code splitting](/server/packages/ssr-islands/registry-and-code-splitting) — make islands' components resolvable on the client.
- [Plugin setup](/server/packages/ssr-islands/plugin-setup) — register the server plugin and transfer signal state.
- [API reference](/server/packages/ssr-islands/api)

---
url: https://sigx.dev/server/packages/server-renderer/fetch-handler/
title: The fetch handler
description: "createFetchHandler — one WinterCG production handler for every fetch-shaped runtime: Cloudflare Workers, Deno, Bun, Vercel Edge and Netlify"
---

# The fetch handler

<p class="lede">`createFetchHandler` is the WinterCG sibling of `createRequestHandler`: a production request handler expressed in Web primitives — `(Request, platform?) => Promise<Response>` — so the same app deploys to Cloudflare Workers, Deno, Bun, Vercel Edge and Netlify. Same dispatch decisions as the Node handler, no Node built-ins.</p>

## One handler, every platform

```ts
import { createFetchHandler } from '@sigx/server-renderer/server';

const handler = createFetchHandler({
    template,
    app: (url) => createApp(url),   // fresh app per request
    document: { assets },           // manifest preloads etc.
});

export default {
    fetch: (request: Request) => handler(request),
};
```

The `{ fetch }` default export is the portable entry shape every platform accepts.
It mirrors the [Node handler](/server/packages/server-renderer/full-app#a-shortcut-createrequesthandler)
decision for decision:

- **Bots get a complete document.** The crawler check flips the render to
  `mode: 'blocking'` — full inline content, no replacement scripts. Everyone else
  streams shell-first.
- **The shell decides the response head.** Status, headers and redirects recorded
  with [`useResponse`](/server/packages/server-renderer/request-lifecycle) resolve
  before the first byte; a redirect sends `Location` and no body.
- **A shell failure is a minimal 500.** There is no `next()` in the fetch world —
  a custom error page is a wrapper around the returned handler.

Also exported from the root entry (`@sigx/server-renderer`); both entries are
WinterCG-clean, so the import works on every edge runtime.

## Options

```ts
interface FetchHandlerOptions<TPlatform = unknown> {
    template:
        | string
        | ((url: string, request: Request, platform: TPlatform) => string | Promise<string>);
    app: (url: string, request: Request, platform: TPlatform) =>
        App | JSXElement | Promise<App | JSXElement>;
    document?:
        | Omit<DocumentOptions, 'template' | 'mode'>
        | ((url: string, request: Request, platform: TPlatform) =>
              Omit<DocumentOptions, 'template' | 'mode'>);
    isBot?: (userAgent: string, request: Request) => boolean;
    ssr?: Pick<SSRInstance, 'renderDocumentChunks'>;
}
```

The contract is frozen with the Node and dev handlers: `app` builds a **fresh app
per request** from the path + query (`/about?tab=1`) — per-request provides
(router, cache) are what make concurrent SSR safe — so one `entry-server` serves
all three. `template` and `document` accept per-request resolvers; `template` and
the render `mode` themselves are owned by the handler. Pass `ssr` (a `createSSR()`
instance) to render with plugins — islands, resume, state serialization.

Server functions called during the render see this request: the handler scopes the
render (streaming body included) so in-process [`@sigx/server`](/server/packages/server/overview)
calls and `useData` fetchers resolve against the live `Request`.

## The platform argument

The handler's second parameter is the **platform context** — Cloudflare's
`{ env, ctx }`, Netlify's context object, whatever your runtime hands you. It is
opaque to sigx and threaded verbatim into `template`, `app` and `document`:

```ts
type Env = { DB: D1Database };

const handler = createFetchHandler<{ env: Env; ctx: ExecutionContext }>({
    template,
    app: (url, request, { env }) => createApp(url, env.DB),   // typed bindings in render
});

export default {
    fetch: (request: Request, env: Env, ctx: ExecutionContext) =>
        handler(request, { env, ctx }),
};
```

Under the default `TPlatform = unknown` the argument is optional (Deno and Bun
pass nothing). Instantiating the generic with real bindings makes it **required** —
omitting Cloudflare's `{ env, ctx }` is a compile error, so the callbacks' typed
`platform` can never silently be `undefined`.

## Supporting exports

Both ship from `@sigx/server-renderer/server` (and the root entry) for
hand-written fetch servers:

### defaultIsBot

```ts
function defaultIsBot(userAgent: string): boolean;
```

The crawler UA regex shared by every handler (fetch, Node and dev). It is the
`isBot` default; pass `() => false` to always stream.

### chunksToBytes

```ts
function chunksToBytes(chunks: AsyncGenerator<string>): ReadableStream<Uint8Array>;
```

Encode a render's chunk generator as a pull-based UTF-8 `ReadableStream` — the
encoder under `renderDocumentToWebStream` and the fetch handler. Backpressure is
honored (one chunk per pull), and a client disconnect releases the generator so
render work stops.

## Where to go next

- [Deploying SignalX](/deploy/docs/overview) — the platform matrix; each adapter
  wires this handler into a platform entry for you
- [The request lifecycle](/server/packages/server-renderer/request-lifecycle) —
  `useResponse`, the error seam, the WinterCG-clean entry split
- [Building a full SSR app](/server/packages/server-renderer/full-app) — the Node
  counterpart, end to end

---
url: https://sigx.dev/terminal/packages/terminal-zero/installation/
title: Installation
description: Install and configure @sigx/terminal-zero, the Terminal Zero package for SignalX Terminal.
---

# Installation

<p class="lede">Add `@sigx/terminal-zero` to your project.</p>

## Install the package

```bash
pnpm add @sigx/terminal-zero
```

## Verify

```tsx
import * as TerminalZero from '@sigx/terminal-zero';

console.log(Object.keys(TerminalZero));
```

---
url: https://sigx.dev/server/packages/server-renderer/installation/
title: Installation
description: Install @sigx/server-renderer, its dependency, and the subpath import map
---

# Installation

<p class="lede">Add `@sigx/server-renderer` to your project and import from the right subpath.</p>

## Install

```bash
pnpm add @sigx/server-renderer
```

## Dependency

The only runtime dependency is **`sigx`**, the host framework. It is declared as a
regular dependency, so installing `@sigx/server-renderer` pulls `sigx` in
automatically — there is no separate install step and no peer dependency to add.

The package is **ESM-only** (`"type": "module"`, no CommonJS build). Use it from
an ESM project or bundler.

## Subpath imports

`@sigx/server-renderer` ships four tree-shakeable entry points (all with
`sideEffects: false`). Import from the right one so a browser or edge bundle never
pulls in Node code:

| Import path | Use it for | Notes |
|---|---|---|
| `@sigx/server-renderer` | `createSSR`, `renderDocument`, `useResponse`, `ssrClientPlugin`, `renderHeadToString`, shared types | Universal, WinterCG-clean — plugin system + convenience re-exports |
| `@sigx/server-renderer/server` | `renderDocument*`, `renderToString`, `renderToStream`, `renderToStreamWithCallbacks` | Web-stream render APIs; WinterCG-clean (runs on the edge) |
| `@sigx/server-renderer/node` | `renderToNodeStream`, `renderDocumentToNodeStream`, `toNodeStream`, `createRequestHandler` | Node-only — anything touching `node:stream` |
| `@sigx/server-renderer/client` | `hydrate`, `ssrClientPlugin`, plugin hooks | Browser-only hydration |

The root and `/server` entries import **no Node built-ins**, so they run on edge
runtimes. Everything that needs `node:stream` — a `Readable`, or the Node request
handler — lives in `/node`.

A typical app uses several across its entry files:

```tsx
// entry-server.tsx
import { renderDocument } from '@sigx/server-renderer/server';

// server.mjs (Node) — a Readable stream, or the request handler
import { renderToNodeStream, createRequestHandler } from '@sigx/server-renderer/node';

// entry-client.tsx
import { ssrClientPlugin } from '@sigx/server-renderer/client';

// any component
import { useHead, useData } from 'sigx';       // head + data loading live in core sigx
```

Node stream APIs (`renderToNodeStream`, `renderDocumentToNodeStream`, `toNodeStream`)
are exported **only** from `/node`. Hydration internals (`hydrate`, `hydrateNode`,
`registerClientPlugin`, …) are exported **only** from `/client`.

> `useHead`, `useData`, and `useStream` come from core **`sigx`**, not this
> package. They are plain composables that gain server behavior when this renderer
> drives them.

## Import side effects

Importing the package runs one-time setup automatically: it augments the SSR
directive types and patches `getSSRProps` onto built-in directives such as `show`
so they serialize correctly during SSR. You do not need to call anything to enable
this.

## Build / Vite wiring

No special Vite config is required to **consume** the package — the standard
SignalX JSX/Vite setup for your host app applies. There is **no CLI or `bin`** —
the package is a library you import.

## Adding islands

`@sigx/server-renderer` has no concept of `client:*` directives on its own. To
hydrate only the interactive parts of a page, add the islands package on top:

```bash
pnpm add @sigx/ssr-islands
```

See [`@sigx/ssr-islands`](/server/packages/ssr-islands/overview) for the full setup.

## Next steps

- [Rendering & streaming](/server/packages/server-renderer/rendering)
- [Hydration & head](/server/packages/server-renderer/hydration)
- [API reference](/server/packages/server-renderer/api)

---
url: https://sigx.dev/actors/packages/actors-surreal/installation/
title: Installation
description: Install and configure @sigx/actors-surreal, the SurrealDB package for SignalX.
---

# Installation

<p class="lede">Connect, define the schema, then wire a clustered host.</p>

## Install

```bash
pnpm add @sigx/actors-surreal surrealdb
```

`surrealdb` is a peer dependency (`^2.0.8`). You need SurrealDB **≥ 3.0** running, 3.2.4 or
newer recommended.

## Connect and define the schema

```ts
import { Surreal } from 'surrealdb';
import { ensureSurrealSchema, surrealRetryable } from '@sigx/actors-surreal';

const db = new Surreal();
await db.connect('ws://127.0.0.1:8000', {
    namespace: 'app',
    database: 'main',
    authentication: { username: 'root', password: 'root' },
    // REQUIRED on a connection you own — see below.
    retry: { enabled: true, attempts: 5, retryable: surrealRetryable },
});

await ensureSurrealSchema(db);
```

**Every replica may call this at boot, concurrently.** SurrealDB 3 has no lock primitive, so
convergence is by a bounded, jittered retry that `ensureSurrealSchema()` carries **itself**,
independent of the connection's `retry` setting — which matters, because the SDK ships retry
disabled and this path would otherwise have none. The retry is deliberately blind to error
shape; if it exhausts its attempts it verifies the tables are present before giving up, and
rethrows the original error if they are not.

`surrealRetryable` is unchanged by any of that and stays deliberately narrow — it is a
connection-wide predicate governing your own queries, and the bootstrap does not depend on it.

`ensureSurrealSchema()` SELECTs the namespace and database; it does not create them.
`DEFINE NAMESPACE` / `DEFINE DATABASE` need root and are a deployment decision, so they are
deliberately not issued for you.

Two things in that snippet are load-bearing:

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong><code>surrealRetryable</code> is not optional on a connection you pass in.</strong>
    The directory claim and the storage create arm are correct <em>because</em> two racers
    collide at commit and the loser re-runs to observe the winner. The SDK ships retry
    disabled, and its built-in predicate matches a structured error code that in practice never
    arrives — so without this, a lost claim race surfaces as a raw conflict error instead of
    the winning entry.
  </div>
</div>

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>The DDL step is mandatory</strong>, unlike with Postgres. Reading an undefined
    table is an <em>error</em> in SurrealDB 3 (2.x returned <code>[]</code>), so the schema has
    to exist before a host starts.
  </div>
</div>

Prefer `ws://`/`wss://` over `http://`: the HTTP engine re-authenticates per request and cannot
serve live queries, so membership push will not work over it.

### In production, use a migration tool

Calling `ensureSurrealSchema()` from every replica is safe, but a migration tool is still the
better shape in production — it runs once, under review, rather than racing at every boot:

```ts
import { surrealSchemaSql } from '@sigx/actors-surreal';

console.log(surrealSchemaSql({ prefix: 'sigx_' }));
```

The DDL is idempotent and safe to re-run. Every table is `SCHEMAFULL` — this package is the
only writer and all five shapes are fixed, so a typo becomes an error at the write rather than
a silently ignored field. That works because a v3 `SCHEMAFULL` table **rejects** an undefined
field instead of dropping it.

Because the providers never issue DDL, a production role needs only DML grants.

## Wire a host

```ts
import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { surrealCluster, surrealReminders, surrealStorage } from '@sigx/actors-surreal';

const app = defineActorApp({
    actors,
    storage: surrealStorage({ db }),
    // Optional: without it the runtime keeps its default sharded reminders,
    // which also work over surrealStorage. Pass it to get the indexed table.
    reminders: surrealReminders({ db }),
}).use(
    cluster({
        providers: surrealCluster({ db }),
        advertise: process.env.ADVERTISE!,
        secret: process.env.CLUSTER_SECRET!,
    }),
);
```

## Connection: shared or owned

Every provider takes one of two shapes:

| You pass | What happens |
|---|---|
| `db` — a connected `Surreal` | Shared with your app; **one socket multiplexes everything**. You own the retry config. |
| `url` plus `namespace` / `database` / `auth` | The package connects lazily and owns the socket, retry included. |

`prefix` (default `sigx_`) names the tables.

## Verify

```ts
import { surrealStorage } from '@sigx/actors-surreal';

const storage = surrealStorage({ db });
await storage.save('Probe', 'k1', { state: '{"n":1}', etag: 'e1' });
console.log(await storage.load('Probe', 'k1'));   // → { state: '{"n":1}', etag: 'e1' }
await storage.clear('Probe', 'k1');
```

A `load` that returns `undefined` immediately after a `save` usually means the schema step did
not run against this namespace/database.

---
url: https://sigx.dev/terminal/packages/runtime-terminal/overview/
title: Overview
description: "@sigx/runtime-terminal — the terminal renderer for SignalX: render modes, key dispatch, color depth"
---

# Runtime Terminal

<p class="lede">The renderer. Walks your component tree into ANSI lines and paints them — render modes, layered key dispatch, color-depth detection, output targets and reactive terminal size. The host platform for `@sigx/runtime-core`.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

The `@sigx/terminal` umbrella re-exports this package, so most apps never install it
directly — it is to the terminal what `@sigx/runtime-dom` is to the web:

```bash
pnpm add @sigx/runtime-terminal
```

## What lives here

- **Render modes** — fullscreen (alternate screen), inline live regions and
  one-shot static rendering, plus the mount options that pick between them. See
  [Render modes](/terminal/docs/render-modes/).
- **Layered key dispatch** — the focus model interactive components plug into. See
  [Input & interactive components](/terminal/docs/input-and-components/).
- **Terminal capabilities** — color-depth detection, output targets and the
  reactive terminal size the layout engine tracks.

## Next steps

See where it sits in the stack in [Architecture](/terminal/docs/architecture/), or
jump to the [API reference](/terminal/packages/runtime-terminal/api).

---
url: https://sigx.dev/terminal/packages/terminal-dev/installation/
title: Installation
description: Install and configure @sigx/terminal-dev, the Terminal Dev package for SignalX Terminal.
---

# Installation

<p class="lede">Add `@sigx/terminal-dev` to your project as a dev dependency.</p>

## Install the package

It runs your app during development only — it is not part of the `@sigx/terminal` umbrella and never ships with your app:

```bash
pnpm add -D @sigx/terminal-dev
```

## JSX setup

`@sigx/terminal-dev` lists `@sigx/runtime-core` (`^0.14.0`) as a peer dependency and bundles Vite. Your `tsconfig.json` needs the usual SignalX JSX setup (`"jsx": "react-jsx"` and `"jsxImportSource": "@sigx/runtime-core"`, or the `@sigx/terminal` facade — see the umbrella's [Installation](/terminal/docs/installation/) guide).

## Verify

```bash
pnpm exec sigx-terminal-dev --help
```

---
url: https://sigx.dev/actors/packages/actors-cloudflare/overview/
title: Overview
description: Cloudflare Durable Objects as the backend for @sigx/actors — one DO per actor, and why the package is so small
---

# Cloudflare

<p class="lede">Cloudflare already guarantees a single instance of a Durable Object globally
and serializes requests to it. That <em>is</em> the virtual-actor contract — so the platform
is the cluster.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-cloudflare
```

## Why it is small

This package needs none of the machinery [`@sigx/actors/cluster`](/actors/docs/clustering)
uses to rebuild that contract: **no membership heartbeats, no activation directory, no
HMAC-authenticated host-to-host mount.**

There is no HMAC because a Durable Object stub is not network-reachable — holding the binding
*is* the capability grant, and guards run once at the public edge. And there is no 421 retry
because ref → object id is a pure function, so a mismatch is a config bug rather than a race.

## Storage

```ts
const storage = durableObjectStorage(state.storage);
```

DO storage is strongly consistent and single-threaded per object, so the runtime's etag
compare-and-set holds without a transaction.

## Reminders

```ts
const reminders = durableObjectReminders({
    storage: state.storage,
    alarms: state.storage,
    blockConcurrencyWhile: (fn) => state.blockConcurrencyWhile(fn),
});

export class ActorHost {
    async alarm() {
        await reminders.onAlarm();   // fire what is due, re-arm the rest
    }
}
```

The default `shardedReminders()` splits one table into fixed hash shards and polls it, because
a host holds many actors and has to find whose reminder is due. **A DO holds exactly one**, so
there is nothing to search and nothing to poll — reminders live in the object's own storage and
the platform wakes it at the earliest due time.

The visible consequence: an alarm fires **at** the due time, where `shardedReminders()`
promises only "at or after `nextDue`".

## Client sockets

Browsers can reach actors over a WebSocket here, terminating in either half:

```ts
createWorkerHandler({ ..., socket: {} });                        // in the Worker
createWorkerHandler({ ..., socket: { terminate: 'object' } });   // in the object
```

**Worker-terminated** gives one multiplexed socket per client, reaching every actor — the
right shape for a dashboard. **Object-terminated** gives one socket per actor, accepted with
the hibernation API inside the object that owns it — the room pattern, and the mode where a
disconnect actually releases the activation, because teardown happens locally instead of dying
at the `stub.fetch` boundary.

Pair either with [`socketTransport()`](/actors/packages/actors-ws/overview) on the client. The
[deployment guide](/actors/docs/cloudflare-workers#client-sockets) has the choice in full,
plus the hibernation contract.

## The getting-started path

Most apps do not touch the two seams directly — `createHostDurableObject()` and
`createWorkerHandler()` assemble them. See
[Cloudflare Workers](/actors/docs/cloudflare-workers) for the full entry, the `wrangler.jsonc`
and the three gotchas that are each worth their own callout.

## Next steps

- [Installation](/actors/packages/actors-cloudflare/installation) — bindings and migrations.
- [API reference](/actors/packages/actors-cloudflare/api) — exports.
- [Cloudflare Workers](/actors/docs/cloudflare-workers) — the deployment guide.
- [`@sigx/actors-ws`](/actors/packages/actors-ws/overview) — the client half of a socket.

---
url: https://sigx.dev/server/packages/server-renderer/boundaries/
title: The boundary model
description: How SignalX SSR decides where HTML flushes and when a component hydrates — flush and hydrate axes, SSRBoundary, resolveBoundary, and selective hydration
---

# The boundary model

<p class="lede">A <strong>boundary</strong> is a component the renderer treats specially: it decides <em>how</em> that component's HTML reaches the page and <em>when</em> the component wakes up on the client. It's the strategy-agnostic core of SignalX SSR — <a href="/server/packages/ssr-islands/overview">islands</a> are one pack built on it.</p>

## Two orthogonal axes

Every boundary is described by two independent choices. Keeping them separate is the whole point of the model — a server-flush decision never dictates a client-hydration decision.

**`flush`** — a **server** concern: how the component's HTML gets to the page.

| `flush` | Meaning |
|---|---|
| `inline` | Await the component's async work in place, even in a streaming render. |
| `stream` | Stream the HTML when there is pending async work and the render is streaming; otherwise degrade to inline. |
| `skip` | Don't run setup on the server at all — emit a placeholder wrapper and let the client mount fresh. |

**`hydrate`** — a **client** concern: when the component becomes interactive.

| `hydrate` | Wakes on |
|---|---|
| `load` | As soon as the bundle loads. |
| `idle` | The next idle callback. |
| `visible` | Scrolled into view. |
| `media` | A media query matches (see `media`). |
| `interaction` | The first pointer/keyboard/touch/focus event on the element. |
| `never` | Never — server HTML only, no client component. |

A static marketing section might be `{ flush: 'inline', hydrate: 'never' }`; a below-the-fold widget `{ flush: 'stream', hydrate: 'visible' }`; a client-only chart `{ flush: 'skip', hydrate: 'load' }`.

## Describing a boundary

`SSRBoundary` is the resolved description the renderer works from:

```ts
interface SSRBoundary {
    id: number;                    // renderer-assigned, from core's component-id scheme
    flush: BoundaryFlush;          // 'inline' | 'stream' | 'skip'
    hydrate: BoundaryHydrate;      // 'load' | 'idle' | 'visible' | 'media' | 'interaction' | 'never'
    media?: string;                // required when hydrate is 'media'
    fallback?: () => JSXElement;   // server-only placeholder for 'stream' / 'skip'; never serialized
    chunk?: { url: string; export?: string };
    props?: Record<string, unknown>;
}
```

You rarely write this by hand — a pack (like islands) produces it from something friendlier, such as a `client:*` directive.

## Resolving a boundary

Boundaries come from a plugin's `resolveBoundary` hook. The renderer calls it once per component — **after it allocates the component's id, before setup runs** — and the first plugin to return an object wins:

```ts
const myBoundaryPlugin: SSRPlugin = {
    server: {
        resolveBoundary(vnode, ctx) {
            if (vnode.type?.__deferred) {
                return { flush: 'stream', hydrate: 'visible' };
            }
            // return nothing → this component is not a boundary
        },
    },
};
```

The returned object is a `ResolvedBoundary` — a partial of the `flush` / `hydrate` / `media` / `fallback` / `chunk` / `props` / `component` fields. Anything omitted falls back to the app's defaults.

`component` is the record's **registry name** — how the client resolves the component, trying the eager registry, then the lazy registry, then the `chunk` URL, in that order. Core derives it from `__islandId || __name`, which is right for packs that use core's stamp; a pack with its own naming vocabulary sets it here instead. An anonymous record — no `component` and no `chunk` — is refused by the client loader rather than silently skipped.

Because the hook runs before setup, a `flush: 'skip'` decision means setup never runs on the server: the renderer emits a `<div data-boundary="ID" style="display:contents">` wrapper around the optional `fallback` and the client mounts into it fresh. For `stream` and `inline`, setup runs normally and the boundary's HTML is produced server-side.

## The client's view: `__SIGX_BOUNDARIES__`

Every recorded boundary is serialized into a per-request table emitted as `window.__SIGX_BOUNDARIES__`. Each entry carries only what the client needs — the resolved `hydrate` strategy, any `props` or transferred signal `state`, the `chunk` reference for a lazy boundary, and an `errorScope` marker if the server caught an error there:

```ts
interface SSRBoundaryRecord {
    flush?: BoundaryFlush;              // present only when 'skip'
    hydrate?: BoundaryHydrate;          // omitted = inherit the app default
    media?: string;
    props?: Record<string, unknown>;
    state?: Record<string, unknown>;    // transferred island signal snapshot
    chunk?: { url: string; export?: string };
    component?: string;
    errorScope?: { message: string };
}
```

The table shares one serializer (and one dev-time serializability warning) with `window.__SIGX_ASYNC__`, so the same escaping and custom-type rules apply to both. That serializer is **codec-aware**: alongside JSON primitives, top-level and nested `Date` / `Map` / `Set` / `bigint` / `URL` / `RegExp` / explicit `undefined` values — plus any registered custom type handlers — round-trip; only functions and circular references are rejected.

## Custom types

The codec ships with handlers for `Date`, `Map`, `Set`, `bigint`, `URL`, `RegExp` and `undefined`. To carry a type of your own across the boundary — the SSR state blob, the boundary table, and server-function arguments and results — register a handler with [`@sigx/serialize`](/server/packages/serialize/overview)'s `defineTypeHandler`, most easily through the `@sigx/server/plugin` app plugin's `types` option:

```ts
import { serverPlugin } from '@sigx/server/plugin';

app.use(serverPlugin({ types: [moneyHandler] }));
```

See [Serialize → Usage](/server/packages/serialize/usage) for writing the handler (its `test` type guard drives the `serialize` / `revive` types) and the other registration paths.

## Selective hydration is the hydrator

On the client, `hydrate()` reads the boundary table and schedules work per strategy — this *is* the hydrator, not an add-on. Its behavior is governed by a per-app hydrate default:

- **`explicit`** — only entries in the boundary table are scheduled; there is no root walk. A page with no table pays nothing.
- **`auto`** — the client walks the tree and intercepts recorded boundaries as it finds them.

Installing a pack is what selects the mode. `app.use(islandsPlugin())` provides the `explicit` default and registers the client hooks — so *installing* the package is what turns on islands semantics, never merely importing it.

## Where to go next

- [Islands & client directives](/server/packages/ssr-islands/client-directives) — the reference pack that maps `client:*` onto these axes
- [Request lifecycle](/server/packages/server-renderer/request-lifecycle) — `useResponse`, the error seam, and the `./node` entry
- [Building a full SSR app](/server/packages/server-renderer/full-app) — wiring it all together

---
url: https://sigx.dev/actors/packages/actors-redis/installation/
title: Installation
description: Install @sigx/actors-redis, wire the providers into your app, and tune the heartbeat
---

# Installation

<p class="lede">Add the package and its <code>ioredis</code> peer, then hand the providers to
the <code>cluster()</code> plugin.</p>

## Install

```bash
pnpm add @sigx/actors-redis ioredis
```

Requires **Redis ≥ 7** and `ioredis` ≥ 5.

## Wire it up

```ts
import Redis from 'ioredis';
import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { redisCluster, redisStorage } from '@sigx/actors-redis';

const client = new Redis(process.env.REDIS_URL!);

export const app = defineActorApp({
    actors,
    storage: redisStorage({ client }),
}).use(cluster({
    providers: redisCluster({ client }),
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
}));
```

One client for both is safe and saves connections. Share the `namespace` between them.

## Options

Both `redisCluster()` and `redisStorage()` take `client` **or** `url`.

| Option | Default | Meaning |
|---|---|---|
| `client` / `url` | — | ioredis client, or a URL to construct one |
| `namespace` | `sigx` | key prefix |
| `heartbeatMs` | `5000` | membership heartbeat cadence |
| `ttlMs` | `15000` | heartbeat key TTL — missed beats past this means dead |
| `pollMs` | `5000` | membership view poll cadence |

`redisStorage()` takes `client`/`url` and `namespace` only.

Tuning guidance: `ttlMs` is how long a dead host's actors stay unclaimable, so lowering it
speeds recovery and raises the risk of fencing a host that merely paused — a long GC, a
throttled container. Three missed heartbeats is a reasonable floor.

## Splitting the providers

Membership and the directory are independent. Kubernetes Leases for liveness with a Redis
directory is a common shape:

```ts
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(client) },
    advertise, secret,
});
```

## Verify

```ts
const report = await clusterStats(placement);
console.log(report.hosts.length, report.partial);
```

Or from a terminal, once [`ops()`](/actors/docs/ops-endpoint) is mounted:

```bash
sigx actors health --url http://localhost:7311
```

## Testing

The provider suite is gated on `REDIS_URL`:

```sh
REDIS_URL=redis://localhost:6379 pnpm test -- actors-redis
```

For unit tests that need a cluster but not a server, `memoryClusterHub()` from
`@sigx/actors/cluster` gives an N-host in-process cluster with no external store.

## Next steps

- [API reference](/actors/packages/actors-redis/api) — exports and key layout.
- [Clustering](/actors/docs/clustering) — the plugin options.
- [Storage](/actors/docs/storage) — choosing a provider.

---
url: https://sigx.dev/terminal/packages/terminal-ui/installation/
title: Installation
description: Install and configure @sigx/terminal-ui, the Terminal UI package for SignalX Terminal.
---

# Installation

<p class="lede">Add `@sigx/terminal-ui` to your project.</p>

## Install the package

```bash
pnpm add @sigx/terminal-ui
```

## Verify

```tsx
import * as TerminalUI from '@sigx/terminal-ui';

console.log(Object.keys(TerminalUI));
```

---
url: https://sigx.dev/server/packages/server-renderer/hydration/
title: Hydration & head
description: Hydrate server-rendered DOM, manage the document head, and extend rendering through the plugin SPI
---

# Hydration & head

<p class="lede">After the server sends HTML, the client re-attaches reactivity to that existing DOM. This guide covers the hydration entry point, head management, and the plugin SPI that advanced strategies build on.</p>

## The client hydration entry

The high-level entry is the `ssrClientPlugin`. It adds `hydrate()` to your `App`:

```tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';

defineApp(<App />)
    .use(ssrClientPlugin)
    .hydrate('#root');
```

`hydrate()` accepts a CSS selector string or an `Element`. It finds the root
component plus `AppContext`, then hydrates the existing SSR DOM. If the container
has **no** SSR content, it falls back to a fresh client render — so the same entry
works for both pre-rendered and client-only pages.

### Gate hydration on the completion script

The document renderer emits a trailing script —
[`__SIGX_STREAMING_COMPLETE__`](/core/docs/advanced/globals) plus
a `sigx:ready` event — in **both** `'blocking'` and `'stream'` modes, so a
blocking-rendered page hydrates the same way a streamed one does. The inline
script runs during HTML parse, before any deferred module script, so your entry
can safely check the flag and otherwise wait for the event before hydrating:

```tsx
// src/entry-client.tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';

function start() {
    defineApp(<App />).use(ssrClientPlugin).hydrate('#root');
}

if ((window as any).__SIGX_STREAMING_COMPLETE__) {
    start();                                    // document already complete
} else {
    window.addEventListener('sigx:ready', start, { once: true });
}
```

### Self-healing on a structural mismatch

Hydration is resilient to SSR/client drift. For a small cursor offset the walk
scans forward for the matching node (dev-warns about skipped siblings). For a
genuine structural mismatch — the server emitted a different element than the
client VNode expects — it **self-heals**: it creates the expected element fresh,
mounts the subtree into it, and advances past the orphaned server node. The page
stays correct and reactive instead of duplicating content or leaving a dead
subtree. These recoveries warn in dev so you can fix the underlying drift.

### Low-level hydration

For custom setups you can call the core `hydrate` function directly. It normalizes
the element to a VNode, sets the current `AppContext` for DI, runs client plugin
`beforeHydrate` hooks, walks the DOM via `hydrateNode`, then runs `afterHydrate`:

```tsx
import { hydrate } from '@sigx/server-renderer/client';
import { App } from './App';

const container = document.getElementById('root')!;
hydrate(<App />, container);
```

`hydrateNode` does the per-VNode work: in the happy path it creates no DOM, just
attaches events/props/directives/refs, skips SSR comment markers
(`<!--t-->`, `<!--$c:N-->`), recovers from minor SSR drift by scanning forward
(with a dev warning), and returns the next sibling.

## Head management

Call `useHead()` — exported from core **`sigx`** — inside any component to manage
`<head>` elements. During SSR the configs are collected onto the per-request
context; on the client `useHead()` mutates the DOM directly and registers cleanup
on unmount:

```tsx
import { component, useHead } from 'sigx';

export const ArticlePage = component((props) => {
    useHead({
        title: props.title,
        titleTemplate: '%s — My Site',
        meta: [
            { name: 'description', content: props.summary },
            { property: 'og:title', content: props.title },
        ],
        link: [{ rel: 'canonical', href: props.url }],
        htmlAttrs: { lang: 'en' },
    });

    return () => <article>{props.body}</article>;
});
```

`renderDocument*` collects these configs during render and injects the rendered
head HTML before `</head>` in your template automatically — there is nothing to
wire up. `titleTemplate` uses `%s` as the title placeholder, and the renderer
dedupes meta by `name`/`property`/`http-equiv`/`charset`.

`renderDocument` injects the collected head into the document for you, so a
`useHead()` call anywhere in the tree just works — no manual wiring.

## Hydrating a server-resolved Defer subtree

The server resolves `lazy()` components inline (and streams a `<Defer>`
fallback then swaps in one replacement — see
[Rendering & streaming](/server/packages/server-renderer/rendering)). To hydrate
that server-resolved subtree, the lazy component must be available **synchronously**
during the hydration walk — otherwise the client would render the fallback again
and mismatch the server output.

Preload the lazy chunk before calling `hydrate()`. Every `lazy()` factory exposes
a `.preload()` promise for exactly this:

```tsx
// src/entry-client.tsx
import { defineApp, lazy } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';
import { HeavyChart } from './HeavyChart'; // a lazy() component used under <Defer>

// Resolve the chunk first, then hydrate — the component is ready when the
// hydration walk reaches it, so it matches the server-rendered DOM.
await HeavyChart.preload();

defineApp(<App />).use(ssrClientPlugin).hydrate('#root');
```

For selective hydration where each island owns its own lazy chunk, the islands
plugin handles this for you — see
[`@sigx/ssr-islands`](/server/packages/ssr-islands/registry-and-code-splitting).

## The scheduler / core split

Selective hydration is deliberately in two halves, so a page pays for triggers
before it pays for a renderer.

| Half | Entry | What it costs |
|---|---|---|
| **Eager scheduler** | `@sigx/server-renderer/client/scheduler` | ~2 kB. Reads `__SIGX_BOUNDARIES__` and wires each boundary's trigger. Value-imports nothing from the sigx family, so no framework code executes at load. |
| **Hydration core** | loaded via `loadHydrationCore()` | The renderer, `hydrateComponent`, and the mount/hydrate primitives. Dynamically imported on the **first strategy that actually fires**. |

A page whose strategies never fire — everything below the fold, everything
`hydrate: 'never'` — never executes any framework JavaScript at all.

```ts
import { scheduleTableBoundaries } from '@sigx/server-renderer/client/scheduler';

scheduleTableBoundaries();   // triggers only; the executor arrives when one fires
```

The entry also exports the pieces a strategy pack builds on without pulling the
core in: `scheduleByStrategy`, `getBoundaryTable` / `getBoundaryRecord`,
`findBoundaryMarker` / `hydrateTableBoundary`, the component registry
(`registerComponent`, `resolveComponent`, `registerComponentChunk`),
`loadBoundaryComponent` / `prefetchBoundaryChunks`, and
`seedBoundaryState` / `consumeBoundaryState`.

`loadHydrationCore()` caches its promise, and a failed load clears the cache so
the next trigger retries.

The one behavioural consequence: a `hydrate: 'load'` boundary now hydrates after
one dynamic-import round trip rather than synchronously. That import is
preloadable — a pack keeps it off the critical path with the
[`assets` hook](#the-plugin-spi).

### Lazy client plugins

Because the core loads late, a pack's client hooks can ride in the same chunk.
`registerClientPlugin` takes either a resolved plugin or a **lazy source**:

```ts
import { registerClientPlugin } from '@sigx/server-renderer/client/scheduler';

registerClientPlugin({
    name: 'my-strategy',
    load: () => import('./my-strategy-client'),   // resolved with the hydration core
});
```

`resolveClientPlugins()` imports every lazy source once, before the first
component hydrates, so the synchronous client hooks always see a resolved plugin.
Registrations dedupe by `name`, first wins — registering the same name again in
either form is a no-op.

## The plugin SPI

The core renderer and hydrator are strategy-agnostic. Every advanced hydration
strategy — selective, islands, resumable, `Defer` — is an `SSRPlugin` with
optional `server` and `client` hook sets.

- Register a hand-written `SSRPlugin`'s **server** hooks by passing it to `createSSR({ plugins: [myPlugin] })`. (Published packs like `islandsPlugin()` are `SSRPack`s — an `SSRPlugin` plus an `install(app)` method — so you install *those* on the app with `app.use()`.)
- Register **client** hooks with `registerClientPlugin(plugin)`.

```tsx
import { createSSR, type SSRPlugin } from '@sigx/server-renderer';

const myPlugin: SSRPlugin = {
    name: 'my-strategy',
    server: {
        // decide how this component flushes and hydrates — the per-component seam
        resolveBoundary(vnode, ctx) {
            return; // no opinion; the next plugin (or the default) decides
        },
        // mutate/replace a component's context after it's built, before setup()
        transformComponentContext(ctx, vnode, componentCtx) {
            return; // accept as-is
        },
        // append-only: capture per-boundary state, emit markup after a component
        afterRenderComponent(id, vnode, html, ctx) {
            return; // append nothing
        },
        // contribute modulepreload hints for chunks core won't schedule itself
        assets(ctx) {
            return; // nothing to preload
        },
    },
    client: {
        // return false to skip the default DOM walk (resumable SSR)
        beforeHydrate(container) {
            return; // run normal hydration
        },
        // hydration-time mirror of server.transformComponentContext
        transformComponentContext(vnode, componentCtx) {
            return; // accept as-is
        },
        // return a Node to "claim" a component during the hydration walk
        hydrateComponent(vnode, dom, parent, regionEnd) {
            return undefined; // let core hydrate it
        },
    },
};

const html = await createSSR({ plugins: [myPlugin] }).render(<App />);
```

Key hook semantics:

- `server.transformComponentContext` runs after a component's context is built and
  **before `setup()`**, letting a plugin mutate or replace it — e.g. swap
  `ctx.signal` for a state-capturing variant. `client.transformComponentContext` is
  its **hydration-time mirror** (same timing, no `SSRContext` argument), so a
  strategy can swap `ctx.signal` for a state-*restoring* variant. The pair keeps
  render and hydration symmetric while core stays strategy-agnostic.
- `server.resolveBoundary` runs **before** the context is built and before
  `setup()`, once per component, and the first plugin to return an object wins.
  Its `flush` axis decides whether the component renders on the server at all —
  `flush: 'skip'` suppresses setup entirely and emits the
  `<div data-boundary="ID" style="display:contents;">` wrapper around an optional
  `fallback` — and its `hydrate` axis is recorded in the boundary table for the
  client. This is how islands make `client:only` ship no server HTML. See
  [The boundary model](/server/packages/server-renderer/boundaries).
- `client.beforeHydrate` returning `false` **skips** the default DOM walk — the
  basis for resumable SSR.
- `client.hydrateComponent` returning a `Node` **claims** that component — the hook
  islands use to intercept `client:*` props and schedule deferred hydration. Its
  fourth argument, `regionEnd`, is the exclusive end of the sibling range the
  component may own; a pack that locates trailing markers itself **must** bound the
  search by it, or a component followed by sibling content latches a *child's*
  marker and duplicates server-rendered content after a bail.
- `server.afterRenderComponent` is append-only (the `html` argument is always
  `''`), `server.assets` contributes modulepreload hints, and `getInjectedHTML` /
  `getStreamingChunks` emit extra markup or streamed chunks.

> **You usually don't write this by hand.** The islands strategy — `client:*`
> directives, deferred hydration, signal-state transfer and per-island code
> splitting — is already implemented as a plugin in
> [`@sigx/ssr-islands`](/server/packages/ssr-islands/overview). Reach for the raw
> SPI only when building a *new* strategy.

## Next steps

- [Building a full SSR app](/server/packages/server-renderer/full-app)
- [Islands & selective hydration](/server/packages/ssr-islands/overview)
- [API reference](/server/packages/server-renderer/api)

---
url: https://sigx.dev/actors/packages/actors-otel/installation/
title: Installation
description: Mounting the Prometheus endpoint, a scrape config, the bucket grid and the reset caveat
---

# Installation

<p class="lede">Mount it beside <code>ops()</code>, give it the same secret, and point your
scraper at it.</p>

## Install

```bash
pnpm add @sigx/actors-otel
# only if you want traces or the OTLP bridge:
pnpm add @opentelemetry/api
```

## Prometheus

```ts
import { metrics } from '@sigx/actors/host';
import { prometheusOps } from '@sigx/actors-otel/prometheus';

export const app = defineActorApp({ actors, storage })
    .use(metrics())
    .use(prometheusOps({ secret: process.env.SIGX_OPS_SECRET }));
```

`metrics()` must be enabled for there to be anything to export — if you run
`metrics({ enabled: false })` in production, the endpoint reports zeroes until you enable it.

```yaml
scrape_configs:
  - job_name: sigx-actors
    metrics_path: /_sigx/metrics
    authorization:
      credentials_file: /etc/prometheus/sigx-ops-secret
    static_configs:
      - targets: ['actors-host:7311']
```

## Options

| Option | Default | Meaning |
|---|---|---|
| `path` | `/_sigx/metrics` | where it mounts |
| `secret` | — | **mandatory outside dev** |
| `prefix` | `sigx_actors_` | metric name prefix |
| `bucketsSeconds` | per-octave grid | histogram bounds |

The default bucket grid runs from 1µs to about 134s in roughly 28 per-octave bounds — wide
enough to cover a sub-millisecond local dispatch and a multi-second turn in the same histogram.

## Two caveats

> **`metrics().reset()` breaks monotonicity.** Prometheus counters are expected only ever to
> increase, so a `reset()` looks like a counter restart. That is survivable — `rate()` handles
> restarts — but do not wire `reset()` to anything periodic.

> **Never label by actor key.** Enforced by the package, but worth knowing why: keys are
> unbounded, and one high-cardinality label is enough to take a Prometheus down.

## Traces and the bridge

```ts
import { otelMetricsBridge, otelTraces } from '@sigx/actors-otel';

app.use(otelTraces({ turnSpans: true }))
   .use(otelMetricsBridge({ percentileGauges: true }));
```

Both are inert with no provider registered. `turnSpans: false` keeps the CLIENT spans and
drops the per-turn SERVER spans, which is the cheaper configuration if you only want the call
graph.

## Verify

```bash
curl -H "authorization: Bearer $SIGX_OPS_SECRET" http://localhost:7311/_sigx/metrics | head
```

## Next steps

- [API reference](/actors/packages/actors-otel/api) — exports.
- [Observability](/actors/docs/observability) — choosing an approach.
- [Metrics](/actors/docs/metrics) — what is being exported.

---
url: https://sigx.dev/server/packages/server-renderer/rendering/
title: Rendering & streaming
description: Render a complete document with renderDocument into Express, Fastify, or an edge runtime, and load server data with useData/useStream
---

# Rendering & streaming

<p class="lede">Hand the renderer an HTML template, let it own the whole response — head, shell, state, async content — and stream it into a real HTTP server.</p>

## The document render APIs

The `renderDocument*` family takes a full HTML template containing an outlet
marker and assembles the complete document: collected `useHead()` tags injected
before `</head>`, the app shell at the outlet, the serialized state blob, any
streamed async chunks, and the template tail. You no longer hand-splice
`template.replace('<!--ssr-outlet-->', html)` in your server.

| API | Returns | Default mode | Best for |
|---|---|---|---|
| `renderDocument` | `Promise<string>` | `'blocking'` | Buffer the full document, then send it once — crawlers, AI agents |
| `renderDocumentToNodeStream` | `{ stream: Readable; shell: Promise<void> }` | `'stream'` | Node servers — Express, Fastify, H3 |
| `renderDocumentToWebStream` | `ReadableStream<Uint8Array>` | `'stream'` | Web-standard runtimes — Workers, Deno, edge |

All three accept a raw JSX element **or** an `App` from `defineApp()` (the `App`
form preserves `AppContext` for `inject()` and plugins such as a router), plus a
`DocumentOptions` object.

### The template and outlet

```tsx
const template = `<!DOCTYPE html>
<html>
  <head><meta charset="utf-8" /></head>
  <body>
    <div id="root"><!--ssr-outlet--></div>
    <script type="module" src="/entry-client.js"></script>
  </body>
</html>`;
```

The outlet marker defaults to `<!--ssr-outlet-->`; override it with the `outlet`
option. The renderer also splits the tail at `</body>`: everything up to it —
including your entry `<script>` — flushes with the shell so the browser starts
downloading the client bundle immediately, while only the closing tags wait for
the stream to finish.

## Blocking vs streaming

The `mode` option controls how keyed `useData()` / `useStream()` data is
delivered:

- **`'blocking'`** — every keyed async value resolves **inline**: complete
  content, no placeholders, no replacement scripts. This is the default for
  `renderDocument`. Ideal for crawlers and AI agents that read the first response
  without executing JavaScript — pick it per `User-Agent`.
- **`'stream'`** — the synchronous shell flushes first with placeholders, then
  out-of-order replacement chunks swap in real content as each async value
  resolves. This is the default for the two streaming variants.

Both modes emit the trailing completion script (`__SIGX_STREAMING_COMPLETE__` +
the `sigx:ready` event) so the client can gate hydration on a complete document,
and both serialize state unless you opt out with `serializeState: false`.

## Express (Node)

`renderDocumentToNodeStream` returns the stream **and** a `shell` promise that
settles *before* the first byte. Await it to choose a real HTTP status code, then
pipe:

```tsx
import express from 'express';
import { renderDocumentToNodeStream } from '@sigx/server-renderer/server';
import { App } from './App';

const template = await readTemplate(); // your index.html with <!--ssr-outlet-->
const server = express();
server.use(express.static('dist/client'));

server.get('*', async (req, res) => {
    const { stream, shell } = renderDocumentToNodeStream(<App />, {
        template,
        onError: (err, phase) => console.error(`[ssr:${phase}]`, err),
    });

    try {
        await shell;                       // shell ready → status is safe to set
    } catch {
        return res.status(500).send('<!doctype html><h1>Server error</h1>');
    }

    res.status(200).setHeader('Content-Type', 'text/html');
    stream.pipe(res);
});

server.listen(3000);
```

Because `shell` settles before any byte goes out, a shell-phase failure still
lets you send a clean 500 page — the stream has not started yet.

## Fastify / H3

The same `{ stream, shell }` shape works with any Node HTTP framework. Await the
shell, set the status, then hand the `Readable` to `reply.send()`:

```tsx
import Fastify from 'fastify';
import { renderDocumentToNodeStream } from '@sigx/server-renderer/server';
import { App } from './App';

const fastify = Fastify();

fastify.get('*', async (req, reply) => {
    const { stream, shell } = renderDocumentToNodeStream(<App />, { template });
    await shell;
    reply.type('text/html');
    return reply.send(stream);
});

await fastify.listen({ port: 3000 });
```

## Web ReadableStream (edge / Workers)

`renderDocumentToWebStream` returns a `ReadableStream<Uint8Array>` of UTF-8 bytes,
ready to use as a `Response` body:

```tsx
import { renderDocumentToWebStream } from '@sigx/server-renderer/server';
import { App } from './App';

export default {
    fetch(request: Request) {
        const stream = renderDocumentToWebStream(<App />, { template });
        return new Response(stream, {
            headers: { 'Content-Type': 'text/html' },
        });
    },
};
```

## Serving complete content to crawlers

Because `renderDocument` defaults to `'blocking'`, a string render delivers full,
inline content with no client round-trip — exactly what search crawlers and AI
agents want. A single server can branch on the request:

```tsx
import { renderDocument, renderDocumentToNodeStream } from '@sigx/server-renderer/server';

const isBot = /bot|crawler|spider|gptbot|claudebot/i.test(req.headers['user-agent'] ?? '');

if (isBot) {
    const html = await renderDocument(<App />, { template, mode: 'blocking' });
    res.status(200).type('text/html').send(html);
} else {
    const { stream, shell } = renderDocumentToNodeStream(<App />, { template });
    await shell;
    res.status(200).type('text/html');
    stream.pipe(res);
}
```

## Aborting & error handling

`DocumentOptions` carries two controls for the request lifecycle:

- **`signal`** — an `AbortSignal` (client disconnect, timeout). A stream ends
  early without the document tail; a `renderDocument` string render rejects so a
  truncated render never looks successful.
- **`onError(error, phase)`** — `phase` is `'shell'` when the failure happens
  *before* any byte is produced (you can still send a 500 page), or `'stream'`
  when it happens mid-stream after the shell flushed. Per-component errors stream
  their own fallbacks and do **not** reach `onError` — only stream-level failures
  do.

```tsx
const ac = new AbortController();
req.on('close', () => ac.abort());

const { stream, shell } = renderDocumentToNodeStream(<App />, {
    template,
    signal: ac.signal,
    onError(err, phase) {
        if (phase === 'shell') metrics.shellFailures.inc();
        else metrics.streamFailures.inc();
    },
});
```

## Server data with useData and useStream

Data loading lives in the `useData` / `useStream` composables from **`sigx`** —
not in this package. Every read is **keyed, and keyed = server-transferable**:

```tsx
import { component, useData } from 'sigx';

export const UserCard = component(({ props }) => {
    // Keyed: runs on the server, serialized under the key, restored on hydration.
    const user = useData(`user:${props.id}`, async (key, { signal }) => {
        const res = await fetch(`https://api.example.com/users/${props.id}`, { signal });
        return res.json();
    });

    return () => user.match({
        pending: () => <p>Loading…</p>,
        error: () => <p>Failed to load.</p>,
        ready: (u) => <div>{u.name}</div>,
    });
});
```

- **`useData(key, fetcher)`** runs the fetcher on the server, awaits it
  (blocking mode) or streams its placeholder then result (streaming mode),
  serializes the resolved value under `key` into the page's
  `window.__SIGX_ASYNC__` blob, and restores it on hydration — so the fetch does
  **not** run again on the client. The fetcher receives the resolved key as its
  first argument and an `AbortSignal` on the context. Pass `{ server: false }`
  for a client-only keyed read: SSR renders the pending arm and the fetch runs
  after hydration. There is no unkeyed form — a read always has a key.
- **`useStream(key, source)`** is for progressive text (LLM-token-style). On the
  server in streaming mode the tokens append into the page as they arrive and the
  final text is serialized under `key`; in blocking mode it is drained fully and
  inlined. On hydration the final text is restored and the source is **not**
  re-run, so there is no duplicate LLM call.

`renderDocument*` serializes this state automatically (`serializeState: false`
opts out). The `ssr` helper on the component context is now just two flags —
`ctx.ssr.isServer` and `ctx.ssr.isHydrating` — for the rare branch that must know
which environment it is in.

## Defer & lazy on the server

`lazy()` components and `<Defer>` boundaries render correctly on the server:

- **`lazy()`** resolves **inline** — the renderer awaits the component's module
  (`preload()`) during render, then renders the resolved component. No empty
  output, no fallback-forever.
- **`<Defer>` in streaming mode** emits its `fallback` immediately, then swaps in
  **one** replacement once everything pending beneath it — lazy chunks *and*
  keyed `useData` reads — has resolved.
- **`<Defer>` in blocking / string mode** needs no special handling: the pending
  work is awaited inline and the children render directly.

To hydrate a server-resolved `<Defer>` subtree, **preload the lazy chunk before
calling `hydrate()`** so the component is available synchronously during the
hydration walk — see
[Hydration & head](/server/packages/server-renderer/hydration).

## Lower-level render APIs

When you assemble the document yourself (or only need a fragment), the renderer
also exposes the building blocks `renderDocument*` are built on:

| API | Returns | Notes |
|---|---|---|
| `renderToString` | `Promise<string>` | The app shell only — no template, head injection, or state serialization |
| `renderToStream` | web `ReadableStream<string>` | Pull-based, 4 KB batching, natural backpressure |
| `renderToNodeStream` | Node `Readable` | Object-mode stream of HTML chunks |
| `renderToStreamWithCallbacks` | `Promise<void>` | `onShellReady` / `onAsyncChunk` / `onComplete` / `onError` |

These stay **opt-in** for state serialization and head injection — reach for them
only when you have a reason to own the document assembly. For everything else,
`renderDocument*` is the zero-config entry point.

## Plugin-driven rendering

`renderDocument` and the lower-level functions all read the SSR plugins installed
on the app, so you register a pack (islands, a custom strategy) with `app.use(pack())`
and render as usual:

```tsx
import { createSSR } from '@sigx/server-renderer';
import { islandsPlugin } from '@sigx/ssr-islands';
import { defineApp } from 'sigx';

const app = defineApp(<App />).use(islandsPlugin());
const html = await createSSR().renderDocument(app, { template });
```

## Next steps

- [Hydration & head](/server/packages/server-renderer/hydration)
- [Building a full SSR app](/server/packages/server-renderer/full-app)
- [API reference](/server/packages/server-renderer/api)

---
url: https://sigx.dev/server/packages/server-renderer/full-app/
title: Building a full SSR app
description: Wire entry-server, entry-client and an HTTP server into a complete SignalX SSR app — with routing and islands
---

# Building a full SSR app

<p class="lede">The render and hydrate primitives are small on purpose. This guide shows how they fit together into a complete, routed SSR application — and where to reach for the router and islands packages.</p>

## The shape of an SSR app

Every SignalX SSR app has the same three-file backbone plus an HTTP server:

```
src/
  App.tsx           # the shared component tree (runs on server AND client)
  entry-server.tsx  # renders App → HTML for a request
  entry-client.tsx  # hydrates the server HTML in the browser
server.ts           # the HTTP server that calls entry-server per request
```

`App.tsx` is **isomorphic** — the exact same components run on both sides. There
are no special "server components"; the only difference is the entry that drives
them.

## 1. The shared app

```tsx
// src/App.tsx
import { component, useHead } from 'sigx';

export const App = component(() => {
    useHead({ title: 'My SignalX app', htmlAttrs: { lang: 'en' } });
    return () => (
        <main class="app">
            <h1>Hello from SSR</h1>
        </main>
    );
});
```

## 2. The server entry

Create a fresh app per request and render the complete document. `renderDocument`
takes your HTML template and owns the whole response — head injection, the app
shell at the outlet, and the serialized state blob:

```tsx
// src/entry-server.tsx
import { defineApp } from 'sigx';
import { renderDocument } from '@sigx/server-renderer/server';
import { App } from './App';

const template = `<!DOCTYPE html>
<html>
  <head><meta charset="utf-8" /></head>
  <body>
    <div id="root"><!--ssr-outlet--></div>
    <script type="module" src="/entry-client.js"></script>
  </body>
</html>`;

export function render() {
    const app = defineApp(<App />);            // App form preserves AppContext
    return renderDocument(app, { template });  // Promise<string>
}
```

The `App` form (from `defineApp()`) preserves the `AppContext`, so `inject()` and
plugins — a router, islands — work during render. To add a pack, install it on the
app and render the same way: `defineApp(<App />).use(islandsPlugin())`, then
`renderDocument(app, { template })`.

## 3. The client entry

Hydrate instead of mounting. `ssrClientPlugin` adds `.hydrate()` to the app:

```tsx
// src/entry-client.tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';

defineApp(<App />)
    .use(ssrClientPlugin)
    .hydrate('#root');
```

## 4. The HTTP server

`render()` already returns the complete document, so the server just sends it and
serves the built client bundle as static files:

```ts
// server.ts
import express from 'express';
import { render } from './entry-server';

const app = express();
app.use(express.static('dist/client'));

app.get('*', async (req, res) => {
    const html = await render();
    res.status(200).set('Content-Type', 'text/html').send(html);
});

app.listen(3000);
```

For streaming instead of buffering, swap `renderDocument` for
`renderDocumentToNodeStream` from `@sigx/server-renderer/node` — it returns
`{ stream, shell }`; await `shell` to pick the status code, then pipe. See
[Rendering & streaming](/server/packages/server-renderer/rendering).

## A shortcut: `createRequestHandler`

Wiring the template, a fresh app per request, streaming, and the bot/redirect
decisions by hand is repetitive. `createRequestHandler` from
`@sigx/server-renderer/node` packages it into a Node/Connect handler:

```ts
// server.mjs
import { createRequestHandler } from '@sigx/server-renderer/node';
import { collectAssets } from '@sigx/vite/assets';
import { App } from './dist/server/entry-server.js';
import manifest from './dist/client/.vite/manifest.json' with { type: 'json' };

const handler = createRequestHandler({
    template,
    app: (url) => defineApp(<App />).use(createServerRouter(url)),   // fresh app per request
    document: { assets: collectAssets(manifest, ['src/entry-client.tsx']) },
});

server.use(handler);
```

The handler owns `template` and the render `mode`: it streams shell-first for
normal visitors and switches to `mode: 'blocking'` for crawlers (override the
detection with `isBot`). The shell is the status/redirect decision point — a
[`useResponse().redirect(...)`](/server/packages/server-renderer/request-lifecycle)
sends the location and no body. It is deliberately **not** a meta-framework: no
file-system routing, no conventions beyond these seams.

`document.assets` (from `collectAssets(manifest, entries)`) injects
`<link rel="modulepreload">` and stylesheet links before `</head>` on the first
flush; every lazy boundary chunk is preloaded on top of that, deduped.

`collectAssets` lives at `@sigx/vite/assets`, an entry that imports nothing at
all — no `node:` builtins, no `process` — so it runs on workerd, Deno and Bun as
happily as on Node. `@sigx/vite/ssr` is the dev half (`createDevRequestHandler`)
and is Node-only by nature; it re-exports `collectAssets` too, so an existing

## Adding routing

Real apps render different pages per URL. `@sigx/server-renderer` does **not**
know about routes — routing is the router's job. The pattern is: build the router
**per request** on the server (memory history) and **once** on the client (web
history), then `.use(router)` on both apps.

```tsx
// entry-server.tsx (sketch)
const app = defineApp(<App />).use(createServerRouter(req.url));
```

`@sigx/router` is isomorphic and integrates directly with `createSSR()`. Rather
than repeat it here, follow the complete, verified walkthrough — router factory,
per-request instances, data loading and SSR redirects:

> **→ [SSR Routing with `@sigx/router`](/router/docs/ssr)**

## Adding islands (selective hydration)

By default `hydrate()` re-attaches reactivity to the **whole** tree. For a mostly
static page with a few interactive spots, hydrate only those islands with
`@sigx/ssr-islands`: mark components `client:visible` / `client:idle` / … in your
JSX, register the plugin on the server, and call `hydrateIslands()` on the client.

> **→ [Islands & selective hydration](/server/packages/ssr-islands/overview)**

## Build & dev

`@sigx/vite`'s SSR mode builds both bundles from one `vite build` and gives you a
dev handler that shares a module graph with your app:

- **Dev** — `createDevRequestHandler` from `@sigx/vite/ssr` renders through Vite's
  module runner, so `entry-server` and `entry-client` hot-reload together.
- **Build** — `sigx({ ssr: { entry } })` emits the client bundle (served
  statically, with its manifest) and the server bundle in one build.

See [Vite SSR mode](/vite/docs/ssr) for the full config.

## Next steps

- [The fetch handler](/server/packages/server-renderer/fetch-handler) — the same handler in WinterCG shape, for Workers, Deno, Bun and the edge.
- [The boundary model](/server/packages/server-renderer/boundaries) — flush and hydrate axes.
- [Request lifecycle](/server/packages/server-renderer/request-lifecycle) — `useResponse`, the error seam, the `./node` entry.
- [Vite SSR mode](/vite/docs/ssr) — the build and dev-server setup.
- [SSR Routing](/router/docs/ssr) — the full router integration.
- [Islands](/server/packages/ssr-islands/overview) — `client:*` selective hydration.

---
url: https://sigx.dev/server/packages/server-renderer/overview/
title: Overview
description: "@sigx/server-renderer — streaming SSR and client hydration"
---

# Server Renderer

<p class="lede">`@sigx/server-renderer` renders your SignalX component tree to HTML on the server — as a string or a stream — then re-attaches reactivity in the browser by hydrating the existing DOM instead of re-creating it.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> ESM-only <span class="mmr-dot" /> MIT</p>

It is the **base SSR package**: the renderer and hydrator are deliberately
*strategy-agnostic* — they know nothing about islands, selective hydration, or
resumability. Those strategies layer on top through a small plugin SPI, so you
only ship what you use. For `client:*` selective hydration, add
[`@sigx/ssr-islands`](/server/packages/ssr-islands/overview) on top.

## What you get

- **Document render APIs** — `renderDocument` (string), `renderDocumentToNodeStream`
  (Node), and `renderDocumentToWebStream` (edge) take an HTML template with an
  outlet and own the **complete** response: head injection, app shell, state
  serialization, and async content — no hand-splicing in your server.
- **Lower-level render APIs** — `renderToString`, `renderToStream` (web
  `ReadableStream`), `renderToNodeStream` (Node `Readable`), and a callback-based
  variant when you assemble the document yourself.
- **Server data loading** — components fetch on the server via keyed
  [`useData`](/core/docs/data-loading) / `useStream` (from `sigx`); their resolved
  values are serialized into the page and restored on hydration, so the fetch does
  not run twice.
- **Hydration** — `defineApp(<App/>).use(ssrClientPlugin).hydrate('#root')`
  re-attaches handlers and effects to server-rendered DOM, with structural
  mismatch self-healing.
- **Head management** — `useHead()` (from `sigx`) collects title/meta/link/script
  from inside components; the document renderer injects them before `</head>`.
- **A plugin SPI** — install packs with `app.use(plugin)`, plus `registerClientPlugin()` — the
  extension points islands, resumable, and `Defer` strategies build on.

## The three subpaths

The package splits into three tree-shakeable entry points (all
`sideEffects: false`) so a browser bundle never pulls in Node code:

| Import path | Use it for |
|---|---|
| `@sigx/server-renderer` | `createSSR`, `renderDocument`, `ssrClientPlugin`, `renderHeadToString`, shared types |
| `@sigx/server-renderer/server` | `renderDocument*`, `renderToString`, `renderToStream`, `renderToNodeStream` — Node render APIs |
| `@sigx/server-renderer/client` | `hydrate`, `ssrClientPlugin`, hydration internals |

> `useHead`, `useData`, and `useStream` are part of core **`sigx`**, not this
> package — they work the same in any component and gain server behavior when this
> renderer drives them.

## A minimal end-to-end example

### 1. A shared component

```tsx
// src/App.tsx
import { component } from 'sigx';

export const App = component(({ signal }) => {
    const count = signal(0, 'count');
    return () => (
        <div class="app">
            <h1>Hello from SignalX SSR</h1>
            <button onClick={() => count(count() + 1)}>
                Count: {count()}
            </button>
        </div>
    );
});
```

### 2. Render on the server

Give the renderer a template with an `<!--ssr-outlet-->` marker and it assembles
the whole document — the app shell at the outlet, head tags before `</head>`, and
the serialized state blob:

```tsx
// src/entry-server.tsx
import { renderDocument } from '@sigx/server-renderer/server';
import { App } from './App';

const template = `<!DOCTYPE html>
<html>
  <head><meta charset="utf-8" /></head>
  <body>
    <div id="root"><!--ssr-outlet--></div>
    <script type="module" src="/src/entry-client.tsx"></script>
  </body>
</html>`;

export function render() {
    return renderDocument(<App />, { template });
}
```

### 3. Hydrate on the client

```tsx
// src/entry-client.tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';

defineApp(<App />)
    .use(ssrClientPlugin)
    .hydrate('#root');
```

`hydrate()` walks the existing server DOM and attaches the click handler and
reactive effects — no DOM is re-created. If the container has no SSR content,
`hydrate()` falls back to a fresh client render.

## Next steps

- [Installation](/server/packages/server-renderer/installation) — install, the `sigx` dependency, and the subpath import map.
- [Rendering & streaming](/server/packages/server-renderer/rendering) — wire the document render APIs into Express, Fastify, or an edge runtime, plus server data with `useData`/`useStream`.
- [Hydration & head](/server/packages/server-renderer/hydration) — the hydration entry, head management, and the plugin SPI.
- [Building a full SSR app](/server/packages/server-renderer/full-app) — entry wiring, an HTTP server, and routing with `@sigx/router`.
- [API reference](/server/packages/server-renderer/api) — every export with signatures.

---
url: https://sigx.dev/server/packages/ssr-islands/installation/
title: Installation
description: Install @sigx/ssr-islands, its dependency, and the four subpath entry points
---

# Installation

<p class="lede">Add `@sigx/ssr-islands` on top of the server renderer and enable the `client:*` JSX types.</p>

## Install

```bash
pnpm add @sigx/ssr-islands
```

## Dependencies

`@sigx/ssr-islands` depends on **`@sigx/server-renderer`** (pulled in
automatically) and lists **`sigx`** as a peer dependency — so it slots into an app
you already render with the server renderer. The package is **ESM-only**.

If you are starting from scratch, install all three:

```bash
pnpm add sigx @sigx/server-renderer @sigx/ssr-islands
```

## Subpath imports

The package ships three entry points:

| Import path | Use it for |
|---|---|
| `@sigx/ssr-islands` | Everything — `islandsPlugin`, client hydration, registry, server helpers |
| `@sigx/ssr-islands/server` | Server-only island utilities (`createTrackingSignal`, `serializeSignalState`) |
| `@sigx/ssr-islands/client` | Client hydration + registry (`hydrateIslands`, `registerComponent`, `loadIslandComponent`, …) |

The main entry re-exports both the server and client surfaces, so most apps just

## Enabling the client:\* directives

Nothing to enable. Importing the pack from anywhere in the program — the server's
`@sigx/ssr-islands`, the client's `@sigx/ssr-islands/client` — augments JSX
program-wide, so the attributes type-check everywhere:

```tsx
// now valid, with no directive-specific import:
<Counter client:visible />
```

This is the same zero-import registration core's `use:*` directives use.

> **Upgrading from 0.13 or earlier:** there used to be a types-only
> `@sigx/ssr-islands/jsx` entry you had to import once. That subpath no longer
> exists as of core 0.14 — delete any `import '@sigx/ssr-islands/jsx';` or
> `/// <reference types="@sigx/ssr-islands/jsx" />`. Nothing replaces it.

## Next steps

- [Client directives](/server/packages/ssr-islands/client-directives)
- [Plugin setup](/server/packages/ssr-islands/plugin-setup)
- [API reference](/server/packages/ssr-islands/api)

---
url: https://sigx.dev/server/packages/ssr-islands/plugin-setup/
title: Plugin setup
description: Register islandsPlugin() on the server, configure custom strategies and manifests, and transfer signal state
---

# Plugin setup

<p class="lede">`islandsPlugin()` is an `SSRPlugin` for `@sigx/server-renderer`. On the server it intercepts `client:*` components, captures their signal state, and injects the hydration data; on the client it schedules deferred hydration.</p>

## Registering the plugin

Install it on your app with `.use()`:

```tsx
import { createSSR } from '@sigx/server-renderer';
import { islandsPlugin } from '@sigx/ssr-islands';
import { defineApp } from 'sigx';
import { App } from './App';

// Minimal HTML shell — the rendered app replaces the outlet marker.
const template = `<!DOCTYPE html><html><body><!--ssr-outlet--></body></html>`;

const app = defineApp(<App />).use(islandsPlugin());
const html = await createSSR().renderDocument(app, { template });   // or .render(app) for a shell
```

That single registration wires both the server hooks (during render) and the
client hooks (during hydration). On the client you still register the island
components and call `hydrateIslands()` — see
[Registry & code splitting](/server/packages/ssr-islands/registry-and-code-splitting).

## What it does

During render, the plugin:

- maps each `client:*` directive onto a [boundary record](/server/packages/server-renderer/boundaries) via `resolveBoundary`,
- captures the component's signal state (so the client can restore it instead of re-fetching),
- manages async streaming for islands, and
- writes each island's strategy, props, `state` and (optionally) chunk reference into the core boundary record — serialized into the page as `window.__SIGX_BOUNDARIES__`.

During hydration, it schedules each recorded boundary according to its strategy
(`load` / `idle` / `visible` / `media` / `interaction` / `only`). When an island
hydrates it **resumes from the server-captured signal state** on its boundary
record's `state` instead of re-initialising — each signal is seeded back to its
server value. A `client:only` island has no captured `state`, so it simply mounts
fresh.

## Automatic state keys

Signal state transfers by **key**, and the keys are derived for you — they are not
part of your component's API. The [`sigxIslands()` Vite transform](/vite/docs/ssr#the-islands-transform)
reads the declaration identifier of each signal and uses it as the key:

```tsx
export const Counter = component((ctx) => {
    const count = ctx.signal(0);   // transform keys this "count"
    return () => <button onClick={() => count.value++}>{count.value}</button>;
}, { name: 'Counter' });
```

The server captures `count` under `"count"`; the client restores it from the same
key. The rule is **named = transferred**: a signal the transform can key travels
from server to client, and a signal it can't — a bare `signal()` import, or a call
that isn't a simple declaration — is just plain local state, created fresh on each
side from the same initial value.

Two properties make this safe:

- Keys are **namespaced per island boundary**, so two different islands can both
  call their signal `state`, and two instances of one island each keep their own.
- Within a single island a **duplicate key is first-wins** — a later signal with
  the same name stays local, with a dev warning — so restoration can never map a
  value onto the wrong signal.

The upshot: any server/client asymmetry degrades to *not transferred*, never to
restoring a wrong value. This matches the rest of the family — `useData`'s content
key, `defineStore(name)` — where **state identity is explicit or there is no
transfer**.

## Options

`islandsPlugin(options?)` takes an `IslandsPluginOptions`:

```ts
interface IslandsPluginOptions {
    /** Custom client-side hydration strategies, keyed by name. */
    strategies?: Record<string, (el: Element, hydrate: () => void) => void>;
    /** Island manifest mapping component names to their chunk URLs. */
    manifest?: Record<string, { chunkUrl: string; exportName: string }>;
}
```

### Custom strategies

Add your own scheduling strategy alongside the built-in six. A strategy receives
the element and a `hydrate` callback to invoke when it should run:

```tsx
const app = defineApp(<App />).use(islandsPlugin({
    strategies: {
        // hydrate after a fixed delay
        delayed: (el, hydrate) => setTimeout(hydrate, 2000),
    },
}));
```

### Manifest (chunk URLs)

Pass a `manifest` so islands carry their chunk URL in the hydration data — the
client can then load each chunk on demand **without** an eager
`registerComponent()` call. The manifest is generated by
[`sigxIslands()`](/vite/docs/ssr#the-islands-transform) from `@sigx/vite/islands`
during the build, at `.vite/sigx-islands-manifest.json`:

```tsx
import manifest from './dist/client/.vite/sigx-islands-manifest.json';

const app = defineApp(<App />).use(islandsPlugin({ manifest }));
```

With a manifest, each island's `chunkUrl` and `exportName` are written into its
boundary record, and `loadIslandComponent()` resolves the component straight from
its chunk.

## Signal-state transfer (low level)

The plugin handles state capture for you. The underlying helpers are exported for
custom server pipelines (from `@sigx/ssr-islands` or `@sigx/ssr-islands/server`):

- `createTrackingSignal(signalMap)` — a `signal()` replacement that records signal
  keys and values during setup.
- `serializeSignalState(signalMap)` — serialize the captured map onto the boundary
  record's `state`, for the client to restore.

Keys are the [automatic keys](#automatic-state-keys) the `sigxIslands()` transform
assigns, so server capture and client restore line up. For keyed
`useData`/`useStream` data the key is the call's own key, serialized into the page
automatically — see
[Rendering & streaming](/server/packages/server-renderer/rendering#server-data-with-usedata-and-usestream).

## Next steps

- [Registry & code splitting](/server/packages/ssr-islands/registry-and-code-splitting)
- [Client directives](/server/packages/ssr-islands/client-directives)
- [API reference](/server/packages/ssr-islands/api)

---
url: https://sigx.dev/terminal/packages/terminal-zero/overview/
title: Overview
description: "@sigx/terminal-zero — the headless, design-system-neutral foundation for SignalX terminal UIs"
---

# Terminal Zero

<p class="lede">The headless, design-system-neutral foundation of the terminal stack: the token contract, the theme engine (`resolveColor`, `setTheme`), shared glyphs, layout primitives (`Box`, `Row`, `Col`, `Text`, …) and the prompts engine. No fixed look — skins build on it.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

The `@sigx/terminal` umbrella re-exports this package, so most apps never install it
directly. `@sigx/terminal-ui` — the SigX-tui skin — is built entirely on its tokens;
install it on its own when you're authoring a custom design system:

```bash
pnpm add @sigx/terminal-zero
```

## What lives here

- **The token contract & theme engine** — components ask for semantic tokens
  (`accent`, `fg`, `line`, `success`, …) that resolve against the active theme at
  render time; skins register concrete themes on top. See
  [Theming](/terminal/docs/theming/).
- **Layout primitives** — the flexbox-style `Box` / `Row` / `Col` / `Text` building
  blocks every terminal component composes. See
  [Layout & styling](/terminal/docs/layout-and-styling/).
- **The prompts engine** — the headless half of the
  [prompt kit](/terminal/docs/prompts/); `@sigx/terminal-ui` themes it.

## Next steps

See where it sits in the stack in [Architecture](/terminal/docs/architecture/), or
jump to the [API reference](/terminal/packages/terminal-zero/api).

---
url: https://sigx.dev/actors/packages/actors-cli/installation/
title: Installation
description: Flags, the app-module convention that unlocks panels, health exit codes and the dashboard keys
---

# Installation

<p class="lede">Install it as a devDependency of the package that owns the host, and the
commands appear.</p>

## Install

```bash
pnpm add -D @sigx/actors-cli
```

Requires `@sigx/cli` ≥ 0.9 and `@sigx/terminal` ≥ 0.11.

## Flags

| Flag | Default | Meaning |
|---|---|---|
| `--url` | — | poll a running host's ops endpoint; wins over a local module |
| `--secret` | `$SIGX_OPS_SECRET` | bearer token for that endpoint |
| `--base` | — | ops mount base path |
| `--app` | discovered | path to the actor app module, for embedded mode |
| `--timeout` | `5000` | request timeout, ms |
| `--json` | off | machine-readable output |
| `--interval` | `1000` | dashboard refresh, ms |

`SIGX_OPS_SECRET` is the preferred way to pass the token — a secret in `--secret` lands in
your shell history and in `ps`.

## The app-module convention

Embedded mode reads named exports from your app module. `app` is required; the rest each
unlock panels:

```ts
// src/actors.app.ts
export const app = defineActorApp({ actors, storage }).use(metrics()).use(health());
export const metrics = m;        // unlocks the latency and error panels
export const ops = o;            // unlocks the ops sections
export const cluster = c;        // unlocks the cluster tab
```

Without `metrics`, the dashboard still runs — it simply has less to show.

## Health exit codes

```sh
sigx actors health --url http://host:7311
```

| Code | Means |
|---|---|
| `0` | ready |
| `1` | reachable but **not ready** |
| `2` | unreachable, or a usage error |

> `1` and `2` are deliberately distinct. A host answering "not ready" is alive and draining; a
> host answering nothing is a different incident. Collapsing them makes an alert unable to
> tell a rolling deploy from an outage.

## The dashboard

`sigx actors` (or `top`) opens the dashboard. It is width- and height-aware: tables window to
the rows available and scroll to follow the cursor, columns shrink from the right so a host id
or actor key is never truncated, and alert banners wrap.

| Key | Action |
|---|---|
| `j` / `k` | move the cursor **on the visible tab only** |
| `enter` | open a per-host drill-down on the Hosts tab |
| `esc` | close it |

Detail is only requested while a drill-down is open, so the extra load is opt-in.

**Every panel states its scope** — cluster-wide or one host. That distinction is easy to lose
and expensive to get wrong. The `READY` column shows `FATAL` distinctly from not-ready, per
[Health & readiness](/actors/docs/health-and-readiness).

## Next steps

- [API reference](/actors/packages/actors-cli/api) — the `/source` data layer.
- [Cluster stats](/actors/docs/cluster-stats) — what the panels are showing.
- [The ops endpoint](/actors/docs/ops-endpoint) — mounting what `--url` reads.

---
url: https://sigx.dev/actors/packages/actors-surreal/overview/
title: Overview
description: "Membership, directory, storage & reminders on SurrealDB 3 — the SurrealDB package for SignalX (@sigx/actors-surreal): what it does, setup and API."
---

# SurrealDB

<p class="lede">The whole cluster on SurrealDB — etag compare-and-set storage,
database-clock membership, the single-activation directory, and durable reminders on a
due-time index. Four providers over one connection.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-surreal surrealdb
```

## What it provides

| Provider | Seam | What it does |
|---|---|---|
| `surrealStorage` | [`ActorStorage`](/actors/docs/storage) | Persisted state with etag CAS, so two hosts can never both persist an activation. |
| `surrealMembership` | `ClusterMembership` | TTL heartbeats judged on the **database** clock, so a skewed host cannot fake a death or a survival. |
| `surrealDirectory` | `ActorDirectory` | The single-activation claim: create-if-absent returning the *winner*, plus compare-and-delete release. |
| `surrealReminders` | `ActorReminders` | Durable reminders on a due-time-indexed table — one indexed query per tick instead of scanning shard records. |

`surrealCluster` bundles membership and directory for `cluster({ providers })`.

## Requirements

SurrealDB **≥ 3.0**, with **3.2.4 or newer recommended**. `surrealdb` (the JS SDK) `^2.0.8`
is a peer dependency.

**Prefer a `ws://` or `wss://` endpoint.** The HTTP engine re-authenticates on every request
and cannot serve live queries, so membership push is unavailable over it.

## Three things to get right

Each of these produces wrong behaviour silently rather than an error, so they are worth
reading before the setup steps.

### 1. Retry is part of the contract, not tuning

**If you pass your own connected `Surreal`, you must install `surrealRetryable` on it.**

SurrealDB has no `SELECT … FOR UPDATE`, no `SKIP LOCKED` and no advisory lock. Snapshot
isolation with a commit-time write–write check is the only mutual exclusion available — so
the directory's `claim()` and the create arm of `save()` are correct *because* two racers
collide and the loser re-runs to observe the winner.

Without a retry, the loser raises a raw conflict error instead of returning the winning
entry. And the SDK ships retry **disabled by default**: its own `isRetryableConflict` matches
only the structured `TransactionConflict` detail (wire code `-32009`), which in practice never
arrives — a conflicting statement surfaces as a message through the `NotExecuted` path
instead. `surrealRetryable` matches what actually arrives.

### 2. The DDL step is mandatory

Unlike Postgres, this is not optional. Reading an **undefined** table is an error in
SurrealDB 3, where 2.x returned `[]`. So `ensureSurrealSchema()` (or the equivalent migration
through `surrealSchemaSql()`) must run before a host starts.

The providers never issue DDL themselves, so a production role needs only DML grants.

### 3. Membership push is best-effort and single-node

Push is a **live query**, and SurrealDB documents live queries as single-node-only, unordered
and at-most-once. A silent expiry also produces no write to notify on.

**The poll is the guarantee.** Do not deploy multi-node expecting push-speed convergence; set
`push: false` to turn it off entirely. It listens on the version *table* rather than a record,
because record-scoped live queries fail to listen on 3.2.4 — and that table holds one record.

## State is stored as a JSON string

Deliberately, and the trade is worth knowing: **state is opaque in Surrealist.**

Actor state is whatever the codec produced. It may be a top-level array or scalar, may contain
NUL, and distinguishes `null` from absent. Round-tripping that through SurrealDB's value model
would risk `none`/`null` conflation, datetime and record-id reinterpretation, and v3's
collapsing of differently-typed numeric ids. One `JSON.stringify` round-trips it exactly.

## Next steps

- [Installation](/actors/packages/actors-surreal/installation) — the schema step and wiring a host.
- [API reference](/actors/packages/actors-surreal/api) — every export and option.
- [Storage](/actors/docs/storage) — the `ActorStorage` seam these implement.
- [Clustering](/actors/docs/clustering) — membership, directory and the required secret.

---
url: https://sigx.dev/actors/packages/actors-k8s/installation/
title: Installation
description: RBAC for Lease access, the options table, clock assumptions, scale limits and running against kubectl proxy locally
---

# Installation

<p class="lede">One Role, one RoleBinding, and everything else is discovered from the pod.</p>

## Install

```bash
pnpm add @sigx/actors-k8s
```

## RBAC

The ServiceAccount needs Lease access in the host namespace, and nothing else:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
    name: sigx-actors-membership
rules:
    - apiGroups: ["coordination.k8s.io"]
      resources: ["leases"]
      verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
    name: sigx-actors-membership
roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: Role
    name: sigx-actors-membership
subjects:
    - kind: ServiceAccount
      name: my-host
```

## Options

| Option | Default | Meaning |
|---|---|---|
| `namespace` | ServiceAccount namespace, else `default` | where the Leases live |
| `clusterName` | `default` | value of the `sigx.dev/cluster` label — two clusters can share a namespace |
| `labels` | — | extra labels stamped on the own Lease **and** selecting peers |
| `leasePrefix` | `sigx` | Lease names are `{leasePrefix}-{hostId}` |
| `heartbeatMs` | `5000` | Lease renewal cadence |
| `ttlMs` | `15000` | liveness TTL, serialized as `spec.leaseDurationSeconds` |
| `clockSkewMs` | `2000` | slack added to peer freshness checks |
| `relistMs` | `60000` | reconciling LIST cadence under the watch; `0` disables |
| `apiServer` | in-cluster env, else `https://kubernetes.default.svc` | API server origin |
| `token` | ServiceAccount token file | bearer token, or a provider function |
| `ca` | ServiceAccount `ca.crt` | PEM bundle |
| `fetch` | `node:https` shim | transport override |
| `watchBackoff` | `{ minMs: 250, maxMs: 5000 }` | watch reconnect bounds |

## Clocks

`renewTime` is written by each host's own clock and compared against the observer's, so peer
freshness assumes NTP-synced nodes — the same assumption kubelet node Leases make.
`clockSkewMs` is the slack; raise it if your nodes drift more.

If that assumption is uncomfortable, [`pgMembership()`](/actors/packages/actors-pg/overview)
judges expiry on the database clock instead.

## Scale

Every renewal is a watch event delivered to every host: **n hosts beating every 5s ≈ n²/5
events per second** cluster-wide.

At tens of hosts this is trivial — 30 hosts is about 180 tiny JSON lines per second, and none
of them touch the membership view, because renewals never bump its version. Only
descriptor-set changes (join, leave, drain, expiry) do.

For hundreds of hosts, raise `heartbeatMs` and `ttlMs`; the volume falls quadratically.

## Local development

Kubeconfigs are deliberately not parsed — client certificates and exec plugins are a
dependency magnet. Let `kubectl` do the auth instead:

```sh
kubectl proxy --port=8001
```

```ts
k8sMembership({ apiServer: 'http://127.0.0.1:8001', token: '', ca: '' });
```

## Next steps

- [API reference](/actors/packages/actors-k8s/api) — exports and fencing behaviour.
- [Kubernetes deployment](/actors/docs/kubernetes) — probes, preStop and scaling.
- [Clustering](/actors/docs/clustering) — the plugin options.

---
url: https://sigx.dev/actors/packages/actors-tcp/installation/
title: Installation
description: Options for tcpTransport, why advertiseHost matters on a multi-homed box, and how simultaneous dials are resolved
---

# Installation

<p class="lede">One option matters more than the rest, and it is the one with a bad
default for real deployments.</p>

## Install

```bash
pnpm add @sigx/actors-tcp
```

Node-only — this package uses `node:net`.

## Use it in a chain

```ts
import { cluster, httpTransport } from '@sigx/actors/cluster';
import { tcpTransport } from '@sigx/actors-tcp';

cluster({
    providers, secret,
    advertise: `http://${process.env.POD_IP}:7311`,
    transport: [
        tcpTransport({ port: 11111, advertiseHost: process.env.POD_IP }),
        httpTransport(),
    ],
});
```

## Options

| Option | Default | Meaning |
|---|---|---|
| `port` | — | the port to listen on |
| `host` | — | bind address |
| `advertiseHost` | the bind host, else `127.0.0.1` | **what peers dial** |
| `maxFrameBytes` | — | frame size cap |
| `credit` | — | flow-control window |
| `keepAliveMs` | `15000` | keep-alive cadence |

> **`advertiseHost` matters on a multi-homed box.** It defaults to the bind host and, failing
> that, to `127.0.0.1` — which is wrong for any real deployment, because peers will dial their
> own loopback and never reach you. Set it to the address peers can actually resolve: a pod
> IP, a private-network address, a service DNS name.

The advertised address takes the form `tcp://host:port`.

## Simultaneous dials

Two hosts discovering each other at the same moment would otherwise open two connections. The
tie is broken deterministically: **the lexicographically smaller `hostId` is the designated
dialer.**

## Failures

A connect failure surfaces as `ActorUnreachableError`, which is retryable by design — see
[Errors](/actors/docs/errors). In a chain, an unreachable TCP peer falls through to the next
transport; as a **single** transport it is strict, and a peer advertising no `tcp` address is
unreachable loudly. That is deliberate, so a silent fallback cannot make you benchmark the
wrong wire.

## Security

Frames are authenticated per request with the cluster HMAC, exactly as over HTTP.
**Transport encryption is out of scope** — run mTLS or a private network between hosts. See
[Design notes](/actors/docs/design-notes).

## Next steps

- [API reference](/actors/packages/actors-tcp/api) — exports.
- [Host transports](/actors/docs/transports) — choosing, and the conformance suite.
- [Clustering](/actors/docs/clustering) — where the transport plugs in.

---
url: https://sigx.dev/core/packages/runtime-core/installation/
title: Installation
description: Install and configure @sigx/runtime-core, the Runtime Core package for SignalX.
---

# Installation

<p class="lede">Add `@sigx/runtime-core` to your project.</p>

## Install the package

```bash
pnpm add @sigx/runtime-core
```

## Verify

```tsx
import * as RuntimeCore from '@sigx/runtime-core';

console.log(Object.keys(RuntimeCore));
```

---
url: https://sigx.dev/deploy/packages/cloudflare/installation/
title: Installation
description: Install and configure @sigx/cloudflare, the Cloudflare adapter for SignalX.
---

# Installation

<p class="lede">Add `@sigx/cloudflare` to your project — a build-time dev dependency, alongside `wrangler` for deploys.</p>

## Install the package

```bash
pnpm add -D @sigx/cloudflare
pnpm add -D wrangler   # deploys, and the devProxy local bindings
```

## Wire the adapter

The adapter is passed to the sigx Vite plugin — a separate platform config keeps
the default Node build untouched:

```ts
// vite.config.cloudflare.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { cloudflare } from '@sigx/cloudflare';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: cloudflare() } })]
});
```

## Verify

```bash
vite build --app -c vite.config.cloudflare.ts
```

The first build scaffolds `src/entry.cloudflare.ts` and a starter
`wrangler.jsonc` (both only when absent — they are yours afterwards) and writes
the bundled worker plus client assets. `wrangler dev` serves the result from
local workerd.

---
url: https://sigx.dev/daisyui/docs/components/radial-progress/
title: Radial Progress
description: Radial progress shows a circular progress indicator with customizable size and color
---

# Radial Progress

Radial progress shows a circular progress indicator. Uses CSS custom properties `--value`, `--size`, and `--thickness` for full control.

## Import

```tsx
import { RadialProgress } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { RadialProgress } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <RadialProgress value={70}>70%</RadialProgress>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

Apply semantic colors to the progress ring.

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <RadialProgress value={60} color="primary">60%</RadialProgress>
            <RadialProgress value={70} color="secondary">70%</RadialProgress>
            <RadialProgress value={80} color="accent">80%</RadialProgress>
            <RadialProgress value={90} color="neutral">90%</RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Status Colors

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <RadialProgress value={50} color="info">50%</RadialProgress>
            <RadialProgress value={70} color="success">70%</RadialProgress>
            <RadialProgress value={85} color="warning">85%</RadialProgress>
            <RadialProgress value={40} color="error">40%</RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Size

Use the `size` prop to control the diameter of the circle.

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <RadialProgress value={70} size="4rem">70%</RadialProgress>
            <RadialProgress value={70} size="6rem">70%</RadialProgress>
            <RadialProgress value={70} size="8rem">70%</RadialProgress>
            <RadialProgress value={70} size="12rem">70%</RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Thickness

Use the `thickness` prop to control the stroke width of the progress ring.

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <RadialProgress value={70} thickness="2px">thin</RadialProgress>
            <RadialProgress value={70} thickness="4px">4px</RadialProgress>
            <RadialProgress value={70}>default</RadialProgress>
            <RadialProgress value={70} thickness="1rem">thick</RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Styled Background

Combine with Tailwind utility classes for styled backgrounds.

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <RadialProgress
                value={75}
                color="primary"
                class="bg-primary text-primary-content border-primary border-4"
            >
                75%
            </RadialProgress>
            <RadialProgress
                value={90}
                color="success"
                class="bg-success text-success-content border-success border-4"
            >
                90%
            </RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Different Values

```tsx
import { component, render } from 'sigx';
import { RadialProgress, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <RadialProgress value={0}>0%</RadialProgress>
            <RadialProgress value={25}>25%</RadialProgress>
            <RadialProgress value={50}>50%</RadialProgress>
            <RadialProgress value={75}>75%</RadialProgress>
            <RadialProgress value={100}>100%</RadialProgress>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `0` | Progress value (0-100) |
| `size` | `string` | `'5rem'` | Diameter of the circle (CSS value, sets `--size`) |
| `thickness` | `string` | `undefined` | Stroke width (CSS value, sets `--thickness`) |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Color of the progress ring |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/terminal/docs/components/suggestionlist/
title: SuggestionList
description: An intellisense-style completion popup that overlays an input
---

# SuggestionList

<p class="lede">An intellisense popup for an input. Mount it to open it — typically rendered conditionally under a <a href="/terminal/docs/components/textarea">TextArea</a> while the value matches a trigger like <code>/</code>.</p>

## Import

```tsx
import { SuggestionList } from '@sigx/terminal';
import type { SuggestionItem } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, TextArea, SuggestionList } from '@sigx/terminal';
import type { SuggestionItem } from '@sigx/terminal';

const commands: SuggestionItem[] = [
    { value: '/help', description: 'Show help' },
    { value: '/clear', description: 'Clear the screen' },
    { value: '/quit', description: 'Exit' },
];

const App = component(() => {
    const input = signal('');
    return () => (
        <box border="rounded" label="Command">
            <TextArea model={() => input} placeholder="Type /…" autofocus />
            {input.value.startsWith('/') && (
                <SuggestionList
                    items={commands.filter((c) => c.value.startsWith(input.value))}
                    maxVisible={5}
                    onAccept={(v) => { input.value = v; }}
                    onDismiss={() => { /* close */ }}
                />
            )}
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `SuggestionItem[]` | **required** — the suggestions |
| `maxVisible` | `number` | rows before scrolling |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `accept` | `string` | Tab/Enter on the highlighted item |
| `dismiss` | — | Esc |

It registers an **overlay**-layer key handler (see [layered key dispatch](/terminal/docs/input-and-components)) that consumes only navigation keys — ↑/↓ move, Tab/Enter accept, Esc dismisses — while printable characters, backspace and the rest fall through to the input below, so filtering keeps working as the user types.

## SuggestionItem

```ts
interface SuggestionItem {
    value: string;
    label?: string;       // defaults to value
    description?: string;
}
```

## See also

- [TextArea](/terminal/docs/components/textarea) — the input it overlays.

---
url: https://sigx.dev/terminal/packages/terminal-dev/overview/
title: Overview
description: "@sigx/terminal-dev — HMR for terminal apps: edit a component, the running TUI updates in place"
---

# Terminal Dev

<p class="lede">`@sigx/terminal-dev` is an HMR dev runner for SignalX terminal apps. Run your TUI under an in-process Vite dev server, save a component file, and watch the **running** terminal app update in place — no restart, no lost state.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> devDependency <span class="mmr-dot" /> MIT</p>

It is not part of the `@sigx/terminal` umbrella — install it as a dev dependency:

```bash
npm install -D @sigx/terminal-dev
```

## Running an app

The package installs a `sigx-terminal-dev` binary:

```bash
sigx-terminal-dev                  # auto-detect src/main.tsx and similar
sigx-terminal-dev src/main.tsx     # point at the mount module
sigx-terminal-dev --root path/to/app
sigx-terminal-dev --config vite.config.ts   # layer your own Vite config on top
```

Point it at the module that **mounts** your app:

```tsx
/** @jsxImportSource @sigx/runtime-core */
// src/main.tsx — the "mount module"
import { defineApp, terminalMount } from '@sigx/terminal';
import { App } from './App';

defineApp(<App />).mount({ fullscreen: true }, terminalMount);
```

Your `tsconfig.json` needs the usual SignalX JSX setup (`"jsx": "react-jsx"` and `"jsxImportSource": "@sigx/runtime-core"`, or the `@sigx/terminal` facade — see [Installation](/terminal/docs/installation/)).

## What a save does

- **Edit a component module** (a file that calls `component(...)`, like `App.tsx`): just that module re-executes. Every live instance re-runs the new setup against its existing context and re-renders in place. The terminal never tears down, and state outside the edited setup — parent components, stores, module-level signals elsewhere — survives.
- **Edit the mount module** (or a module nothing accepts): the app restarts in-process — clean terminal teardown, module cache dropped, entry re-imported.
- **Break the build**: the error is reported (above the live region while mounted); the next successful save recovers automatically.
- **Quit with Ctrl+C**: the dev process exits `0`. Quitting the app is the normal end of a dev session, so wrappers like pnpm scripts don't report a failure. (Raw mode delivers Ctrl+C to the app as a key; the app's conventional exit 130 is translated by the bin, and other exit codes pass through.)

## Programmatic API

For embedding the dev runner in your own tooling:

```ts
import { startDev } from '@sigx/terminal-dev';

const handle = await startDev({
    entry: 'src/main.tsx',
    root: process.cwd(),
    onError: (err) => { /* entry failed to (re)start */ },
    onRestart: () => { /* entry (re)started */ },
});

// handle.server  — the ViteDevServer
// handle.runner  — the Vite ModuleRunner
await handle.restart();   // manual in-process restart
await handle.close();
```

For a custom Vite setup, use `terminalDevPlugin()` — the Vite plugin that injects HMR identity registration and self-accept into component modules and keeps `@sigx/*` external for SSR. The HMR runtime that patches live instances lives at `@sigx/terminal-dev/hmr` and is injected automatically.

## How it works

- An in-process Vite dev server (middleware mode, silent) plus a [module runner](https://vite.dev/guide/api-environment) executes the app in Node. `@sigx/*` packages stay out of the hot graph wherever possible, so the renderer's terminal state and the reactivity instance survive hot updates.
- The plugin gives every `component(...)` definition a stable identity (`moduleId:index`). When an edited module re-executes, the HMR runtime re-runs the new setup with each live instance's existing context, swaps `ctx.renderFn`, and calls `ctx.update()` — the contract `@sigx/runtime-core` exposes for HMR. Factories previously defined under the same identity are repointed at the new setup too, so parents that captured a component reference before the edit (tab catalogs, navigation) mount the new code on the next visit.
- Mount modules (those calling `defineApp` / `renderTerminal` / `mountTerminal`) never self-accept — re-executing one would mount a second app — so edits there surface as a full reload, which the runner intercepts: tear down the terminal, clear the module cache, re-import the entry.

## Limitations

These are inherent to setup-rerun HMR:

- Signals created **inside** the edited component's setup are re-created (their state resets); state anywhere else survives.
- `onMounted` does not re-fire for already-mounted instances on a hot update.

## Peer dependency

`@sigx/terminal-dev` lists `@sigx/runtime-core` (`^0.14.0`) as a peer dependency and bundles Vite. Install it as a dev dependency.

## Next steps

- [Installation](/terminal/docs/installation/) — the TSX/Vite config dev mode expects.
- [Render modes](/terminal/docs/render-modes/) — `terminalMount` and the mount options.
- [Architecture](/terminal/docs/architecture/) — where `terminal-dev` sits in the stack.

---
url: https://sigx.dev/actors/packages/actors-pg/installation/
title: Installation
description: Create the schema, wire all four Postgres providers onto one pool, and grant only DML in production
---

# Installation

<p class="lede">One pool, four providers, and a schema you own.</p>

## Install

```bash
pnpm add @sigx/actors-pg pg
```

Postgres ≥ 13, `pg` ≥ 8.

## Create the schema

Tables live in one Postgres schema, `sigx` by default. **DDL is explicit** — nothing issues it
implicitly, so a production role that never runs the bootstrap needs only DML grants.

```ts
import pg from 'pg';
import { ensurePgSchema, pgSchemaSql } from '@sigx/actors-pg';

const pool = new pg.Pool({ connectionString: process.env.PG_URL });

await ensurePgSchema(pool);
```

**Every replica may call this at boot, concurrently.** `ensurePgSchema()` takes
`pg_advisory_xact_lock` as the first statement of the same multi-statement string as the DDL,
so the lock spans the whole thing and releases at commit — before the pooled client is
recycled. A bounded, jittered retry sits underneath as a backstop.

Two things to know about it:

- **`pgSchemaSql()` takes no lock.** It is pure DDL, for a migration tool that brings its own
  serialization.
- **`ensurePgSchema()` expects to own its transaction.** Called with a `PgQueryable` already
  inside your open transaction, a failure poisons that transaction and the retry burns its
  attempts on `25P02`.

In production, running the SQL through your migration tool remains the better shape:

```ts
console.log(pgSchemaSql('sigx'));
```

## Wire it up

```ts
import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { pgCluster, pgReminders, pgStorage } from '@sigx/actors-pg';

export const app = defineActorApp({
    actors,
    storage: pgStorage({ pool }),
    reminders: pgReminders({ pool }),
}).use(cluster({
    providers: pgCluster({ pool }),
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
}));
```

Every provider takes `pool` **or** `url` — with `url`, the package constructs its own
`pg.Pool`. Sharing one pool is the point of this package.

## Options

| Option | Default | Applies to | Meaning |
|---|---|---|---|
| `pool` / `url` | — | all | a `pg.Pool`, or a URL to construct one |
| `schema` | `sigx` | all | validated as an SQL identifier |
| `heartbeatMs` | `5000` | membership | heartbeat cadence |
| `ttlMs` | `15000` | membership | expiry, on the **database** clock |
| `pollMs` | `5000` | membership | view poll cadence, and the propagation bound |

## Pool sizing

Every provider shares the pool, and `pgMembership()` checks out a connection to hold `LISTEN`
when it can. Size the pool with that in mind — a pool of one works, but pushes membership onto
the poll path permanently.

## Verify

```sh
PG_URL=postgres://postgres:postgres@localhost:5432/postgres pnpm test -- actors-pg
```

The provider suite is env-gated on `PG_URL`; CI provides a `postgres:16` service container and
the rest of the matrix skips cleanly.

## Next steps

- [API reference](/actors/packages/actors-pg/api) — exports, tables and semantics.
- [Timers & reminders](/actors/docs/timers-and-reminders) — what `pgReminders()` replaces.
- [Storage](/actors/docs/storage) — the seam `pgStorage()` implements.

---
url: https://sigx.dev/actors/packages/actors-ws/installation/
title: Installation
description: Wiring socketTransport on the client and attachActorSocket on Node, the session options, and recipes for ws, socket.io, uWS, Bun and Deno
---

# Installation

<p class="lede">One package, two halves: a transport in the browser and an upgrade adapter on
the server. The adapter is Node-only; every other runtime already has what it needs.</p>

```bash
pnpm add @sigx/actors-ws
```

`ws` is an **optional** peer (`>= 8`), imported lazily and only by the Node adapter — and only
once a server actually sees an upgrade. Browsers, Bun, Deno and Workers never pull it in.

## The client

```ts
import { actorsPlugin } from '@sigx/actors/app';
import { socketTransport } from '@sigx/actors-ws/client';

app.use(actorsPlugin({ transport: socketTransport({ url: 'wss://example.com/_sigx/socket' }) }));
```

| Option | Default | Meaning |
|---|---|---|
| `connect(handlers)` | — | build one connection attempt; the primary seam |
| `url` | — | sugar over `connect`, dialling the global `WebSocket` |
| `retryMs` | `300` | backoff floor between failed attempts |
| `maxRetryMs` | `10_000` | backoff ceiling |

Nothing is dialled until the first call, so a transport configured at module scope costs
nothing on pages that never touch an actor.

## The Node adapter

```ts
import { attachActorSocket } from '@sigx/actors-ws/node';

const detach = attachActorSocket(server, { host, origin: 'same-origin' });
```

It registers an `upgrade` listener and returns a **detach** function; sockets an already
detached listener accepted keep running until they close on their own.

| Option | Default | Meaning |
|---|---|---|
| `path` | `/_sigx/socket` | upgrade path, **matched exactly** — never a prefix |
| `wss` | — | bring your own `new WebSocketServer({ noServer: true })`; without one, `ws` is imported dynamically |

Everything else is forwarded to the session — see
[Socket sessions](/actors/docs/socket-sessions) for `origin`, `maxMessageBytes`,
`maxConcurrent`, `maxSubscriptions`, `pingMs`, `revalidateMs`, `maxConnectionMs` and `stats`.

Two details worth knowing:

- **An unmatched upgrade is left alone** unless nothing else is listening for one, in which
  case the socket is destroyed rather than hanging unanswered forever.
- **Messages arriving before the session finishes constructing are buffered**, not dropped.
  `ws` begins reading the moment the upgrade completes, which is earlier than the session's
  own async setup can finish.

## Interop

The adapter is a convenience, not a requirement. `createActorSocketSession` takes a `Request`
and a pair of callbacks, so any server that can hand you those can drive it.

### An existing `ws` server

Construct the session in your own upgrade handler, and use `toRequest()` to build the
WinterCG `Request` a Node upgrade does not come with:

```ts
import { createActorSocketSession } from '@sigx/actors/server';
import { toRequest } from '@sigx/actors-ws/node';

wss.on('connection', async (socket, req) => {
    const session = await createActorSocketSession({
        host,
        request: toRequest(req),
        send: (message) => socket.send(message),
        close: (code, reason) => socket.close(code, reason),
    });
    socket.on('message', (data) => session.handle(String(data)));
    socket.on('close', () => session.close());
});
```

Cookies and `Origin` carry over verbatim, which is exactly what the session's upgrade-time
authentication and origin check need.

### socket.io

About ten lines per side. The protocol is text, so carry it as an event payload:

```ts
// server
io.on('connection', async (socket) => {
    const session = await createActorSocketSession({
        host,
        request: toRequest(socket.request),
        send: (message) => socket.emit('sigx', message),
        close: () => socket.disconnect(true),
    });
    socket.on('sigx', (message: string) => session.handle(message));
    socket.on('disconnect', () => session.close());
});

// client
socketTransport({
    connect: (handlers) => {
        io.on('connect', handlers.onOpen);
        io.on('sigx', handlers.onMessage);
        io.on('disconnect', handlers.onClose);
        return { send: (m) => io.emit('sigx', m), close: () => io.disconnect() };
    },
});
```

This is a recipe rather than a package — there is nothing to abstract.

### uWebSockets.js

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Build the <code>Request</code> synchronously inside <code>upgrade()</code>.</strong>
    uWS reuses its <code>req</code> object and it is dead the moment the handler returns, so
    reading headers from it later yields garbage. Read what you need, construct the
    <code>Request</code>, then go async.
  </div>
</div>

### Bun and Deno

No adapter needed. Both hand you a real `Request` at upgrade time and a real `WebSocket`
afterwards, so `createActorSocketSession` wires up directly.

## Security

The origin check happens **at the upgrade**, and it is the one check that cannot be deferred
to per-message: a browser will open a cross-origin WebSocket with cookies attached and no
preflight to stop it. The default is `posture.origin ?? 'same-origin'`.

Identity is pinned once, at the upgrade, from the cookies the browser sent. For an app with
sign-out or short-lived sessions, set `revalidateMs` or `maxConnectionMs` — see
[session lifetime](/actors/docs/socket-sessions#session-lifetime).

TLS is your terminator's job; use `wss://` in production.

## Next steps

- [Socket sessions](/actors/docs/socket-sessions) — the server half in full.
- [API](/actors/packages/actors-ws/api) — the exported surface.
- [Observability](/actors/docs/observability) — `socketStats()` and the ops section.

---
url: https://sigx.dev/core/packages/runtime-dom/installation/
title: Installation
description: Install and configure @sigx/runtime-dom, the Runtime DOM package for SignalX.
---

# Installation

<p class="lede">Add `@sigx/runtime-dom` to your project.</p>

## Install the package

```bash
pnpm add @sigx/runtime-dom
```

## Verify

```tsx
import * as RuntimeDOM from '@sigx/runtime-dom';

console.log(Object.keys(RuntimeDOM));
```

---
url: https://sigx.dev/server/packages/serialize/installation/
title: Installation
description: Install and configure @sigx/serialize, the Serialize package for SignalX Server.
---

# Installation

<p class="lede">Add `@sigx/serialize` to your project.</p>

## Install the package

```bash
pnpm add @sigx/serialize
```

## Verify

```tsx
import * as Serialize from '@sigx/serialize';

console.log(Object.keys(Serialize));
```

---
url: https://sigx.dev/terminal/packages/runtime-terminal/api/
title: API reference
description: API reference for @sigx/runtime-terminal — every export of the SignalX Terminal Runtime Terminal package.
---

# API reference

<p class="lede">Exports of `@sigx/runtime-terminal` .</p>

## Exports

The renderer's public surface — mounting, render modes, key dispatch and terminal
capabilities — is documented in the umbrella's
[API reference](/terminal/docs/api/) (the umbrella re-exports this package).

See the package source for the complete typed surface.

---
url: https://sigx.dev/terminal/packages/terminal-ui/overview/
title: Overview
description: "@sigx/terminal-ui — themed components for SignalX terminal UIs: the SigX-tui skin"
---

# Terminal UI

<p class="lede">The themed component library for SignalX terminal apps — the SigX-tui skin: forms, feedback, navigation, layout, data, fx and tasks components, plus five built-in themes (default **obsidian**). Built entirely on `@sigx/terminal-zero` tokens.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

The `@sigx/terminal` umbrella re-exports this package, so most apps never install it
directly — `pnpm add @sigx/terminal` brings it along, and importing the umbrella
registers the five built-in themes automatically. Install it on its own only when
you're composing a custom stack on `@sigx/terminal-zero`:

```bash
pnpm add @sigx/terminal-ui
```

## The components

Every component is documented in the umbrella's **[component gallery](/terminal/docs/components/)** —
24 components across Forms, Feedback, Navigation, Layout, Data, Effects and Tasks,
each with its own page. The interactive ones plug into the
[focus and layered key dispatch](/terminal/docs/input-and-components/) model.

## Theming

Components don't hard-code colors — they ask for semantic tokens that resolve
against the active theme at render time. The token pipeline lives in
`@sigx/terminal-zero`; this package registers the five concrete SigX-tui themes and
binds the theme canvas. See **[Theming](/terminal/docs/theming/)**.

## Prompts

The async prompt kit (`input`, `select`, `confirm`, …) also ships from here
(re-exported by the umbrella as `@sigx/terminal-ui/prompts`). See
**[Prompts](/terminal/docs/prompts/)**.

## Next steps

Browse the [component gallery](/terminal/docs/components/), or jump to the
[API reference](/terminal/packages/terminal-ui/api).

---
url: https://sigx.dev/actors/packages/actors-redis/overview/
title: Overview
description: Redis providers for @sigx/actors — membership, the distributed actor directory and etag-CAS storage on one client
---

# Redis

<p class="lede">The usual first step out of one process. Membership, the distributed actor
directory and actor storage — all on one <code>ioredis</code> client.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-redis ioredis
```

Requires **Redis ≥ 7** — the directory claim uses `SET NX GET`. `ioredis` ≥ 5 is a peer
dependency.

## What it provides

```ts
import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { redisCluster, redisStorage } from '@sigx/actors-redis';

export const app = defineActorApp({
    actors,
    storage: redisStorage({ url: process.env.REDIS_URL }),
}).use(cluster({
    providers: redisCluster({ url: process.env.REDIS_URL }),
    advertise: 'http://10.0.4.7:7311',
    secret: process.env.HOST_SECRET,
}));
```

| Export | Role |
|---|---|
| `redisCluster()` | membership + directory together |
| `redisMembership(client, opts)` | membership alone |
| `redisDirectory(client, opts)` | directory alone — pairs with [k8s membership](/actors/packages/actors-k8s/overview) |
| `redisStorage()` | etag-CAS [`ActorStorage`](/actors/docs/storage) |

Pass an existing client instead of `url` to share the app's connection —
`redisCluster({ client })`. Sharing one `ioredis` client across `redisCluster()` and
`redisStorage()` is safe and saves connections.

> **Call `redisCluster()` once per host.** Each call returns *that host's* own membership
> handle. The directory is safely shared.

## Fencing

A host that cannot heartbeat past `ttlMs` **self-fences**: it stops claiming actors and
deactivates what it holds. Directory entries belonging to dead hosts are evicted lazily on
lookup.

State integrity never rests on any of this. The runtime's storage etag CAS is the floor — a
briefly wrong directory entry costs a rejected save and a fault-and-reload, never corruption.

## Reminders

Reminders ride the same storage automatically. If your reminder table grows large enough that
scanning it becomes the problem, [`@sigx/actors-pg`](/actors/packages/actors-pg/overview) has
a `SKIP LOCKED` implementation designed for exactly that.

## Next steps

- [Installation](/actors/packages/actors-redis/installation) — setup and the options table.
- [API reference](/actors/packages/actors-redis/api) — exports and the key layout.
- [Clustering](/actors/docs/clustering) — where the providers plug in.

---
url: https://sigx.dev/actors/packages/actors-cloudflare/api/
title: API reference
description: Exports of @sigx/actors-cloudflare — storage, reminders, placement, the host Durable Object and the Worker handler
---

# API reference

<p class="lede">Exports of `@sigx/actors-cloudflare` .</p>

## Assembled entries

Most apps use these two rather than the seams below.

### `createHostDurableObject<Env>(options)`

Returns a class to extend. The object hosts exactly the actor its id names.

```ts
interface HostDurableObjectOptions<Env> {
    actors?: AnyActorDefinition[];
    namespace(env: Env): DurableObjectNamespaceLike;
    app?(base: DurableAppOptions): ActorApp;
    placement?: Pick<DurableObjectPlacementOptions,
        'objectName' | 'locationHint' | 'jurisdiction' | 'base'>;
    endpoint?: HostEndpointOptions;
    /** Terminate client sockets inside this object. */
    socket?: Omit<ActorSocketSessionOptions,
        'host' | 'request' | 'send' | 'close' | 'pingMs'> & { path?: string };
}
```

The instance exposes `fetch(request)`, `alarm()` and `host(): Promise<Host>`.

The `app` factory receives the object's own storage, reminders and defaults and must pass them
on. It **never receives `env`**, so it cannot reach a namespace binding and build a placement
of its own.

### `createWorkerHandler<Env>(options)`

The edge. Hosts nothing, routes everything. Same options minus `endpoint`, plus
`fetch?: FetchHandlerOptions` and `socket?`:

```ts
socket?:
    | (WorkerSocketOptions & { terminate?: 'worker' })
    | { terminate: 'object'; path?: string };
```

A discriminated union on purpose: in `'object'` mode the session runs inside the Durable
Object, so the type refusing session options on the Worker side is what stops them being
configured where they would never run. See
[client sockets](/actors/docs/cloudflare-workers#client-sockets).

## Seams

| Export | Role |
|---|---|
| `durableObjectStorage(storage, options?)` | [`ActorStorage`](/actors/docs/storage) on DO storage |
| `durableObjectReminders(options)` | `ActorReminders` on the DO alarm |
| `durableObjectPlacement(options?)` | routes a ref to its object |
| `durableObjects(options?)` | the placement as a plugin |
| `durableObjectName(...)` | the ref → object-name function |
| `unhostedStorage()` | storage for the Worker half, which hosts nothing |
| `durableObjectStubResolver(...)` | the ref → stub derivation, shared by placement and the forwarding socket route so the two cannot disagree about where an actor lives |
| `workerSocket(options?)` | the Worker-terminated socket route, as a plugin |
| `objectSocketRoute(options)` | the forwarding half of the object-terminated mode |
| `parseSocketActorPath(pathname, path?)` | `{path}/{type}/{key}` → the actor it names |

### Placement runs on both sides

```ts
// inside the object
durableObjectPlacement({ isSelf: (ref) => actorId(ref) === state.id.name });
// in the Worker — no isSelf; everything is remote
durableObjectPlacement();
```

> Using the plain local host inside an object **silently corrupts state**: a cross-actor call
> would activate the callee inside the caller's object, writing its record into the wrong
> storage and violating single activation. See
> [Cloudflare Workers](/actors/docs/cloudflare-workers).

`locationHint` is a hint and safe to change. **`jurisdiction` and `objectName` are part of
identity**, so changing either is a state migration.

## Alarm concurrency

`onAlarm()` runs in three phases and does **not** hold `blockConcurrencyWhile` across
delivery: claim and persist (gated) → deliver (ungated) → re-read and re-arm (gated).

Holding the gate across delivery deadlocked the object, because rescheduling from inside
`onReminder` takes the gate itself and `blockConcurrencyWhile` does not nest.

Relatedly, an expected failure — the wrong-owner error from `ctx.reminders.set()` — is
returned as a value and thrown **after** the gate closes. An exception escaping
`blockConcurrencyWhile` *resets* the Durable Object.

## Types

`DurableObjectIdLike`, `DurableObjectNamespaceLike`, `DurableObjectStubLike`,
`DurableObjectStorageOptions`, `DurableObjectRemindersOptions`,
`DurableObjectPlacementOptions`, `DurableAppOptions`, `DurableObjectStateLike`,
`HostDurableObjectInstance`, `WorkerHandler`, `WorkerHandlerOptions`, `BlockConcurrencyWhile`,
`DurableStorage`, `DurableAlarms`, `DurableObjectStubResolver`, `WorkerSocketOptions`,
`ObjectSocketRouteOptions`, `CloudflareWebSocketLike`, `DurableWebSocketLike`.

`DurableObjectStateLike` carries the hibernation members — `acceptWebSocket`,
`setWebSocketAutoResponse` and friends — as optional, so a runtime without them still
type-checks.

## Next steps

- [Overview](/actors/packages/actors-cloudflare/overview) — the two seams.
- [Client sockets](/actors/docs/cloudflare-workers#client-sockets) — the two termination modes.
- [Installation](/actors/packages/actors-cloudflare/installation) — bindings and migrations.
- [Cloudflare Workers](/actors/docs/cloudflare-workers) — the deployment guide.

---
url: https://sigx.dev/core/packages/reactivity/installation/
title: Installation
description: Install and configure @sigx/reactivity, the Reactivity package for SignalX.
---

# Installation

<p class="lede">Add `@sigx/reactivity` to your project.</p>

## Install the package

```bash
pnpm add @sigx/reactivity
```

## Verify

```tsx
import * as Reactivity from '@sigx/reactivity';

console.log(Object.keys(Reactivity));
```

---
url: https://sigx.dev/server/packages/server/native-clients/
title: Native clients
description: "Pointing a lynx, terminal or native app's server-function stubs at a remote backend — configureServerFn, role: 'client', stable routes and the live-client guard"
---

# Native clients

<p class="lede">A web app and its server functions ship together, so the stubs can bake in a relative path and forget about it. A <strong>native</strong> app — lynx, terminal, or anything installed on a device — is built separately from the backend it calls, updates on its own schedule, and has no same-origin to fall back on. This page is the four things that changes.</p>

## 1. Build the app as a client

In a web build, `sigxServer()` swaps `*.server.ts` modules for fetch stubs in the
**client** environment only; the SSR environment keeps the real module, because
there is a server in the build. A native app has no server in the build at all.

Set `role: 'client'` and every environment gets stubs:

```ts
// vite.config.ts
import { sigxServer } from '@sigx/vite/server';

export default {
  plugins: [
    sigxServer({
      role: 'client',
      endpoint: 'https://api.example.com/_sigx/fn',
    }),
  ],
};
```

| `role` | Behaviour |
|---|---|
| `'auto'` (default) | Stub swap in the Vite `client` environment only — the web posture |
| `'client'` | Every environment gets stubs, baked with **stable** symbols; no registry chunk is emitted |

The registry chunk maps symbols back to real modules for a server to execute. A
client build has nothing to execute, so none is produced.

### Server modules outside the app

A native client usually imports its server functions from a shared workspace
package, which sits outside the Vite root and is therefore invisible to the
plugin's file scan. Point `scan` at it:

```ts
sigxServer({
  role: 'client',
  scan: ['../../packages/api/src'],
  endpoint: 'https://api.example.com/_sigx/fn',
});
```

## 2. Point the stubs at a backend

`endpoint` above bakes a default fetch target into the build. That is enough when
the backend URL is known at build time and never changes — which, for an app that
has to work against dev, staging and production, it usually is not.

`configureServerFn` sets the transport that every stub resolves **at call time**,
so one build serves every environment:

```ts
import { configureServerFn } from '@sigx/server/client';

configureServerFn({
  endpoint: await resolveBackendUrl(),
  headers: () => ({ authorization: `Bearer ${session.accessToken}` }),
});
```

```ts
interface ServerFnTransport {
  /** Absolute URL or path prefix; wins over the build-time endpoint. */
  endpoint?: string;
  /** Extra request headers — a static map, or a (possibly async) factory. */
  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
  /** Fetch implementation; defaults to the global fetch. */
  fetch?: typeof globalThis.fetch;
}
```

Because `headers` may be a **factory**, and it is called per request, a rotating
credential works without rebuilding or re-configuring:

```ts
configureServerFn({
  headers: async () => ({ authorization: `Bearer ${await auth.freshToken()}` }),
});
```

Pass `null` to clear the transport.

Precedence, highest first: `configureServerFn`'s `endpoint` → `sigxServer({ endpoint })`
→ `sigxServer({ base })`.

### From a plugin instead

If you would rather configure this with the rest of your app, `serverPlugin`
carries the same transport:

```ts
import { serverPlugin } from '@sigx/server/plugin';

app.use(serverPlugin({
  transport: { endpoint: 'https://api.example.com/_sigx/fn' },
}));
```

Pick one or the other — mixing `serverPlugin({ transport })` with direct
`configureServerFn` calls is unsupported. The transport is a module-level seam
(stubs are dependency-free and cannot read app DI), so with several apps on one
page the last install wins, and `app.unmount()` clears it only if it is still the
active one.

## 3. Pin the routes

A web deploy ships the client and the server together, so a route that changes
shape between builds is invisible. An installed app is the opposite case: it was
built months ago, it is still calling, and the backend has been redeployed since.

By default a function's transport symbol is **content-hashed** — change the body
and the symbol changes, which is exactly what you want for version-skew
detection on the web, and exactly what you do not want for an installed client.

The registry dual-registers a hash-free **stable** symbol (`<stableId>#<name>`)
alongside the hashed one, and `role: 'client'` builds bake the stable form. Pin
the id explicitly for anything a long-lived client calls:

```ts
export const getCart = serverFn({
  id: 'cart',                 // route is now /cart/getCart, across file moves
  input: CartKey,
  use: [requireUser],
  handler: async (rq, key) => db.cart.load(key),
});
```

`id` must be a **string literal** — it is read statically by the build, and
anything else (a variable, a template, an empty string) is warned about and falls
back to the file-derived id.

Without it, the stable id is derived from the file path, so moving or renaming
the module changes the route and breaks installed clients.

## 4. The live-client guard

Getting the build wrong here fails in a specific and dangerous way: the stub swap
does not happen, the app bundles the **real** server module, and the handler body
runs on the device — with whatever database client and secrets that module
imported.

So a declared live client refuses to execute a server body at all:

```
[sigx server] server function "getCart" reached a live client unextracted —
this app must call its backend over stubs (set role: 'client' in sigxServer(),
or fix the bundler integration).
```

Non-web platform packages (lynx, terminal) call `declareLiveClient()` once on

If you see this, the build is misconfigured, not the call. Check `role: 'client'`
and, for shared packages, `scan`.

> `@sigx/runtime-dom/platform` deliberately does **not** declare — the `sigx`
> umbrella is evaluated server-side too, where executing server bodies is the
> whole point.

## Origin policy for programmatic clients

The endpoint's default `origin: 'same-origin'` requires a matching `Origin`
header. Browsers always send one on POST; native apps, CLIs and server-to-server
callers never do, so a native client is rejected under the default.

`'verify-when-present'` admits Origin-less requests while still verifying the
header when it *is* sent:

```ts
handleServerFnRequest(request, {
  resolve,
  origin: 'verify-when-present',
});
```

Browser CSRF stays blocked by the non-safelisted JSON content type, and the
endpoint never emits CORS approval. Two things to know before choosing it:

- **Never deploy an Origin-stripping proxy** in front of a cookie-authenticated
  app under this policy — stripping the header turns every cross-site POST into
  an admitted one.
- It does **not** admit Origin-less *form* posts. A `form: true` target
  deliberately gives up the JSON content-type gate, so the combination would
  reopen classic CSRF; those are `403` under every policy short of
  `origin: false`.

Prefer bearer tokens over cookies for native clients — then the ambient-authority
problem CSRF exploits does not exist in the first place.

## Next steps

- [Deployment & security](/server/packages/server/deployment) — the endpoint's options in full
- [Authoring](/server/packages/server/usage) — `serverFn`, guards and `.with()`
- [API reference](/server/packages/server/api) — `configureServerFn`, `ServerFnTransport`

---
url: https://sigx.dev/deploy/packages/cloudflare/deploying/
title: Deploying to Workers
description: Cloudflare — the scaffolded worker entry, the wrangler.jsonc posture, dev binding proxies and wrangler deploy
---

# Deploying to Workers

<p class="lede">The first build scaffolds a worker entry and a starter `wrangler.jsonc` — both written once when absent and yours from that moment. This guide walks the whole path: entry, config, dev bindings, deploy.</p>

## The platform entry — yours, scaffolded once

The first build writes `src/entry.cloudflare.ts` **iff absent** and never
touches it again. It is the `server.mjs` of the edge world — the composition
order is your app's routing policy and stays visible in your file:

```
static assets  →  server functions  →  document render
```

```ts
// src/entry.cloudflare.ts (scaffolded)
import { createFetchHandler } from '@sigx/server-renderer/server';
import { template, assets } from 'virtual:sigx-app';
import { createApp } from './entry-server';

const handler = createFetchHandler({
    template,
    app: (url) => createApp(url),
    document: { assets }
});

export default {
    async fetch(request: Request): Promise<Response> {
        return handler(request);
    }
};
```

Static assets never reach the worker: wrangler's `assets` config serves matching
files before it runs. Using server functions (`sigxServer()`)? Mount the endpoint
before the document render — the scaffold carries this block as a comment:

```ts
import { handleServerFnRequest, matchesServerFn } from '@sigx/server/server';
import { createBoundaryRefresh } from '@sigx/resume/server';
// virtual:sigx-server-fns maps each symbol to a LAZY FACTORY — resolve
// invokes it to get the server function. `serverFnBase` is the mount path
// the build used: pass it to both, so they cannot disagree.
import { serverFns, serverFnBase } from 'virtual:sigx-server-fns';

// Module scope, built once. Omit it and boundary refresh silently never runs.
const renderBoundaries = createBoundaryRefresh({ components: { /* … */ } });

if (matchesServerFn(request, serverFnBase)) {
    return handleServerFnRequest(request, {
        base: serverFnBase,
        resolve: (symbol) => serverFns[symbol]?.() ?? null,
        renderBoundaries
    });
}
return handler(request);
```

In a bundled build the `virtual:sigx-app` artifacts and the
`virtual:sigx-server-fns` registry **inline into the one worker file** — no
separate chunks, one module graph.

### Resolving preloads yourself

`virtual:sigx-app`'s `assets` export is precomputed for every client entry. When
a worker needs to resolve preloads itself — per route, or for an entry the build
didn't know about — import `collectAssets` from `@sigx/vite/assets`:

```ts
import { collectAssets } from '@sigx/vite/assets';
import { manifest } from 'virtual:sigx-app';

const resolvedAssets = collectAssets(manifest, ['src/entry-client.tsx']);
```

That is the entry to reach for on workerd: it imports nothing at all, with no
`node:` builtins and no `process`. `@sigx/vite/ssr` re-exports the same function,
but it also carries the dev request handler, which imports `node:fs/promises` and
`node:path` at module top level — fine on Node, unusable in a worker.

## wrangler.jsonc — written once, validated after

`generate()` writes a starter config iff absent (name from your package.json,
`main` → the built worker, `assets.directory` → the client outDir, a pinned
`compatibility_date`); when present it only warns on drift. One default is
load-bearing:

```jsonc
"assets": { "directory": "dist/client", "html_handling": "none" }
```

`html_handling: "none"` limits the asset router to exact file paths. The client
outDir contains `index.html` — the raw outlet template — and with the default
handling the router would serve it for `GET /` *before the worker runs*.
(`run_worker_first` routing is the wrangler ≥ 4.20 alternative.)

## nodejs_compat — one feature, not a requirement

`nodejs_compat` is **not** required to render: sigx's edge graph takes no
`node:` import. It IS required for one feature — the ambient request scope that
lets a server function called during SSR read `rq.request`. That scope is
AsyncLocalStorage (`node:async_hooks`), so a worker whose renders need it wants:

```jsonc
"compatibility_flags": ["nodejs_compat"]
```

Without the flag nothing breaks: the render simply runs unscoped, server
functions still work over RPC, and only SSR-time `rq.request` falls back to the
request-less detached context (`fn.with({ context })` supplies one with no ALS
at all). Beyond that, `nodejs_compat` is a concern for your own dependencies
only.

## Dev — one loop, optional bindings

`vite dev` + `createDevRequestHandler` stays the dev loop; adapters change
builds, not dev. Apps that read Cloudflare bindings during render opt into local
proxies:

```ts
// vite config
sigx({ ssr: { entry, adapter: cloudflare({ devProxy: true }) } })
```

```js
// server.mjs (dev branch) — the composition stays visible
import { getDevPlatform } from '@sigx/cloudflare';

app.use(await createDevRequestHandler(vite, {
    entry: '/src/entry-server.tsx',
    platform: getDevPlatform(vite)   // { env, cf, ctx, caches } — wrangler's local sims
}));
```

`devProxy` boots wrangler's `getPlatformProxy()` (install `wrangler` as a dev
dependency) and disposes it with the dev server. For binding-heavy apps that
want dev inside real workerd, `@cloudflare/vite-plugin` is the escalation path.

## Deploy

```bash
vite build --app -c vite.config.cloudflare.ts
wrangler deploy
```

## Reference apps

`examples/resume` (full composition including the server-fn mount) and
`examples/storefront` (islands + resume) in the
[SignalX core repo](https://github.com/signalxjs/core) each ship a committed
`entry.cloudflare.ts`, `vite.config.cloudflare.ts`, and `wrangler.jsonc` — CI
serves both from real workerd (Miniflare) and asserts they behave identically to
the Node servers.

---
url: https://sigx.dev/deploy/packages/netlify/installation/
title: Installation
description: Install and configure @sigx/netlify, the Netlify adapter for SignalX.
---

# Installation

<p class="lede">Add `@sigx/netlify` to your project — a build-time dev dependency, alongside the Netlify CLI for deploys.</p>

## Install the package

```bash
pnpm add -D @sigx/netlify
pnpm add -D netlify-cli   # or use the globally installed CLI
```

## Wire the adapter

A separate platform config keeps the default Node build untouched:

```ts
// vite.config.netlify.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { netlify } from '@sigx/netlify';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: netlify() } })]
});
```

## netlify.toml — printed, never written

The adapter prints the config it needs and leaves the file to you. All it needs:

```toml
[build]
  publish = "dist/client"
  command = "vite build --app -c vite.config.netlify.ts"
```

## Verify

```bash
vite build --app -c vite.config.netlify.ts
```

The first build scaffolds `src/entry.netlify.ts` (only when absent — yours
afterwards) and emits `.netlify/v1/functions/sigx-ssr/`. `netlify dev` serves
the result locally; `netlify deploy --prod` ships it.

---
url: https://sigx.dev/actors/packages/actors-otel/overview/
title: Overview
description: Observability exporters for @sigx/actors — Prometheus text exposition, OpenTelemetry traces and a metrics bridge
---

# OpenTelemetry

<p class="lede">Turns the host's own metrics into something your monitoring stack already
speaks — without making OpenTelemetry a dependency of anything that does not want it.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-otel
```

`@opentelemetry/api` ≥ 1.9 is an **optional** peer dependency — the `/prometheus` entry
imports no OpenTelemetry at all.

## Two entries, deliberately

**`@sigx/actors-otel/prometheus`** — `prometheusOps()` and `renderPrometheus()`. Zero OTel.
If you scrape, this is all you need.

**`@sigx/actors-otel`** — `otelTraces()` and `otelMetricsBridge()`. For OTLP stacks.

```ts
import { prometheusOps } from '@sigx/actors-otel/prometheus';

app.use(metrics()).use(prometheusOps({ secret: process.env.SIGX_OPS_SECRET }));
```

Mounts `GET /_sigx/metrics` beside [`ops()`](/actors/docs/ops-endpoint), with the same bearer
posture. **The secret is mandatory outside dev.**

## Traces

```ts
app.use(otelTraces({ turnSpans: true }));
```

One CLIENT span per dispatch and one SERVER span per turn, joined across hosts by the W3C
`traceparent` the runtime propagates — captured from the public endpoint header and carried on
the cluster envelope.

With no tracer provider registered the plugin is inert and costs nothing.

## The cardinality rule

> **Labels are `type` and `method` — never actor keys.** An actor key is unbounded by
> construction, and a key-labelled metric will take your Prometheus down. This is enforced,
> not advisory.

Span attributes use a **key hash** for the same reason the
[routing token](/actors/docs/locality-routing) does — and with the same caveat that a hash is
log hygiene, not privacy.

## Next steps

- [Installation](/actors/packages/actors-otel/installation) — scrape config and options.
- [API reference](/actors/packages/actors-otel/api) — exports.
- [Observability](/actors/docs/observability) — choosing between these.

---
url: https://sigx.dev/terminal/docs/components/multiselect/
title: MultiSelect
description: Checkbox list with a movable cursor and optional group headers
---

# MultiSelect

<p class="lede">A checkbox list with a movable cursor. The <code>model</code> holds the array of checked values. ↑/<code>k</code> ↓/<code>j</code> move, Space toggles, <code>a</code> toggles all, Enter submits.</p>

## Import

```tsx
import { MultiSelect } from '@sigx/terminal';
import type { MultiSelectOption } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, MultiSelect } from '@sigx/terminal';
import type { MultiSelectOption } from '@sigx/terminal';

const options: MultiSelectOption[] = [
    { label: 'TypeScript', value: 'ts', group: 'Language' },
    { label: 'ESLint', value: 'eslint', group: 'Tooling' },
    { label: 'Vitest', value: 'vitest', group: 'Tooling' },
];

const App = component(() => {
    const features = signal<string[]>([]);
    return () => (
        <box border="rounded" label="Features">
            <MultiSelect
                options={options}
                model={() => features}
                label="Select features"
                required
                showHint
                autofocus
                onSubmit={(v) => console.log('chosen:', v)}
            />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `MultiSelectOption[]` | **required** — the choices |
| `model` | `Model<string[]>` | two-way bound array of checked values |
| `label` | `string` | caption above the list |
| `autofocus` | `boolean` | grab focus on mount |
| `required` | `boolean` | block an empty submit |
| `showHint` | `boolean` | show the keys hint |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `string[]` | the checked set changes |
| `submit` | `string[]` | Enter (blocked with a hint when `required` and nothing is checked) |

## MultiSelectOption

```ts
interface MultiSelectOption<T = string> {
    label: string;
    value: T;
    description?: string;
    group?: string; // section header when it differs from the previous option's group
}
```

Set `group` to render section headers; the cursor skips headers. Pre-sort options by group.

## See also

- [Select](/terminal/docs/components/select) — single choice.
- [multiselect() prompt](/terminal/docs/prompts) — the imperative form.

---
url: https://sigx.dev/server/packages/ssr-islands/overview/
title: Overview
description: "@sigx/ssr-islands — islands architecture and selective hydration for SignalX SSR"
---

# Islands

<p class="lede">`@sigx/ssr-islands` adds islands architecture to SignalX SSR: ship a static, server-rendered page and hydrate only the interactive components, each on its own schedule, with optional per-island code splitting.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> ESM-only <span class="mmr-dot" /> MIT</p>

It is the **first-party reference strategy pack** built entirely on the pluggable
[`@sigx/server-renderer`](/server/packages/server-renderer/overview) plugin API —
**not** baked into core. The base renderer is strategy-agnostic; islands is just an
`SSRPlugin` registered on top (installed automatically as a dependency). The base
renderer hydrates the whole tree; islands lets you hydrate just the parts marked
with `client:*` directives — everything else stays as cheap static HTML. Because it
ships against the same public hooks, a third party can author their own strategy
pack the same way.

It ships from the core monorepo (`signalxjs/core`, `packages/ssr-islands`) and is
released in lockstep with `@sigx/server-renderer`.

## Why islands

Most pages are mostly static. Hydrating the entire tree ships and runs JavaScript
for content that never changes. With islands you opt **in** to interactivity per
component:

- A `client:visible` chart hydrates only when scrolled into view.
- A `client:idle` widget waits for the browser to be idle.
- The surrounding article ships zero client JS.

## The two pieces

Using islands always involves the same pair (from the package's own quick-start):

```tsx
// 1. Server — install the pack on your app
import { createSSR } from '@sigx/server-renderer';
import { islandsPlugin } from '@sigx/ssr-islands';
import { defineApp } from 'sigx';

const app = defineApp(<App />).use(islandsPlugin());
const html = await createSSR().render(app);
```

```ts
// 2. Client — register island components, then hydrate them
import { hydrateIslands, registerComponent } from '@sigx/ssr-islands';
import { Counter } from './components/Counter';

registerComponent('Counter', Counter);
hydrateIslands();
```

The `client:*` attributes type-check with no extra import — importing
`@sigx/ssr-islands` on the server or `@sigx/ssr-islands/client` on the client (which
the two entries above already do) augments every JSX component program-wide, the same
way core's `use:*` directives do:

```tsx
<Counter client:visible />
<Widget client:idle />
```

The server plugin maps each `client:*` directive onto a core
[boundary record](/server/packages/server-renderer/boundaries), captures the
component's signal state, and injects the `window.__SIGX_BOUNDARIES__` hydration
table. On the client, `hydrateIslands()` reads that table and schedules each island
according to its strategy.

`hydrateIslands()` is the **whole** client bootstrap. The state-restoration hooks
register themselves as a lazy plugin source, loaded with the hydration core and
resolved before the first component hydrates, so there is nothing else to wire.
(Apps that already call `registerClientPlugin(islandsPlugin())` keep working —
registration dedupes by name, first wins.)

## The runtime loads late

An islands page ships **~2 kB eager** and executes **no framework JavaScript at
load**. The trigger wiring is all that runs up front; the renderer and hydration
machinery arrive by dynamic import on the first `client:*` strategy that actually
fires. A page whose islands are all below the fold executes nothing until the
reader scrolls — and a page of `client:never` boundaries never loads it at all.

The cost is one import round trip before a `client:load` island hydrates. To keep
that off the critical path, pass the build's manifest:

```ts
import { islandsManifest } from 'virtual:sigx-manifests';

const app = defineApp(<App />).use(islandsPlugin({ manifest: islandsManifest }));
```

Manifest v2 carries `runtimePreload` — the chunk holding the lazily-imported
executor plus its transitive imports — and the plugin emits
`<link rel="modulepreload">` for it whenever a request records schedulable
islands. A page with no islands pays nothing.

```ts
interface IslandsManifestV2 {
    version: 2;
    islands: Record<string, { chunkUrl: string; exportName: string }>;
    runtimePreload?: string[];
}
```

The legacy flat name → entry map is still accepted.

## Hydration strategies

| Directive | Hydrates… |
|---|---|
| `client:load` | immediately on page load |
| `client:idle` | during browser idle time (`requestIdleCallback`) |
| `client:visible` | when the element scrolls into view (`IntersectionObserver`) |
| `client:media` | when a media query matches (`client:media="(min-width: 768px)"`) |
| `client:interaction` | on the first pointerdown / keydown / touchstart / focusin |
| `client:only` | skip SSR entirely — empty placeholder on the server, mount fresh on the client |

See [Client directives](/server/packages/ssr-islands/client-directives) for the
details of each.

## Next steps

- [Installation](/server/packages/ssr-islands/installation) — install, dependency, and the three subpaths.
- [Client directives](/server/packages/ssr-islands/client-directives) — the six `client:*` strategies.
- [Registry & code splitting](/server/packages/ssr-islands/registry-and-code-splitting) — register components eagerly or lazily for per-island chunks.
- [Plugin setup](/server/packages/ssr-islands/plugin-setup) — `islandsPlugin()` options, manifests, and signal-state transfer.
- [API reference](/server/packages/ssr-islands/api) — every export with signatures.

---
url: https://sigx.dev/terminal/docs/components/progressbar/
title: ProgressBar
description: Determinate progress indicator with solid, gradient and rainbow variants
---

# ProgressBar

<p class="lede">A read-only progress indicator: a bar of filled and empty cells plus a percentage. Not focusable, emits no events.</p>

## Import

```tsx
import { ProgressBar } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, onMounted, ProgressBar } from '@sigx/terminal';

const App = component(() => {
    const value = signal(0);
    onMounted(() => {
        const t = setInterval(() => { value.value = Math.min(100, value.value + 5); }, 200);
        return () => clearInterval(t);
    });
    return () => (
        <box border="single" label="Download">
            <ProgressBar value={value.value} max={100} width={30} variant="gradient" smooth showPercent />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `value` | `number` | `0` | current value |
| `max` | `number` | `100` | full value |
| `width` | `number` | `20` | bar width in cells |
| `char` | `string` | `█` | filled cell glyph |
| `emptyChar` | `string` | `░` | empty cell glyph |
| `color` | token \| `#hex` | — | bar color (solid variant) |
| `variant` | `'solid' \| 'gradient' \| 'rainbow'` | `'solid'` | fill style |
| `colors` | `string[]` | — | gradient stops (tokens or hex) |
| `smooth` | `boolean` | — | sub-cell leading edge for a finer bar |
| `showPercent` | `boolean` | — | append the percentage label |

## See also

- [Spinner](/terminal/docs/components/spinner) — indeterminate activity.
- [TaskList](/terminal/docs/components/tasklist) — per-task progress.

---
url: https://sigx.dev/actors/packages/actors-cli/overview/
title: Overview
description: sigx actors — a terminal dashboard for hosts, actors, latency, errors and cluster topology
---

# CLI

<p class="lede">A <a href="/cli/docs/plugins">sigx CLI</a> plugin for observing actors: hosts,
latency, errors and cluster topology, from a terminal.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add -D @sigx/actors-cli
```

```sh
sigx actors                                        # the dashboard
sigx actors top --url http://host:7311             # …against a running host
sigx actors stats --json | jq '.cluster.totals'    # a snapshot, for piping
sigx actors health --url http://host:7311          # exit code by readiness
```

Requires `@sigx/cli` ≥ 0.9 and `@sigx/terminal` ≥ 0.11. On older versions the plugin's version
guard warns and the dashboard never learns its pane size.

## Two ways to reach a host

**Embedded** (the default) loads your project's actor app module in-process and reads it
directly. Zero config, no secret, and it sees strictly more than the wire can — full latency
histograms, the whole activation list, the cluster placement itself.

> **It also starts a host.** That host is real: it joins membership, claims actors and ticks
> reminders. Fine pointed at a dev app, **wrong pointed at production**.

**HTTP** (`--url`) polls a running host's [`ops()`](/actors/docs/ops-endpoint) endpoint. It
loads no user code and holds no host, so it is the mode for anything you did not just start
yourself. `--url` wins over a local module.

## Why the commands might not be there

The `sigx` binary discovers plugins from the **dependencies of the project you run it in**. It
reads `./package.json`, looks for a `sigx-cli` field in each dependency's manifest, and calls
the plugin's `detect(cwd)`. Two things must be true in that directory:

1. `@sigx/actors-cli` is in its `dependencies` or `devDependencies`;
2. it depends on `@sigx/actors` — that is what `detect` looks for.

```
$ sigx actors top
error: Unknown command 'actors'
```

That is not a broken install. It is the CLI correctly declining to offer actor commands in a
project that has no actors — `sigx --help` lists what it did find. Run it from the package
that owns the host, or in a monorepo:

```sh
pnpm --filter my-app exec sigx actors top
```

## Next steps

- [Installation](/actors/packages/actors-cli/installation) — flags, exit codes and the app-module convention.
- [API reference](/actors/packages/actors-cli/api) — the `/source` data layer.
- [The ops endpoint](/actors/docs/ops-endpoint) — what HTTP mode reads.

---
url: https://sigx.dev/actors/packages/actors-k8s/overview/
title: Overview
description: Kubernetes membership for @sigx/actors — host liveness on coordination.k8s.io Leases, with no extra store and no client library
---

# Kubernetes

<p class="lede">Host liveness and peer discovery on <code>coordination.k8s.io</code> Leases —
the same primitive kubelet uses for node heartbeats. A cluster already running in Kubernetes
needs no extra store for membership.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-k8s
```

No Kubernetes client library. The API surface this package touches is seven verbs on one
resource — `get`, `list`, `watch`, `create`, `update`, `patch`, `delete` — spoken in plain
HTTPS and JSON. Those are exactly the verbs the
[RBAC Role](/actors/packages/actors-k8s/installation#rbac) grants.

## Membership only — bring a directory

Membership and the actor **directory** are independent seams, and this package provides only
the first. Compose it:

```ts
import { cluster } from '@sigx/actors/cluster';
import { k8sMembership } from '@sigx/actors-k8s';
import { redisDirectory } from '@sigx/actors-redis';

app.use(cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(redis) },
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
}));
```

Inside a pod everything is discovered: the API server from the service env vars, and namespace,
token and CA from the ServiceAccount mount — with the bound token re-read on rotation.

> Call `k8sMembership()` once per host.

## Why pick it

You are already on Kubernetes and would rather not make Redis or Postgres responsible for
knowing which pods are alive — especially when the orchestrator already knows, and its answer
is the one your probes and endpoints agree with.

Pair it with a [Redis](/actors/packages/actors-redis/overview) or
[Postgres](/actors/packages/actors-pg/overview) directory and storage.

## The Lease

Each host owns one Lease; nobody else ever writes it.

```json
{
    "apiVersion": "coordination.k8s.io/v1",
    "kind": "Lease",
    "metadata": {
        "name": "sigx-s.k3f9a2",
        "labels": { "sigx.dev/cluster": "default" },
        "annotations": { "sigx.dev/descriptor": "{\"hostId\":\"s.k3f9a2\",…}" }
    },
    "spec": {
        "holderIdentity": "s.k3f9a2",
        "leaseDurationSeconds": 15,
        "renewTime": "2026-07-29T12:04:05.123456Z"
    }
}
```

## Next steps

- [Installation](/actors/packages/actors-k8s/installation) — RBAC, options and local dev.
- [API reference](/actors/packages/actors-k8s/api) — exports and behaviour.
- [Kubernetes deployment](/actors/docs/kubernetes) — probes and shutdown ordering.

---
url: https://sigx.dev/core/packages/runtime-core/overview/
title: Overview
description: "Renderer-agnostic component model — the Runtime Core package for SignalX (@sigx/runtime-core): what it does, setup and API."
---

# Runtime Core

<p class="lede">Component model and renderer base shared across every render target.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/runtime-core
```

## About

`@sigx/runtime-core` is a Core package — renderer-agnostic component model. It is versioned in lockstep with the rest of the Core repo, so any combination of modules just works together.

## Next steps

Continue with [Installation](/core/packages/runtime-core/installation) for project setup, or jump to the [API reference](/core/packages/runtime-core/api).

---
url: https://sigx.dev/actors/packages/actors-tcp/overview/
title: Overview
description: Framed TCP transport for @sigx/actors — one multiplexed connection per peer instead of one per in-flight request
---

# TCP

<p class="lede">One multiplexed, framed connection per peer instead of one HTTP connection per
in-flight request. On Node, this is the recommended host-to-host transport.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-tcp
```

```ts
import { cluster, httpTransport } from '@sigx/actors/cluster';
import { tcpTransport } from '@sigx/actors-tcp';

cluster({
    providers,
    advertise: 'http://10.0.4.7:7311',
    secret: process.env.HOST_SECRET,
    // A CHAIN: TCP wherever the peer advertises it, HTTP everywhere else.
    // That is what makes a rolling deploy of this transport possible.
    transport: [tcpTransport({ port: 11111 }), httpTransport()],
});
```

## Why you would use it

Measured against a **tuned** HTTP baseline — pool bounded to the concurrency — at concurrency
64:

| | Connections per peer | ops/s | p99 |
|---|---:|---:|---:|
| tuned HTTP | 64 | 14,287 | 9.6 ms |
| **TCP** | **1** | **69,768** | **1.58 ms** |

Two separate wins, worth different amounts.

**Socket count — real at any network.** HTTP's pool sizes to `concurrency × peers`, measured
at *two* connections per in-flight request: roughly 12,600 per host at concurrency 64 across
99 peers. That is file descriptors, kernel buffers, conntrack entries and a connection burst
on every peer restart. One connection per peer does not change with RTT.

**Throughput — real, but mostly a loopback effect.** The 4.9× is a *software* ratio: ~70µs per
call versus ~14µs. On a LAN with a 200–1000µs round trip that difference is worth roughly
**1.1×, not 4.9×**.

> Take the socket property as the reason to choose this; treat the throughput as a bonus that
> shrinks the further apart your hosts are.

## HTTP remains the default

And must: `@sigx/actors/cluster` stays zero-dependency and WinterCG-clean so Cloudflare
Workers keep working, and HTTP is the only transport that runs everywhere. With
[a bounded pool](/actors/docs/transports#bounding-the-http-pool) it is a perfectly reasonable
choice.

This package is **Node-only** by design — it uses `node:net`.

## Deploying it

`HostDescriptor.addresses` carries a `tcp` entry per host, so a mixed cluster is expressible
and the rollout is safe:

1. Deploy with `transport: [tcpTransport(), httpTransport()]` everywhere.
2. Hosts on the new build advertise `tcp` and use it with each other; hosts that do not are
   still reached over HTTP.
3. Once every host advertises `tcp`, drop `httpTransport()` from the chain if you want the
   internal HTTP mount gone entirely.

## Next steps

- [Installation](/actors/packages/actors-tcp/installation) — options and `advertiseHost`.
- [API reference](/actors/packages/actors-tcp/api) — exports.
- [Host transports](/actors/docs/transports) — the full comparison.

---
url: https://sigx.dev/deploy/packages/cloudflare/overview/
title: Overview
description: "Bundled workerd worker + wrangler scaffold — the Cloudflare adapter for SignalX (@sigx/cloudflare): what it does, setup and API."
---

# Cloudflare

<p class="lede">The flagship adapter — a fully bundled, workerd-conditioned worker with a node-free render path, a wrangler.jsonc scaffolded once and validated on drift, and optional local binding proxies in dev. Deploy with wrangler deploy.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add -D @sigx/cloudflare
pnpm add -D wrangler   # deploys, and the devProxy local bindings
```

## Usage

```ts
// vite.config.cloudflare.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { cloudflare } from '@sigx/cloudflare';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: cloudflare() } })]
});
```

`vite build --app -c vite.config.cloudflare.ts` then produces a **fully bundled** workerd-conditioned worker
(`serverBuild: 'bundled'`, conditions `['workerd', 'worker']` — the `node`
condition is deliberately dropped; the render path is `node:`-free by CI
guarantee) plus the client assets. Deploy with `wrangler deploy` — wrangler's
own bundling is a pass-through for the prebundled output (`no_bundle` is the
escape hatch if it ever isn't).

## About

`@sigx/cloudflare` is a Deploy adapter — bundled workerd worker + wrangler scaffold. It ships from the core repo in lockstep with the release it deploys, so the adapter always matches your sigx version.

It is a pack in the established sense: it rides `@sigx/vite`'s public
[`SigxAdapter` seam](/vite/docs/deploy-adapters) with no privileged access. The
runtime story is [`createFetchHandler`](/server/packages/server-renderer/fetch-handler)
(WinterCG-clean, CI-enforced); everything in this package is **build glue**.

## Next steps

Continue with [Deploying to Workers](/deploy/packages/cloudflare/deploying) for the entry, wrangler.jsonc and dev-bindings walkthrough, or jump to the [API reference](/deploy/packages/cloudflare/api).

---
url: https://sigx.dev/deploy/packages/vercel/installation/
title: Installation
description: Install and configure @sigx/vercel, the Vercel adapter for SignalX.
---

# Installation

<p class="lede">Add `@sigx/vercel` to your project — a build-time dev dependency, alongside the Vercel CLI for deploys.</p>

## Install the package

```bash
pnpm add -D @sigx/vercel
pnpm add -D vercel   # or use the globally installed CLI
```

## Wire the adapter

A separate platform config keeps the default Node build untouched:

```ts
// vite.config.vercel.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { vercel } from '@sigx/vercel';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: vercel() } })]
});
```

## Verify

```bash
vite build --app -c vite.config.vercel.ts
```

The first build scaffolds `src/entry.vercel.ts` (only when absent — yours
afterwards) and generates `.vercel/output/` with `config.json`, `static/` and
`functions/_render.func/`. Link the project (`vercel link`) and deploy the
prebuilt output with `vercel deploy --prebuilt`.

---
url: https://sigx.dev/server/packages/resume/installation/
title: Installation
description: Install and configure @sigx/resume, the Resume package for SignalX Server.
---

# Installation

<p class="lede">Add `@sigx/resume` to your project.</p>

## Install the package

```bash
pnpm add @sigx/resume
```

## Verify

```tsx
import * as Resume from '@sigx/resume';

console.log(Object.keys(Resume));
```

---
url: https://sigx.dev/server/packages/server/installation/
title: Installation
description: Install and configure @sigx/server, the Server Functions package for SignalX Server.
---

# Installation

<p class="lede">Add `@sigx/server` to your project.</p>

## Install the package

```bash
pnpm add @sigx/server
```

## Verify

```tsx
import * as ServerFunctions from '@sigx/server';

console.log(Object.keys(ServerFunctions));
```

---
url: https://sigx.dev/terminal/docs/components/detaillist/
title: DetailList
description: Aligned label/value pairs — the detail pane beside a table
---

# DetailList

<p class="lede">Aligned label/value pairs — the detail pane beside a table, or the header block of a status screen.</p>

## Import

```tsx
import { DetailList } from '@sigx/terminal';
```

## Usage

```tsx
<DetailList
    rows={[
        { label: 'Host', value: host.id },
        { label: 'Activations', value: String(host.activations) },
        { label: 'p99', value: `${host.p99}ms`, tone: host.p99 > 500 ? 'danger' : undefined },
    ]}
/>
```

Labels are fitted to one width so the values form a column. **That alignment is the only reason to reach for this over hand-written text** — and it is measured in *display cells*, so a label containing wide glyphs still lines up.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `DetailRow[]` | **required** — `{ label, value, tone? }`; `tone` is a theme token, e.g. `danger` for a figure out of range |
| `labelWidth` | `number` | fix the label column instead of measuring |
| `align` | `CellAlign` | value alignment |
| `gap` | `number` | space between the columns |

## See also

- [DataTable](/terminal/docs/components/datatable) — the table this often sits beside.

---
url: https://sigx.dev/terminal/docs/components/statusgrid/
title: StatusGrid
description: A dense grid of status cells — many things at a glance
---

# StatusGrid

<p class="lede">A dense grid of status cells, for seeing many things at once.</p>

## Import

```tsx
import { StatusGrid } from '@sigx/terminal';
```

## Usage

```tsx
<StatusGrid
    cells={partitions.value.map((p) => ({ label: p.id, tone: p.healthy ? 'success' : 'danger' }))}
    perRow={16}
    legend="● healthy  ● degraded"
/>
```

Use it when the count is high enough that one row per item would not fit — partitions, shards, replicas, checks. When you need the numbers rather than the shape, reach for [`DataTable`](/terminal/docs/components/datatable) instead.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `cells` | `StatusCell[]` | **required** |
| `perRow` | `number` | cells per row |
| `labelWidth` | `number` | label column width when labels are shown |
| `showLabels` | `boolean` | label each cell |
| `legend` | `string` | a line explaining the tones |
| `emptyText` | `string` | shown when `cells` is empty |

## See also

- [DataTable](/terminal/docs/components/datatable) — when you need the figures, not the shape.

---
url: https://sigx.dev/terminal/packages/args/installation/
title: Installation
description: Install and configure @sigx/args, the Args package for SignalX Terminal.
---

# Installation

<p class="lede">Add `@sigx/args` to your project.</p>

## Install the package

```bash
pnpm add @sigx/args
```

## Verify

```tsx
import * as Args from '@sigx/args';

console.log(Object.keys(Args));
```

---
url: https://sigx.dev/server/packages/server-renderer/api/
title: API reference
description: "@sigx/server-renderer — every public export with signatures"
---

# API reference

<p class="lede">Every public export of `@sigx/server-renderer` , grouped by kind. The import path for each symbol is noted, since the package splits into three subpaths: `@sigx/server-renderer` (main), `@sigx/server-renderer/server`, and `@sigx/server-renderer/client`.</p>

## Document render functions

These take a full HTML template with an outlet marker and assemble the complete
response (head injection, app shell, state serialization, async content). State
serialization is **on** by default here (`serializeState: false` opts out) — these
are the zero-config entry points. All accept a JSX element or an `App` and a
`DocumentOptions`. Exported from the main entry and `/server`; also available as
methods on `createSSR()` (where registered plugins apply).

### renderDocument

Render a complete HTML document to a string. Default mode: `'blocking'` — every
keyed `useData`/`useStream` resolves inline (no placeholders or replacement
scripts), which is ideal for crawlers and AI agents. The `sigx:ready` completion
script is still emitted so gated hydration runs.

```ts
function renderDocument(input: JSXElement | App, options: DocumentOptions): Promise<string>
```

- **Returns** — a promise resolving to the full document HTML. Rejects if
  `options.signal` aborts.

### renderDocumentToNodeStream

Stream a complete document as a Node `Readable`, plus a `shell` promise that
settles **before** the first byte — await it to decide the HTTP status code, then
pipe. Default mode: `'stream'`.

```ts
function renderDocumentToNodeStream(
  input: JSXElement | App,
  options: DocumentOptions
): { stream: import('node:stream').Readable; shell: Promise<void> }
```

- **Returns** — `{ stream, shell }`. The stream is byte-mode (not object mode) so
  backpressure is measured in bytes.

### renderDocumentToWebStream

Stream a complete document as a web `ReadableStream<Uint8Array>` of UTF-8 bytes,
ready as a `Response` body (edge runtimes, Workers, Deno). Default mode:
`'stream'`.

```ts
function renderDocumentToWebStream(input: JSXElement | App, options: DocumentOptions): ReadableStream<Uint8Array>
```

### DocumentOptions

Options for the `renderDocument*` family. Extends `SSRContextOptions`.

```ts
interface DocumentOptions extends SSRContextOptions {
  template: string;                                   // full HTML with the outlet marker
  outlet?: string;                                    // default: '<!--ssr-outlet-->'
  mode?: 'stream' | 'blocking';                       // default: 'blocking' (string) / 'stream' (streams)
  signal?: AbortSignal;                               // abort: stream ends early, string render rejects
  serializeState?: boolean;                           // default: true
}

// inherited from SSRContextOptions
interface SSRContextOptions {
  streaming?: boolean;
  nonce?: string;                                     // CSP nonce for renderer-emitted scripts
  onError?: (error: Error, info: SSRErrorInfo) => void;
  renderError?: (error: Error, info: SSRErrorInfo) => string;
  appContext?: AppContext;
}

interface SSRErrorInfo {
  phase: 'shell' | 'stream';                          // 'shell' = before the first byte flushed
  componentId?: number;                               // the `<!--$c:ID-->` id
  componentName?: string;                             // `__name`, or 'Anonymous'
  boundaryId?: number;                                // present for a recorded boundary
}
```

- **template** — the HTML document; must contain `outlet`. Head tags inject before
  `</head>`; the tail splits at `</body>` so entry scripts flush with the shell.
- **mode** — `'blocking'` resolves all keyed async inline; `'stream'` flushes the
  shell then swaps in async chunks out of order.
- **onError** — one seam for every failure. It receives **per-component** render
  errors on both the synchronous and streamed paths (with `componentId` /
  `componentName` / `boundaryId`), plus request-level shell and stream failures
  (phase only). `phase: 'shell'` fires before any byte is produced, so you can
  still send a 500; `'stream'` fires mid-stream.
- **renderError** — the HTML rendered in place of a failed component. Default: the
  stable `<!--ssr-error:ID-->` comment, plus a visible diagnostic box in
  development.
- **nonce** — see [Content Security Policy](#content-security-policy).
- **serializeState** — serialize resolved `useData`/`useStream` values for
  hydration pickup. Set `false` to opt out.

## Production fetch handler

Exported from `/server` and the main entry — both WinterCG-clean. See
[The fetch handler](/server/packages/server-renderer/fetch-handler) for the guide.

### createFetchHandler

Create a fetch-shaped production request handler — the WinterCG sibling of
`createRequestHandler` for Cloudflare Workers, Deno, Bun, Vercel Edge and Netlify.
Streams shell-first, switches to `mode: 'blocking'` for crawlers, resolves
`useResponse` status/redirects before the first byte.

```ts
function createFetchHandler<TPlatform = unknown>(
  options: FetchHandlerOptions<TPlatform>
): FetchHandler<TPlatform>

type FetchHandler<TPlatform = unknown> =
  (request: Request, platform?: TPlatform) => Promise<Response>
// `platform` becomes REQUIRED when TPlatform doesn't admit undefined

interface FetchHandlerOptions<TPlatform = unknown> {
  template: string | ((url: string, request: Request, platform: TPlatform) => string | Promise<string>);
  app: (url: string, request: Request, platform: TPlatform) => App | JSXElement | Promise<App | JSXElement>;
  document?: Omit<DocumentOptions, 'template' | 'mode'>
    | ((url: string, request: Request, platform: TPlatform) => Omit<DocumentOptions, 'template' | 'mode'>);
  isBot?: (userAgent: string, request: Request) => boolean;   // default: defaultIsBot
  ssr?: Pick<SSRInstance, 'renderDocumentChunks'>;            // default: plugin-less shared instance
}
```

### defaultIsBot

The crawler UA regex shared by the fetch, Node and dev handlers.

```ts
function defaultIsBot(userAgent: string): boolean
```

### chunksToBytes

Encode a chunk generator as a pull-based UTF-8 byte stream (backpressure honored;
cancellation releases the generator). The encoder under `renderDocumentToWebStream`
and `createFetchHandler`.

```ts
function chunksToBytes(chunks: AsyncGenerator<string>): ReadableStream<Uint8Array>
```

## Render functions

### renderToString

Render a JSX element or `App` to the app-shell HTML string — no template, head
injection, or state serialization (use `renderDocument` for those). Awaits all
keyed `useData`/`useStream` components and plugin streaming chunks before
resolving. Accepts an `App` from `defineApp()` (extracts the root component +
`AppContext` for DI) or a raw JSX element.

```ts
function renderToString(input: JSXElement | App, context?: SSRContext): Promise<string>
```

- **input** — a raw JSX element, or an `App` from `defineApp()`.
- **context** — optional pre-built `SSRContext` (auto-created if omitted).
- **Returns** — a promise resolving to the full HTML string.
- Exported from the main entry and `/server`.

### renderToStream

Render to a web `ReadableStream<string>`. Pull-based with 4KB chunk batching and
natural backpressure; streams the shell first, then async-component replacement
scripts interleaved as they resolve, then a final completion script. Recommended
default.

```ts
function renderToStream(input: JSXElement | App, context?: SSRContext): ReadableStream<string>
```

- **input** — JSX element or `App`.
- **context** — optional `SSRContext`.
- **Returns** — a web `ReadableStream<string>`.
- Exported from the main entry and `/server`.

### renderToNodeStream

Render to a Node.js `Readable` stream (objectMode), bypassing WebStream overhead.
Faster than `renderToStream()` on Node — recommended for Express/Fastify/H3. Pipe
directly to the HTTP response.

```ts
function renderToNodeStream(input: JSXElement | App, context?: SSRContext): Readable
```

- **input** — JSX element or `App`.
- **context** — optional `SSRContext`.
- **Returns** — a Node `Readable` (pipe to the response: `stream.pipe(res)`).
- Exported from `/server` only (not the main entry).

### renderToStreamWithCallbacks

Callback-based streaming for fine-grained control. Calls `onShellReady(html)` once
with the full synchronous shell (including plugin-injected HTML and the completion
script), then `onAsyncChunk(chunk)` per resolved async component, then
`onComplete()`; `onError(err)` on failure.

```ts
function renderToStreamWithCallbacks(input: JSXElement | App, callbacks: StreamCallbacks, context?: SSRContext): Promise<void>
```

- **input** — JSX element or `App`.
- **callbacks** — a `StreamCallbacks` set.
- **context** — optional `SSRContext`.
- **Returns** — a promise that resolves when streaming completes.
- Exported from `/server` only (not the main entry).

### renderVNodeToString

Low-level helper that renders a single VNode subtree to an HTML string using an
existing `SSRContext` (used internally for deferred async content).

```ts
function renderVNodeToString(element: JSXElement, ctx: SSRContext, appContext?: AppContext | null): Promise<string>
```

- **element** — the VNode subtree to render.
- **ctx** — an existing `SSRContext`.
- **appContext** — optional `AppContext` for DI.
- **Returns** — a promise resolving to the subtree's HTML.
- Exported from the main entry and `/server`.

## SSR instance & context

### createSSR

Creates an SSR render pipeline. Plugins are **installed on the app**
(`app.use(pack())`) and merged in per render call — the public install path;
`SSRInstance.use()` was removed in 0.13. Pass a render input as a JSX element or an
`App`, and render complete documents with `.renderDocument()`/
`.renderDocumentToNodeStream()`/`.renderDocumentToWebStream()`, or a shell with the
lower-level `.render()`/`.renderStream()`/`.renderNodeStream()`/
`.renderStreamWithCallbacks()`. With no plugins the hooks are no-ops and it behaves
like the standalone functions; islands/selective/resumable hydration are layered on
as `SSRPlugin`s. The `renderDocument*` methods append `stateSerializationPlugin()`
automatically unless it is already registered or `serializeState: false` is passed.

```ts
function createSSR(instanceOptions?: CreateSSROptions): SSRInstance
```

- **instanceOptions** — advanced/internal `{ plugins? }`; prefer installing packs
  with `app.use(pack())`. Instance plugins run before app-carried ones (deduped by
  name, first wins).
- **Returns** — an `SSRInstance`.
- Exported from the main entry.

### createSSRContext

Create a fresh `SSRContext` that tracks component IDs/markers, collected `<head>`
HTML, plugin data, streaming mode, and pending async components.

```ts
function createSSRContext(options?: SSRContextOptions): SSRContext
```

- **options** — `streaming`, `onError`, `renderError`, `nonce`, and `appContext`
  (seed the context from an existing `AppContext` so `inject()` resolves during
  render).
- **Returns** — a new `SSRContext`.
- Exported from the main entry and `/server`.

#### Content Security Policy

The renderer emits `<script>` tags of its own — the boundary table, state blobs,
the streaming protocol and its replacement scripts, and the completion script. A
strict CSP blocks all of them, which breaks hydration on a page that otherwise
rendered fine.

Pass your per-request nonce and every one of them carries it:

```ts
const nonce = crypto.randomUUID();

const html = await renderDocument(app, { template, nonce });

return new Response(html, {
  headers: {
    'content-security-policy': `script-src 'nonce-${nonce}' 'strict-dynamic'`,
  },
});
```

`nonce` is available anywhere `SSRContextOptions` is — `createSSRContext`,
`renderDocument*`, `createRequestHandler` and `createFetchHandler` — because
`DocumentOptions` extends it. Generate a fresh value per request; a reused nonce
is no better than `'unsafe-inline'`.

### SSRContext state & pack authoring (0.13)

The request-scoped `SSRContext` exposes a typed contract for pack authors:

```ts
// register request-scoped state to ship to the client under a key
registerSerializedState(key: string, value: unknown): void;
// the component currently rendering, and the recorded hydration boundaries
currentComponentId(): number | undefined;
boundaries(): ReadonlyMap<number, SSRBoundaryRecord>;
```

- **`registerSerializedState(key, value)`** — publish a value into the page's
  `window.__SIGX_ASYNC__` blob under `key`. The blob is **codec-aware**: top-level
  and nested `Date` / `Map` / `Set` / `bigint` / `URL` / `RegExp` / explicit
  `undefined` — plus any registered custom type handlers — round-trip, not just
  JSON primitives. Functions and circular references are still rejected.
- A plugin can also implement the **`onStreamEnd(ctx)`** server hook — called once
  after the streaming loop drains, before the completion script — to flush
  end-of-response state.

Packs install through a small public seam:

```ts
interface SSRPack extends SSRPlugin { install(app: App): void }
```

- **`SSRPack`** — an `SSRPlugin` with an `install(app)` method; `app.use(pack)`
  calls it. Inside, `provideSSRPlugin(app._context, pack)` registers the plugin on
  the app so the render pipeline picks it up (`getSSRPlugins` / `SSR_PLUGINS_TOKEN`
  read it back).
- **`reviveFromServer(...)`** — now public — revives a value serialized into the
  hydration blob (applying the same codec + custom handlers) on the client; it is
  exported from the client entry (`@sigx/server-renderer/client`).

## Head management

> `useHead()` itself lives in core **`sigx`** (a browser-standalone composable).
> During server rendering it collects configs onto the per-request `SSRContext`;
> this package only renders them. `renderDocument*` injects the result
> automatically.

### renderHeadToString

Render an array of collected `HeadConfig` objects to an HTML string. Dedupes meta
by name/property/http-equiv/charset, applies the last title (through
`titleTemplate`'s `%s` if set), and HTML/attr-escapes output.

```ts
function renderHeadToString(configs: HeadConfig[]): string
```

- **configs** — collected `HeadConfig` objects (the `HeadConfig` type is exported
  from `sigx`).
- **Returns** — the head HTML string.
- Exported from the main entry.

## State serialization

### stateSerializationPlugin

The built-in `SSRPlugin` (name `'sigx:state'`) that ships values resolved by keyed
`useData`/`useStream` to the client as `window.__SIGX_ASYNC__`, keyed by the
calls' explicit keys, so fetchers don't re-run after hydration. It's a plain
`SSRPlugin`, so opt in for the lower-level render APIs by passing it to
`createSSR({ plugins: [stateSerializationPlugin()] })`; the `renderDocument*` family
enables it by default.

```ts
function stateSerializationPlugin(): SSRPlugin
```

- Exported from the main entry.

### serializeAsyncScript / asyncAssignmentJs

Low-level helpers behind the state plugin: `serializeAsyncScript` builds the
`<script>` that assigns the `__SIGX_ASYNC__` blob; `asyncAssignmentJs` produces the
assignment JS for a set of key/value pairs. Both exported from `/server`.

```ts
function serializeAsyncScript(values: Record<string, unknown>): string
function asyncAssignmentJs(values: Record<string, unknown>): string
```

## Streaming script helpers

### generateStreamingScript

Returns the one-time client bootstrap `<script>` defining
`window.$SIGX_REPLACE(id, html)`, which swaps an async placeholder
(`[data-async-placeholder="id"]`) with rendered HTML and dispatches a
`sigx:async-ready` CustomEvent. Emitted once before any replacement scripts.

```ts
function generateStreamingScript(): string
```

- **Returns** — the bootstrap script HTML.
- Exported from `/server`.

### generateReplacementScript

Generate the `<script>$SIGX_REPLACE(id, "...escaped html...")</script>` for a
resolved async component, used during streaming to replace its placeholder.

```ts
function generateReplacementScript(id: number, html: string, extraScript?: string, preScript?: string): string
```

- **id** — the async component id.
- **html** — rendered HTML to inject.
- **extraScript** — optional script appended after the replacement call.
- **preScript** — optional script run **before** the replacement call (the state
  plugin installs per-component keys here, ahead of hydration listeners).
- **Returns** — the replacement script HTML.
- Exported from `/server`.

### generateAppendBootstrap / generateAppendScript

Progressive-text streaming helpers for `useStream`. `generateAppendBootstrap`
returns the one-time `window.$SIGX_APPEND(id, text)` bootstrap; `generateAppendScript`
returns a per-chunk append call that grows a streaming text node as tokens arrive.

```ts
function generateAppendBootstrap(): string
function generateAppendScript(id: number, text: string): string
```

- Exported from `/server`.

### escapeJsonForScript

Escape a JSON string for safe embedding inside a `<script>` tag (replaces `<`, `>`,
U+2028, U+2029) to prevent XSS / script-context breakout.

```ts
function escapeJsonForScript(json: string): string
```

- **json** — the JSON string to escape.
- **Returns** — the escaped string.
- Exported from `/server`.

### generateSignalKey

Generate the stable serialization key for a signal during SSR state
capture/restore. Named signals use the name; unnamed use a positional key
(`$0`, `$1`, …). Server (tracking) and client (restoring) MUST both use this for
key parity.

```ts
function generateSignalKey(name: string | undefined, index: number): string
```

- **name** — the signal's name, or `undefined` for positional keying.
- **index** — the declaration index for unnamed signals.
- **Returns** — the serialization key.
- Exported from the main entry and `/server`.

## Client hydration

### ssrClientPlugin

A sigx app `Plugin` that adds `app.hydrate(container)` to the `App` instance.
`hydrate()` resolves a string selector or `Element`, finds the root component +
`AppContext`, and hydrates existing SSR DOM (or falls back to client-side
`render()` when the container has no SSR content).

```ts
const ssrClientPlugin: Plugin
```

- Use via `defineApp(<App/>).use(ssrClientPlugin).hydrate('#root')`.
- Exported from the main entry and `/client`.

### hydrate

Core hydration entry: normalizes `element` to a VNode, sets the current
`AppContext` for DI, runs registered client plugins' `beforeHydrate` (return
`false` to skip the DOM walk, e.g. resumable SSR), walks existing SSR DOM via
`hydrateNode`, then runs `afterHydrate` hooks. Stores `_vnode` on the container.

```ts
function hydrate(element: any, container: Element, appContext?: AppContext): void
```

- Exported from `/client`.

### hydrateNode

Hydrate a single VNode against existing DOM (no DOM creation in the happy path);
attaches events/props/directives/refs, skips SSR comment markers
(`<!--t-->`, `<!--$c:N-->`), recovers from minor SSR drift by scanning forward
(dev warns), and returns the next sibling DOM node. Recurses for
fragments/components/elements.

```ts
function hydrateNode(vnode: VNode, dom: Node | null, parent: Node, regionEnd?: Node | null): Node | null
```

- Exported from `/client`. See [Bounding a marker search](#bounding-a-marker-search) for `regionEnd`.

### hydrateComponent

Hydrate a single component: locates its trailing `<!--$c:N-->` marker, builds
reactive props/slots, creates the `ComponentSetupContext` (with the client `ssr`
flags), runs setup, and creates the reactive effect that hydrates-on-first-run
then patches. Used by SSR strategy plugins for selective/island hydration.

```ts
function hydrateComponent(vnode: VNode, dom: Node | null, parent: Node, trailingMarker?: Comment | null, regionEnd?: Node | null): Node | null
```

- Exported from `/client`.
- Server state is no longer a parameter: stage it with `stageBoundaryState` immediately before the call, and the pack's context hook consumes it.

### Bounding a marker search

`hydrateNode`, `hydrateComponent`, `findComponentBoundaries` and
`scheduleWalkedBoundary` each take an optional trailing **`regionEnd`** — the
exclusive end of the sibling range the component may own. It is the enclosing
component's trailing `<!--$c:ID-->` marker, or `null` at the top of a DOM parent.

```ts
function findComponentBoundaries(dom: Node | null, regionEnd?: Node | null): {
  contentStart: Node | null;
  trailingMarker: Comment | null;
}

function scheduleWalkedBoundary(vnode: VNode, dom: Node | null, parent: Node, record: SSRBoundaryRecord, regionEnd?: Node | null): Node | null
```

It is optional and additive — existing packs compile and behave as before. But a
strategy pack that locates a component's trailing marker **itself** must bound
that search by `regionEnd`. Without it, a component whose content is followed by
sibling content in the same parent latches a **child's** marker, which shows up
as duplicated server-rendered content after a hydration bail.

### findBoundaryMarker / hydrateTableBoundary

One-shot boundary hydration, for packs that own their own wake-up scheduling
rather than using the strategy scheduler:

```ts
function findBoundaryMarker(id: number): Comment | null
function hydrateTableBoundary(id: number): Promise<boolean>
```

`hydrateTableBoundary` loads the boundary's component and hydrates it in place,
right now; it resolves `false` when the id is not in the table or its component
cannot be resolved. Both are exported from `/client`.

### registerClientPlugin

Register a client-side `SSRPlugin` so its
`client.beforeHydrate`/`hydrateComponent`/`afterHydrate` hooks run during
hydration. The mechanism behind selective/island/resumable hydration strategies.

```ts
function registerClientPlugin(plugin: SSRPlugin): void
```

- Exported from `/client`.

### getClientPlugins / clearClientPlugins

Return all currently registered client-side `SSRPlugin`s, or clear them (useful in
tests).

```ts
function getClientPlugins(): SSRPlugin[]
function clearClientPlugins(): void
```

- Exported from `/client`.

### createRestoringSignal

Create a `signal()` replacement that restores values from server-captured state by
key (via `generateSignalKey`), avoiding client re-fetch during hydration.
Dev-warns once if an unnamed (positional-key) signal is restored, since
declaration-order drift between server/client builds silently mismatches state.

```ts
function createRestoringSignal(serverState: Record<string, any>): SSRSignalFn
```

- Exported from `/client`.

### setPendingServerState

Set server-captured signal state to apply to the next component mounted during
hydration (used internally when mounting async components after streaming). The
context extension consumes and clears it.

```ts
function setPendingServerState(state: Record<string, any> | null): void
```

- Exported from `/client`.

### getCurrentAppContext / setCurrentAppContext

Get or set the `AppContext` tracked during hydration (for DI in deferred/island
hydration callbacks).

```ts
function getCurrentAppContext(): AppContext | null
function setCurrentAppContext(ctx: AppContext | null): void
```

- Exported from `/client`.

## Interfaces & types

### SSRInstance

The object returned by `createSSR()`. Plugins come from the app you render
(`app.use(pack())`) — there is no `use()` method as of 0.13. Render methods accept
`SSRContextOptions` or a pre-built `SSRContext`. `createContext()` builds a raw
`SSRContext` with this instance's plugins pre-configured.

```ts
interface SSRInstance {
  // Complete-document rendering (state serialization on by default)
  renderDocument(input: JSXElement | App, options: DocumentOptions): Promise<string>;
  renderDocumentToNodeStream(input: JSXElement | App, options: DocumentOptions): { stream: import('node:stream').Readable; shell: Promise<void> };
  renderDocumentToWebStream(input: JSXElement | App, options: DocumentOptions): ReadableStream<Uint8Array>;
  // Lower-level shell rendering
  render(input: JSXElement | App, options?: SSRContextOptions | SSRContext): Promise<string>;
  renderStream(input: JSXElement | App, options?: SSRContextOptions | SSRContext): ReadableStream<string>;
  renderNodeStream(input: JSXElement | App, options?: SSRContextOptions | SSRContext): import('node:stream').Readable;
  renderStreamWithCallbacks(input: JSXElement | App, callbacks: StreamCallbacks, options?: SSRContextOptions | SSRContext): Promise<void>;
  createContext(options?: SSRContextOptions): SSRContext;
}
```

- Exported as a type from the main entry.

### SSRPlugin

The strategy-agnostic extension interface that implements
selective/island/resumable/`Defer` hydration without core changes. Server hooks
fire during render; client hooks fire during hydration.

```ts
interface SSRPlugin {
  name: string;
  server?: {
    setup?(ctx: SSRContext): void;
    resolveBoundary?(vnode: VNode, ctx: SSRContext): ResolvedBoundary | undefined | void;
    transformComponentContext?(ctx: SSRContext, vnode: VNode, componentCtx: ComponentSetupContext): ComponentSetupContext | void;
    afterRenderComponent?(id: number, vnode: VNode, html: string, ctx: SSRContext): string | void;
    onAsyncComponentResolved?(id: number, html: string, ctx: SSRContext): { html?: string; script?: string; preScript?: string } | void;
    assets?(ctx: SSRContext): { modulepreload?: string[] } | void;
    getInjectedHTML?(ctx: SSRContext): string | Promise<string>;
    getStreamingChunks?(ctx: SSRContext): AsyncGenerator<string> | void;
  };
  client?: {
    beforeHydrate?(container: Element): boolean | void;
    transformComponentContext?(vnode: VNode, componentCtx: ComponentSetupContext): ComponentSetupContext | void;
    hydrateComponent?(vnode: VNode, dom: Node | null, parent: Node, regionEnd?: Node | null): Node | null | undefined;
    afterHydrate?(container: Element): void;
  };
}
```

Server hooks, in lifecycle order around each component:

- `server.setup` runs once before rendering starts — initialize plugin data via
  `ctx.setPluginData()`.
- `server.resolveBoundary` is **the** per-component seam. It runs after the
  component's id is allocated but **before** the setup context is built and
  before setup runs, and the first plugin to return an object wins. Its
  `flush` / `hydrate` / `media` / `chunk` / `props` / `component` axes decide
  whether the component renders on the server at all and how the client
  hydrates it — see [The boundary model](/server/packages/server-renderer/boundaries).
  Islands maps `client:only` to `{ flush: 'skip', hydrate: 'load' }` and
  `client:visible` to `{ hydrate: 'visible' }`.
- `server.transformComponentContext` runs after the `ComponentSetupContext` is
  built but **before `setup()`** — mutate or replace it (swap `ctx.signal`,
  adjust the `ssr` helper, transform props). Return a new context, or void to
  accept as-is. Not called for a `flush: 'skip'` boundary, whose setup never runs.
- `server.afterRenderComponent` is **append-only**. Output accumulates in one
  shared buffer — that is what makes streaming cheap — so there is no per-component
  HTML to intercept: the `html` argument is always `''`, and a returned string is
  appended between the component's content and its trailing `<!--$c:ID-->` marker.
  Use it to capture per-boundary state into `ctx.getBoundary(id)`. To influence
  what a component *renders*, use `transformComponentContext`; rewriting emitted
  markup is deliberately unsupported.
- `server.onAsyncComponentResolved` can rewrite a streamed replacement, with
  `script` (runs after the `$SIGX_REPLACE` call) or `preScript` (runs before it —
  for state that must land before `sigx:async-ready` dispatches).
- `server.assets` contributes `modulepreload` URLs to the document shell, deduped
  against the caller's assets and core's per-boundary chunk preloads. Core only
  warms chunks *it* will schedule, so a pack whose runtime loads lazily uses this
  to keep that fetch off the critical path.
- `server.getInjectedHTML` and `server.getStreamingChunks` emit extra markup after
  the render.

Client hooks (during hydration):

- `client.beforeHydrate` returning `false` skips the default DOM walk (resumable).
- `client.transformComponentContext` is the **hydration-time mirror** of
  `server.transformComponentContext`: it runs after the context is built and
  before `setup()` during hydration (no `SSRContext` is available then, so only
  the vnode and built context are passed). A strategy can swap `ctx.signal` for a
  variant that restores each signal from server-captured state — keeping render
  and hydration symmetric.
- `client.hydrateComponent` returning a `Node` claims a component (islands
  intercept `client:*` props). Its fourth argument, `regionEnd`, bounds the
  sibling range the component may own — a pack that finds markers itself must
  respect it, or it will latch a child's marker. See
  [Bounding a marker search](#bounding-a-marker-search).
- Exported as a type from the main entry.

### SSRContext

Per-render context tracking component IDs/markers, collected head HTML, streaming
flag, pending async components, and per-plugin data (get/setPluginData keyed by
plugin name).

```ts
interface SSRContext {
  _componentId: number;
  _componentStack: number[];
  _head: string[];
  _onComponentError?: (error: Error, componentName: string, componentId: number) => string | null;
  _plugins?: SSRPlugin[];
  _pluginData: Map<string, any>;
  _streaming: boolean;
  _pendingAsync: CorePendingAsync[];
  nextId(): number;
  pushComponent(id: number): void;
  popComponent(): number | undefined;
  addHead(html: string): void;
  getHead(): string;
  getPluginData<T>(pluginName: string): T | undefined;
  setPluginData<T>(pluginName: string, data: T): void;
}
```

- Exported as a type from the main entry and `/server`.

### SSRContextOptions

Options for `createSSRContext()` and the render methods. `streaming` defaults to
`true`. `onComponentError` returns fallback HTML for a component whose `setup()`
throws, or `null` for the default error placeholder.

```ts
interface SSRContextOptions {
  streaming?: boolean;
  onComponentError?: (error: Error, componentName: string, componentId: number) => string | null;
}
```

- Exported as a type from the main entry and `/server`.

### RenderOptions

Optional wrapper carrying a custom `SSRContext` (auto-created if absent).

```ts
interface RenderOptions {
  context?: SSRContext;
}
```

- Exported as a type from the main entry and `/server`.

### CorePendingAsync

A core-managed pending async component: its component id plus a promise resolving
to its rendered HTML once its keyed `useData`/`useStream` data resolves. Populated
by render-core in streaming mode when no plugin overrides.

```ts
interface CorePendingAsync {
  id: number;
  promise: Promise<string>;
}
```

- Exported as a type from the main entry and `/server`.

### StreamCallbacks

Callback set for `renderToStreamWithCallbacks()`: `onShellReady(shell html)`,
`onAsyncChunk(per resolved async component)`, `onComplete()`, `onError(err)`.

```ts
interface StreamCallbacks {
  onShellReady: (html: string) => void;
  onAsyncChunk: (chunk: string) => void;
  onComplete: () => void;
  onError: (error: Error) => void;
}
```

- Exported as a type from `/server`.

### SSRHelper

The `ssr` object exposed as `ctx.ssr` on every `ComponentSetupContext` — two
environment flags for the rare branch that must know where it is running. Async
data loading lives in the `useData`/`useStream` composables (from `sigx`), not
here.

```ts
interface SSRHelper {
  readonly isServer: boolean;     // running on the server
  readonly isHydrating: boolean;  // hydrating server-rendered DOM on the client
}
```

- Exported as a type from the main entry.

### HeadConfig & friends

Config objects passed to `useHead()`/`renderHeadToString()`. `titleTemplate` uses
`%s` as the title placeholder; meta is deduped by
name/property/http-equiv/charset.

```ts
interface HeadConfig {
  title?: string;
  titleTemplate?: string;
  meta?: HeadMeta[];
  link?: HeadLink[];
  script?: HeadScript[];
  htmlAttrs?: { lang?: string; dir?: string; [key: string]: string | undefined };
  bodyAttrs?: { class?: string; [key: string]: string | undefined };
}
```

`HeadMeta`, `HeadLink` and `HeadScript` are the per-tag descriptors (boolean
script attrs like `async`/`defer` render as bare attributes; `innerHTML` becomes
the script body). All exported as types from the main entry.

### SSRSignalFn

`signal()` function type augmented with an optional name used as the hydration
serialization key. Shared by server tracking signals and client restoring signals.

```ts
type SSRSignalFn = {
  <T extends Primitive>(initial: T, name?: string): PrimitiveSignal<T>;
  <T extends object>(initial: T, name?: string): Signal<T>;
}
```

- Exported as a type from the main entry and `/server` (re-exported from `/client`).

### HydrateFn

The hydrate function signature (mirrors the `MountFn` pattern).

```ts
type HydrateFn<TContainer = any> = (element: any, container: TContainer, appContext: AppContext) => (() => void) | void
```

- Exported from `/client` alongside `ssrClientPlugin`.

### ComponentFactory / InternalVNode

`ComponentFactory` is the minimal component-factory shape consumed by
`hydrateComponent`; `InternalVNode` is a `VNode` extended with internal hydration
bookkeeping (subtree refs, reactive effect, props/slots), exposed for plugin
authors. Both exported as types from `/client`.

## Module augmentations

The package augments `@sigx/runtime-core` via `declare module` to integrate SSR
into the core framework types. These apply automatically on import: `getSSRProps`
on directive definitions, `hydrate()` on `App` (via `ssrClientPlugin`), and the
`ssr` helper on `ComponentSetupContext`.

> The `client:*` directive types (`client:load`, `client:visible`, …) are **not**
> part of this package — they ship with
> [`@sigx/ssr-islands`](/server/packages/ssr-islands/api) via its `/jsx` subpath.

---
url: https://sigx.dev/terminal/packages/terminal-zero/api/
title: API reference
description: API reference for @sigx/terminal-zero — every export of the SignalX Terminal Terminal Zero package.
---

# API reference

<p class="lede">Exports of `@sigx/terminal-zero` .</p>

## Exports

The token contract, theme engine, layout primitives and prompts engine are
documented in the umbrella's [API reference](/terminal/docs/api/) (the umbrella
re-exports this package).

See the package source for the complete typed surface.

---
url: https://sigx.dev/actors/packages/actors-pg/overview/
title: Overview
description: Postgres providers for @sigx/actors — storage, membership, directory and durable reminders, all on one pool
---

# Postgres

<p class="lede">For the team whose one durable store is SQL. Four providers, one pool — and the
only shipped backend that covers reminders as well.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-pg pg
```

`pg` (node-postgres) ≥ 8 is a peer dependency; Postgres ≥ 13.

## The four providers

**`pgStorage()`** — etag-CAS [`ActorStorage`](/actors/docs/storage): one row per actor, no
TTL. A conflict throws the branded `ActorStorageConflict` the runtime turns into
fault-and-reload.

**`pgMembership()`** — TTL-heartbeat membership with expiry judged on the **database clock**,
so host clock skew cannot fake a death or a survival. LISTEN/NOTIFY push with a poll fallback,
and self-suspect fencing when a host cannot prove its own membership.

**`pgReminders()`** — durable reminders on an indexed table. A tick is one
`FOR UPDATE SKIP LOCKED` claim statement for exactly the due rows, and the advance or delete
**commits before delivery** — at-most-once, no catch-up bursts, database clock throughout.
Every host may tick the same table, because row locks replace shard ownership.

**`pgDirectory()`** — the single-activation claim directory: create-if-absent claim,
compare-and-delete release and evict, plus an `evictHost` sweep for departed hosts.

`pgCluster()` bundles membership and directory.

## Why you might pick it over Redis

- **You already run Postgres** and would rather not add Redis.
- **Reminder tables get large.** The `SKIP LOCKED` design is the scan answer;
  [Redis](/actors/packages/actors-redis/overview) rides storage with 16 hash shards, which is
  fine until it is not.
- **Clock skew worries you.** Expiry on the database clock removes a whole class of
  split-brain question.

## DDL is explicit

The providers **never issue DDL on their own** — it happens only when you call for it, so a
production role that never runs the bootstrap needs only DML grants.

```ts
await ensurePgSchema(pool);   // safe from every replica, concurrently
// or: run pgSchemaSql() through the migration tool that owns your schema
```

## Next steps

- [Installation](/actors/packages/actors-pg/installation) — schema, wiring and options.
- [API reference](/actors/packages/actors-pg/api) — exports and table layout.
- [Clustering](/actors/docs/clustering) — where the providers plug in.

---
url: https://sigx.dev/actors/packages/actors-surreal/api/
title: API reference
description: API reference for @sigx/actors-surreal — every export of the SignalX SurrealDB package.
---

# API reference

<p class="lede">Exports of `@sigx/actors-surreal` . One
entry point; everything below imports from `@sigx/actors-surreal`.</p>

## Providers

```ts
function surrealStorage(options: SurrealStorageOptions): ActorStorage;
function surrealCluster(options: SurrealClusterOptions): ClusterProviders;
function surrealMembership(options: SurrealClusterOptions): ClusterMembership;
function surrealDirectory(options: SurrealConnectionOptions): ActorDirectory;
function surrealReminders(options?: SurrealRemindersOptions): ActorReminders;
```

`surrealCluster` is membership + directory for one host — the bundle you hand to
`cluster({ providers })`. Take the two individually when you want to mix backends.

## Schema

```ts
function surrealSchemaSql(options?: { prefix?: string }): string;
function ensureSurrealSchema(db: SurrealQueryable, options?: { prefix?: string }): Promise<void>;
```

- **`surrealSchemaSql`** returns the DDL for one prefix. Idempotent and safe to re-run. Every
  table is `SCHEMAFULL`.
- **`ensureSurrealSchema`** runs it, and is safe to call from every replica at boot: it carries
  its own bounded, jittered retry, independent of the connection's `retry` setting, and
  verifies the tables exist before surfacing a failure. In production, prefer carrying
  `surrealSchemaSql()` through the tool that already owns the schema. It SELECTs the namespace
  and database rather than creating them; `DEFINE NAMESPACE` / `DEFINE DATABASE` need root and
  are a deployment decision.

Running the DDL is **mandatory**: reading an undefined table is an error in SurrealDB 3.

## Retry

```ts
function surrealRetryable(error: unknown): boolean;
```

The conflict predicate. **Install it on any connection you pass in as `db`** — see
[Installation](/actors/packages/actors-surreal/installation).

It is a connection-wide predicate, so it governs your own queries on that connection too, not
only this package's.

## Options

### `SurrealConnectionOptions`

Shared by every provider.

| Option | Default | Notes |
|---|---|---|
| `db` | — | An existing, already-connected `Surreal`, shared with your app — one socket multiplexes everything. |
| `url` | — | Or an endpoint, in which case the package connects lazily and owns the socket. Prefer `ws://`/`wss://`. |
| `namespace` / `database` | — | For the self-constructed connection. |
| `auth` | — | `{ username, password }` for the self-constructed connection. |
| `prefix` | `'sigx_'` | Table-name prefix. |

Pass `db` **or** `url`, not both.

### `SurrealClusterOptions`

Adds the membership knobs, on `surrealCluster` and `surrealMembership`.

| Option | Default | Notes |
|---|---|---|
| `heartbeatMs` | `5000` | Heartbeat cadence. |
| `ttlMs` | `15000` | Heartbeat record TTL — missed beats past this read as dead. |
| `pollMs` | `5000` | Membership view poll cadence, the fallback under the push. |
| `push` | `true` | Subscribe to a live query for immediate convergence. **The poll remains the guarantee either way.** |
| `coalesceMs` | `0` | Trailing quiet window for coalescing push notifications. |

The subscriber is single-flight regardless of `coalesceMs`: a burst of N changes costs one
refresh plus at most one trailing catch-up, not N. A non-zero window widens the net past one
round-trip, at the price of that much extra staleness.

TTL is judged on the **database** clock, so a skewed host cannot fake a death or a survival.

## Semantics worth knowing

- **Etags are opaque and client-minted.** The runtime only ever compares them.
- **State is stored as a JSON string**, so it is opaque in Surrealist. That is deliberate:
  actor state may be a top-level array or scalar, may contain NUL, and distinguishes `null`
  from absent — round-tripping it through SurrealDB's value model would risk `none`/`null`
  conflation and record-id reinterpretation.
- **`UPDATE … WHERE`, never `UPSERT … WHERE`.** `UPSERT`'s create arm carries no condition
  check, so a writer holding a stale etag whose record had since been deleted would
  *resurrect* it.
- **No NUL escaping layer.** An actor id is `type<NUL>key`, and SurrealDB carries a NUL
  verbatim and injectively inside a record id. (Postgres `text` cannot, which is the only
  reason `@sigx/actors-pg` has `pgText`.)
- **Every hot-path record is addressed by its record id** — the primary index.
  `{prefix}state:[type, key]` is a composite id, not a secondary index, so a load or save never
  scans. The three secondary indexes serve only cold sweeps.
- **Directory entries carry no TTL.** An entry is valid iff its host is live in the membership
  view — one heartbeat per host, not per activation.
- **Membership change detection compares host signatures**, not just a version counter,
  because a silent expiry changes the view without bumping anything.
- **Reminders honour shard ownership** — the opposite of `pgReminders`, which ignores it
  because `SKIP LOCKED` lets every host claim disjoint rows from one scan. With no lock
  available, partitioning is what removes contention.
- **Reminder firing is at-most-once.** The advance/delete commits before any delivery, and a
  periodic reminder advances to `time::now() + period` — so downtime costs one firing rather
  than replaying the gap.

## See also

- [Storage](/actors/docs/storage) — the `ActorStorage` seam and its ownership contract.
- [Clustering](/actors/docs/clustering) — membership, the directory, and the required `secret`.
- [Postgres](/actors/packages/actors-pg/overview) — the same four providers with a lock primitive available.

---
url: https://sigx.dev/core/packages/runtime-dom/overview/
title: Overview
description: "The DOM renderer — the Runtime DOM package for SignalX (@sigx/runtime-dom): what it does, setup and API."
---

# Runtime DOM

<p class="lede">The DOM renderer — this is SignalX on the web. Web isn't a platform you switch to; it's the default render target that ships inside the core repo.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

You rarely install this directly — the `sigx` umbrella re-exports it:

```bash
pnpm add sigx                # reactivity + runtime-core + runtime-dom
pnpm add @sigx/runtime-dom   # direct, for custom setups
```

## What it does

`@sigx/runtime-dom` binds the renderer-agnostic component model from `@sigx/runtime-core` to the browser DOM:

- **Fine-grained DOM patches** — a changed signal updates exactly the text nodes, attributes and properties that read it. No virtual DOM.
- **Event delegation** — `onClick` and friends attach once per root.
- **Hydration** — pairs with `@sigx/server-renderer` to hydrate server-rendered HTML, selectively via islands.

## Mount an app

```tsx
import { createApp } from 'sigx';
import { App } from './App';

createApp(App).mount('#root');
```

## The renderer family

Every target implements the same `RuntimeRenderer` contract — this one for the DOM, `@sigx/lynx-runtime` for native views, `@sigx/terminal` for cells. Same components, different surfaces.

## Next steps

See [Usage](/core/packages/runtime-dom/usage), or start with the [Core getting-started guide](/core/docs/getting-started).

---
url: https://sigx.dev/actors/packages/actors-ws/overview/
title: Overview
description: The client-facing WebSocket transport for @sigx/actors — calls and live subscriptions over one socket, with no held-open POST and no preflight
---

# WebSocket

<p class="lede">One socket from the browser to your host, carrying every call and every live
subscription on the page.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/actors-ws
```

Client side, the transport is the whole integration:

```ts
import { actorsPlugin } from '@sigx/actors/app';
import { socketTransport } from '@sigx/actors-ws/client';

app.use(actorsPlugin({ transport: socketTransport({ url: 'wss://example.com/_sigx/socket' }) }));
```

Server side on Node, attach the upgrade listener:

```ts
import { createServer } from 'node:http';
import { createAppHandler } from '@sigx/actors/node';
import { attachActorSocket } from '@sigx/actors-ws/node';

const server = createServer(createAppHandler(app));

await app.start();                                  // the session needs a running host
attachActorSocket(server, { host: app.host! });

await new Promise<void>((r) => server.listen(7311, r));
```

`useActorState` and `useActorAction` need no changes — the plugin routes them over the socket
for you.

## What it buys

Three things, and they are all about the shape of the connection rather than raw speed:

- **No cross-origin preflight.** A WebSocket upgrade is not a CORS-preflighted request, so a
  browser talking to an actor host on another origin stops paying an `OPTIONS` round trip per
  call.
- **No held-open POST.** [Live reads](/actors/docs/live-reads) over HTTP ride a long-lived
  response body, which proxies, mobile NATs and corporate middleboxes all treat with
  suspicion. A WebSocket is the thing that infrastructure expects to stay open.
- **Subscriptions change incrementally.** Adding one is a ~40-byte `{i,sub}` message and
  removing one is `{i,uns}` — nothing reopens, so a page whose live set changes as components
  mount does not reconnect and re-seed every time.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Per-call latency and throughput are not the win.</strong> Against a warm
    same-origin HTTP/2 connection, a socket call measures about the same — and reliability is
    <em>worse</em>, because sockets drop and in-flight calls fail with them.
    <a href="/actors/docs/client"><code>fetchTransport()</code></a> remains the default, and
    it is the right default.
  </div>
</div>

## What happens when it drops

**In-flight calls fail, and are never retried.** Re-sending a call whose response was lost
would mean re-running an actor method that may not be idempotent — a correctness bug wearing a
reliability costume. They reject, and the caller decides.

**Subscriptions re-establish on their own.** They are declarative, so replaying them is safe.
Each one re-seeds on reconnect, and `fingerprint()` suppresses the value if it has not changed
— so a reconnect does not repaint the page.

Reconnection backs off from `retryMs` (default 300 ms) to `maxRetryMs` (default 10 s).

## It is host-affine

Every call re-dispatches through placement anyway, so a per-call `endpoint` makes no sense
over a socket and is **ignored**, with a `__DEV__` warning. If you need to reach a specific
host, that is [locality routing](/actors/docs/locality-routing)'s job.

## Not only WebSocket

The primary seam is a **link, not a URL**:

```ts
socketTransport({
    connect: (handlers) => ({
        send: (message) => channel.emit('sigx', message),
        close: () => channel.disconnect(),
    }),
});
```

`url` is sugar that dials the global `WebSocket`. Supply `connect` instead and socket.io, a
`MessageChannel`, a React Native bridge or anything else message-oriented can carry the same
protocol — see [Installation](/actors/packages/actors-ws/installation#interop) for worked
recipes.

## Next steps

- [Installation](/actors/packages/actors-ws/installation) — options, adapters and interop.
- [API](/actors/packages/actors-ws/api) — the exported surface.
- [Socket sessions](/actors/docs/socket-sessions) — the server half, and its posture.
- [Host transports](/actors/docs/transports) — the *other* kind of transport, between hosts.

---
url: https://sigx.dev/daisyui/docs/components/form-field/
title: FormField
description: Form field wrapper with label, hint text, and validation error support using daisyUI fieldset/legend/label/validator-hint classes
---

# FormField

FormField is a convenience wrapper that combines `fieldset`, `fieldset-legend`, `label` (hint), and `validator-hint` (error) into a single compound component for consistent form layouts.

## Import

```tsx
import { FormField, Input, Textarea, Select } from '@sigx/daisyui';
```

## Basic Usage

Wrap any form input with `FormField` for a labeled field:

```tsx
import { component, render } from 'sigx';
import { FormField, Input } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ email: '' });

    return () => (
        <FormField label="Email Address">
            <Input
                model={() => form.email}
                type="email"
                placeholder="you@example.com"
            />
        </FormField>
    );
});

render(<Demo />, "#sandbox");
```

## Required Field

Use the `required` prop to show a red asterisk indicator after the label:

```tsx
import { component, render } from 'sigx';
import { FormField, Input, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ name: '', email: '' });

    return () => (
        <Col gap="4">
            <FormField label="Full Name" required>
                <Input
                    model={() => form.name}
                    placeholder="John Doe"
                />
            </FormField>

            <FormField label="Email" required>
                <Input
                    model={() => form.email}
                    type="email"
                    placeholder="john@example.com"
                />
            </FormField>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Hint Text

Add helper text below the field with the `hint` prop. Renders as a `<p class="label">`:

```tsx
import { component, render } from 'sigx';
import { FormField, Input, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ username: '', password: '' });

    return () => (
        <Col gap="4">
            <FormField label="Username" hint="Only letters, numbers, and underscores">
                <Input
                    model={() => form.username}
                    placeholder="john_doe"
                />
            </FormField>

            <FormField label="Password" hint="Must be at least 8 characters">
                <Input
                    model={() => form.password}
                    type="password"
                    placeholder="••••••••"
                />
            </FormField>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Error Messages

Show validation errors with the `error` prop. Renders as a `<p class="validator-hint text-error">`. When both `error` and `hint` are set, the error takes priority:

```tsx
import { component, render } from 'sigx';
import { FormField, Input, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ email: 'invalid-email' });
    const emailError = () => {
        if (!form.email) return 'Email is required';
        if (!form.email.includes('@')) return 'Please enter a valid email';
        return '';
    };

    return () => (
        <Col gap="4">
            <FormField
                label="Email"
                required
                error={emailError()}
            >
                <Input
                    model={() => form.email}
                    type="email"
                    placeholder="you@example.com"
                    color={emailError() ? 'error' : undefined}
                />
            </FormField>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Different Inputs

FormField works with all form components — Input, Textarea, Select, and more:

```tsx
import { component, render } from 'sigx';
import { FormField, Input, Textarea, Select, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({
        name: '',
        bio: '',
        country: ''
    });

    const countries = [
        { value: 'us', label: 'United States' },
        { value: 'uk', label: 'United Kingdom' },
        { value: 'ca', label: 'Canada' }
    ];

    return () => (
        <Col gap="4">
            <FormField label="Name" required>
                <Input
                    model={() => form.name}
                    placeholder="Your name"
                />
            </FormField>

            <FormField label="Bio" hint="Brief description about yourself">
                <Textarea
                    model={() => form.bio}
                    placeholder="Tell us about yourself..."
                    rows={3}
                />
            </FormField>

            <FormField label="Country">
                <Select
                    model={() => form.country}
                    options={countries}
                    placeholder="Select a country"
                />
            </FormField>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Complete Form

A full registration form combining FormField with validation, multiple input types, and layout components:

```tsx
import { component, render } from 'sigx';
import { FormField, Input, Textarea, Select, Checkbox, Button, Card, Divider, Col, Row, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({
        firstName: '',
        lastName: '',
        email: '',
        phone: '',
        role: '',
        bio: '',
        terms: false
    });

    const errors = signal({
        firstName: '',
        email: '',
        terms: ''
    });

    const roles = [
        { value: 'developer', label: 'Developer' },
        { value: 'designer', label: 'Designer' },
        { value: 'manager', label: 'Manager' }
    ];

    const validate = () => {
        let valid = true;

        if (!form.firstName) {
            errors.firstName = 'First name is required';
            valid = false;
        } else {
            errors.firstName = '';
        }

        if (!form.email) {
            errors.email = 'Email is required';
            valid = false;
        } else if (!form.email.includes('@')) {
            errors.email = 'Please enter a valid email';
            valid = false;
        } else {
            errors.email = '';
        }

        if (!form.terms) {
            errors.terms = 'You must accept the terms';
            valid = false;
        } else {
            errors.terms = '';
        }

        return valid;
    };

    const handleSubmit = () => {
        if (validate()) {
            alert('Form submitted successfully!');
        }
    };

    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Heading level={2} size="xl">Registration Form</Heading>

                    <Row gap="4" wrap>
                        <FormField label="First Name" required error={errors.firstName} class="flex-1 min-w-60">
                            <Input
                                model={() => form.firstName}
                                placeholder="John"
                                color={errors.firstName ? 'error' : undefined}
                            />
                        </FormField>

                        <FormField label="Last Name" class="flex-1 min-w-60">
                            <Input
                                model={() => form.lastName}
                                placeholder="Doe"
                            />
                        </FormField>
                    </Row>

                    <Row gap="4" wrap>
                        <FormField label="Email" required error={errors.email} class="flex-1 min-w-60">
                            <Input
                                model={() => form.email}
                                type="email"
                                placeholder="john@example.com"
                                color={errors.email ? 'error' : undefined}
                            />
                        </FormField>

                        <FormField label="Phone" hint="Optional" class="flex-1 min-w-60">
                            <Input
                                model={() => form.phone}
                                type="tel"
                                placeholder="+1 (555) 000-0000"
                            />
                        </FormField>
                    </Row>

                    <FormField label="Role">
                        <Select
                            model={() => form.role}
                            options={roles}
                            placeholder="Select your role"
                        />
                    </FormField>

                    <FormField label="Bio" hint="Tell us about yourself">
                        <Textarea
                            model={() => form.bio}
                            placeholder="A brief description..."
                            rows={3}
                        />
                    </FormField>

                    <Divider />

                    <FormField error={errors.terms}>
                        <Checkbox
                            model={() => form.terms}
                            color={errors.terms ? 'error' : 'primary'}
                            label="I accept the terms of service and privacy policy"
                        />
                    </FormField>

                    <Button variant="primary" block onClick={handleSubmit}>
                        Register
                    </Button>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Label text rendered as `<legend class="fieldset-legend">` |
| `required` | `boolean` | `false` | Shows a red asterisk (*) after the label |
| `hint` | `string` | - | Helper text rendered as `<p class="label">` below the field |
| `error` | `string` | - | Error message rendered as `<p class="validator-hint text-error">` (replaces hint) |
| `class` | `string` | - | Additional CSS classes on the fieldset container |

## Slots

| Slot | Description |
|------|-------------|
| `default` | The form input component(s) to wrap |

---
url: https://sigx.dev/daisyui/docs/components/file-input/
title: File Input
description: File Input is a styled file upload control
---

# File Input

File Input is a styled file upload control with DaisyUI styling.

## Import

```tsx
import { FileInput } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { FileInput } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <FileInput class="w-full max-w-xs" />
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { FileInput, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <FileInput class="w-full max-w-xs" />
            <FileInput color="primary" class="w-full max-w-xs" />
            <FileInput color="secondary" class="w-full max-w-xs" />
            <FileInput color="accent" class="w-full max-w-xs" />
            <FileInput color="neutral" class="w-full max-w-xs" />
            <FileInput color="info" class="w-full max-w-xs" />
            <FileInput color="success" class="w-full max-w-xs" />
            <FileInput color="warning" class="w-full max-w-xs" />
            <FileInput color="error" class="w-full max-w-xs" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { FileInput, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <FileInput size="xs" class="w-full max-w-xs" />
            <FileInput size="sm" class="w-full max-w-xs" />
            <FileInput size="md" class="w-full max-w-xs" />
            <FileInput size="lg" class="w-full max-w-xs" />
            <FileInput size="xl" class="w-full max-w-xs" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Ghost

Ghost variant gives a minimal background style.

```tsx
import { component, render } from 'sigx';
import { FileInput } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <FileInput ghost class="w-full max-w-xs" />
    );
});

render(<Demo />, "#sandbox");
```

## Disabled

```tsx
import { component, render } from 'sigx';
import { FileInput } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <FileInput disabled class="w-full max-w-xs" />
    );
});

render(<Demo />, "#sandbox");
```

## With Accept Filter

```tsx
import { component, render } from 'sigx';
import { FileInput, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Text>Images only</Text>
            <FileInput accept="image/*" class="w-full max-w-xs" />
            <Text>PDF and Word documents</Text>
            <FileInput accept=".pdf,.doc,.docx" class="w-full max-w-xs" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the file input |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | — | Color variant |
| `ghost` | `boolean` | `false` | Ghost/minimal style |
| `accept` | `string` | — | Accepted file types (e.g. `"image/*"`, `".pdf"`) |
| `multiple` | `boolean` | `false` | Allow multiple file selection |
| `disabled` | `boolean` | `false` | Disable the input |
| `class` | `string` | — | Additional CSS classes |
| `onChange` | `(files: FileList \| null) => void` | — | Fired when files are selected |

---
url: https://sigx.dev/server/packages/serialize/overview/
title: Overview
description: "Serialize — the boundary codec: round-trip Date/Map/Set/bigint/URL/RegExp and your own types"
---

# Serialize

<p class="lede">The codec that carries values JSON can't across every server↔client boundary — the SSR state blob, server-function arguments and results, resume boundary props and cache seeds. Round-trips Date / Map / Set / bigint / URL / RegExp / undefined out of the box; <code>defineTypeHandler</code> adds your own types with type-guard-driven inference.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/serialize
```

## About

`@sigx/serialize` is the low-level codec beneath SignalX's server↔client boundaries. Out of the box it round-trips `Date`, `Map`, `Set`, `bigint`, `URL`, `RegExp` and explicit `undefined`; `defineTypeHandler` adds your own types. It has **zero runtime dependencies** by design — it's imported by the dependency-free `@sigx/server/client` stub — and is side-effect-free.

Two functions do the work — [`encodeWithHandlers`](/server/packages/serialize/api#encodewithhandlers) and [`reviveWithHandlers`](/server/packages/serialize/api#revivewithhandlers) — but most apps never call them directly: the [server renderer](/server/packages/server-renderer/overview), [server functions](/server/packages/server/overview), [resume](/server/packages/resume/overview) and [actors](/actors/) all run the codec for you. You reach for this package only to **register a custom type** — see [Usage](/server/packages/serialize/usage).

On the wire, a handled value takes a single-key tagged form:

```json
{ "createdAt": { "$date": 1700000000000 }, "tags": { "$set": ["priority"] } }
```

## Next steps

- [Usage](/server/packages/serialize/usage) — write and register a custom type handler.
- [API reference](/server/packages/serialize/api) — `defineTypeHandler`, `encodeWithHandlers`, `reviveWithHandlers`, `TypeHandler` and the built-ins.

---
url: https://sigx.dev/terminal/docs/components/sparkline/
title: Sparkline
description: "A time series in one line — the 'is this going up?' glyph"
---

# Sparkline

<p class="lede">A time series in one line, or a few — the "is this going up?" glyph a dashboard needs and a <code>ProgressBar</code> cannot give, since that is a single ratio.</p>

## Import

```tsx
import { Sparkline } from '@sigx/terminal';
```

## Usage

```tsx
<Sparkline label="req/s" values={rps.value} value={`${last}`} width={40} />
```

## Three things it deliberately does not do

Each of these is a way a sparkline can lie, so each is refused by default:

- **It does not anchor the scale to the series minimum.** A flat line at 1000 req/s would otherwise draw as a mountain range. Pass `baseline="min"` if you genuinely want that framing.
- **It does not let a tiny non-zero value round away to the baseline.** "Almost nothing" and "nothing" are different readings.
- **It does not draw a gap as a zero.** `null` renders as `·`, because a counter reset and an idle period are different facts.

## Density

`variant="braille"` packs two samples per cell, doubling horizontal density. `height` buys proportionally more vertical levels.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `values` | `(number \| null)[]` | **required** — `null` is a gap, not a zero |
| `width` / `height` | `number` | cells; `height` adds vertical levels |
| `max` | `number` | fix the top of the scale |
| `baseline` | `number \| 'min'` | the bottom of the scale |
| `variant` | `SparkVariant` | `'braille'` doubles horizontal density |
| `label` / `labelWidth` | `string` / `number` | leading label, fitted to a column |
| `value` | `string` | trailing readout |
| `color` | `string` | theme token |
| `thresholds` | `Threshold[]` | colour by magnitude |
| `pad` | `boolean` | pad to `width` |

## See also

- [Meter](/terminal/docs/components/meter) — a single ratio rather than a series.
- [BarChart](/terminal/docs/components/barchart) — labelled bars on one shared scale.

---
url: https://sigx.dev/terminal/docs/components/datatable/
title: DataTable
description: A table with a cursor, a viewport and a sort — the shape a dashboard needs
---

# DataTable

<p class="lede">A table with a cursor, a scrolling viewport and a sort. Columns are typed accessors, so the data stays your own objects and the table never has to be re-flattened to re-sort it.</p>

## Import

```tsx
import { DataTable } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, DataTable } from '@sigx/terminal';

const COLUMNS = [
    { key: 'host', label: 'Host', get: (r) => r.host },
    { key: 'turns', label: 'Turns', get: (r) => String(r.turns), align: 'right' },
    { key: 'p99', label: 'p99', get: (r) => `${r.p99}ms`, align: 'right' },
];

const App = component(() => {
    return () => (
        <DataTable
            title="Hosts"
            columns={COLUMNS}
            rows={hosts.value}
            identity={(r) => r.host}
            sortable
            height={20}
        />
    );
});
```

Prefer [`Table`](/terminal/docs/components/table) when you have a static grid of strings and want none of this.

## Three behaviours worth knowing

**Shrinking takes space from the rightmost columns.** The left column is nearly always the identity, and a table whose identities are truncated to make room for a latency figure is unusable. Truncation is always marked with `…`, never silent.

**Sorting breaks ties on identity.** A dashboard re-sorts every poll, and rows with equal values would otherwise swap places each time — motion that reads as activity when nothing changed. Pass `identity` for a stable key; the row index is the fallback.

**The cursor clamps and the window moves by one.** Holding <kbd>↓</kbd> stops at the bottom rather than wrapping, and stepping past the edge scrolls one row, not a screenful.

## Keys

While focused:

| Key | Action |
| --- | --- |
| <kbd>↑</kbd> / <kbd>k</kbd>, <kbd>↓</kbd> / <kbd>j</kbd> | Move the cursor |
| <kbd>PgUp</kbd> / <kbd>PgDn</kbd> | Page |
| <kbd>Home</kbd> / <kbd>End</kbd> | Jump to the ends |
| <kbd>Enter</kbd> | Submit |
| <kbd>←</kbd> / <kbd>→</kbd> | Pick the sort column (with `sortable`) |
| <kbd>r</kbd> | Reverse the sort (with `sortable`) |

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `TableColumn<T>[]` | **required** — typed accessors (`key`, `label`, `get`, `align`, width hints) |
| `rows` | `T[]` | the data, as your own objects |
| `width` / `height` | `number` | the area to fill; pair with a [`Shell`](/terminal/docs/components/shell) pane |
| `identity` | `(row: T) => string` | stable key for tie-breaking the sort |
| `sortable` | `boolean` | enable the sort keys |
| `sortKey` / `sortDir` | `string` / `'asc' \| 'desc'` | controlled sort state |
| `tone` | `(row: T) => string \| undefined` | per-row theme token |
| `variant` | `'boxed' \| 'plain' \| 'ruled'` | frame style |
| `title` | `string` | panel title |
| `emptyText` | `string` | shown when `rows` is empty |
| `showFooter` | `boolean` | show the position/count footer |
| `gap` | `number` | column gap |

## See also

- [Table](/terminal/docs/components/table) — the static string grid.
- [Shell](/terminal/docs/components/shell) — the dashboard frame that supplies `width`/`height`.

---
url: https://sigx.dev/terminal/docs/components/statusbar/
title: StatusBar
description: A footer of keyed status chips
---

# StatusBar

<p class="lede">A footer row of status chips — each item is a <code>key</code> in an accent fill followed by a <code>label</code>.</p>

## Import

```tsx
import { StatusBar } from '@sigx/terminal';
import type { StatusItem } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, StatusBar } from '@sigx/terminal';
import type { StatusItem } from '@sigx/terminal';

const items: StatusItem[] = [
    { key: 'MODE', label: 'insert' },
    { key: 'BRANCH', label: 'main' },
    { key: 'LSP', label: 'ready' },
];

const App = component(() => {
    return () => (
        <box>
            <StatusBar items={items} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `StatusItem[]` | **required** — the chips |

## StatusItem

```ts
interface StatusItem {
    key: string;
    label: string;
}
```

## See also

- [KeyHints](/terminal/docs/components/keyhints) — a lighter shortcut footer.
- [Badge](/terminal/docs/components/badge) — a single tag.

---
url: https://sigx.dev/terminal/packages/terminal-dev/api/
title: API reference
description: API reference for @sigx/terminal-dev — every export of the SignalX Terminal Terminal Dev package.
---

# API reference

<p class="lede">Exports of `@sigx/terminal-dev` .</p>

## Exports

| Export | What it is |
| --- | --- |
| `sigx-terminal-dev` (bin) | The CLI entry: `sigx-terminal-dev [entry] [--root <dir>] [--config <vite config>]`. See [running an app](/terminal/packages/terminal-dev/overview/#running-an-app). |
| `startDev(options)` | Programmatic entry — returns `{ server, runner, restart, close }` for embedding the dev runner in your own tooling. See [programmatic API](/terminal/packages/terminal-dev/overview/#programmatic-api). |
| `terminalDevPlugin()` | The Vite plugin that injects HMR identity registration and self-accept into component modules. |
| `@sigx/terminal-dev/hmr` | The runtime that patches live component instances on a hot update — injected automatically; you never import it yourself. |

See the package source for the complete typed surface.

---
url: https://sigx.dev/core/packages/reactivity/overview/
title: Overview
description: "Signals, computed & effects — the Reactivity package for SignalX (@sigx/reactivity): what it does, setup and API."
---

# Reactivity

<p class="lede">Signals, computed and effects — the reactive primitives everything is built on.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/reactivity
```

## About

`@sigx/reactivity` is a Core package — signals, computed & effects. It is versioned in lockstep with the rest of the Core repo, so any combination of modules just works together.

## Next steps

Continue with [Installation](/core/packages/reactivity/installation) for project setup, or jump to the [API reference](/core/packages/reactivity/api).

---
url: https://sigx.dev/daisyui/docs/components/countdown/
title: Countdown
description: Countdown gives you a transition effect of changing numbers
---

# Countdown

Countdown gives you a transition effect of changing numbers. Uses the `--value` CSS variable (0–999) and optionally `--digits` to set minimum digit display.

## Import

```tsx
import { Countdown } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Countdown } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Countdown value={42} />
    );
});

render(<Demo />, "#sandbox");
```

## Large Text

Use the `class` prop to add Tailwind utility classes for sizing.

```tsx
import { component, render } from 'sigx';
import { Countdown } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Countdown value={59} digits={2} class="font-mono text-6xl" />
    );
});

render(<Demo />, "#sandbox");
```

## Clock Format

Combine multiple Countdown components to create a clock display.

```tsx
import { component, render } from 'sigx';
import { Countdown, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="1" align="center" class="font-mono text-2xl">
            <Countdown value={10} digits={2} />
            <Text>:</Text>
            <Countdown value={24} digits={2} />
            <Text>:</Text>
            <Countdown value={53} digits={2} />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## With Labels

Display countdown values with descriptive labels underneath.

```tsx
import { component, render } from 'sigx';
import { Countdown, Row, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="5" class="font-mono text-4xl">
            <Col gap="1" align="center">
                <Countdown value={15} digits={2} />
                <Text class="text-sm">days</Text>
            </Col>
            <Col gap="1" align="center">
                <Countdown value={10} digits={2} />
                <Text class="text-sm">hours</Text>
            </Col>
            <Col gap="1" align="center">
                <Countdown value={24} digits={2} />
                <Text class="text-sm">min</Text>
            </Col>
            <Col gap="1" align="center">
                <Countdown value={53} digits={2} />
                <Text class="text-sm">sec</Text>
            </Col>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Boxed Style

Wrap each countdown in a styled container for a card-like appearance.

```tsx
import { component, render } from 'sigx';
import { Countdown, Row, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="5" class="font-mono text-4xl text-center">
            <Col gap="1" align="center" class="bg-neutral rounded-box text-neutral-content p-2">
                <Countdown value={15} digits={2} />
                <Text class="text-sm">days</Text>
            </Col>
            <Col gap="1" align="center" class="bg-neutral rounded-box text-neutral-content p-2">
                <Countdown value={10} digits={2} />
                <Text class="text-sm">hours</Text>
            </Col>
            <Col gap="1" align="center" class="bg-neutral rounded-box text-neutral-content p-2">
                <Countdown value={24} digits={2} />
                <Text class="text-sm">min</Text>
            </Col>
            <Col gap="1" align="center" class="bg-neutral rounded-box text-neutral-content p-2">
                <Countdown value={53} digits={2} />
                <Text class="text-sm">sec</Text>
            </Col>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Three Digit Values

Use `digits={3}` to display values up to 999 with minimum 3 digits.

```tsx
import { component, render } from 'sigx';
import { Countdown, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" class="font-mono text-4xl">
            <Countdown value={365} digits={3} />
            <Countdown value={42} digits={3} />
            <Countdown value={7} digits={3} />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `0` | The numeric value to display (0–999) |
| `digits` | `2 \| 3` | `undefined` | Minimum number of digits to display |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/indicator/
title: Indicator
description: Indicator is used to place an element on the corner of another element
---

# Indicator

Indicator is used to place an element (like a badge or status dot) on the corner of another element. Uses `Indicator.Item` sub-component for the positioned content.

## Import

```tsx
import { Indicator } from '@sigx/daisyui';
```

## Basic Usage

A simple indicator badge on a content area.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Card } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item>
                <Badge variant="primary">New</Badge>
            </Indicator.Item>
            <Card class="bg-base-300 grid h-32 w-60 place-items-center">
                Content
            </Card>
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## Badge on Button

Show a notification count on a button.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item>
                <Badge variant="secondary">99+</Badge>
            </Indicator.Item>
            <Button>Inbox</Button>
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## All Positions

Use `vertical` (top, middle, bottom) and `horizontal` (start, center, end) props on `Indicator.Item` to control placement.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Card } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item vertical="top" horizontal="start">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="top" horizontal="center">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="top" horizontal="end">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="middle" horizontal="start">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="middle" horizontal="center">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="middle" horizontal="end">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="bottom" horizontal="start">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="bottom" horizontal="center">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Indicator.Item vertical="bottom" horizontal="end">
                <Badge size="xs" variant="secondary" />
            </Indicator.Item>
            <Card class="bg-base-300 grid h-32 w-60 place-items-center">
                All 9 positions
            </Card>
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## Multiple Indicators

Use multiple `Indicator.Item` children to show indicators at different corners.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Card } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item vertical="top" horizontal="start">
                <Badge variant="warning">Hot</Badge>
            </Indicator.Item>
            <Indicator.Item vertical="top" horizontal="end">
                <Badge variant="error">-20%</Badge>
            </Indicator.Item>
            <Indicator.Item vertical="bottom" horizontal="end">
                <Badge variant="success">New</Badge>
            </Indicator.Item>
            <Card class="bg-base-300 grid h-32 w-60 place-items-center">
                Product
            </Card>
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## For Avatar

Show a status badge on an avatar.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Avatar } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item>
                <Badge variant="success" size="xs" />
            </Indicator.Item>
            <Avatar shape="circle" size="md" src="https://img.daisyui.com/images/stock/photo-1534528741775-53994a69daeb.webp" />
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## For Input

Show a "Required" badge on an input field.

```tsx
import { component, render } from 'sigx';
import { Indicator, Badge, Input } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator class="w-full max-w-xs">
            <Indicator.Item>
                <Badge variant="secondary">Required</Badge>
            </Indicator.Item>
            <Input class="w-full" placeholder="Your email address" />
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## Center on Image

Use center placement to overlay content on an image.

```tsx
import { component, render } from 'sigx';
import { Indicator, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Indicator>
            <Indicator.Item vertical="middle" horizontal="center">
                <Button variant="primary">Apply</Button>
            </Indicator.Item>
            <img src="https://img.daisyui.com/images/stock/photo-1606107557195-0e29a4b5b4aa.webp" class="rounded-lg w-60" />
        </Indicator>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Indicator

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | — | Additional CSS classes for the container |

### Indicator.Item

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `vertical` | `'top' \| 'middle' \| 'bottom'` | — | Vertical alignment of the indicator item |
| `horizontal` | `'start' \| 'center' \| 'end'` | — | Horizontal alignment of the indicator item |
| `class` | `string` | — | Additional CSS classes for the indicator item |

---
url: https://sigx.dev/daisyui/docs/components/accordion/
title: Accordion
description: Collapsible content panels for organizing and hiding content
---

# Accordion

Accordion allows showing and hiding content in collapsible panels. Only one panel can be open at a time.

## Import

```tsx
import { Accordion, Row, Col, Heading, Text } from '@sigx/daisyui';
```

Sub-components are available as `Accordion.Item` and `Accordion.Collapse`.

## Basic Usage

Use the `items` prop for a simple accordion:

```tsx
import { component, render } from 'sigx';
import { Accordion, Card, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const active = signal({ id: '' });
    
    const faqs = [
        { 
            id: '1', 
            title: 'How do I create an account?', 
            content: 'Click the "Sign Up" button in the top right corner and follow the registration process.' 
        },
        { 
            id: '2', 
            title: 'How do I reset my password?', 
            content: 'Go to the login page and click "Forgot Password" to receive a reset link via email.' 
        },
        { 
            id: '3', 
            title: 'Where can I find pricing information?', 
            content: 'Visit our pricing page at /pricing for detailed plan information and comparisons.' 
        }
    ];
    
    return () => (
        <Card>
            <Card.Body>
                <Heading level={2} size="xl" class="mb-4">FAQ</Heading>
                <Accordion 
                    items={faqs} 
                    model:activeId={() => active.id}
                    variant="arrow"
                />
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With Plus/Minus Icon

```tsx
import { component, render } from 'sigx';
import { Accordion } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const active = signal({ id: '1' });
    
    const items = [
        { id: '1', title: 'What is SignalX?', content: 'SignalX is a reactive UI framework for building modern web applications.' },
        { id: '2', title: 'What is DaisyUI?', content: 'DaisyUI is a component library for Tailwind CSS with beautiful ready-made components.' },
        { id: '3', title: 'How do they work together?', content: '@sigx/daisyui combines both to provide reactive, beautiful UI components.' }
    ];
    
    return () => (
        <Accordion 
            items={items} 
            model:activeId={() => active.id}
            variant="plus"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Joined Accordion

Use the `join` prop to connect items visually:

```tsx
import { component, render } from 'sigx';
import { Accordion } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const active = signal({ id: '' });
    
    const items = [
        { id: '1', title: 'Step 1: Install', content: 'Run npm install @sigx/daisyui to add the package to your project.' },
        { id: '2', title: 'Step 2: Configure', content: 'Add daisyui to your Tailwind config and import the components.' },
        { id: '3', title: 'Step 3: Use', content: 'Import and use any component in your SignalX application.' }
    ];
    
    return () => (
        <Accordion 
            items={items} 
            model:activeId={() => active.id}
            variant="arrow"
            join
        />
    );
});

render(<Demo />, "#sandbox");
```

## Using Details Element

Use the `type="details"` prop to use native HTML `<details>` elements. This makes the collapsed content searchable by the browser:

```tsx
import { component, render } from 'sigx';
import { Accordion } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const active = signal({ id: '' });
    
    const items = [
        { id: '1', title: 'What is the return policy?', content: 'We offer a 30-day return policy for all unused items in original packaging.' },
        { id: '2', title: 'How long does shipping take?', content: 'Standard shipping takes 5-7 business days. Express shipping is available for 2-3 day delivery.' },
        { id: '3', title: 'Do you offer international shipping?', content: 'Yes, we ship to over 100 countries worldwide with calculated shipping rates.' }
    ];
    
    return () => (
        <Accordion 
            items={items} 
            model:activeId={() => active.id}
            variant="arrow"
            type="details"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Accordion.Collapse (Single Collapsible)

For a single collapsible panel, use `Accordion.Collapse`:

```tsx
import { component, render } from 'sigx';
import { Accordion, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const isOpen = signal({ value: false });
    
    return () => (
        <Card>
            <Card.Body>
                <Accordion.Collapse 
                    model={() => isOpen.value}
                    title="Click to reveal more information"
                    variant="arrow"
                >
                    <Text>This is the hidden content that appears when you expand the collapse.</Text>
                    <Text class="mt-2">You can put any content here including forms, images, or other components.</Text>
                </Accordion.Collapse>
                
                <Text size="sm" class="mt-4 opacity-70">
                    Collapse is {isOpen.value ? 'open' : 'closed'}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Accordion.Item (Custom Content)

For custom content in each accordion item:

```tsx
import { component, render } from 'sigx';
import { Accordion, Card, Button, Badge, Row, Col, Text } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body class="space-y-2">
                <Accordion.Item 
                    title="Premium Features" 
                    name="features" 
                    variant="plus"
                >
                    <Col gap="2">
                        <Row align="center" gap="2">
                            <Badge variant="success">✓</Badge>
                            <Text as="span">Unlimited projects</Text>
                        </Row>
                        <Row align="center" gap="2">
                            <Badge variant="success">✓</Badge>
                            <Text as="span">Priority support</Text>
                        </Row>
                        <Row align="center" gap="2">
                            <Badge variant="success">✓</Badge>
                            <Text as="span">Advanced analytics</Text>
                        </Row>
                        <Button variant="primary" size="sm" class="mt-4">
                            Upgrade Now
                        </Button>
                    </Col>
                </Accordion.Item>
                
                <Accordion.Item 
                    title="Basic Features" 
                    name="features"
                    variant="plus"
                >
                    <Col gap="2">
                        <Row align="center" gap="2">
                            <Badge variant="ghost">✓</Badge>
                            <Text as="span">Up to 5 projects</Text>
                        </Row>
                        <Row align="center" gap="2">
                            <Badge variant="ghost">✓</Badge>
                            <Text as="span">Email support</Text>
                        </Row>
                    </Col>
                </Accordion.Item>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Force Open/Close

Use `forceOpen` or `forceClose` to control the collapse state via CSS:

```tsx
import { component, render } from 'sigx';
import { Accordion, Card, Button, Row, Text } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const forceState = signal({ value: '' as '' | 'open' | 'close' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Row gap="2">
                    <Button size="sm" onClick={() => forceState.value = 'open'}>Force Open</Button>
                    <Button size="sm" onClick={() => forceState.value = 'close'}>Force Close</Button>
                    <Button size="sm" variant="ghost" onClick={() => forceState.value = ''}>Reset</Button>
                </Row>
                
                <Accordion.Collapse 
                    title="Controlled collapse"
                    variant="arrow"
                    forceOpen={forceState.value === 'open'}
                    forceClose={forceState.value === 'close'}
                >
                    <Text>This collapse can be force-opened or force-closed using the buttons above.</Text>
                </Accordion.Collapse>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## FAQ Section Example

```tsx
import { component, render } from 'sigx';
import { Accordion, Card, Heading, Input, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const active = signal({ id: '' });
    const search = signal({ text: '' });
    
    const allFaqs = [
        { id: '1', title: 'What payment methods do you accept?', content: 'We accept all major credit cards (Visa, MasterCard, American Express), PayPal, and bank transfers.' },
        { id: '2', title: 'How long does shipping take?', content: 'Standard shipping takes 5-7 business days. Express shipping is available for 2-3 day delivery.' },
        { id: '3', title: 'What is your return policy?', content: 'We offer a 30-day return policy for unused items in original packaging. Contact support to initiate a return.' },
        { id: '4', title: 'Do you offer international shipping?', content: 'Yes, we ship to over 100 countries. Shipping costs and times vary by location.' },
        { id: '5', title: 'How can I track my order?', content: 'Once shipped, you will receive an email with a tracking number. Use this on our website or the carrier site.' }
    ];
    
    const filteredFaqs = () => {
        if (!search.text) return allFaqs;
        const term = search.text.toLowerCase();
        return allFaqs.filter(faq => 
            faq.title.toLowerCase().includes(term) || 
            faq.content.toLowerCase().includes(term)
        );
    };
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Heading level={2} size="2xl">Frequently Asked Questions</Heading>
                
                <Input 
                    model={() => search.text}
                    placeholder="Search FAQs..."
                    variant="bordered"
                />
                
                {filteredFaqs().length > 0 ? (
                    <Accordion 
                        items={filteredFaqs()} 
                        model:activeId={() => active.id}
                        variant="arrow"
                        join
                    />
                ) : (
                    <Text align="center" class="py-8 opacity-70">No FAQs match your search.</Text>
                )}
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Accordion Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `Array<{ id, title, content }>` | - | Array of accordion items |
| `model:activeId` | `() => signal.property` | - | Currently open item ID |
| `variant` | `'arrow' \| 'plus' \| 'none'` | `'none'` | Icon style |
| `type` | `'radio' \| 'details'` | `'radio'` | Use radio inputs or details elements |
| `join` | `boolean` | `false` | Connect items visually |
| `class` | `string` | - | Additional CSS classes |

### Accordion.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | - | Item title |
| `name` | `string` | `'accordion'` | Radio group name (for mutual exclusivity) |
| `open` | `boolean` | `false` | Open state |
| `forceOpen` | `boolean` | `false` | Force open via CSS (collapse-open) |
| `forceClose` | `boolean` | `false` | Force close via CSS (collapse-close) |
| `variant` | `'arrow' \| 'plus' \| 'none'` | `'none'` | Icon style |
| `type` | `'radio' \| 'details'` | `'radio'` | Use radio input or details element |
| `class` | `string` | - | Additional CSS classes |

### Accordion.Collapse Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Open state binding |
| `title` | `string` | - | Collapse title |
| `variant` | `'arrow' \| 'plus' \| 'none'` | `'none'` | Icon style |
| `forceOpen` | `boolean` | `false` | Force open via CSS (collapse-open) |
| `forceClose` | `boolean` | `false` | Force close via CSS (collapse-close) |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(id: string) => void` | Fired when active item changes |
| `onToggle` | `(open: boolean) => void` | Fired when collapse toggles (Collapse only) |

## CSS Classes

The component uses these DaisyUI classes:

| Class | Description |
|-------|-------------|
| `collapse` | Main component class |
| `collapse-title` | Title part |
| `collapse-content` | Content part |
| `collapse-arrow` | Adds arrow icon |
| `collapse-plus` | Adds plus/minus icon |
| `collapse-open` | Force open state |
| `collapse-close` | Force close state |

---
url: https://sigx.dev/deploy/packages/netlify/deploying/
title: Deploying to Netlify
description: Netlify — the Frameworks API function, preferStatic routing, and the printed-not-written netlify.toml
---

# Deploying to Netlify

<p class="lede">The build emits a v2 function through Netlify's Frameworks API with the routing policy made declarative: the CDN serves files first, the catch-all function renders everything else, and your `netlify.toml` stays yours.</p>

## The generated layout

```
.netlify/v1/functions/sigx-ssr/
├── sigx-ssr.mjs        # the v2 function: bare default fetch fn + in-source config
├── <bundled entry>.js  # your entry, fully self-contained (+ any chunks)
└── package.json        # {"type":"module"}
```

The **Frameworks API** is Netlify's recommended channel for build-tool
adapters. The generated in-source config is the routing policy made
declarative:

- `path: '/*'` — the catch-all,
- `preferStatic: true` — CDN files win before the function runs,
- `nodeBundler: 'none'` — the output is final; Netlify ships the directory
  as-is.

Two details are load-bearing:

- **`index.html` is removed from the publish dir** after the build — it is the
  raw outlet template, and `preferStatic` would serve it for `/`, shadowing the
  document render. (The template is already inlined into the bundle via
  [`virtual:sigx-app`](/vite/docs/deploy-adapters#virtualsigx-app).)
- **`netlify.toml` is printed, never written** — the config is yours from its
  first character.

## The platform entry — yours, scaffolded once

The first build scaffolds `src/entry.netlify.ts` iff absent and never touches
it again. It keeps the same `export default { fetch }` shape as every sigx
platform entry — the Netlify-specific contract (bare default function +
`export const config`) lives in the generated wrapper, so your composition
stays portable:

```
static assets  →  server functions  →  document render
```

## Deploy

```bash
vite build --app -c vite.config.netlify.ts
netlify deploy --prod             # builds by default
netlify deploy --prod --no-build  # ship the prebuilt output as-is
```

## Verification posture

Structural, not emulation: CI asserts the generated layout and invokes the
function's default export directly under Node with real `Request`s (a pure
fetch handler — the `context` argument is optional sugar it never touches).
Reference wiring: `examples/resume` in the
[SignalX core repo](https://github.com/signalxjs/core)
(`vite.config.netlify.ts`, committed `entry.netlify.ts`, `netlify.toml`).

---
url: https://sigx.dev/terminal/docs/components/barchart/
title: BarChart
description: Labelled horizontal bars, all measured against one shared scale
---

# BarChart

<p class="lede">Labelled horizontal bars, all measured against <strong>one</strong> scale.</p>

## Import

```tsx
import { BarChart, commonScale } from '@sigx/terminal';
```

## Usage

```tsx
const items = [
    { label: 'p50', value: p50 },
    { label: 'p90', value: p90 },
    { label: 'p99', value: p99 },
];

<BarChart items={items} scale={commonScale(items.map((i) => i.value))} width={40} />
```

## `scale` is required, and that is the point

Sizing each bar to its own value is not a chart — it is a list of full bars. A 12µs queue wait and a 47ms turn would draw identically, and the comparison you opened the panel for is exactly what you would lose.

Derive it once with `commonScale(values)`. For data with a long tail, `commonScale(values, { clip: 0.99 })` ignores the top percentile so a single pathological outlier cannot flatten every other bar to nothing.

Percentile rows are three items; so is anything else you want compared side by side.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `BarChartItem[]` | **required** — `{ label, value, tone?, text? }`; `value: null` is "no reading", drawn as such rather than as zero |
| `scale` | `number` | **required** — the shared maximum |
| `width` | `number` | bar area in cells |
| `labelWidth` | `number` | label column width |
| `format` | `(value: number) => string` | trailing text per bar |
| `color` | `string` | theme token |
| `thresholds` | `Threshold[]` | colour by magnitude |
| `emptyText` | `string` | shown when `items` is empty |

## See also

- [Meter](/terminal/docs/components/meter) — one ratio rather than a comparison.

---
url: https://sigx.dev/server/packages/server/deployment/
title: Deployment & security
description: Serve server functions in dev, Node and edge runtimes — and the security defaults you get
---

# Deployment & security

A server function is served at `POST /_sigx/fn/<symbol>`, where `<symbol>` is a
content-hashed id derived from the function. You wire that endpoint once per
runtime; everything else — validation, error masking, the security gate — is the
same everywhere.

**The URL is percent-free.** A stable symbol spends as real path segments, so it
reads back as what you wrote:

```
POST /_sigx/fn/@acme/api/src/cart.server.ts/addToCart
POST /_sigx/fn/cart/add                        # serverFn({ id: 'cart/add' })
```

That also retires a deploy hazard: nothing in front of the app has to preserve
encoded slashes any more. A proxy or CDN that decodes or merges them no longer
mangles these routes.

## Development

Zero config. Add the `sigxServer()` plugin from `@sigx/vite/server` to your Vite
config and the dev server handles the endpoint from its middleware, loading the
real `*.server.ts` modules on demand:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import sigxServer from '@sigx/vite/server';

export default defineConfig({
  plugins: [sigx(), sigxServer()],
});
```

`sigxServer()` options: `include` (default `**/*.server.{ts,tsx}`), `exclude`,
`base` (default `/_sigx/fn`), `serverApp` (a root-relative path to your
[`createServerApp`](/server/packages/server/usage#the-app) module), and the full
endpoint posture — `origin`, `maxBodyBytes`, `maxUrlBytes`, `maxResponseBytes`,
`timeoutMs` and `onError` — so dev runs the same knobs described below.

```js
sigxServer({ serverApp: '/src/server-app.ts' })
```

Dev loads that module eagerly through the SSR module runner and re-evaluates it
after edits, so the app-wide pipeline is live in development rather than
production-only. Production builds inject one side-effect import at the top of
`virtual:sigx-server-fns`.

The endpoint-level `guard` option is gone. App `middleware` runs at the same
pre-decode slot **and** reaches in-process SSR calls, which the wire-only `guard`
never could; a genuinely wire-only concern is one line in the middleware body:

```ts
if (fn.transport !== 'wire') return;
```

## Production (Node)

The SSR build emits a registry chunk (`dist/server/sigx-server-fns.js`) that
maps every symbol to its implementation. Pass it **explicitly** to
`createServerFnHandler` from `@sigx/server/node` and mount the handler **before**
your document/SSR handler:

```js
import { createServerFnHandler } from '@sigx/server/node';
import { createRequestHandler } from '@sigx/server-renderer';

const { serverFns } = await import('./dist/server/sigx-server-fns.js');

app.use(createServerFnHandler({
  functions: serverFns,     // the build's registry chunk — never ambient
}));
app.use(createRequestHandler({ /* your document handler, unchanged */ }));
```

`createServerFnHandler` returns a connect-style `(req, res, next?)` middleware,
so it drops into Express/Connect/Polka and most Node servers.

## Edge (WinterCG)

For fetch-shaped runtimes (Workers, Deno, etc.), use `@sigx/server/server`.
Match the endpoint and hand the request off; anything else falls through to
[`createFetchHandler`](/server/packages/server-renderer/fetch-handler) — the
production document renderer for every fetch-shaped platform:

```js
import { createFetchHandler } from '@sigx/server-renderer/server';
import { handleServerFnRequest, matchesServerFn } from '@sigx/server/server';

const handler = createFetchHandler({ template, app: (url) => createApp(url) });

export default {
  async fetch(request) {
    if (matchesServerFn(request)) {
      return handleServerFnRequest(request, { resolve: (symbol) => registry[symbol] });
    }
    return handler(request);
  },
};
```

This composition — static assets → server functions → document render — is
exactly what the [deploy adapters](/deploy/docs/overview) scaffold as your
platform entry on Cloudflare, Vercel and Netlify; security defaults are
unchanged by deployment.

## Security defaults

Every server function is a public HTTP endpoint, so the runtime hardens each one
by default. You get all of this without opting in:

- **POST-only, JSON required.** Calls must be `POST` with a JSON content type.
  Because that content type is not
  [CORS-safelisted](https://fetch.spec.whatwg.org/#cors-safelisted-request-header),
  a cross-site form can't forge one — this is the CSRF gate. The endpoint never
  emits CORS headers.
- **Origin check** — default `'same-origin'`: the `Origin` header must match the
  request's origin.
- **A fail-closed pipeline** — middleware, then authentication, then the identity
  gate, all *before* the wire payload is revived. A function that declares neither
  `authorize:` nor `allowAnonymous: true`, under no configured app, denies with
  `401` rather than running open. An anonymous attacker's payload never reaches
  the codec or the validator.
- **Body & URL limits** — bodies are capped at `maxBodyBytes` (default 1 MiB)
  during the read; GET reads are capped at `maxUrlBytes` (default 8 KiB → `414`).
- **An immutable control seam** — the app config carrying `middleware`,
  `authenticate`, `authorize`, posture and `codec` is frozen when it is stamped,
  so nothing can weaken the pipeline in place at runtime. Reconfiguring means
  stamping a new app, which is an act with an owner rather than a silent
  assignment. See
  [the frozen config](/server/packages/server/api#the-config-is-frozen-once-stamped).
- **Prototype-pollution-safe parsing** on both the client and server sides.
- **Production error masking** — any non-`ServerFnError` throw becomes a generic
  `500`; the original never leaves the server.
- **Structured version-skew `404`** — a stale client calling a symbol that no
  longer exists gets a typed 404, not a silent hang.

### Request-handler options

`handleServerFnRequest` (edge) and `createServerFnHandler` (Node) take the same
`ServerFnRequestOptions`:

| Option | Default | Purpose |
|---|---|---|
| `resolve` | — | **Required.** Symbol → wrapped function. Return null/undefined for unknown symbols; the stub surfaces that as a version-skew error. A **throwing** `resolve` is masked like any other failure — it does not leak. |
| `base` | `/_sigx/fn` | The mount prefix. Everything after it *is* the symbol, so pass the same value you gave `sigxServer({ base })` — `serverFnBase` from `virtual:sigx-server-fns` is the single source of truth. Overlapping mounts throw at mount time. |
| `origin` | `'same-origin'` | `'verify-when-present'`, an allowlist, or `false`. |
| `maxBodyBytes` | 1 MiB | Body cap, enforced while reading. An error **mid-read** is a `400`, not a 500 — a truncated upload is the caller's problem. |
| `maxUrlBytes` | 8 KiB | Cap on a GET read's query string → `414`. Sits under mainstream proxies' request-line caps. |
| `maxResponseBytes` | none | Opt-in **outbound** cap — the missing analog of `maxBodyBytes`, for a function whose result is unbounded (an unfiltered query, a runaway generator). Measures actual UTF-8 bytes, never `.length`. A breach is a masked 500 through `onError`. |
| `onError` | — | Observability seam for **masked** failures. |
| `timeoutMs` | none | Upper bound on the middleware + handler. Note the timeout race never triggers request-value disposal — a 504 does not yank resources from a still-settling handler. |
| `renderBoundaries` | — | Single-flight boundary refresh; `createBoundaryRefresh` from [`@sigx/resume/server`](/server/packages/resume/api) builds one. **Required for boundary refresh to happen at all** — omitting it fails silently. |
| `authorizeBoundary` | — | Vetoes ONE boundary descriptor under the request's principal, after the deps ∩ `invalidates` gate. Strict-`true`; a deny drops that descriptor silently, a throw drops the whole refresh. The mutation is never affected. |

Every posture option above is also settable once on
[`createServerApp`](/server/packages/server/usage#the-app) and inherited by every
mount and by bare `handleServerFnRequest` calls; an explicit per-call value wins.

The symbol registry is a **null-prototype** object, so a symbol named
`__proto__` or `constructor` cannot reach anything but a real registration.

#### `onError`

Called for every **masked** failure — any non-`ServerFnError` throw from
middleware, a policy, `resolve` or the handler, timeouts included — in dev *and*
production, **before** the client response is built:

```ts
handleServerFnRequest(request, {
  resolve,
  onError(error, info, rq) {
    telemetry.report(error, { fn: info.name, url: rq.url.pathname });
  },
});
```

`ServerFnError`s are expected, client-visible failures and do **not** fire it —
this hook is for the errors the client never sees.

It is **awaited**, because an edge runtime may cancel post-response microtasks
and lose fire-and-forget telemetry. Its own throws are swallowed and never affect
the response.

#### `timeoutMs`

An upper bound on the middleware pipeline + handler, in milliseconds:

```ts
handleServerFnRequest(request, { resolve, timeoutMs: 10_000 });
```

On expiry the caller gets a `504`, `rq.abortSignal` fires — alongside client
disconnect, via `AbortSignal.any` — and `onError` receives the timeout error. So
a handler that threads `rq.abortSignal` into its own `fetch` and database calls
gets those cancelled too; one that ignores it keeps running.

For a stream, the bound covers **time to first chunk** only. Once an NDJSON
stream has started it is not bounded — cancel a long stream from the consumer
side instead.

There is no default: without `timeoutMs`, a handler runs until it settles.

> **Everything here is app-wide, not per-transport.** Configure the posture once
> on [`createServerApp`](/server/packages/server/usage#the-app) and every mount
> inherits it, in-process SSR calls included — there is no longer a wire-only
> layer to keep in sync with a definition-level one. Per-operation authorization
> stays on the function, as
> [`authorize:`](/server/packages/server/usage#writing-a-policy).

### Relaxing a default — deliberately

A few options weaken a default on purpose. Reach for them only when you mean to:

- **`cache` (a GET read)** drops the JSON content-type CSRF gate — only mark a
  function `cache` when it is genuinely side-effect-free.
- **`form: true`** gives up the JSON-CSRF layer so the function can accept a
  progressively-enhanced HTML form post; the origin check stays at full strength,
  and `input` is required.
- **`public: true`** on a read is a promise that its output depends only on its
  arguments — no cookies, auth or per-user headers.
- **`origin`** can be widened from `'same-origin'` to `'verify-when-present'` (to
  admit Origin-less programmatic clients), an explicit allowlist, or `false` for
  a deliberately public API.

## Next steps

- [Authoring server functions](/server/packages/server/usage) — the definition surface
  these endpoints serve.
- [Server renderer](/server/packages/server-renderer/overview) — pair RPC with
  streaming SSR and hydration.

---
url: https://sigx.dev/terminal/docs/components/checkbox/
title: Checkbox
description: Focusable boolean toggle with two-way model binding
---

# Checkbox

<p class="lede">A focusable boolean toggle with two-way <code>model</code> binding. Enter or Space toggles it.</p>

## Import

```tsx
import { Checkbox } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Checkbox } from '@sigx/terminal';

const App = component(() => {
    const agreed = signal(false);
    return () => (
        <box border="single" label="Terms">
            <Checkbox
                model={() => agreed}
                label="I agree"
                autofocus
                onChange={(v) => console.log('agreed:', v)}
            />
            <br />
            <text>{agreed.value ? 'Thank you!' : 'Please accept to continue.'}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `model` | `Model<boolean>` | two-way bound checked state |
| `label` | `string` | text beside the box |
| `autofocus` | `boolean` | grab focus on mount |
| `disabled` | `boolean` | non-interactive |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `boolean` | toggled |

Renders with a `◉` / `◯` marker and a focus accent bar.

## See also

- [Confirm](/terminal/docs/components/confirm) — yes/no with explicit labels.
- [MultiSelect](/terminal/docs/components/multiselect) — many checkboxes in a list.

---
url: https://sigx.dev/terminal/docs/components/gradient/
title: Gradient
description: Multi-stop colored text, optionally animated
---

# Gradient

<p class="lede">Colors text across multiple stops. Stops are theme tokens or raw hex — token-based presets re-color when the theme changes.</p>

## Import

```tsx
import { Gradient } from '@sigx/terminal';
import type { GradientPreset } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Gradient } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box>
            <Gradient text="SignalX Terminal" preset="sigx" />
            <br />
            <Gradient text="Custom stops" colors={['#ff7e5f', '#feb47b', '#ffcd94']} animate speed={1} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `text` | `string` | **required** — the text to color |
| `colors` | `string[]` | gradient stops (tokens or hex); overrides `preset` |
| `preset` | `GradientPreset` | a named preset |
| `animate` | `boolean` | sweep the gradient over time |
| `speed` | `number` | animation speed |

## Presets

`GRADIENT_PRESETS` provides: `sigx` (token-based, theme-aware), `rainbow`, `sunset`, `ocean`, `fire`. `GradientPreset` is the union of these names.

## See also

- [Shimmer](/terminal/docs/components/shimmer) — an animated highlight sweep.
- [Banner](/terminal/docs/components/banner) — large block-font text.

---
url: https://sigx.dev/terminal/docs/components/keyhints/
title: KeyHints
description: A single-line key-shortcut footer
---

# KeyHints

<p class="lede">A one-line shortcut footer — accent keys, dim labels, faint separators, e.g. <code>r reload · d devices · q quit</code>. Deliberately lighter than <a href="/terminal/docs/components/statusbar">StatusBar</a>: no chips, no fill.</p>

## Import

```tsx
import { KeyHints } from '@sigx/terminal';
import type { KeyHint } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, KeyHints } from '@sigx/terminal';
import type { KeyHint } from '@sigx/terminal';

const hints: KeyHint[] = [
    { key: 'r', label: 'reload' },
    { key: 'd', label: 'devices' },
    { key: 'q', label: 'quit' },
];

const App = component(() => {
    return () => (
        <box>
            <KeyHints hints={hints} separator=" · " />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `hints` | `KeyHint[]` | **required** — the shortcuts |
| `separator` | `string` | between hints |

## KeyHint

```ts
interface KeyHint {
    key: string;
    label: string;
}
```

## See also

- [StatusBar](/terminal/docs/components/statusbar) — a heavier chip footer.

---
url: https://sigx.dev/terminal/docs/components/logpanel/
title: LogPanel
description: A bounded log tail with bar, plain or panel chrome
---

# LogPanel

<p class="lede">A bounded tail of recent log lines — the non-scrolling companion to <a href="/terminal/docs/components/logview">LogView</a>. Shows the last <code>height</code> lines of a <code>LogStore</code> (or static <code>lines</code>).</p>

## Import

```tsx
import { LogPanel, createLogStore } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, onMounted, LogPanel, createLogStore } from '@sigx/terminal';

const App = component(() => {
    const log = createLogStore();
    onMounted(() => {
        let n = 0;
        const t = setInterval(() => { log.push(`event ${++n}\n`); }, 300);
        return () => clearInterval(t);
    });
    return () => (
        <box>
            <LogPanel store={log} height={5} title="recent" variant="panel" color="dim" />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `store` | `LogStore` | the reactive source |
| `lines` | `string[]` | static lines (alternative to `store`) |
| `height` | `number` | number of tail lines to show |
| `width` | `number` | wrap width |
| `title` | `string` | caption |
| `variant` | `'bar' \| 'plain' \| 'panel'` | chrome style |
| `color` | token \| `#hex` | text color |

## See also

- [LogView](/terminal/docs/components/logview) — a scrollable viewport and the `LogStore` API.
- [TaskList](/terminal/docs/components/tasklist) — task status with a streamed tail.

---
url: https://sigx.dev/terminal/docs/components/pixelart/
title: PixelArt
description: Palette-mapped pixel grids drawn with terminal cells
---

# PixelArt

<p class="lede">Draws a grid of colored cells from <code>rows</code> of single-character keys mapped through a <code>palette</code> — a logo or sprite as terminal pixels.</p>

## Import

```tsx
import { PixelArt } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, PixelArt } from '@sigx/terminal';

const rows = [
    '.rrr.',
    'rrrrr',
    '.ggg.',
    '..b..',
];

const palette = { r: '#e0606a', g: '#5fd17f', b: '#6ea8ff' };

const App = component(() => {
    return () => (
        <box border="single" label="Logo">
            <PixelArt rows={rows} palette={palette} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `rows` | `string[]` | **required** — rows of palette keys; `.` / space is transparent |
| `palette` | `Record<string, string>` | **required** — key → color (token or hex) |

`renderPixelArt(rows, palette)` is the headless renderer that returns the ANSI lines.

## See also

- [Banner](/terminal/docs/components/banner) — block-font headings.

---
url: https://sigx.dev/terminal/docs/components/tasklist/
title: TaskList
description: A build-pipeline status list with per-task status glyphs
---

# TaskList

<p class="lede">A build-pipeline status list: one row per task with a status glyph (pending <code>◌</code>, running spinner, <code>✔</code>/<code>✖</code>, skipped <code>−</code>). Mutate the <code>tasks</code> array in place — statuses are reactive.</p>

## Import

```tsx
import { TaskList } from '@sigx/terminal';
import type { TaskItem, TaskStatus } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, onMounted, TaskList } from '@sigx/terminal';
import type { TaskItem } from '@sigx/terminal';

const App = component(() => {
    const tasks = signal<TaskItem[]>([
        { id: 'install', label: 'Install dependencies', status: 'running' },
        { id: 'build', label: 'Build', status: 'pending' },
        { id: 'test', label: 'Test', status: 'pending' },
    ]);

    onMounted(() => {
        setTimeout(() => {
            tasks.value[0].status = 'success';
            tasks.value[0].detail = '1.2s';
            tasks.value[1].status = 'running';
        }, 1500);
    });

    return () => (
        <box border="single" label="Pipeline">
            <TaskList tasks={tasks.value} variant="tree" />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `tasks` | `TaskItem[]` | **required** — the rows |
| `variant` | `'plain' \| 'tree'` | flat list or `├─`/`└─` guides |
| `log` | `LogStore` | stream a log tail under the running task |
| `logHeight` | `number` | tail height when `log` is set |

Pass a [`LogStore`](/terminal/docs/components/logview) via `log` to show a live tail of output beneath the running task.

## Types

```ts
type TaskStatus = 'pending' | 'running' | 'success' | 'fail' | 'skipped';

interface TaskItem {
    id: string;
    label: string;
    status: TaskStatus;
    detail?: string; // dimmed suffix, e.g. a duration
}
```

## See also

- [LogView](/terminal/docs/components/logview) — a scrollable log viewport and the `LogStore`.
- [Spinner](/terminal/docs/components/spinner) — the running-task glyph.

---
url: https://sigx.dev/terminal/packages/terminal-ui/api/
title: API reference
description: API reference for @sigx/terminal-ui — every export of the SignalX Terminal Terminal UI package.
---

# API reference

<p class="lede">Exports of `@sigx/terminal-ui` .</p>

## Exports

Every component is documented in the umbrella's
[component gallery](/terminal/docs/components/), and the shared surface (themes,
prompts) in the umbrella's [API reference](/terminal/docs/api/) — the umbrella
re-exports this package.

See the package source for the complete typed surface.

---
url: https://sigx.dev/terminal/docs/components/textarea/
title: TextArea
description: Growing multi-line text editor on the headless text buffer
---

# TextArea

<p class="lede">A focusable multi-line editor that grows with its content, built on the headless <code>textBuffer</code> layout engine. Word-wraps to a width and windows the visible rows so the cursor stays in view.</p>

## Import

```tsx
import { TextArea } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, TextArea } from '@sigx/terminal';

const App = component(() => {
    const body = signal('');
    return () => (
        <box border="rounded" label="Message">
            <TextArea
                model={() => body}
                placeholder="Write a message…"
                width={60}
                maxRows={8}
                autofocus
                onSubmit={(v) => console.log('sent:', v)}
            />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `model` | `Model<string>` | two-way bound multi-line value |
| `placeholder` | `string` | shown when empty |
| `promptGlyph` | `string` | per-line prompt glyph |
| `width` | `number` | wrap width in columns |
| `maxRows` | `number` | max visible rows before the view windows |
| `autofocus` | `boolean` | grab focus on mount |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `input` | `string` | the value changes |
| `submit` | `string` | a submit keystroke |

Editing supports arrow movement, line start/end and word wrapping. A trailing backslash continues a line: it is stripped and a newline inserted. Several "Shift/Ctrl+Enter" encodings insert a newline (`Ctrl+J`, `ESC`+Enter, and the CSI-u sequences); plain Enter submits where the terminal can distinguish it. Paste chunks are accepted, with control bytes stripped.

## See also

- [Input](/terminal/docs/components/input) — single-line input.
- [SuggestionList](/terminal/docs/components/suggestionlist) — pair with a TextArea for completions.

---
url: https://sigx.dev/actors/packages/actors-redis/api/
title: API reference
description: Exports of @sigx/actors-redis — redisCluster, redisMembership, redisDirectory, redisStorage — and the Redis key layout
---

# API reference

<p class="lede">Exports of `@sigx/actors-redis` .</p>

## `redisCluster(options)`

Returns `ClusterProviders` — membership and directory together. The common case.

```ts
cluster({ providers: redisCluster({ client }), advertise, secret });
```

```ts
interface RedisClusterOptions {
    client?: RedisClient;      // an ioredis instance
    url?: string;              // …or a URL to construct one
    namespace?: string;        // 'sigx'
    heartbeatMs?: number;      // 5000
    ttlMs?: number;            // 15000
    pollMs?: number;           // 5000
}
```

Call it **once per host** — each call returns that host's own membership handle.

## `redisMembership(client, options?)`

Membership alone: TTL heartbeats, a polled view with pub/sub push, and self-fencing when this
host cannot renew past `ttlMs`.

## `redisDirectory(client, options?)`

The single-activation claim directory. Options: `{ namespace?: string }`.

Pairs with any membership provider — notably
[`k8sMembership()`](/actors/packages/actors-k8s/overview).

## `redisStorage(options)`

An [`ActorStorage`](/actors/docs/storage) with etag compare-and-set.

```ts
defineActorApp({ storage: redisStorage({ client, namespace: 'sigx' }) });
```

```ts
interface RedisStorageOptions {
    client?: RedisClient;
    url?: string;
    namespace?: string;        // 'sigx' — share it with the cluster providers
}
```

Etags are client-minted UUIDs. `save` and `clear` compare-and-set atomically in Redis via Lua,
registered as `EVALSHA` commands because `save` is the hot path, and throw the branded
`ActorStorageConflict` on mismatch — which the runtime turns into discard-and-reload.

## Types

`RedisClient` (the ioredis `Redis` type), `RedisClusterOptions`, `RedisStorageOptions`.

## Key layout

```
{ns}:host:{hostId}    HASH {d: descriptor JSON}   PX ttlMs, renewed each beat
{ns}:hosts            SET of hostIds              lazily pruned
{ns}:mver             INCR'd version counter      cheap view-poll compare
{ns}:dir:{actorId}    "hostId\nactivationId"      no TTL (validity = owner liveness)
{ns}:membership       pub/sub channel             change push (poll = fallback)
{ns}:st:{type}\x00{key}   HASH {e: etag, s: state JSON}
```

The storage record key joins actor type and key with a **NUL byte** — the same `actorId` shape
the directory uses. Redis keys are binary-safe, and a NUL renders invisibly in
`redis-cli SCAN` output.

Directory entries carry no TTL: their validity *is* the owner's liveness, and entries for dead
hosts are evicted lazily on lookup.

Operations used: the directory claim is `SET NX GET`; release and evict are Lua
compare-and-delete; `evictHost` is a `SCAN` plus an owner-prefix delete.

## Next steps

- [Overview](/actors/packages/actors-redis/overview) — what it is for.
- [Installation](/actors/packages/actors-redis/installation) — options and tuning.
- [Storage](/actors/docs/storage) — the seam this implements.

---
url: https://sigx.dev/core/packages/cache/installation/
title: Installation
description: Install @sigx/cache and register cachePlugin() on your app
---

# Installation

<p class="lede">Add <code>@sigx/cache</code>  and register its plugin. Your <code>useData</code> / <code>useAction</code> call sites don't change.</p>

## Install the package

```bash
pnpm add @sigx/cache
```

Its only dependencies are `@sigx/runtime-core` and `@sigx/reactivity` — the two packages any SignalX renderer already builds on (web apps get them through the `sigx` umbrella). It never pulls in a renderer of its own, which is what makes it [portable](/core/packages/cache/usage#renderer-portability).

## Register the plugin

Install `cachePlugin()` on the app before you mount. This is the one line that switches `useData`/`useAction` from core's default async engine to the caching one:

```ts
import { createApp } from 'sigx';
import { cachePlugin } from '@sigx/cache';
import { App } from './App';

const app = createApp(App);
app.use(cachePlugin());
app.mount('#app');
```

The defaults you pass here apply app-wide; every option is optional:

```ts
app.use(cachePlugin({
    staleTime: 30_000,   // reads are fresh for 30s before revalidating
    gcTime: 300_000,     // keep entries 5min after the last consumer leaves (the default)
}));
```

## The `cache` option lights up

Once the package is a dependency, TypeScript adds the `cache` option to `useData` and `useAction` — it's a module augmentation of core's open option interfaces, so it appears with no extra imports:

```tsx
const user = useData('user', fetchUser, {
    cache: { staleTime: 60_000 },
});
```

If you see the `cache` option flagged as unknown, the package isn't resolving — check it's installed and that your editor has picked up the new types.

## Verify

A quick check that the plugin is wired up: a cached read should survive an unmount-and-remount within `gcTime` instead of refetching. The [Usage](/core/packages/cache/usage) guide walks through each policy with a runnable shape.

## Next steps

- [Usage](/core/packages/cache/usage) — the policy options in practice
- [API reference](/core/packages/cache/api) — every export and option

---
url: https://sigx.dev/core/packages/runtime-core/usage/
title: Usage
description: Using Runtime Core in a SignalX app — renderer-agnostic component model patterns and examples with @sigx/runtime-core.
---

# Using Runtime Core

<p class="lede">Renderer-agnostic component model — the essentials.</p>

`@sigx/runtime-core` is the platform-agnostic heart of the framework: the component system, the JSX runtime, lifecycle hooks, dependency injection, control-flow helpers, and the reconciler base. It has no DOM dependency of its own — a render target (such as the DOM renderer) plugs in via the `mount` function.

Most applications should install the `sigx` meta-package instead, which bundles this core with the DOM renderer and `@sigx/reactivity` so everything is wired up for you. Install `@sigx/runtime-core` directly when you are building a custom renderer or need the component primitives in isolation.

```bash
pnpm add @sigx/runtime-core
```

To make TSX compile against this runtime, point your `tsconfig.json` at the package as the JSX import source:

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@sigx/runtime-core"
  }
}
```

## Defining a component

A component is a `setup` function that runs once and returns a render (view) function. Put reactive reads inside the returned function so re-renders track them. The `setup` receives a context object with `props`, `slots`, `emit`, `signal`, `el`, and the lifecycle registrars.

```tsx
import { component, signal, onMounted, onUnmounted } from '@sigx/runtime-core';

const Timer = component(() => {
  const elapsed = signal(0);
  let interval: ReturnType<typeof setInterval>;

  onMounted(() => {
    interval = setInterval(() => elapsed.value++, 1000);
  });
  onUnmounted(() => clearInterval(interval));

  return () => <span>Elapsed: {elapsed.value}s</span>;
});
```

`onMounted`, `onUnmounted`, `onCreated`, and `onUpdated` must be called synchronously during `setup`. Called outside a component they simply warn and no-op. `onUnmounted` is your cleanup hook — clear timers and unsubscribe there.

## Typing props, events, and slots

Type a component through the `Define` namespace and combine members with the `&` intersection. The render context destructures `props` (a reactive accessor), `slots` (always carries `.default()`), and `emit`.

```tsx
import { component, type Define } from '@sigx/runtime-core';

type ButtonProps =
  & Define.Prop<'variant', 'primary' | 'secondary'>
  & Define.Prop<'disabled', boolean>
  & Define.Event<'click', MouseEvent>
  & Define.Slot<'default'>;

const Button = component<ButtonProps>(({ props, slots, emit }) => {
  return () => (
    <button
      class={props.variant}
      disabled={props.disabled}
      onClick={(e: MouseEvent) => emit('click', e)}
    >
      {slots.default?.()}
    </button>
  );
});
```

`Define.Prop`, `Define.Event`, `Define.Model`, `Define.Slot`, and `Define.Expose` are the discoverable way to describe a component's surface.

## Creating and mounting an app

`defineApp` builds a renderer-agnostic application instance with a chainable API. Install plugins with `use`, register directives with `directive`, and provide app-wide services with `defineProvide`, then call `mount` with a render target.

```tsx
import { defineApp, defineInjectable } from '@sigx/runtime-core';

const useApiConfig = defineInjectable(() => ({ baseUrl: '' }));

const app = defineApp(<App />);

const config = app.defineProvide(useApiConfig);
config.baseUrl = 'https://api.example.com';

app
  .use(myPlugin)
  .mount(document.getElementById('app'));
```

When you use the `sigx` meta-package, `mount` already has the DOM renderer wired in. With `@sigx/runtime-core` alone, pass a `MountFn` as the second argument to `mount` so the core knows how to render into your target.

## Dependency injection

`defineInjectable` returns a callable token. Calling it resolves the nearest instance provided up the component tree, or lazily creates a global singleton if none was provided. Provide a fresh instance for a subtree with `defineProvide` during `setup`.

```tsx
import { component, defineInjectable, defineProvide } from '@sigx/runtime-core';

const useStore = defineInjectable(() => ({ count: signal(0) }));

const Provider = component(({ slots }) => {
  defineProvide(useStore); // new instance for descendants
  return () => <>{slots.default?.()}</>;
});

const Consumer = component(() => {
  const store = useStore(); // nearest provided instance
  return () => <span>{store.count.value}</span>;
});
```

`defineProvide` must run during `setup` — calling it elsewhere throws `SIGX200`. Because an unprovided injectable falls back to a process-wide global singleton, prefer explicit `defineProvide` in SSR so state does not leak across requests.

For services that need managed disposal and a real lifetime, use `defineFactory(setup, lifetime)` with a `Lifetime` string literal: `'singleton'` (one instance per app, disposed on `app.unmount()`), `'scoped'` (nearest `defineProvide` in the tree, falling back to the app instance), or `'transient'` (a new instance per call, disposed with the calling component). This is the machinery `@sigx/store`'s `defineStore` lifetimes are built on.

## Messaging with topics

`createTopic<T>()` gives you a small in-memory pub/sub primitive. Publishing is error-isolated (a throwing subscriber is logged and never breaks the publisher or its siblings), subscribing inside a component auto-unsubscribes on unmount, and subscribing to a destroyed topic throws.

```ts
import { createTopic } from '@sigx/runtime-core';

const userLoggedIn = createTopic<{ id: string }>({
  namespace: 'auth', name: 'loggedIn',   // tooling metadata (devtools discovery)
  onActivate: () => startPolling(),       // first subscriber arrived
  onDeactivate: () => stopPolling(),      // last subscriber left
});

const sub = userLoggedIn.subscribe(user => console.log(user.id));
userLoggedIn.publish({ id: 'u1' });
sub.unsubscribe();
```

The `onActivate` / `onDeactivate` hooks fire on the 0 → 1 and → 0 subscriber transitions, so producers can pay for upstream work only while someone is listening. `topic.hasSubscribers` lets a publisher skip building payloads nobody will see.

For a typed set of related events, `createTopicGroup<EventMap>({ namespace })` creates topics lazily per event key and destroys them together:

```ts
import { createTopicGroup } from '@sigx/runtime-core';

const events = createTopicGroup<{ saved: { at: number }; cleared: void }>({ namespace: 'editor' });
events.topics.saved.subscribe(({ at }) => console.log('saved at', at));
events.topics.saved.publish({ at: Date.now() });
events.destroy();
```

Topics created with a `namespace` also register in the inspection registry at `@sigx/runtime-core/inspect` (`getTopic`, `listTopics`, `subscribeTopics`, `onTopicCreated`) — a string-addressed, `Topic<unknown>`-typed surface meant for devtools and diagnostics. Typed code should hold and share `Topic<T>` references; the strings are tooling metadata, not an app-level lookup mechanism.

## Two-way binding with models

A `Model<T>` unifies reading (`.value` get), writing (`.value` set routes through the update handler), and forwarding (`.binding`). At the JSX level the runtime accepts a getter, a `[obj, 'key']` tuple, or a forwarded model on the `model` prop; named models use `model:name` and emit `update:name`.

```tsx
import { component, createModel, type Define } from '@sigx/runtime-core';

type FieldProps = Define.Model<string>;

const Field = component<FieldProps>(({ props }) => {
  return () => <input value={props.model?.value} />;
});

// In a parent, build a model from a [source, key] tuple:
const state = signal({ name: '' });
const nameModel = createModel<string>([state, 'name'], (v) => {
  state.name = v;
});
```

Use `createModelFromBinding` when you need to forward a full `[obj, key, handler]` binding tuple down to a child, and `isModel` to detect a model at runtime.

## Lazy loading with Defer

`lazy` wraps a dynamic-import loader into a component loaded on first render. While the chunk loads the wrapper renders null; wrap it in `<Defer>` to show a fallback until every lazy chunk beneath it resolves. The lazy factory also exposes `preload()` so you can warm the chunk ahead of time.

```tsx
import { lazy, Defer } from '@sigx/runtime-core';

const HeavyChart = lazy(() => import('./HeavyChart'));

const Dashboard = component(() => {
  return () => (
    <Defer fallback={<span>Loading chart…</span>}>
      <HeavyChart />
    </Defer>
  );
});

// Warm the chunk on hover, before it is needed:
// onMouseEnter={() => HeavyChart.preload()}
```

`<Defer>` covers **chunk** loading only — a pending `useData` read renders through its own component's `match()`, not a wrapper. A lazy chunk that fails to load throws from render and routes to the nearest [`errorScope`](/core/docs/error-handling), then `app.onError`.

## Loading data

For async data, reach for the value-first primitives — `useData` for reads and `useAction` for writes. `useData(key, fetcher)` auto-runs and returns a reactive `AsyncState` you render through `match()`; the fetcher receives the resolved key and an `AbortSignal`.

```tsx
import { component, useData } from '@sigx/runtime-core';

const Editor = component(() => {
  const libs = useData('editor:libs', async (key, { signal }) => ({
    EditorView: (await import('@codemirror/view')).EditorView,
  }));

  return () => libs.match({
    pending: () => <span>Loading…</span>,
    error: (e) => <span>Failed: {e.message}</span>,
    ready: () => <div>Editor ready</div>,
  });
});
```

Every read has a **key** — it is the reactive trigger, the cache / SSR identity, and the fetcher's input. A static string key is SSR-transferable: it runs during SSR, serializes its value under the key, restores on hydration without refetching, and dedupes across components sharing the key. Pass a getter for a reactive key (`() => ['user', id]`), or `{ server: false }` for a client-only read. `useAction(fn)` is the manual write counterpart (trigger with `.run(input)`, resolves a settled `RunResult`), and `useStream(key, source)` streams progressive text (LLM tokens). See the [Data Loading](/core/docs/data-loading) guide for the full story.

## Handling errors

Call `errorScope` during setup to scope the calling component's own subtree — it is a function, not a wrapper component. Its `fallback` receives the error and a `retry()`, where `retry` is a real remount (the subtree unmounts and re-runs setup from a clean slate).

```tsx
import { component, errorScope } from '@sigx/runtime-core';

const Safe = component(() => {
  errorScope({
    fallback: (error, retry) => (
      <div>
        {error.message}
        <button onClick={retry}>Retry</button>
      </div>
    ),
  });

  return () => <RiskyComponent />;
});
```

`errorScope` catches setup / render / reactive-re-render throws in the subtree, plus data errors bubbled by a `match()` with no `error` arm. It does **not** catch fetcher rejections (those are values on `.error`) or DOM event-handler throws — those route to the app-wide `app.onError(fn)` handler, which is also the last stop for anything no scope took. See [Error handling](/core/docs/error-handling) for the full model.

Runtime errors are instances of `SigxError`, each carrying a stable `code` (such as `SIGX102` for an async setup attempted on the client). Catch `SigxError` and branch on `.code` for targeted handling.

## Directives

`defineDirective` marks a directive definition so it can be applied through the `use:name` prop syntax. Each lifecycle hook receives the element and a binding with the current `value`.

```tsx
import { defineDirective } from '@sigx/runtime-core';

const tooltip = defineDirective<string>({
  mounted(el, { value }) { el.title = value; },
  updated(el, { value }) { el.title = value; },
  unmounted(el) { el.title = ''; },
});

// Usage: <div use:tooltip="Helpful hint" />
```

## Next steps

See the [API reference](/core/packages/runtime-core/api) for the complete typed surface, or the [Installation](/core/packages/runtime-core/installation) guide for project setup.

---
url: https://sigx.dev/daisyui/docs/components/checkbox/
title: Checkbox
description: Checkboxes are used to select or deselect a value
---

# Checkbox

Checkbox is used to select or deselect a value.

## Import

```tsx
import { Checkbox } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Checkbox } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Checkbox checked />
    );
});

render(<Demo />, "#sandbox");
```

## With Label

```tsx
import { component, render } from 'sigx';
import { Checkbox, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Checkbox label="Remember me" />
            <Checkbox label="Accept terms" checked />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Checkbox, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Checkbox checked />
            <Checkbox color="primary" checked />
            <Checkbox color="secondary" checked />
            <Checkbox color="accent" checked />
            <Checkbox color="neutral" checked />
            <Checkbox color="info" checked />
            <Checkbox color="success" checked />
            <Checkbox color="warning" checked />
            <Checkbox color="error" checked />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Checkbox, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" items="center" wrap>
            <Checkbox size="xs" checked />
            <Checkbox size="sm" checked />
            <Checkbox size="md" checked />
            <Checkbox size="lg" checked />
            <Checkbox size="xl" checked />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled

```tsx
import { component, render } from 'sigx';
import { Checkbox, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <Checkbox disabled />
            <Checkbox disabled checked />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Indeterminate

```tsx
import { component, render } from 'sigx';
import { Checkbox } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Checkbox indeterminate />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `Signal<boolean>` | - | Two-way binding for checked state |
| `name` | `string` | - | Name attribute for form submission |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Checkbox size |
| `color` | `"primary" \| "secondary" \| "accent" \| "neutral" \| "info" \| "success" \| "warning" \| "error"` | - | Checkbox color |
| `disabled` | `boolean` | `false` | Disabled state |
| `indeterminate` | `boolean` | `false` | Indeterminate state |
| `label` | `string` | - | Label text displayed next to checkbox |
| `class` | `string` | - | Additional CSS classes |
| `onChange` | `(checked: boolean) => void` | - | Change event handler |

---
url: https://sigx.dev/daisyui/docs/components/dropdown/
title: Dropdown
description: Dropdown component for action menus and context menus
---

# Dropdown

Dropdown component for creating action menus, context menus, and select-like interfaces.

## Import

```tsx
import { Dropdown } from '@sigx/daisyui';
```

## Basic Dropdown

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body class="py-12">
                <Row justify="center">
                    <Dropdown
                        slots={{
                            trigger: () => <Button>Click me</Button>
                        }}
                    >
                        <Menu.Item><Text as="span">Item 1</Text></Menu.Item>
                        <Menu.Item><Text as="span">Item 2</Text></Menu.Item>
                        <Menu.Item><Text as="span">Item 3</Text></Menu.Item>
                    </Dropdown>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Dropdown Positions

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const positions = ['bottom', 'top', 'left', 'right'] as const;
    
    return () => (
        <Card>
            <Card.Body class="py-12">
                <Row wrap justify="center" gap="4">
                    {positions.map(pos => (
                        <Dropdown 
                            position={pos}
                            width="40"
                            slots={{
                                trigger: () => <Button>{pos}</Button>
                            }}
                        >
                            <Menu.Item><Text as="span">Option 1</Text></Menu.Item>
                            <Menu.Item><Text as="span">Option 2</Text></Menu.Item>
                        </Dropdown>
                    ))}
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Dropdown End Alignment

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body class="py-12">
                <Row justify="center" gap="4">
                    <Dropdown
                        width="40"
                        slots={{
                            trigger: () => <Button>Start (default)</Button>
                        }}
                    >
                        <Menu.Item><Text as="span">Option 1</Text></Menu.Item>
                        <Menu.Item><Text as="span">Option 2</Text></Menu.Item>
                    </Dropdown>
                    
                    <Dropdown 
                        position="end"
                        width="40"
                        slots={{
                            trigger: () => <Button>End aligned</Button>
                        }}
                    >
                        <Menu.Item><Text as="span">Option 1</Text></Menu.Item>
                        <Menu.Item><Text as="span">Option 2</Text></Menu.Item>
                    </Dropdown>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hover Dropdown

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body class="py-12">
                <Row justify="center">
                    <Dropdown 
                        hover
                        width="52"
                        slots={{
                            trigger: () => <Button>Hover me</Button>
                        }}
                    >
                        <Menu.Item><Text as="span">Item 1</Text></Menu.Item>
                        <Menu.Item><Text as="span">Item 2</Text></Menu.Item>
                        <Menu.Item><Text as="span">Item 3</Text></Menu.Item>
                    </Dropdown>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## User Menu Example

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Badge, Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body class="py-12">
                <Row justify="center">
                    <Dropdown 
                        position="end"
                        width="56"
                        slots={{
                            trigger: () => (
                                <Button variant="ghost" shape="circle">
                                    <Text as="span" weight="bold" class="w-10 h-10 rounded-full bg-primary text-primary-content inline-flex items-center justify-center">
                                        JD
                                    </Text>
                                </Button>
                            )
                        }}
                    >
                        <Col gap="1" class="px-4 py-3 border-b border-base-300">
                            <Text weight="bold">John Doe</Text>
                            <Text size="sm" color="muted">john@example.com</Text>
                        </Col>
                        <Menu.Item>
                            <Row justify="between" align="center" class="w-full">
                                <Text as="span">Profile</Text>
                                <Badge variant="primary" size="sm">New</Badge>
                            </Row>
                        </Menu.Item>
                        <Menu.Item><Text as="span">Settings</Text></Menu.Item>
                        <Menu.Item><Text as="span">Billing</Text></Menu.Item>
                        <Col class="border-t border-base-300 mt-2 pt-2">
                            <Menu.Item><Text as="span" color="error">Logout</Text></Menu.Item>
                        </Col>
                    </Dropdown>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Navbar Dropdown

```tsx
import { component, render } from 'sigx';
import { Dropdown, Button, Menu, Card, Navbar, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Navbar
                background="base-200" rounded
                slots={{
                    start: () => <Text as="span" size="xl" weight="bold">App</Text>,
                    end: () => (
                        <Row gap="2">
                            <Dropdown 
                                position="end"
                                width="48" menuClass="mt-2"
                                slots={{
                                    trigger: () => <Button variant="ghost">Products</Button>
                                }}
                            >
                                <Menu.Item><Text as="span">Electronics</Text></Menu.Item>
                                <Menu.Item><Text as="span">Clothing</Text></Menu.Item>
                                <Menu.Item><Text as="span">Home & Garden</Text></Menu.Item>
                            </Dropdown>
                            
                            <Dropdown 
                                position="end"
                                width="48" menuClass="mt-2"
                                slots={{
                                    trigger: () => <Button variant="ghost">About</Button>
                                }}
                            >
                                <Menu.Item><Text as="span">Company</Text></Menu.Item>
                                <Menu.Item><Text as="span">Team</Text></Menu.Item>
                                <Menu.Item><Text as="span">Contact</Text></Menu.Item>
                            </Dropdown>
                        </Row>
                    ),
                }}
            />
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Context Menu Example

```tsx
import { component, render } from 'sigx';
import { Dropdown, Menu, Card, Badge, Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [
        { id: 1, name: 'Document 1.pdf', type: 'PDF' },
        { id: 2, name: 'Image.png', type: 'Image' },
        { id: 3, name: 'Report.xlsx', type: 'Excel' }
    ];
    
    return () => (
        <Card>
            <Card.Body>
                <Col gap="2">
                    <Text size="sm" color="muted" margin={{ bottom: "4" }}>Hover on items to see menu:</Text>
                    
                    {items.map(item => (
                        <Dropdown 
                            hover
                            width="48"
                            slots={{
                                trigger: () => (
                                    <Row align="center" gap="3" class="p-3 bg-base-200 rounded-lg cursor-pointer hover:bg-base-300 w-full">
                                        <Text as="span" size="2xl">📄</Text>
                                        <Col gap="1" class="flex-1">
                                            <Text as="span" weight="medium">{item.name}</Text>
                                            <Badge variant="ghost" size="sm">{item.type}</Badge>
                                        </Col>
                                    </Row>
                                )
                            }}
                        >
                            <Menu.Item><Text as="span">Open</Text></Menu.Item>
                            <Menu.Item><Text as="span">Download</Text></Menu.Item>
                            <Menu.Item><Text as="span">Rename</Text></Menu.Item>
                            <Menu.Item><Text as="span">Share</Text></Menu.Item>
                            <Col class="border-t border-base-300 mt-1 pt-1">
                                <Menu.Item><Text as="span" color="error">Delete</Text></Menu.Item>
                            </Col>
                        </Dropdown>
                    ))}
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `'end' \| 'top' \| 'bottom' \| 'left' \| 'right'` | - | Dropdown position |
| `hover` | `boolean` | `false` | Open on hover instead of click |
| `menuClass` | `string` | - | Additional CSS classes for the content panel |
| `background` | `BackgroundColor` | - | Content panel background (overrides default `bg-base-100`) |
| `rounded` | `RadiusValue \| boolean` | - | Content panel rounding (default `rounded-box`) |
| `width` | `SizeValue` | - | Content panel width — Tailwind step (`"52"`) or unitful value (`"560px"`) |
| `padding` | `Spacing` | - | Content panel padding (overrides default `p-2`) |
| `class` | `string` | - | Additional CSS classes for the container (root) |

## Slots

| Slot | Description |
|------|-------------|
| `trigger` | The element that opens the dropdown (can be any component) |
| `default` | Dropdown menu content (typically Menu.Item components) |

---
url: https://sigx.dev/daisyui/docs/components/carousel/
title: Carousel
description: Carousel component for sliding content
---

# Carousel

Carousel for displaying sliding content with navigation.

## Import

```tsx
import { Carousel, CarouselItem } from '@sigx/daisyui';
```

## Basic Carousel

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const images = [
        'https://picsum.photos/400/200?random=1',
        'https://picsum.photos/400/200?random=2',
        'https://picsum.photos/400/200?random=3',
        'https://picsum.photos/400/200?random=4'
    ];
    
    return () => (
        <Card>
            <Carousel class="rounded-box">
                {images.map((src, i) => (
                    <CarouselItem id={`slide${i}`}>
                        <img src={src} class="w-full" alt={`Slide ${i + 1}`} />
                    </CarouselItem>
                ))}
            </Carousel>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Carousel with Navigation

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Button, Row, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const state = signal({ currentSlide: 0 });
    const slides = [1, 2, 3, 4, 5];
    
    const goTo = (index) => {
        state.currentSlide = index;
        document.getElementById(`item${index}`).scrollIntoView({ behavior: 'smooth', inline: 'start' });
    };
    
    const next = () => goTo((state.currentSlide + 1) % slides.length);
    const prev = () => goTo((state.currentSlide - 1 + slides.length) % slides.length);
    
    return () => (
        <Card class="p-4 space-y-4">
            <Carousel class="rounded-box">
                {slides.map((num, i) => (
                    <CarouselItem id={`item${i}`} class="w-full">
                        <Card class="w-full h-48 bg-base-200">
                            <Card.Body class="items-center justify-center">
                                <Heading level={3} size="3xl">Slide {num}</Heading>
                            </Card.Body>
                        </Card>
                    </CarouselItem>
                ))}
            </Carousel>
            
                <Row justify="between" align="center">
                    <Button variant="circle" onClick={prev}>❮</Button>
                    <Row gap="2">
                        {slides.map((_, i) => (
                            <Button
                                size="xs"
                                variant={state.currentSlide === i ? 'primary' : 'ghost'}
                                onClick={() => goTo(i)}
                            >
                                {i + 1}
                            </Button>
                        ))}
                    </Row>
                    <Button variant="circle" onClick={next}>❯</Button>
            </Row>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Full-bleed Carousel

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    const cards = [
        { title: 'Card 1', color: 'bg-primary text-primary-content' },
        { title: 'Card 2', color: 'bg-secondary text-secondary-content' },
        { title: 'Card 3', color: 'bg-accent text-accent-content' },
        { title: 'Card 4', color: 'bg-neutral text-neutral-content' }
    ];
    
    return () => (
        <Card>
            <Carousel variant="full" class="w-full">
                {cards.map((card, i) => (
                    <CarouselItem id={`fb${i}`} class="w-full">
                        <Card class={`w-full h-64 ${card.color}`}>
                            <Card.Body class="items-center justify-center">
                                <Heading level={2} size="4xl">{card.title}</Heading>
                            </Card.Body>
                        </Card>
                    </CarouselItem>
                ))}
            </Carousel>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Carousel with Half-width Items

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Text, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    const products = [
        { name: 'Product 1', price: '$29', img: 'https://picsum.photos/200/200?random=10' },
        { name: 'Product 2', price: '$49', img: 'https://picsum.photos/200/200?random=11' },
        { name: 'Product 3', price: '$19', img: 'https://picsum.photos/200/200?random=12' },
        { name: 'Product 4', price: '$39', img: 'https://picsum.photos/200/200?random=13' },
        { name: 'Product 5', price: '$59', img: 'https://picsum.photos/200/200?random=14' },
        { name: 'Product 6', price: '$25', img: 'https://picsum.photos/200/200?random=15' }
    ];
    
    return () => (
        <Card>
            <Card.Body>
                <Heading level={3} size="lg">Featured Products</Heading>
                <Carousel class="space-x-4 rounded-box">
                    {products.map((product, i) => (
                        <CarouselItem id={`prod${i}`} class="w-1/2">
                            <Card class="bg-base-200 w-full">
                                <img src={product.img} alt={product.name} class="w-full h-32 object-cover" />
                                <Card.Body class="p-3">
                                    <Text weight="semibold">{product.name}</Text>
                                    <Text color="primary" weight="bold">{product.price}</Text>
                                </Card.Body>
                            </Card>
                        </CarouselItem>
                    ))}
                </Carousel>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Vertical Carousel

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [1, 2, 3, 4, 5];
    
    return () => (
        <Card>
            <Card.Body>
                <Carousel vertical class="h-96 rounded-box">
                    {items.map((num, i) => (
                        <CarouselItem id={`vert${i}`} class="h-full">
                            <Card class={`w-full h-full ${
                                i % 2 === 0 ? 'bg-primary text-primary-content' : 'bg-secondary text-secondary-content'
                            }`}>
                                <Card.Body class="items-center justify-center">
                                    <Heading level={3} size="4xl">{num}</Heading>
                                </Card.Body>
                            </Card>
                        </CarouselItem>
                    ))}
                </Carousel>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Center Snap

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [1, 2, 3, 4, 5, 6, 7];
    
    return () => (
        <Card>
            <Card.Body>
                <Carousel snap="center" class="p-4 space-x-4 rounded-box">
                    {items.map((num, i) => (
                        <CarouselItem id={`center${i}`}>
                            <Card class="w-64 h-48 bg-neutral text-neutral-content">
                                <Card.Body class="items-center justify-center">
                                    <Heading level={3} size="4xl">{num}</Heading>
                                </Card.Body>
                            </Card>
                        </CarouselItem>
                    ))}
                </Carousel>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Carousel with Indicators

```tsx
import { component, render } from 'sigx';
import { Carousel, CarouselItem, Card, Row, Button, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    const slides = [
        { id: 'a', content: 'First Slide', bg: 'bg-primary text-primary-content' },
        { id: 'b', content: 'Second Slide', bg: 'bg-secondary text-secondary-content' },
        { id: 'c', content: 'Third Slide', bg: 'bg-accent text-accent-content' },
        { id: 'd', content: 'Fourth Slide', bg: 'bg-info text-info-content' }
    ];
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Carousel class="w-full rounded-box">
                    {slides.map((slide) => (
                        <CarouselItem id={slide.id} class="w-full">
                            <Card class={`w-full h-48 ${slide.bg}`}>
                                <Card.Body class="items-center justify-center">
                                    <Heading level={3} size="2xl">{slide.content}</Heading>
                                </Card.Body>
                            </Card>
                        </CarouselItem>
                    ))}
                </Carousel>
                
                <Row gap="2" justify="center" class="w-full py-2">
                    {slides.map((slide) => (
                        <Button size="xs" onClick={() => document.getElementById(slide.id)?.scrollIntoView({ behavior: 'smooth', inline: 'start' })}>
                            {slide.id.toUpperCase()}
                        </Button>
                    ))}
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Auto-play Carousel

```tsx
import { component, render, onMounted, onUnmounted } from 'sigx';
import { Carousel, CarouselItem, Card, Button, Badge, Row, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const state = signal({ 
        currentSlide: 0,
        playing: true
    });
    
    const slides = [
        { text: 'Slide 1', bg: 'from-primary to-secondary' },
        { text: 'Slide 2', bg: 'from-secondary to-accent' },
        { text: 'Slide 3', bg: 'from-accent to-info' },
        { text: 'Slide 4', bg: 'from-info to-success' },
        { text: 'Slide 5', bg: 'from-success to-warning' }
    ];
    
    let intervalId;
    
    const startAutoplay = () => {
        intervalId = setInterval(() => {
            if (state.playing) {
                state.currentSlide = (state.currentSlide + 1) % slides.length;
            }
        }, 3000);
    };
    
    const stopAutoplay = () => {
        if (intervalId) clearInterval(intervalId);
    };
    
    onMounted(() => startAutoplay());
    onUnmounted(() => stopAutoplay());
    
    const togglePlay = () => {
        state.playing = !state.playing;
    };
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <div class="relative w-full h-48 overflow-hidden rounded-box">
                    {slides.map((slide, i) => (
                        <div 
                            class={`absolute inset-0 transition-opacity duration-500 bg-gradient-to-r ${slide.bg} flex items-center justify-center text-white text-3xl font-bold ${
                                state.currentSlide === i ? 'opacity-100' : 'opacity-0'
                            }`}
                        >
                            <Text size="3xl" weight="bold" color="white">{slide.text}</Text>
                        </div>
                    ))}
                </div>
                
                <Row justify="between" align="center">
                    <Button 
                        variant="ghost" 
                        size="sm"
                        onClick={togglePlay}
                    >
                        {state.playing ? '⏸ Pause' : '▶ Play'}
                    </Button>
                    
                    <Row gap="2">
                        {slides.map((_, i) => (
                            <Button
                                size="xs"
                                variant={state.currentSlide === i ? 'primary' : 'ghost'}
                                onClick={() => state.currentSlide = i}
                            >
                                {i + 1}
                            </Button>
                        ))}
                    </Row>
                    
                    <Badge variant="ghost">
                        {state.currentSlide + 1} / {slides.length}
                    </Badge>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Carousel Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `vertical` | `boolean` | `false` | Vertical scrolling |
| `snap` | `'start' \| 'center' \| 'end'` | `'start'` | Snap alignment |
| `variant` | `'full'` | - | Full-bleed mode |
| `class` | `string` | - | Additional CSS classes |

### Carousel Slots

| Slot | Description |
|------|-------------|
| `default` | CarouselItem components |

### CarouselItem Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | - | Unique identifier for navigation |
| `class` | `string` | - | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/fieldset/
title: Fieldset
description: Container for grouping related form elements with a legend and labels
---

# Fieldset

Fieldset is a container for grouping related form elements. Use `Fieldset.Legend` for the title and `Label` for description text.

## Import

```tsx
import { Fieldset, Label, Input, Button, Join, Row, Col, Text } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Fieldset, Label, Input } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Fieldset>
            <Fieldset.Legend>Page title</Fieldset.Legend>
            <Input placeholder="My awesome page" />
            <Label>You can edit page title later on from settings</Label>
        </Fieldset>
    );
});

render(<Demo />, "#sandbox");
```

## Styled Fieldset

Add background, border, and padding with Tailwind utility classes.

```tsx
import { component, render } from 'sigx';
import { Fieldset, Label, Input } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Fieldset class="bg-base-200 border-base-300 rounded-box w-xs border p-4">
            <Fieldset.Legend>Page title</Fieldset.Legend>
            <Input placeholder="My awesome page" />
            <Label>You can edit page title later on from settings</Label>
        </Fieldset>
    );
});

render(<Demo />, "#sandbox");
```

## Multiple Inputs

Group several labeled inputs together.

```tsx
import { component, render } from 'sigx';
import { Fieldset, Label, Input } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Fieldset class="bg-base-200 border-base-300 rounded-box w-xs border p-4">
            <Fieldset.Legend>Page details</Fieldset.Legend>
            <Label>Title</Label>
            <Input placeholder="My awesome page" />
            <Label>Slug</Label>
            <Input placeholder="my-awesome-page" />
            <Label>Author</Label>
            <Input placeholder="Name" />
        </Fieldset>
    );
});

render(<Demo />, "#sandbox");
```

## With Join

Combine inputs and buttons inside a fieldset using Join.

```tsx
import { component, render } from 'sigx';
import { Fieldset, Label, Input, Button, Join } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Fieldset class="bg-base-200 border-base-300 rounded-box w-xs border p-4">
            <Fieldset.Legend>Settings</Fieldset.Legend>
            <Join>
                <Input placeholder="Product name" class="join-item" />
                <Button class="join-item">Save</Button>
            </Join>
        </Fieldset>
    );
});

render(<Demo />, "#sandbox");
```

## Login Form

A complete login form example.

```tsx
import { component, render } from 'sigx';
import { Fieldset, Label, Input, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Fieldset class="bg-base-200 border-base-300 rounded-box w-xs border p-4">
            <Fieldset.Legend>Login</Fieldset.Legend>
            <Label>Email</Label>
            <Input type="email" placeholder="Email" />
            <Label>Password</Label>
            <Input type="password" placeholder="Password" />
            <Button variant="neutral" class="mt-4">Login</Button>
        </Fieldset>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Fieldset

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes (e.g. `bg-base-200 border p-4`) |
| `children` | `JSX.Element` | — | Child elements (legend, labels, inputs) |

### Fieldset.Legend

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |
| `children` | `JSX.Element` | — | Legend text content |

### Label

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |
| `children` | `JSX.Element` | — | Label/description text |

---
url: https://sigx.dev/daisyui/docs/components/skeleton/
title: Skeleton
description: Animated loading placeholder for content that is being fetched
---

# Skeleton

Display animated placeholder content while data is loading. Use Tailwind utility classes for sizing and shape.

## Import

```tsx
import { Skeleton } from '@sigx/daisyui';
```

## Basic Skeleton

```tsx
import { component, render } from 'sigx';
import { Skeleton } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Skeleton class="h-32 w-32" />
    );
});

render(<Demo />, "#sandbox");
```

## Circle with Content

```tsx
import { component, render } from 'sigx';
import { Skeleton, Row, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4" class="w-52">
            <Row align="center" gap="4">
                <Skeleton class="h-16 w-16 shrink-0 rounded-full" />
                <Col gap="4">
                    <Skeleton class="h-4 w-20" />
                    <Skeleton class="h-4 w-28" />
                </Col>
            </Row>
            <Skeleton class="h-32 w-full" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Rectangle with Content

```tsx
import { component, render } from 'sigx';
import { Skeleton, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4" class="w-52">
            <Skeleton class="h-32 w-full" />
            <Skeleton class="h-4 w-28" />
            <Skeleton class="h-4 w-full" />
            <Skeleton class="h-4 w-full" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Animated Text (skeleton-text)

Use the `text` prop to animate text color instead of background. Renders as a `<span>`.

```tsx
import { component, render } from 'sigx';
import { Skeleton } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Skeleton text>AI is thinking harder...</Skeleton>
    );
});

render(<Demo />, "#sandbox");
```

## Card Placeholder

```tsx
import { component, render } from 'sigx';
import { Skeleton, Card, Col, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card class="w-64">
            <Skeleton class="h-48 w-full" />
            <Card.Body>
                <Col gap="4">
                    <Skeleton class="h-6 w-3/4" />
                    <Skeleton class="h-4 w-full" />
                    <Skeleton class="h-4 w-full" />
                    <Skeleton class="h-4 w-2/3" />
                    <Row gap="2">
                        <Skeleton class="h-8 w-20 rounded-full" />
                        <Skeleton class="h-8 w-20 rounded-full" />
                    </Row>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## List Placeholder

```tsx
import { component, render } from 'sigx';
import { Skeleton, Card, Row, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card class="w-80">
            <Card.Body>
                <Col gap="4">
                    {[1, 2, 3].map(() => (
                        <Row align="center" gap="4">
                            <Skeleton class="h-12 w-12 shrink-0 rounded-lg" />
                            <Col gap="2" class="flex-1">
                                <Skeleton class="h-4 w-1/2" />
                                <Skeleton class="h-3 w-3/4" />
                            </Col>
                            <Skeleton class="h-8 w-16 shrink-0 rounded" />
                        </Row>
                    ))}
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `boolean` | `false` | Applies `skeleton-text` class, animates text color instead of background. Renders as `<span>` instead of `<div>`. |
| `class` | `string` | - | CSS utility classes for sizing (`h-*`, `w-*`), shape (`rounded-full`, `rounded-lg`), and other styling. |

---
url: https://sigx.dev/daisyui/docs/components/progress/
title: Progress
description: Progress bar shows the progress of a task
---

# Progress

Progress bar shows the progress of a task. Uses the native HTML `<progress>` element with daisyUI styling.

## Import

```tsx
import { Progress } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Progress } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Progress value={40} class="w-56" />
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Progress, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Progress value={20} color="primary" class="w-56" />
            <Progress value={30} color="secondary" class="w-56" />
            <Progress value={40} color="accent" class="w-56" />
            <Progress value={50} color="neutral" class="w-56" />
            <Progress value={60} color="info" class="w-56" />
            <Progress value={70} color="success" class="w-56" />
            <Progress value={80} color="warning" class="w-56" />
            <Progress value={90} color="error" class="w-56" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Indeterminate

Omit the `value` prop for an indeterminate (animated) progress bar.

```tsx
import { component, render } from 'sigx';
import { Progress, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Progress class="w-56" />
            <Progress color="primary" class="w-56" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Different Values

```tsx
import { component, render } from 'sigx';
import { Progress, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Progress value={0} class="w-56" />
            <Progress value={10} class="w-56" />
            <Progress value={40} class="w-56" />
            <Progress value={70} class="w-56" />
            <Progress value={100} class="w-56" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Max

Use the `max` prop to set a custom maximum value.

```tsx
import { component, render } from 'sigx';
import { Progress, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Progress value={3} max={10} color="primary" class="w-56" />
            <Progress value={7} max={10} color="secondary" class="w-56" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Full Width

Use `class="w-full"` for a full-width progress bar.

```tsx
import { component, render } from 'sigx';
import { Progress } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Progress value={65} color="success" class="w-full" />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `undefined` | Current progress value. Omit for indeterminate state |
| `max` | `number` | `100` | Maximum value |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Color variant |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/deploy/packages/netlify/overview/
title: Overview
description: "Frameworks API function generation — the Netlify adapter for SignalX (@sigx/netlify): what it does, setup and API."
---

# Netlify

<p class="lede">Emits the .netlify/v1/functions/sigx-ssr catch-all function with preferStatic routing — CDN files win, the raw outlet template stays off "/", and netlify.toml stays yours. Deploy with netlify deploy --prod.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add -D @sigx/netlify
```

## Usage

```ts
// vite.config.netlify.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { netlify } from '@sigx/netlify';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: netlify() } })]
});
```

`vite build --app -c vite.config.netlify.ts` produces a fully bundled function
and generates the **Frameworks API** channel — Netlify's recommended target for
build-tool adapters. Deploy with `netlify deploy --prod` (builds by default) or
`netlify deploy --prod --no-build` for prebuilt output.

## About

`@sigx/netlify` is a Deploy adapter — Frameworks API function generation. It ships from the core repo in lockstep with the release it deploys, so the adapter always matches your sigx version.

It rides `@sigx/vite`'s public [`SigxAdapter` seam](/vite/docs/deploy-adapters);
the runtime story is
[`createFetchHandler`](/server/packages/server-renderer/fetch-handler)
(WinterCG-clean, CI-enforced) — everything in this package is **build glue**.

## Next steps

Continue with [Deploying to Netlify](/deploy/packages/netlify/deploying) for the function layout and routing policy, or jump to the [API reference](/deploy/packages/netlify/api).

---
url: https://sigx.dev/daisyui/docs/components/textarea/
title: Textarea
description: Multi-line text input for longer text content
---

# Textarea

Multi-line text input component with model binding support.

## Import

```tsx
import { Textarea, Col } from '@sigx/daisyui';
```

## Basic Usage

Use `model` for two-way binding:

```tsx
import { component, render } from 'sigx';
import { Textarea, Card, Col, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ bio: '' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Textarea 
                    model={() => form.bio}
                    placeholder="Tell us about yourself..."
                    variant="bordered"
                />
                
                <Col gap="1">
                    <Text size="sm" class="opacity-70">Characters: {form.bio.length}</Text>
                    <Text size="sm" class="opacity-70">Preview: {form.bio || '(empty)'}</Text>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Textarea, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Textarea size="xs" placeholder="Extra small" variant="bordered" />
            <Textarea size="sm" placeholder="Small" variant="bordered" />
            <Textarea size="md" placeholder="Medium (default)" variant="bordered" />
            <Textarea size="lg" placeholder="Large" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Textarea, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Textarea color="primary" placeholder="Primary" variant="bordered" />
            <Textarea color="secondary" placeholder="Secondary" variant="bordered" />
            <Textarea color="accent" placeholder="Accent" variant="bordered" />
            <Textarea color="success" placeholder="Success" variant="bordered" />
            <Textarea color="warning" placeholder="Warning" variant="bordered" />
            <Textarea color="error" placeholder="Error" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

```tsx
import { component, render } from 'sigx';
import { Textarea, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Textarea placeholder="Default (no variant)" />
            <Textarea placeholder="Bordered" variant="bordered" />
            <Textarea placeholder="Ghost" variant="ghost" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Rows

Control the visible height with `rows`:

```tsx
import { component, render } from 'sigx';
import { Textarea, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Textarea rows={2} placeholder="2 rows" variant="bordered" />
            <Textarea rows={4} placeholder="4 rows" variant="bordered" />
            <Textarea rows={8} placeholder="8 rows" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Character Counter

```tsx
import { component, render } from 'sigx';
import { Textarea, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ message: '' });
    const maxLength = 280;
    const remaining = () => maxLength - form.message.length;
    const isOverLimit = () => remaining() < 0;
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField 
                    label="Message" 
                    hint={`${remaining()} characters remaining`}
                    error={isOverLimit() ? 'Message is too long' : ''}
                >
                    <Textarea 
                        model={() => form.message}
                        placeholder="What's on your mind?"
                        rows={4}
                        color={isOverLimit() ? 'error' : undefined}
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With FormField

```tsx
import { component, render } from 'sigx';
import { Textarea, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ feedback: '' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField 
                    label="Feedback" 
                    required
                    hint="Please provide detailed feedback"
                >
                    <Textarea 
                        model={() => form.feedback}
                        placeholder="Share your thoughts..."
                        rows={5}
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled State

```tsx
import { component, render } from 'sigx';
import { Textarea } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Textarea 
            placeholder="This textarea is disabled" 
            variant="bordered"
            disabled 
        />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for two-way sync |
| `name` | `string` | - | Textarea name for form submission |
| `placeholder` | `string` | - | Placeholder text |
| `rows` | `number` | `3` | Number of visible text rows |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Textarea size |
| `variant` | `'bordered' \| 'ghost'` | - | Visual variant |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Border color |
| `disabled` | `boolean` | `false` | Disable the textarea |
| `autoComplete` | `string` | - | Browser autocomplete hint (`'off'`, `'on'`, etc.) |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onInput` | `(e: InputEvent) => void` | Fired on each keystroke (raw DOM event) |
| `onChange` | `(e: Event) => void` | Fired when focus leaves the textarea |

---
url: https://sigx.dev/deploy/packages/vercel/deploying/
title: Deploying to Vercel
description: Vercel — the generated .vercel/output layout, Node vs Edge runtimes, and the { fetch } entry shape
---

# Deploying to Vercel

<p class="lede">Every build regenerates the complete Build Output API v3 layout — the route table, the static tier and the bundled render function. This guide walks the layout, the two runtimes, and why the entry's `{ fetch }` shape is load-bearing.</p>

## The generated layout

```
.vercel/output/
├── config.json                # routes: fn prefix → filesystem → catch-all
├── static/                    # the client outDir (minus index.html, .vite)
└── functions/_render.func/    # the bundled server + .vc-config.json
```

The Build Output API is a **generation contract** — hand-writing it has no
copyability value, so `generate()` rebuilds it every time. Two layout choices
are load-bearing:

- **`static/` omits `index.html`** — the filesystem handle would serve
  `static/index.html` for `/`, shadowing the document render with the raw
  outlet template.
- **The server-fn route precedes the filesystem handle** — POSTs to
  `/_sigx/fn/*` must never be shadowed by files.

## The platform entry — yours, scaffolded once

The first build scaffolds `src/entry.vercel.ts` iff absent and never touches it
again. The composition order stays visible in your file:

```
static assets  →  server functions  →  document render
```

The `export default { fetch }` shape is **load-bearing on the Node runtime**:
Vercel's launcher detects a web handler by the `fetch` *method* on the default

## Node vs Edge

The default runtime is **`node`** — Vercel's current guidance (Fluid compute).
Edge is opt-in:

```ts
vercel({ runtime: 'edge' })
```

For `runtime: 'edge'` the build resolves the `edge-light`/`worker` conditions
and `generate()` emits a tiny wrapper entrypoint — the edge contract is a bare
default fetch function, while your entry keeps the `{ fetch }` shape, identical
across platforms.

## Deploy

```bash
vite build --app -c vite.config.vercel.ts
vercel deploy --prebuilt          # add --prod for production
```

## Verification posture

Structural, not emulation (there is no official Build Output API emulator): CI
asserts the generated layout and invokes the function's fetch export directly
under Node with real `Request`s — exactly what Vercel's launcher calls. The
reference wiring lives at `examples/resume` in the
[SignalX core repo](https://github.com/signalxjs/core)
(`vite.config.vercel.ts` + the committed `src/entry.vercel.ts`).

---
url: https://sigx.dev/daisyui/docs/components/timeline/
title: Timeline
description: Timeline component for displaying chronological events with connectors and icons
---

# Timeline

Display chronological events with connecting lines, icons, and content on either side.

## Import

```tsx
import { Timeline } from '@sigx/daisyui';
```

## Basic Usage

Timeline with content on both sides and a middle icon.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical>
            <Timeline.Item>
                <Timeline.Start>1984</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>1998</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2001</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPod</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2007</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPhone</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2015</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>Apple Watch</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## End Only (Bottom/Right Side)

Show content only on the end side — useful for compact timelines.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical>
            <Timeline.Item>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPod</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Start Only (Top/Left Side)

Show content only on the start side.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical>
            <Timeline.Item>
                <Timeline.Start boxed>First Macintosh computer</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start boxed>iMac</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start boxed>iPod</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Colored Connectors

Use the `color` prop on `Timeline.Hr` to color the connecting lines.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical>
            <Timeline.Item>
                <Timeline.Start>1984</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr color="primary" />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr color="primary" />
                <Timeline.Start>1998</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr color="primary" />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr color="primary" />
                <Timeline.Start>2001</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPod</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2007</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPhone</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2015</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>Apple Watch</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Without Icons

Timeline without middle icons — just connectors and content.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical>
            <Timeline.Item>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.End boxed>iPod</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Compact

The `compact` modifier forces all content to one side.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical compact>
            <Timeline.Item>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPod</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPhone</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Snap Icon

The `snap` modifier snaps icons to the start instead of the middle.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline vertical snap>
            <Timeline.Item>
                <Timeline.Start>1984</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>First Macintosh computer</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>1998</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start>2015</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>Apple Watch</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Horizontal Timeline

Use the `horizontal` modifier for a horizontal layout.

```tsx
import { component, render } from 'sigx';
import { Timeline } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Timeline horizontal class="overflow-x-auto">
            <Timeline.Item>
                <Timeline.Start boxed>1984</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>Macintosh</Timeline.End>
                <Timeline.Hr color="primary" />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr color="primary" />
                <Timeline.Start boxed>1998</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iMac</Timeline.End>
                <Timeline.Hr />
            </Timeline.Item>
            <Timeline.Item>
                <Timeline.Hr />
                <Timeline.Start boxed>2001</Timeline.Start>
                <Timeline.Middle>●</Timeline.Middle>
                <Timeline.End boxed>iPod</Timeline.End>
            </Timeline.Item>
        </Timeline>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Timeline Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `vertical` | `boolean` | `false` | Vertical layout (`timeline-vertical`) |
| `horizontal` | `boolean` | `false` | Horizontal layout (`timeline-horizontal`) |
| `snap` | `boolean` | `false` | Snap icon to start (`timeline-snap-icon`) |
| `compact` | `boolean` | `false` | Force all items to one side (`timeline-compact`) |
| `class` | `string` | - | Additional CSS classes |

### Timeline.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | - | Additional CSS classes |

### Timeline.Start / Timeline.End Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `boxed` | `boolean` | `false` | Apply box styling (`timeline-box`) |
| `class` | `string` | - | Additional CSS classes |

### Timeline.Middle Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | - | Additional CSS classes |

### Timeline.Hr Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Connector line color (`bg-*`) |
| `class` | `string` | - | Additional CSS classes |

---
url: https://sigx.dev/terminal/docs/components/confirm/
title: Confirm
description: Inline yes/no toggle with custom active and inactive labels
---

# Confirm

<p class="lede">A focusable inline yes/no control with two-way <code>model</code> binding and customizable labels for each state.</p>

## Import

```tsx
import { Confirm } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Confirm } from '@sigx/terminal';

const App = component(() => {
    const overwrite = signal(false);
    return () => (
        <box border="single" label="Confirm">
            <Confirm
                model={() => overwrite}
                label="Overwrite the existing file?"
                activeLabel="Yes"
                inactiveLabel="No"
                autofocus
                onSubmit={(v) => console.log('decided:', v)}
            />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `model` | `Model<boolean>` | two-way bound choice |
| `label` | `string` | the question |
| `activeLabel` | `string` | label for `true` |
| `inactiveLabel` | `string` | label for `false` |
| `autofocus` | `boolean` | grab focus on mount |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `boolean` | the selection flips |
| `submit` | `boolean` | Enter |

## See also

- [confirm() prompt](/terminal/docs/prompts) — the imperative wizard form.
- [Checkbox](/terminal/docs/components/checkbox) — a plain boolean toggle.

---
url: https://sigx.dev/terminal/docs/components/logview/
title: LogView
description: A scrollable log viewport backed by a LogStore
---

# LogView

<p class="lede">A focusable, scrollable viewport over a stream of log lines. Pairs with a <code>LogStore</code> — a reactive ring buffer that handles partial lines and <code>\r</code> overwrites.</p>

## Import

```tsx
import { LogView, createLogStore } from '@sigx/terminal';
import type { LogStore } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, onMounted, LogView, createLogStore } from '@sigx/terminal';

const App = component(() => {
    const log = createLogStore();
    onMounted(() => {
        let n = 0;
        const t = setInterval(() => { log.push(`line ${++n}\n`); }, 200);
        return () => clearInterval(t);
    });
    return () => (
        <box border="single" label="Build output">
            <LogView store={log} height={10} width={60} title="output" autofocus />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `store` | `LogStore` | the reactive source (alternative to `lines`) |
| `lines` | `string[]` | static lines (alternative to `store`) |
| `height` | `number` | visible rows |
| `width` | `number` | wrap width |
| `title` | `string` | caption |
| `autofocus` | `boolean` | grab focus on mount (for scrolling) |

**A line too wide for the viewport is marked, not silently cut.** The truncation carries a `…`, so a message that ends mid-word reads as clipped rather than as a message that genuinely ended there — which matters most for the stack traces and JSON payloads a log view exists to show. Widen the view, or scroll.

`LogView` and [`LogPanel`](/terminal/docs/components/logpanel) derive their own box chrome via [`boxChrome`](/terminal/docs/api#boxchrome) rather than hardcoding it, so their viewport arithmetic stays correct if the frame changes shape.

## LogStore

`createLogStore(opts?)` returns a reactive store:

```ts
interface LogStore {
    readonly passthrough: boolean;     // streams completed lines to printStatic
    push(chunk: string): void;
    end(): void;                       // commit a trailing partial line
    clear(): void;
    lines(): readonly string[];        // completed + live partial (reactive)
    tail(n: number): string[];         // last n (reactive)
    count(): number;
}
```

`LogStoreOptions`: `limit` (retained-line ring buffer, default 10 000) and `passthrough` (stream completed lines straight to `printStatic` — defaults on for non-TTY so piped/CI logs stay complete and ordered, off when interactive). `collapseTask(opts)` collapses a finished task's output into a single line.

## See also

- [LogPanel](/terminal/docs/components/logpanel) — a bounded, non-scrolling tail.
- [TaskList](/terminal/docs/components/tasklist) — stream a tail under the running task.

---
url: https://sigx.dev/terminal/docs/components/shimmer/
title: Shimmer
description: An animated highlight sweep across text
---

# Shimmer

<p class="lede">Sweeps a brighter <code>highlight</code> band across <code>text</code> over a base <code>color</code> — a subtle loading/attention effect.</p>

## Import

```tsx
import { Shimmer } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Shimmer } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box>
            <Shimmer text="Loading…" color="dim" highlight="accent" speed={1} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `text` | `string` | **required** — the text |
| `color` | token \| `#hex` | base color |
| `highlight` | token \| `#hex` | sweep color |
| `width` | `number` | width of the highlight band |
| `speed` | `number` | sweep speed |

## See also

- [Gradient](/terminal/docs/components/gradient) — multi-stop coloring.
- [Spinner](/terminal/docs/components/spinner) — an activity indicator.

---
url: https://sigx.dev/actors/packages/actors-otel/api/
title: API reference
description: Exports of @sigx/actors-otel — prometheusOps, renderPrometheus, otelTraces, otelMetricsBridge and the traceparent helpers
---

# API reference

<p class="lede">Exports of `@sigx/actors-otel` .</p>

## `@sigx/actors-otel/prometheus`

Imports no OpenTelemetry.

### `prometheusOps(options?)`

An `ActorPlugin` mounting the scrape endpoint.

```ts
interface PrometheusOpsOptions extends RenderPrometheusOptions {
    path?: string;              // '/_sigx/metrics'
    secret?: string;            // mandatory outside dev
}
interface RenderPrometheusOptions {
    prefix?: string;            // 'sigx_actors_'
    bucketsSeconds?: number[];  // per-octave grid, 1µs → ~134s
}
```

### `renderPrometheus(digest, stats, options)`

The pure function underneath — no plugin, no route. Use it to serve the exposition yourself.

## `@sigx/actors-otel`

### `otelTraces(options?)`

```ts
interface OtelTracesOptions {
    tracerProvider?: TracerProvider;
    turnSpans?: boolean;   // true
}
```

One CLIENT span per dispatch, one SERVER span per turn. Cross-host joins ride the runtime's
W3C `traceparent`.

### `otelMetricsBridge(options?)`

```ts
interface OtelMetricsBridgeOptions {
    meterProvider?: MeterProvider;
    percentileGauges?: boolean;   // true
}
```

### `traceparent` helpers

`formatTraceparent(fields)`, `parseTraceparent(header)`, and the `TraceparentFields` type.

## Core plumbing this rides on

Exported from `@sigx/actors` and `@sigx/actors/host` rather than here, but relevant:

- `ActorCallContext.traceparent`
- the trailing `call` parameter on `ActorTurnObserver`
- `bucketUpperBoundsUs()` and `timingSafeEquals` from `@sigx/actors/host`

## Labels

`type` and `method` only. **Never actor keys** — enforced, because keys are unbounded and one
high-cardinality label is enough to take a Prometheus down.

## Next steps

- [Overview](/actors/packages/actors-otel/overview) — the two entries.
- [Installation](/actors/packages/actors-otel/installation) — scrape config and caveats.
- [Observability](/actors/docs/observability) — the guide.

---
url: https://sigx.dev/terminal/docs/components/spinner/
title: Spinner
description: Animated activity indicator that resolves to a check or cross
---

# Spinner

<p class="lede">An animated activity indicator. When <code>done</code> it resolves to a success check (<code>✔</code>); when <code>failed</code>, a danger cross (<code>✖</code>); <code>done</code> wins. Driven by a shared ticker — one interval for every animated component, frozen on non-TTY output.</p>

## Import

```tsx
import { Spinner } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, onMounted, Spinner } from '@sigx/terminal';

const App = component(() => {
    const done = signal(false);
    onMounted(() => {
        const t = setTimeout(() => { done.value = true; }, 2000);
        return () => clearTimeout(t);
    });
    return () => (
        <box border="single" label="Build">
            <Spinner label={done.value ? 'Built' : 'Building…'} done={done.value} variant="dots" />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `string` | — | text beside the glyph |
| `done` | `boolean` | — | resolve to a success check |
| `failed` | `boolean` | — | resolve to a danger cross (`done` wins) |
| `interval` | `number` | — | animation interval override |
| `variant` | `SpinnerVariant` | `'dots'` | frame set |
| `color` | token \| `#hex` | — | glyph color |

`SpinnerVariant` is one of `'dots'`, `'line'`, `'arc'`, `'circle'`, `'bounce'`, `'moon'`. All frame sets are width-1 except `'moon'` (emoji — 2 cells; use only where a wider glyph column is fine).

## See also

- [spinner() prompt](/terminal/docs/prompts) — the imperative form for wizard flows.
- [ProgressBar](/terminal/docs/components/progressbar) — determinate progress.

---
url: https://sigx.dev/core/packages/runtime-dom/usage/
title: Usage
description: Using Runtime DOM in a SignalX app — the DOM renderer patterns and examples with @sigx/runtime-dom.
---

# Using Runtime DOM

<p class="lede">The DOM renderer — the essentials. Mount component trees into the browser, portal content elsewhere, toggle visibility, and write your own DOM directives.</p>

## The umbrella vs. the package

Most apps install the `sigx` umbrella, which bundles `@sigx/reactivity`, `@sigx/runtime-core` and `@sigx/runtime-dom` together. When you call `createApp(App).mount('#root')` from `sigx`, runtime-dom is what actually puts nodes on the page.

You only import `@sigx/runtime-dom` directly for custom setups — for example, mounting without the app/plugin layer, or wiring up portals and directives by hand.

```bash
pnpm add @sigx/runtime-dom
```

Importing the package is impure by design. The entry module wires up the DOM platform globally the moment it loads: it sets `HTMLElement` as the default element type for core, installs the singleton DOM renderer as the default mount target, registers the built-in `show` directive, and enables v-model on form elements. Import it once and the rest of SignalX targets the browser.

## Mount a tree with `render`

`render` mounts a JSX element tree into a container. The container can be a live `Element` or a CSS selector string.

```tsx
import { component, signal } from 'sigx';
import { render } from '@sigx/runtime-dom';

const App = component(() => {
  const name = signal('world');
  return () => (
    <div>
      <input
        value={name.value}
        onInput={e => (name.value = e.currentTarget.value)}
      />
      <p>Hello, {name.value}!</p>
    </div>
  );
});

// By selector string...
render(<App />, '#app');

// ...or by element reference
render(<App />, document.getElementById('app')!);
```

If the selector or element resolves to nothing, `render` throws a render-target-not-found error. To unmount and clear a container, call `render` with `null`:

```tsx
import { render } from '@sigx/runtime-dom';

render(<App />, '#app');
// later: tear it down
render(null, '#app');
```

## Render elsewhere with `Portal`

`Portal` renders its children into a different DOM container — by default `document.body`. This is the standard tool for modals, toasts and tooltips that must escape an overflow or stacking context. The target is set with the `to` prop (an `Element` or a CSS selector string), and a `disabled` prop renders children in place instead.

```tsx
import { component, signal } from 'sigx';
import { Portal } from '@sigx/runtime-dom';

const Modal = component(() => {
  const open = signal(true);
  return () => (
    <>
      <button onClick={() => (open.value = !open.value)}>Toggle</button>
      {open.value && (
        <Portal to="#modal-root">
          <div class="modal">Rendered into #modal-root, not in place.</div>
        </Portal>
      )}
    </>
  );
});
```

If a selector passed to `to` is not found, `Portal` warns and falls back to `document.body`. See [Portals](/core/docs/portal) for the full guide.

## Keep elements mounted with `use:show`

The built-in `show` directive toggles an element's CSS `display` property while keeping the element in the DOM — unlike conditional rendering, which removes it. Reach for it when you want to preserve element state (form input, scroll position) across visibility changes.

```tsx
import { component, signal } from 'sigx';
import 'sigx'; // or import '@sigx/runtime-dom' — registers `show`

const Panel = component(() => {
  const visible = signal(true);
  return () => (
    <>
      <button onClick={() => (visible.value = !visible.value)}>Toggle</button>
      {/* shorthand: resolves the built-in `show` by name */}
      <div use:show={visible.value}>Stays in the DOM, just hidden.</div>
    </>
  );
});
```

The directive resolves through the same lookup as any `use:*` prop, so `use:show` also accepts an explicit tuple of `[show, visible.value]`.

## Write a custom DOM directive

`DOMDirective` is a directive definition narrowed to `HTMLElement`, which gives you correctly-typed element access in lifecycle hooks. Define a directive with `defineDirective` and apply it via `use:`.

```tsx
import { component, defineDirective } from 'sigx';
import type { DOMDirective } from '@sigx/runtime-dom';

const tooltip: DOMDirective<string> = defineDirective<string, HTMLElement>({
  mounted(el, { value }) {
    el.title = value;
  },
  updated(el, { value }) {
    el.title = value;
  },
});

const Hint = component(() => {
  return () => <span use:tooltip="Helpful hint">Hover me</span>;
});
```

A `use:` prop accepts three shapes: a directive definition directly, a `[definition, value]` tuple, or a plain value that resolves by name (built-in directives first, then app-registered directives). Lifecycle hooks fire as `created` (first set), `updated` (when the value changes), `mounted` (after DOM insertion) and `unmounted` (before removal). See [Directives](/core/docs/directives) for the complete model.

## Notes

- DOM property semantics — styles, `on*` handlers, `className`, `.prop`/`prop:` bindings, SVG/xlink attributes and form `value`/`checked` — are covered in [DOM properties](/core/docs/dom-properties).
- Two-way `value` binding is documented in [Two-way binding](/core/docs/two-way-binding).
- For low-level renderer primitives (SSR/hydration), see the [API reference](/core/packages/runtime-dom/api) and the `@sigx/runtime-dom/internals` subpath — those are not stable public API.

---
url: https://sigx.dev/daisyui/docs/components/loading/
title: Loading
description: Loading indicators for async operations
---

# Loading

Loading indicators show users that content is being loaded or processed.

## Import

```tsx
import { Loading, Row, Col, Text, Button } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Spinner

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="spinner" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Dots

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="dots" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Ring

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="ring" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Ball

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="ball" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Bars

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="bars" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## Loading Infinity

```tsx
import { component, render } from 'sigx';
import { Loading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Loading type="infinity" size="lg" />
    );
});

render(<Demo />, "#sandbox");
```

## All Types

```tsx
import { component, render } from 'sigx';
import { Loading, Row, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="8" align="center">
            <Col align="center">
                <Loading type="spinner" />
                <Text size="sm" class="mt-2">Spinner</Text>
            </Col>
            <Col align="center">
                <Loading type="dots" />
                <Text size="sm" class="mt-2">Dots</Text>
            </Col>
            <Col align="center">
                <Loading type="ring" />
                <Text size="sm" class="mt-2">Ring</Text>
            </Col>
            <Col align="center">
                <Loading type="ball" />
                <Text size="sm" class="mt-2">Ball</Text>
            </Col>
            <Col align="center">
                <Loading type="bars" />
                <Text size="sm" class="mt-2">Bars</Text>
            </Col>
            <Col align="center">
                <Loading type="infinity" />
                <Text size="sm" class="mt-2">Infinity</Text>
            </Col>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Loading, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Loading type="spinner" size="xs" />
            <Loading type="spinner" size="sm" />
            <Loading type="spinner" size="md" />
            <Loading type="spinner" size="lg" />
            <Loading type="spinner" size="xl" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Loading, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Loading type="spinner" color="primary" />
            <Loading type="spinner" color="secondary" />
            <Loading type="spinner" color="accent" />
            <Loading type="spinner" color="neutral" />
            <Loading type="spinner" color="info" />
            <Loading type="spinner" color="success" />
            <Loading type="spinner" color="warning" />
            <Loading type="spinner" color="error" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Loading with Button

```tsx
import { component, signal, render } from 'sigx';
import { Button, Loading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const isLoading = signal(false);

    const handleClick = () => {
        isLoading.value = true;
        setTimeout(() => isLoading.value = false, 2000);
    };

    return () => (
        <Button
            variant="primary"
            disabled={isLoading.value}
            onClick={handleClick}
        >
            {isLoading.value ? (
                <>
                    <Loading type="spinner" size="sm" />
                    <Text as="span">Processing...</Text>
                </>
            ) : (
                <Text as="span">Click me</Text>
            )}
        </Button>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'spinner' \| 'dots' \| 'ring' \| 'ball' \| 'bars' \| 'infinity'` | `'spinner'` | Animation type |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Loading indicator size |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Color variant |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/deploy/packages/vercel/overview/
title: Overview
description: "Build Output API v3 generation — the Vercel adapter for SignalX (@sigx/vercel): what it does, setup and API."
---

# Vercel

<p class="lede">Generates the complete .vercel/output layout on every build — static assets, the bundled render function and the route table — on the Node runtime (default) or the edge. Deploy with vercel deploy --prebuilt.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add -D @sigx/vercel
```

## Usage

```ts
// vite.config.vercel.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { vercel } from '@sigx/vercel';

export default defineConfig({
    plugins: [sigx({ ssr: { entry: 'src/entry-server.tsx', adapter: vercel() } })]
});
```

`vite build --app -c vite.config.vercel.ts` produces a fully bundled function
and then generates the complete `.vercel/output` layout. Unlike wrangler-style tools, the Build Output
API **is a generation contract**: hand-writing it has no copyability value, so
the layout is regenerated every build. Deploy with `vercel deploy --prebuilt`
(link the project first).

## About

`@sigx/vercel` is a Deploy adapter — Build Output API v3 generation. It ships from the core repo in lockstep with the release it deploys, so the adapter always matches your sigx version.

It rides `@sigx/vite`'s public [`SigxAdapter` seam](/vite/docs/deploy-adapters)
with no privileged access; the runtime story is
[`createFetchHandler`](/server/packages/server-renderer/fetch-handler)
(WinterCG-clean, CI-enforced) — everything in this package is **build glue**.

## Next steps

Continue with [Deploying to Vercel](/deploy/packages/vercel/deploying) for the output layout, runtimes and entry walkthrough, or jump to the [API reference](/deploy/packages/vercel/api).

---
url: https://sigx.dev/daisyui/docs/components/tooltip/
title: Tooltip
description: Tooltip displays informational text when hovering over or focusing on an element
---

# Tooltip

Tooltip displays informational text when hovering over or focusing on an element.

## Import

```tsx
import { Tooltip, Button, Badge, Row, Flex } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Tooltip tip="hello">
            <Button>Hover me</Button>
        </Tooltip>
    );
});

render(<Demo />, "#sandbox");
```

## Force Open

Use the `open` prop to force the tooltip to be visible.

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Tooltip tip="I am always visible" open>
            <Button>Force open</Button>
        </Tooltip>
    );
});

render(<Demo />, "#sandbox");
```

## Positions

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" class="p-16 flex-wrap justify-center">
            <Tooltip tip="top" position="top">
                <Button>Top</Button>
            </Tooltip>
            <Tooltip tip="bottom" position="bottom">
                <Button>Bottom</Button>
            </Tooltip>
            <Tooltip tip="left" position="left">
                <Button>Left</Button>
            </Tooltip>
            <Tooltip tip="right" position="right">
                <Button>Right</Button>
            </Tooltip>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" class="p-8 flex-wrap justify-center">
            <Tooltip tip="neutral" color="neutral" open>
                <Button>neutral</Button>
            </Tooltip>
            <Tooltip tip="primary" color="primary" open>
                <Button variant="primary">primary</Button>
            </Tooltip>
            <Tooltip tip="secondary" color="secondary" open>
                <Button variant="secondary">secondary</Button>
            </Tooltip>
            <Tooltip tip="accent" color="accent" open>
                <Button variant="accent">accent</Button>
            </Tooltip>
            <Tooltip tip="info" color="info" open>
                <Button variant="info">info</Button>
            </Tooltip>
            <Tooltip tip="success" color="success" open>
                <Button variant="success">success</Button>
            </Tooltip>
            <Tooltip tip="warning" color="warning" open>
                <Button variant="warning">warning</Button>
            </Tooltip>
            <Tooltip tip="error" color="error" open>
                <Button variant="error">error</Button>
            </Tooltip>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Content

Use `Tooltip.Content` for rich tooltip content instead of plain text.

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button, Badge, Flex, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Tooltip open>
            <Button>Hover for details</Button>
            <Tooltip.Content class="bg-base-200 text-base-content p-4 rounded-box shadow-lg">
                <Flex direction="column" gap="2">
                    <Text weight="bold">Custom Tooltip</Text>
                    <Text size="sm">This tooltip has rich content</Text>
                    <Badge variant="success" size="sm">Active</Badge>
                </Flex>
            </Tooltip.Content>
        </Tooltip>
    );
});

render(<Demo />, "#sandbox");
```

## Responsive

Use Tailwind responsive prefixes on the `class` prop to control tooltip visibility at different breakpoints.

```tsx
import { component, render } from 'sigx';
import { Tooltip, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Tooltip tip="Only visible on large screens" class="lg:tooltip-open" position="right">
            <Button>Responsive tooltip</Button>
        </Tooltip>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Tooltip

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tip` | `string` | `undefined` | Tooltip text (sets `data-tip` attribute) |
| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | `undefined` (top) | Position of the tooltip |
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Color variant |
| `open` | `boolean` | `false` | Force the tooltip to be visible |
| `class` | `string` | `undefined` | Additional CSS classes |

### Tooltip.Content

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/server/packages/resume/overview/
title: Overview
description: "Resume — resumable SSR: 0 JS on load, upgrade-on-write, single-flight boundary refresh"
---

# Resume

<p class="lede">Resumability for SignalX SSR — the server renders the page fully, the browser ships only a tiny delegation loader, and a component's chunk loads only when a handler first writes state. Plus single-flight refresh of the server boundaries a mutation invalidated.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Installation

```bash
pnpm add @sigx/resume
```

## About

`@sigx/resume` is the second first-party strategy pack on [`@sigx/server-renderer`](/server/packages/server-renderer/overview)'s plugin API (the sibling of [islands](/server/packages/ssr-islands/overview)). The `sigxResume()` Vite transform (`@sigx/vite/resume`) lifts event handlers into lazily-imported chunks that run against a **resumed scope** of named signals, so component setup never re-runs on load.

The result is a three-step ladder:

1. **On load — 0 app JS.** The page's only script is the generated delegation loader.
2. **First interaction.** The handler's chunk (usually < 1 kB, runtime-free) loads, the resumed scope's signals are rebuilt from serialized state, and the triggering event replays.
3. **State changes.** Only when a handler actually writes does the component's chunk load and *that one boundary* hydrate — "upgrade-on-write".

On top of that, `@sigx/resume` powers **single-flight boundary refresh**: when a mutation [server function](/server/packages/server/overview) declares what it `invalidates`, the endpoint re-renders exactly the server boundaries whose `useData` reads it touched — fresh HTML in the same response, without loading those boundaries' chunks.

Combine it with islands when you need both — `app.use(islandsPlugin()).use(resumePlugin())`.

## Next steps

- [Usage](/server/packages/resume/usage) — write resumable components, install the plugin, wire boundary refresh.
- [API reference](/server/packages/resume/api) — `resumePlugin`, the manifest, and `createBoundaryRefresh`.

---
url: https://sigx.dev/server/packages/serialize/usage/
title: Usage
description: Add a custom type with defineTypeHandler and register it
---

# Using Serialize

<p class="lede">Register a custom type once, and it round-trips wherever the codec runs — SSR state, server-function args/results and resume boundaries.</p>

## Define a handler

`defineTypeHandler` describes how one type crosses the wire. Declare `test` as a **type guard** and the `serialize` / `revive` parameter types (and their pairing) are inferred from it — no casts:

```ts
import { defineTypeHandler } from '@sigx/serialize';

const money = defineTypeHandler({
  name: 'money',                            // identifies the handler (dev warnings, dedupe)
  tag: '$money',                            // wire discriminator: { "$money": <payload> }
  test: (v): v is Money => v instanceof Money,
  serialize: (m) => m.cents,               // m: Money
  revive: (cents) => new Money(cents),     // cents: number — serialize's output
});
```

- `serialize` returns a JSON-safe payload; the result is itself walked, so nested handled types re-encode.
- `revive` is optional — omit it for a legacy serialize-only handler whose output ships as-is and is never revived.

> **Inference caveat.** TypeScript only infers the predicate from a **bare** `instanceof` / `typeof` arrow. A compound test like `(v) => typeof URL !== 'undefined' && v instanceof URL` infers `boolean` and collapses `T` to `unknown` — annotate those explicitly: `(v): v is URL => …`.

## Register it

`@sigx/serialize` itself has no registration function — it stays a pure codec. Registration lives with the runtime:

- **Server functions** — pass handlers to the app plugin from `@sigx/server/plugin`; one call covers both the RPC wire and the SSR state registry:

  ```ts
  import { serverPlugin } from '@sigx/server/plugin';
  app.use(serverPlugin({ types: [money] }));
  ```

- **A plugin of your own** — register into the per-app DI registry with `provideTypeHandlers` (re-exported from `sigx/internals`):

  ```ts
  import { provideTypeHandlers } from 'sigx/internals';
  export const moneyPack = { install(app) { provideTypeHandlers(app._context, [money]); } };
  ```

Registered handlers are consulted **before** the built-ins, so you can override a built-in for a type if you need to.

## Encode / revive by hand

When you hold a serialized tree yourself (a custom transport, a stored snapshot), run the codec directly:

```ts
import { encodeWithHandlers, reviveWithHandlers } from '@sigx/serialize';

const wire = JSON.stringify(encodeWithHandlers(value, [money]));
const back = reviveWithHandlers<Cart>(JSON.parse(wire), [money]);
```

`reviveWithHandlers<T>` types the result as `T` for callers that know the tree's shape — it's an **assertion, not validation**; nothing checks wire data against `T`. Only apply it to trees `encodeWithHandlers` produced.

---
url: https://sigx.dev/server/packages/server/overview/
title: Overview
description: Type-safe RPC for SignalX — call server code from a component as a plain async function with @sigx/server
---

# Server Functions

`@sigx/server` is how a SignalX app talks to its own server. You write an async
function, mark it as a server function, and call it from a component like any
other `async` function — the framework turns it into a typed RPC endpoint, runs
the body on the server, and returns the result. No REST routes to design, no
fetch wrappers to hand-write, no request/response DTOs to keep in sync.

> **Not the same as `@sigx/server-renderer`.** The
> [server renderer](/server/packages/server-renderer/overview) turns your
> component tree into HTML on the server. `@sigx/server` is the RPC layer — the
> way running components read and write server-side data. They compose, but you
> can use either on its own.

> **Need identity, ordering or memory between calls?** A server function is
> stateless by design. [`@sigx/actors`](/actors/) builds on this package —
> an actor call *is* a synthesized server function, inheriting these guards, this
> codec and this origin policy — and adds an addressable object that handles one
> call at a time and keeps its state.
> [Which to use](/actors/docs/actors-or-server-functions) is a short read.

```ts
// src/cart.server.ts — a server-only module
import { serverFn, ServerFnError } from '@sigx/server';
import { db } from './db';
import { sessionFrom } from './auth';

export const addToCart = serverFn(async (rq, productId: string, qty: number) => {
  const user = await sessionFrom(rq.request);
  if (!user) throw new ServerFnError(401, 'Sign in first');
  return db.cart.add(user.id, productId, qty);
});
```

```tsx
// any component — addToCart is just an async function here
import { useAction } from 'sigx';
import { addToCart } from './cart.server';

// useAction's fetcher takes ONE argument, so a multi-parameter server
// function is wrapped: the tuple is what you hand to run().
const add = useAction(
  ([sku, qty]: [string, number]) => addToCart(sku, qty),
  { cache: { invalidates: [['cart']] } },
);
// add.run(['sku-1', 1]) → POSTs to the server, runs the body, returns the row
```

The `db` and `sessionFrom` imports never reach the browser: the client build
replaces `*.server.ts` with typed fetch stubs, so the bundle ships only the
call signature. The server keeps the real module.

## What you get

- **Plain-function ergonomics.** A server function is called with its declared
  arguments and returns its declared type. Argument and return types flow from
  the definition to the call site — rename a parameter and every caller updates.
- **Value-first data flow.** Server functions are the natural fetchers for
  [`useData`](/core/docs/data-loading) (reads) and `useAction` (writes), so
  loading, error and refresh state come for free.
- **Secure by default.** Every server function is a public HTTP endpoint, and
  the runtime treats it as one: POST-only with a required JSON content type (a
  CSRF gate), a same-origin check, body-size limits, prod error masking and an
  app-wide guard hook. See [Deployment & security](/server/packages/server/deployment).
- **Streaming.** `serverStream` yields values over time (NDJSON on the wire) and
  plugs a string stream straight into `useStream` for token-at-a-time output.

## Requirements

Server functions ship with **SignalX 0.13+**. Install the package:

```bash
npm install @sigx/server
```

`@sigx/server` depends on `sigx` and `@sigx/serialize` (pulled in
automatically). During development the endpoint is served with zero config by
the `sigxServer()` Vite plugin from `@sigx/vite/server`; see
[Deployment & security](/server/packages/server/deployment) for the dev, production (Node)
and edge (WinterCG) wiring.

## The model in one paragraph

Each server function compiles to a stable, content-hashed symbol and is served
at `POST /_sigx/fn/<symbol>`. Calling the stub sends `{"args":[...]}` as JSON;
the server validates and runs the function and replies with `{"data":...}` or a
structured `{"error":{ message, status, data? }}`. Arguments cross the wire as
**typed values** — there is no closure serialization, so a server function can
only see what you pass it, its imports, and server-side globals. That single
constraint is what makes the boundary safe and the types honest.

## Next steps

- [Authoring server functions](/server/packages/server/usage) — the two forms,
  validation, the request context, errors and streaming.
- [Native clients](/server/packages/server/native-clients) — a lynx, terminal or
  installed app calling a remote backend over stubs.
- [Deployment & security](/server/packages/server/deployment) — dev, Node and edge wiring,
  plus the security defaults and how to relax them deliberately.

---
url: https://sigx.dev/terminal/docs/components/banner/
title: Banner
description: Large block-font headings with gradient fills
---

# Banner

<p class="lede">Renders <code>text</code> in a large block font and fills it with a gradient — a splash heading for a CLI's intro screen.</p>

## Import

```tsx
import { Banner } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Banner } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box>
            <Banner text="SIGX" preset="sigx" direction="diagonal" animate speed={1} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `text` | `string` | **required** — the heading |
| `colors` | `string[]` | gradient stops (tokens or hex) |
| `preset` | `GradientPreset` | a named gradient preset |
| `direction` | `'horizontal' \| 'vertical' \| 'diagonal'` | gradient direction |
| `animate` | `boolean` | animate the fill |
| `speed` | `number` | animation speed |

The block font is 5 rows tall (`BLOCK_FONT_HEIGHT`); `renderBlock(text)` is the headless renderer.

## See also

- [Gradient](/terminal/docs/components/gradient) — inline gradient text and the presets.
- [PixelArt](/terminal/docs/components/pixelart) — palette-mapped grids.

---
url: https://sigx.dev/terminal/docs/components/qrcode/
title: QRCode
description: A scannable QR code rendered as terminal cells
---

# QRCode

<p class="lede">Renders a string as a scannable QR code, drawn with half-block cells.</p>

## Import

```tsx
import { QRCode } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, QRCode } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box border="single" label="Scan to open">
            <QRCode text="https://sigx.dev/terminal/" quiet={2} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `text` | `string` | **required** — the data to encode |
| `invert` | `boolean` | swap dark/light modules (for light terminals) |
| `quiet` | `number` | quiet-zone border width in modules |

The headless `generateQR(text)` helper produces the underlying matrix if you want to render it yourself.

## See also

- [Table](/terminal/docs/components/table) — tabular data.

---
url: https://sigx.dev/server/packages/ssr-islands/api/
title: API reference
description: "@sigx/ssr-islands — every public export with signatures"
---

# API reference

<p class="lede">Every public export of `@sigx/ssr-islands` . The main entry re-exports the server and client surfaces; `/server`, `/client` and `/jsx` are the split entry points.</p>

## Server plugin

### islandsPlugin

Create the islands `SSRPlugin`. Register it on an SSR instance with `.use()`.
Server-side it maps `client:*` components onto boundary records, tracks signal
state, manages async streaming, and writes the hydration data into
`__SIGX_BOUNDARIES__`; client-side it schedules deferred hydration.

```ts
function islandsPlugin(options?: IslandsPluginOptions): SSRPlugin
```

- Exported from the main entry.

### IslandsPluginOptions

```ts
interface IslandsPluginOptions {
  strategies?: Record<string, (el: Element, hydrate: () => void) => void>;
  manifest?: Record<string, { chunkUrl: string; exportName: string }>;
}
```

- `strategies` — custom client-side hydration strategies, keyed by name.
- `manifest` — component → chunk-URL map (generated by `@sigx/vite`'s
  `sigxIslandsPlugin()`); enables on-demand chunk loading without eager
  registration.
- Exported as a type from the main entry.

## Client hydration

### hydrateIslands

Hydrate the page's islands according to their `client:*` strategies (selective
hydration). Call once after registering components.

```ts
function hydrateIslands(): void
```

### scheduleComponentHydration

Schedule one component's hydration for the given strategy; returns the next DOM
node after the component's content. Used internally by the plugin's hydration walk.

```ts
function scheduleComponentHydration(
  vnode: VNode, dom: Node | null, parent: Node,
  strategy: { strategy: 'load' | 'idle' | 'visible' | 'media' | 'only'; media?: string },
): Node | null
```

### initIslandHydration

Initialize island hydration with context accessors from the server renderer
(`getCurrentAppContext` / `setCurrentAppContext` / `setPendingServerState`). Called
by the plugin during setup.

```ts
function initIslandHydration(fns: {
  getCurrentAppContext: () => any;
  setCurrentAppContext: (ctx: any) => void;
  setPendingServerState: (state: Record<string, any> | null) => void;
}): void
```

### cleanupPendingHydrations

Tear down all pending deferred-hydration observers/listeners. Call on SPA
navigation to prevent `IntersectionObserver` / `matchMedia` leaks for islands that
have not triggered yet.

```ts
function cleanupPendingHydrations(): void
```

### invalidateMarkerIndex

Invalidate the cached island-marker index — call when the DOM changes (e.g. after
async component streaming) so the next hydration re-scans.

```ts
function invalidateMarkerIndex(): void
```

### hydrateLeftoverAsyncComponents

Hydrate async island components that streamed in after the initial walk.

```ts
function hydrateLeftoverAsyncComponents(): void
```

## Component registry

### registerComponent / registerComponents

Register island components eagerly by name, before `hydrateIslands()`.

```ts
function registerComponent(name: string, component: ComponentFactory): void
function registerComponents(components: Record<string, ComponentFactory>): void
```

### registerComponentChunk

Register a **lazy** island loader for code-split hydration; the loader's `import()`
runs only when the island's strategy triggers. Normally emitted automatically by
the `sigxIslandsPlugin` Vite transform. (Renamed from `__registerIslandChunk` in
0.13 — there is no alias.)

```ts
function registerComponentChunk(name: string, loader: LazyComponentLoader): void
```

### resolveComponent / getComponent / hasComponent

Resolve a component by name — `resolveComponent` checks eager then lazy (async,
cached, deduped); `getComponent` is sync (eager only); `hasComponent` reports
availability in either registry.

```ts
function resolveComponent(name: string): Promise<ComponentFactory | undefined>
function getComponent(name: string): ComponentFactory | undefined
function hasComponent(name: string): boolean
```

### HydrationRegistry

The class behind the module-level helpers, for isolated registry instances.

```ts
class HydrationRegistry {
  register(name: string, component: ComponentFactory): this;
  registerLazy(name: string, loader: LazyComponentLoader): this;
  registerAll(components: Record<string, ComponentFactory>): this;
  get(name: string): ComponentFactory | undefined;
  has(name: string): boolean;
  resolve(name: string): Promise<ComponentFactory | undefined>;
}
```

### ComponentFactory / LazyComponentLoader

```ts
interface ComponentFactory {
  __setup: Function;
  __name?: string;
  __islandId?: string;   // stable file-path identity (injected by the Vite plugin)
  __async?: boolean;
}
type LazyComponentLoader =
  () => Promise<ComponentFactory | { default: ComponentFactory; [key: string]: any }>;
```

- Exported as types from the main entry and `/client`.

## Chunk loading

### loadIslandComponent

Resolve an island's component across all paths (eager registry → lazy registry →
direct chunk URL from the manifest), with in-flight dedup.

```ts
function loadIslandComponent(info: IslandInfo): Promise<ComponentFactory | undefined>
```

### prefetchIslandChunks

Warm the browser cache with `<link rel="modulepreload">` for deferred islands.

```ts
function prefetchIslandChunks(islands: Record<string, IslandInfo>, strategies?: string[]): void
```

## Island data (client)

### getIslandData / getIslandServerState / invalidateIslandCache

Read the parsed island hydration data (from the `__SIGX_BOUNDARIES__` boundary
table), look up a rendered component's captured server state by its numeric render
id, or invalidate the cached island data.

```ts
function getIslandData(): Record<string, IslandInfo>
function getIslandServerState(componentId: number): Record<string, any> | undefined
function invalidateIslandCache(): void
```

> The `componentId` parameter here is the **numeric** id assigned to a component
> during render — not `IslandInfo.componentId`, which is a separate **string**
> identifier (path- or name-based) used to resolve the component on the client.

## Server utilities

### createTrackingSignal / serializeSignalState

Capture signal keys + values during setup, then serialize them onto the boundary
record's `state` for client hydration. Exported from the main entry and `/server`.

```ts
function createTrackingSignal(signalMap: Map<string, any>): SSRSignalFn
function serializeSignalState(signalMap: Map<string, any>): Record<string, any> | undefined
```

## Types

### IslandInfo

The per-island record serialized from server to client.

```ts
interface IslandInfo {
  strategy: HydrationStrategy;
  media?: string;
  props?: Record<string, any>;
  componentId?: string;
  state?: Record<string, any>;   // captured signal state
  placeholder?: string;          // streaming async placeholder HTML
  chunkUrl?: string;             // for lazy loading
  exportName?: string;
}
```

### HydrationStrategy

```ts
type HydrationStrategy = 'load' | 'idle' | 'visible' | 'media' | 'interaction' | 'only';
```

### ClientDirectives

The JSX attributes. They register program-wide when the pack is imported — there is
no directive-specific import.

```ts
interface ClientDirectives {
  'client:load'?: boolean;
  'client:idle'?: boolean;
  'client:visible'?: boolean;
  'client:media'?: string;
  'client:interaction'?: boolean;
  'client:only'?: boolean;
}
```

### PendingAsyncComponent / HydrationOptions

`PendingAsyncComponent` describes an in-flight async island (id, HTML promise,
captured `signalMap`, `islandInfo`); `HydrationOptions` carries `recover` and an
`onMismatch` callback. Both exported as types.

## Re-exports

For convenience the package re-exports the `SSRHelper` type from
`@sigx/server-renderer`.

## JSX types

The `client:*` attributes type-check with no import of their own. Importing
`@sigx/ssr-islands` (server) or `@sigx/ssr-islands/client` (client) — which your
entries already do — augments every JSX component in the program:

```tsx
<Counter client:visible />;
```

---
url: https://sigx.dev/terminal/docs/components/select/
title: Select
description: Single-choice menu with keyboard navigation and optional descriptions
---

# Select

<p class="lede">A focusable single-choice menu. ↑/<code>k</code> and ↓/<code>j</code> move the selection (wrapping); the chosen option is marked with <code>❯</code>.</p>

## Import

```tsx
import { Select } from '@sigx/terminal';
import type { SelectOption } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Select } from '@sigx/terminal';
import type { SelectOption } from '@sigx/terminal';

const options: SelectOption[] = [
    { label: 'Development', value: 'dev', description: 'Local dev build' },
    { label: 'Staging', value: 'staging', description: 'Pre-production' },
    { label: 'Production', value: 'prod', description: 'Live environment' },
];

const App = component(() => {
    const env = signal('dev');
    return () => (
        <box border="rounded" label="Deploy target">
            <Select
                options={options}
                model={() => env}
                label="Environment"
                showDescription
                autofocus
                onChange={(v) => console.log('selected:', v)}
                onSubmit={(v) => console.log('confirmed:', v)}
            />
            <br />
            <text>Target: {env.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `SelectOption[]` | **required** — the choices |
| `model` | `Model<string>` | two-way bound selected value |
| `label` | `string` | caption above the list |
| `autofocus` | `boolean` | grab focus on mount |
| `showDescription` | `boolean` | render the selected option's `description` below |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `string` | selection moves |
| `submit` | `string` | Enter |

## SelectOption

```ts
interface SelectOption<T = string> {
    label: string;
    value: T;
    description?: string;
}
```

## See also

- [Radio](/terminal/docs/components/radio) — every option always visible.
- [MultiSelect](/terminal/docs/components/multiselect) — choose several.
- [select() prompt](/terminal/docs/prompts) — the imperative form.

---
url: https://sigx.dev/terminal/packages/args/overview/
title: Overview
description: "@sigx/args — a fluent, type-aware command & argument parser where the builders you chain drive your handler's types"
---

# Args

<p class="lede">`@sigx/args` is a fluent, type-aware command and argument parser for CLIs. The arg builders you chain drive the **types** your handler receives — declare `port: a.number().required()` and `ctx.args.port` is `number`, not `number | undefined`.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> Zero dependencies <span class="mmr-dot" /> MIT</p>

It has **zero runtime dependencies**, is platform-neutral, and is the parser behind
`@sigx/cli` and the lynx CLI plugins. It ships from the terminal monorepo
(`signalxjs/terminal`, `packages/args`) but is **fully standalone** — install it on
its own, with or without a terminal UI:

```bash
npm install @sigx/args
```

## Quick start

```ts
import { a, command, runMain } from '@sigx/args';

const dev = command('dev')
    .describe('Start the dev server')
    .args({
        entry: a.positional().required().describe('Entry file'),
        port: a.number().alias('p').required().describe('Port to listen on'),
        host: a.string().default('localhost').describe('Host name'),
        mode: a.enum(['dev', 'prod']).describe('Build mode'),
        open: a.boolean().describe('Open the browser'),
    })
    .run((ctx) => {
        ctx.args.entry; // string                    (required → non-optional)
        ctx.args.port;  // number                    (required → non-optional)
        ctx.args.host;  // string                    (default → non-optional)
        ctx.args.mode;  // 'dev' | 'prod' | undefined
        ctx.args.open;  // boolean | undefined
        ctx.args._;     // string[]  (everything after `--`, verbatim)
    });

const main = command('sigx')
    .version('1.0.0')
    .describe('SignalX CLI')
    .subcommands({ dev });

await runMain(main);
```

`--help` / `-h` is handled automatically at every level (`sigx --help`, `sigx dev --help`), and `--version` at the root when `.version()` is set. The names `help` and `h` (and `version`, when set) are reserved — declaring an arg with one of them throws a `DefinitionError`.

## Arg builders

Declare each arg with a chainable `a.*` builder. The builder determines what it parses and the inferred type:

| Builder | Parses | Inferred type |
| --- | --- | --- |
| `a.string()` | `--name value`, `--name=value` | `string` (`\| undefined` unless `.required()` / `.default()`) |
| `a.number()` | finite numbers, including negative | `number` |
| `a.boolean()` | `--flag`, `--flag=false`, `--no-flag` | `boolean` |
| `a.enum(['a', 'b'])` | exact member match | `'a' \| 'b'` |
| `a.positional()` | non-flag tokens, in declaration order | `string` |
| `a.rest()` | remaining positional tokens | `string[]` (always present) |

## Refiners

Refiners chain, and each returns a **new** builder — they're immutable, so a base builder can be shared and re-refined safely:

| Refiner | Applies to | Effect |
| --- | --- | --- |
| `.required()` | all but `rest` | non-optional; parse fails when absent |
| `.default(v)` | all but `rest` | non-optional; `v` is type-checked (an enum default must be one of its options) |
| `.multiple()` | string, number, enum | repeatable flag → array, always present (`[]` when absent) |
| `.alias('p', …)` | flags | alternate names; single characters become short flags (`-p`) |
| `.negatable(false)` | boolean | disable the automatic `--no-x` negation |
| `.describe(text)` / `.valueHint(hint)` / `.hidden()` | all | help output |

Invalid combinations **don't typecheck**: the refiner either doesn't exist on that builder (`a.boolean().multiple()`, `a.positional().alias()`) or the chain is rejected (`a.string().default('x').required()`). The same rules are enforced at runtime for untyped callers.

## The command chain

```
command(name)
    .describe(text)
    .version(v)            // root only; enables --version
    .aliases(...)
    .hidden()
    .allowUnknownFlags()
    .args({ ... })         // once
    .subcommands({ ... })  // nested commands, may have their own aliases
    .run(handler)          // terminal: returns the finished Command
```

There is no `.build()`. A group without a handler is passed to `runMain` as-is; `.run()` is terminal, so declare `.args()` and `.subcommands()` before it.

## Parsing rules

- `--flag value`, `--flag=value`, short `-p value` / `-p=value`, boolean clusters `-abc`.
- Kebab and camel spellings both resolve: `--dry-run` and `--dryRun` both hit the `dryRun` key.
- Booleans never consume the next token; a flag-looking token is never read as a value (`--port --open` is `MISSING_VALUE`, not a silent swallow). Negative numbers (`-2`) are values.
- Bare `--` ends flag parsing; the remainder lands verbatim in `args._`.
- Unknown flags throw by default; `.allowUnknownFlags()` collects them into `ctx.unknownFlags` instead.
- Repeated flags: `.multiple()` appends, otherwise last wins.

## Errors

Parse failures throw a typed `ParseError` with a machine-readable `code` (`UNKNOWN_FLAG`, `MISSING_REQUIRED`, `INVALID_ENUM`, …) and structured `detail` (`arg`, `received`, `expected`, `command`), so a host can render rich error UI without string matching. Definition bugs (alias collisions, a required positional after an optional one, …) throw `DefinitionError` eagerly from `.args()`.

## Headless parsing

`parseArgs(argv, shape)` parses against a record of builders without any command — same inference, same validation:

```ts
import { a, parseArgs } from '@sigx/args';

const { args } = parseArgs(process.argv.slice(2), {
    port: a.number().required(),
    verbose: a.boolean(),
});
args.port;    // number
args.verbose; // boolean | undefined
```

## Headless help catalog

`buildHelpCatalog(cmd)` returns a fully structured `HelpCatalog` — flags, positionals, types, requiredness, defaults, enum options, subcommands, plus the synthesized `--help` / `--version` entries (`builtin: true`). The built-in `renderHelp(catalog)` formats it as plain text; a themed TUI help screen can consume the catalog directly instead of re-parsing strings. This is how a SignalX terminal app can render its own help.

## Embedding

`runMain` prints and sets `process.exitCode` (it never calls `process.exit`), with injectable `rawArgs` / `stdout` / `stderr`. For hosts that render errors themselves — an interactive shell, tests — `runCommand(cmd, { rawArgs })` resolves, parses, runs, and **throws** instead of printing.

## Next steps

- [Prompts](/terminal/docs/prompts/) — gather answers interactively after parsing args.
- [Terminal Dev](/terminal/packages/terminal-dev/overview/) — `sigx-terminal-dev` uses `@sigx/args` for its own flags.
- [`@sigx/cli`](/cli/) — the SignalX CLI, built on `@sigx/args`.

---
url: https://sigx.dev/actors/packages/actors-cli/api/
title: API reference
description: The plugin export and @sigx/actors-cli/source — the renderer-free data layer for building another front end
---

# API reference

<p class="lede">Exports of `@sigx/actors-cli` .</p>

## The plugin

The default export is a `definePlugin({ name: 'actors', detect, commands, tui })`. You do not

```json
"sigx-cli": { "plugin": "./dist/plugin.js", "requires": ">=0.9.0" }
```

`detect(cwd: string): boolean` is also exported; it is what decides whether the `actors`
commands appear, by checking that the project depends on `@sigx/actors`.

## `@sigx/actors-cli/source`

The renderer-free data layer, for anyone building another front end over the same data.

| Export | Role |
|---|---|
| `httpSource(options)` | poll a running host's ops endpoint |
| `embeddedSource(options)` | load an app module in-process |
| `hostViewFromReport(report)` | a `HostReport` → `HostView` |
| `rateBetween(a, b)` | derive a rate from two samples |
| `RateTracker` | stateful rate tracking |
| `* as format` | the display formatters the dashboard uses |

Types: `MonitorSource`, `MonitorSnapshot`, `HostView`, `ClusterView`, `HttpSourceOptions`,
`EmbeddedSourceOptions`, `Series`, `Rate`, `RateSample`. Errors: `OpsRequestError`,
`EmbeddedSourceError`.

## The counter-reset rule

> **A counter going backwards is a reset, and must yield a gap rather than a rate.**

[`metrics().reset()`](/actors/docs/metrics) exists, and a host restart re-zeros everything.
Computing `(now - then) / dt` across that boundary produces a large negative or wildly wrong
rate, which on a graph looks like an incident that did not happen.

`rateBetween` returns nothing for a decreasing pair. If you build your own, do the same.

## Next steps

- [Overview](/actors/packages/actors-cli/overview) — the two modes.
- [Installation](/actors/packages/actors-cli/installation) — flags and exit codes.
- [Observability](/actors/docs/observability) — Prometheus and OTel instead.

---
url: https://sigx.dev/actors/packages/actors-k8s/api/
title: API reference
description: Exports of @sigx/actors-k8s — k8sMembership and kubeClient — plus heartbeat, discovery, fencing and exit behaviour
---

# API reference

<p class="lede">Exports of `@sigx/actors-k8s` .</p>

## `k8sMembership(options?)`

Returns a `ClusterMembership`. Pair it with a directory provider — this package does not
supply one.

```ts
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(redis) },
    advertise, secret,
});
```

Options are documented in [Installation](/actors/packages/actors-k8s/installation#options).

## `kubeClient(options?)`

The minimal HTTPS + JSON client the provider uses, exported for reuse. Types: `KubeClient`,
`KubeClientOptions`.

## Constants

| Export | Value | Purpose |
|---|---|---|
| `CLUSTER_LABEL` | `sigx.dev/cluster` | selects peers; lets two clusters share a namespace |
| `DESCRIPTOR_ANNOTATION` | `sigx.dev/descriptor` | carries the host descriptor JSON |

## Types

`K8sMembershipOptions`, `KubeClient`, `KubeClientOptions`.

## Behaviour

**Heartbeat** — a merge-patch of `spec.renewTime` every `heartbeatMs`. No read-modify-write,
so no `resourceVersion` races.

**Discovery** — the standard list-then-watch loop over Leases matching this host's labels. A
peer is live while its `renewTime` is within its own declared duration.

Watch events for renewals **never bump the membership view's version** — only descriptor-set
changes do (join, leave, drain, expiry), so heartbeats cause zero `onChange` traffic.

**Self-fencing** — renewal failures past `ttlMs` fire `onSelfSuspect` once: the host stops
claiming actors and deactivates what it holds. See
[Health & readiness](/actors/docs/health-and-readiness), where this surfaces as the `fatal`
state.

> A broken **watch** never fences. That is staleness, not death, and the `relistMs` safety net
> covers it.

**Graceful exit** — `setStatus('leaving')` patches the descriptor immediately, so a drain is
visible now rather than next beat; `leave()` deletes the Lease. A crashed host simply stops
renewing and ages out.

**Versions** — `view().version` is a local monotonic counter. Kubernetes `resourceVersion` is
an opaque watch bookmark and is never interpreted.

State integrity never rests on any of this: the runtime's storage etag CAS remains the floor,
exactly as with every other provider.

## Next steps

- [Overview](/actors/packages/actors-k8s/overview) — what it replaces.
- [Installation](/actors/packages/actors-k8s/installation) — RBAC and options.
- [Kubernetes deployment](/actors/docs/kubernetes) — the surrounding manifest.

---
url: https://sigx.dev/actors/packages/actors-tcp/api/
title: API reference
description: Exports of @sigx/actors-tcp — tcpTransport, the transport name constant and the re-exported frame codec
---

# API reference

<p class="lede">Exports of `@sigx/actors-tcp` .</p>

## `tcpTransport(options?)`

Returns a `HostTransportFactory` for `cluster({ transport })`.

```ts
interface TcpTransportOptions {
    port?: number;
    host?: string;
    advertiseHost?: string;        // what peers dial — see Installation
    maxFrameBytes?: number;
    credit?: number;
    keepAliveMs?: number;          // 15000
    handshakeTimeoutMs?: number;   // 10000 — 0 disables
    maxPendingInbound?: number;    // 256 — 0 disables
}
```

`handshakeTimeoutMs` and `maxPendingInbound` bound what an unauthenticated peer can hold open:
a connection that never completes its handshake is dropped, and the number of in-flight
inbound connections awaiting one is capped.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>This transport binds all interfaces unless <code>host</code> is set, and speaks no
    TLS.</strong> It belongs on a private network. Set <code>host</code> to the interface you
    mean, and do not expose the port.
  </div>
</div>

## Constants

| Export | Value |
|---|---|
| `TCP_TRANSPORT_NAME` | `'tcp'` — the key under `HostDescriptor.addresses` |

## Re-exported frame codec

The codec from [`@sigx/actors/cluster/frames`](/actors/docs/entry-points), re-exported here
for transport authors:

`DEFAULT_CREDIT`, `DEFAULT_MAX_FRAME_BYTES`, `encodeFrame`, `FrameType`.

The same codec is available from `@sigx/actors/cluster/frames`.

## Writing your own transport

`transportConformance` holds the cases a transport must pass and is the definition of correct
behaviour. It is currently **contributor-facing only** — reachable inside the actors workspace
as `@sigx/actors/cluster/testing` through a tsconfig and vitest alias, but not in the published
`exports` map.

The rule it enforces throughout: *assert on the error `kind`, never on an HTTP status*. That
is what makes the contract expressible off HTTP at all.

## Next steps

- [Overview](/actors/packages/actors-tcp/overview) — the measured case for it.
- [Installation](/actors/packages/actors-tcp/installation) — options and `advertiseHost`.
- [Host transports](/actors/docs/transports) — the comparison and rollout.

---
url: https://sigx.dev/core/packages/reactivity/usage/
title: Usage
description: Using Reactivity in a SignalX app — signals, computed & effects patterns and examples with @sigx/reactivity.
---

# Using Reactivity

<p class="lede">Signals, computed & effects — the essentials.</p>

`@sigx/reactivity` is the Core reactivity engine that powers the whole `sigx` umbrella. The runtime packages build their rendering on top of these same primitives, so everything you learn here applies framework-wide. You can also use the package standalone for state management with no DOM involved.

## Basic usage

Wrap state in a `signal`, derive from it with `computed`, and react to changes with `effect`. Effects run once immediately and then re-run whenever any signal they read changes.

```ts
import { signal, computed, effect } from '@sigx/reactivity';

const count = signal(0);
const doubled = computed(() => count.value * 2);

effect(() => {
  console.log(count.value, doubled.value);
});
// logs: 0 0

count.value++;
// logs: 1 2
```

Primitive signals are accessed through `.value`. Reading `.value` inside an `effect` or `computed` subscribes that consumer to future changes; writing `.value` notifies subscribers.

## Reactive objects and arrays

When you pass an object or array to `signal`, you get a deeply reactive proxy instead of a `.value` box. Mutate properties directly — there is no `.value` to unwrap. Use the proxy's `$set` method when you need to replace the whole value at once.

```ts
import { signal, computed, effect } from '@sigx/reactivity';

const user = signal({ name: 'Alice', tags: ['admin'] });
const summary = computed(() => `${user.name} (${user.tags.length})`);

effect(() => console.log(summary.value));
// logs: Alice (1)

user.name = 'Bob';        // logs: Bob (1)
user.tags.push('editor'); // logs: Bob (2)
user.$set({ name: 'Carol', tags: [] }); // logs: Carol (0)
```

Nested objects become reactive lazily on first access, and array mutator methods like `push`, `splice`, and `sort` are batched automatically. Note that exotic built-ins such as `Date` and `RegExp` are returned unwrapped and are not reactive.

## Enumerating a reactive object

Enumeration inside an effect or computed — `Object.keys()`, `for…in`, spread,
rest destructuring — subscribes to the object's **key set**, so adding or
deleting a key re-runs the reader:

```ts
import { signal, effect, batch } from '@sigx/reactivity';

const config = signal<Record<string, string>>({ theme: 'dark' });

effect(() => console.log(Object.keys(config).length));
// logs: 1

config.locale = 'sv';   // logs: 2
delete config.theme;    // logs: 1
```

The key-set dependency sits alongside the per-key ones. `Object.keys()` reads no
values, so it re-runs only when the key set changes; a spread copies every value,
so it re-runs on a value change too. `'theme' in config` subscribes to the same
dependency `config.theme` would.

Arrays carry their enumeration dependency on `length` instead, and Maps and Sets
keep their own iteration and `.size` tracking. Since every inserted key notifies
enumerating readers, bulk insertion belongs in a `batch`:

```ts
batch(() => {
    for (const [key, value] of entries) config[key] = value;
});
```

## Destructuring without losing reactivity

Destructuring a reactive object snapshots its values — `const { name } = user` is just a plain string afterwards. Use `toSignal` (one property) or `toSignals` (every property) to get `{ value }` views that read and write through to the source:

```ts
import { signal, effect, toSignal, toSignals } from '@sigx/reactivity';

const user = signal({ name: 'Alice', age: 30 });

const name = toSignal(user, 'name');
effect(() => console.log(name.value)); // logs: Alice
user.name = 'Bob';                     // logs: Bob
name.value = 'Carol';                  // writes through; logs: Carol

const { age } = toSignals(user);
age.value++;                           // user.age is now 31
```

`toSignals` creates views for every own enumerable string key except `$set`.

## Batching updates

Multiple synchronous writes each notify subscribers. Wrap them in `batch` so dependent effects flush only once, after the function returns. `batch` is nestable — only the outermost batch triggers the flush.

```ts
import { signal, effect, batch } from '@sigx/reactivity';

const count = signal(0);
effect(() => console.log(count.value));
// logs: 0

batch(() => {
  count.value++;
  count.value++;
  count.value++;
});
// logs: 3 (once, not three times)
```

## Watching for changes

Use `watch` when you need the previous value, lazy callbacks (no immediate run), or cleanup hooks. The source is either a getter or a value; the callback receives the new value, the old value, and an `onCleanup` registrar that runs before the next callback and on stop.

```ts
import { signal, watch } from '@sigx/reactivity';

const query = signal('');

const handle = watch(
  () => query.value,
  (next, prev, onCleanup) => {
    const controller = new AbortController();
    onCleanup(() => controller.abort());
    console.log(`searching "${next}" (was "${prev}")`);
  },
  { immediate: false, deep: false }
);

query.value = 'sigx'; // fires the callback

handle.stop(); // or call handle() directly to stop
```

`watch` supports `immediate` (fire once at setup with `oldValue` undefined), `deep` (a boolean for full traversal or a number for limited depth), and `once` (stop after the first delivered callback). The returned `WatchHandle` is callable to stop and also exposes `stop`, `pause`, and `resume`.

## Disposing effects

`effect` returns an `EffectRunner` — a callable that re-runs the effect, with a `.stop()` method to dispose it. This package does not tie cleanup to any component lifecycle, so you are responsible for stopping effects and watches you create outside the runtime.

```ts
import { signal, effect } from '@sigx/reactivity';

const count = signal(0);
const runner = effect(() => console.log(count.value));

count.value++; // logs the new value
runner.stop(); // future changes are ignored
```

To dispose a batch of reactive work in one call, create it inside an `effectScope`. Stopping the scope disposes every effect and watcher created inside `run()`; nested scopes stop with their parent unless created detached (`effectScope(true)`).

```ts
import { signal, effect, watch, effectScope } from '@sigx/reactivity';

const count = signal(0);
const scope = effectScope();

scope.run(() => {
  effect(() => console.log('count is', count.value));
  watch(() => count.value, (next) => console.log('changed to', next));
});

count.value++; // both run
scope.stop();  // both disposed
count.value++; // nothing runs
```

To read a signal without subscribing to it, wrap the read in `untrack`:

```ts
import { signal, effect, untrack } from '@sigx/reactivity';

const a = signal(1);
const b = signal(10);

effect(() => {
  // re-runs when `a` changes, but not when `b` changes
  console.log(a.value + untrack(() => b.value));
});
```

## Writable computeds

Pass a `{ get, set }` options object to `computed` to create a two-way derived value. Assigning to `.value` routes through your setter.

```ts
import { signal, computed } from '@sigx/reactivity';

const celsius = signal(0);
const fahrenheit = computed({
  get: () => celsius.value * 9 / 5 + 32,
  set: (f) => { celsius.value = (f - 32) * 5 / 9; },
});

fahrenheit.value = 212;
console.log(celsius.value); // 100
```

## Next steps

See the [API reference](/core/packages/reactivity/api) for the complete typed surface, or the [Installation](/core/packages/reactivity/installation) guide for project setup.

---
url: https://sigx.dev/daisyui/docs/components/avatar/
title: Avatar
description: User profile images with various sizes and shapes
---

# Avatar

Avatars represent users or entities with images or placeholders.

## Import

```tsx
import { Avatar } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Avatar } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Avatar src="https://i.pravatar.cc/150?u=1" alt="User avatar" />
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar size="xs" src="https://i.pravatar.cc/150?u=1" />
            <Avatar size="sm" src="https://i.pravatar.cc/150?u=2" />
            <Avatar size="md" src="https://i.pravatar.cc/150?u=3" />
            <Avatar size="lg" src="https://i.pravatar.cc/150?u=4" />
            <Avatar size="xl" src="https://i.pravatar.cc/150?u=5" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Shapes

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar shape="circle" src="https://i.pravatar.cc/150?u=10" />
            <Avatar shape="rounded" src="https://i.pravatar.cc/150?u=11" />
            <Avatar shape="square" src="https://i.pravatar.cc/150?u=12" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Mask Shapes

Use mask-based shapes for unique avatar outlines.

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar shape="squircle" src="https://i.pravatar.cc/150?u=13" />
            <Avatar shape="hexagon" src="https://i.pravatar.cc/150?u=14" />
            <Avatar shape="heart" src="https://i.pravatar.cc/150?u=15" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Online / Offline Status

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar src="https://i.pravatar.cc/150?u=30" online />
            <Avatar src="https://i.pravatar.cc/150?u=31" offline />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Placeholder

When no image is provided, show initials or text.

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar placeholder="AB" />
            <Avatar placeholder="CD" class="bg-primary text-primary-content" />
            <Avatar placeholder="EF" class="bg-secondary text-secondary-content" />
            <Avatar placeholder="GH" class="bg-accent text-accent-content" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## With Ring

Add a ring border around the avatar.

```tsx
import { component, render } from 'sigx';
import { Avatar, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Avatar src="https://i.pravatar.cc/150?u=40" ring />
            <Avatar src="https://i.pravatar.cc/150?u=41" ring ringColor="secondary" />
            <Avatar src="https://i.pravatar.cc/150?u=42" ring ringColor="accent" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Avatar Group

Display multiple avatars overlapping.

```tsx
import { component, render } from 'sigx';
import { Avatar } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Avatar.Group>
            <Avatar src="https://i.pravatar.cc/150?u=20" size="sm" />
            <Avatar src="https://i.pravatar.cc/150?u=21" size="sm" />
            <Avatar src="https://i.pravatar.cc/150?u=22" size="sm" />
            <Avatar src="https://i.pravatar.cc/150?u=23" size="sm" />
            <Avatar placeholder="+5" size="sm" class="bg-neutral text-neutral-content" />
        </Avatar.Group>
    );
});

render(<Demo />, "#sandbox");
```

## Avatar Group with Custom Spacing

```tsx
import { component, render } from 'sigx';
import { Avatar } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Avatar.Group spacing={3}>
            <Avatar src="https://i.pravatar.cc/150?u=50" size="sm" />
            <Avatar src="https://i.pravatar.cc/150?u=51" size="sm" />
            <Avatar src="https://i.pravatar.cc/150?u=52" size="sm" />
        </Avatar.Group>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | `undefined` | Image URL |
| `alt` | `string` | `'Avatar'` | Alt text for image |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Avatar size |
| `shape` | `'circle' \| 'rounded' \| 'square' \| 'squircle' \| 'hexagon' \| 'heart'` | `'circle'` | Avatar shape |
| `online` | `boolean` | `false` | Show online indicator |
| `offline` | `boolean` | `false` | Show offline indicator |
| `placeholder` | `string` | `undefined` | Text to show when no image (e.g., initials) |
| `ring` | `boolean` | `false` | Add ring border |
| `ringColor` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'neutral'` | `'primary'` | Ring border color |
| `class` | `string` | `undefined` | Additional CSS classes |

## Avatar.Group Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `spacing` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10` | `6` | Overlap spacing |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/button/
title: Button
description: Interactive button component with multiple variants, sizes, and states
---

# Button

Buttons allow users to take actions with a single tap. They come in various styles and sizes.

## Import

```tsx
import { Button, ButtonGroup, Row } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button>Default</Button> 
            <Button variant="primary">Primary</Button>
            <Button variant="secondary">Secondary</Button>
            <Button variant="accent">Accent</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

Use the `variant` prop to change the button style.

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button variant="neutral">Neutral</Button>
            <Button variant="primary">Primary</Button>
            <Button variant="secondary">Secondary</Button>
            <Button variant="accent">Accent</Button>
            <Button variant="info">Info</Button>
            <Button variant="success">Success</Button>
            <Button variant="warning">Warning</Button>
            <Button variant="error">Error</Button>
            <Button variant="ghost">Ghost</Button>
            <Button variant="link">Link</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

Use the `size` prop to change button size.

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" align="center" wrap>
            <Button size="xs">Extra Small</Button>
            <Button size="sm">Small</Button>
            <Button size="md">Medium</Button>
            <Button size="lg">Large</Button>
            <Button size="xl">Extra Large</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## States

Buttons support `disabled` and `loading` states.

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button disabled>Disabled</Button>
            <Button loading>Loading</Button>
            <Button variant="primary" loading>Saving...</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Styles

Use `outline`, `soft`, or `dash` for alternative styles.

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button variant="primary" outline>Outline</Button>
            <Button variant="primary" soft>Soft</Button>
            <Button variant="primary" dash>Dash</Button>
            <Button variant="primary">Solid</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Shapes

Use `square` or `circle` for icon-only buttons.

```tsx
import { component, render } from 'sigx';
import { Button, Row, Text } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button square variant="primary"><Text>A</Text></Button>
            <Button circle variant="primary"><Text>B</Text></Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Wide and Block

Use `wide` for a wider button or `block` for full width.

```tsx
import { component, render } from 'sigx';
import { Button, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Button wide variant="primary">Wide</Button>
            <Button block variant="primary">Block</Button>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Active

Force the active state with the `active` prop.

```tsx
import { component, render } from 'sigx';
import { Button, Row } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Button variant="primary">Default</Button>
            <Button variant="primary" active>Active</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Button Group

Group related buttons together.

```tsx
import { component, render } from 'sigx';
import { Button, ButtonGroup } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <ButtonGroup>
            <Button>Left</Button>
            <Button>Center</Button>
            <Button>Right</Button>
        </ButtonGroup>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Button Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'ghost' \| 'link'` | `undefined` | Button color variant |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Button size |
| `outline` | `boolean` | `false` | Use outline style |
| `soft` | `boolean` | `false` | Use soft style |
| `dash` | `boolean` | `false` | Use dashed-border style |
| `wide` | `boolean` | `false` | Wider button |
| `block` | `boolean` | `false` | Full-width button |
| `square` | `boolean` | `false` | Square shape (icon button) |
| `circle` | `boolean` | `false` | Circle shape (icon button) |
| `active` | `boolean` | `false` | Force active state |
| `disabled` | `boolean` | `false` | Disable the button |
| `loading` | `boolean` | `false` | Show loading spinner |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |
| `class` | `string` | `undefined` | Additional CSS classes |

### ButtonGroup Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/drawer/
title: Drawer
description: Side panel component for navigation and mobile menus
---

# Drawer

Slide-out side panel for navigation, filters, and mobile menus with model binding support.

## Import

```tsx
import { Drawer, Text } from '@sigx/daisyui';
```

## Basic Drawer

Use `model` for two-way binding to control drawer visibility. The Drawer component should wrap your main content:

```tsx
import { component, render } from 'sigx';
import { Drawer, Button, Card, Col, Menu, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const drawer = signal({ open: false });
    
    return () => (
        <Card class="relative h-56 overflow-hidden">
            <Drawer 
                model={() => drawer.open}
                slots={{
                    side: () => (
                        <Menu padding="4" width="60" background="base-200" class="md:w-80 min-h-full">
                            <Menu.Item value="item-1">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 1</Text>
                            </Menu.Item>
                            <Menu.Item value="item-2">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 2</Text>
                            </Menu.Item>
                        </Menu>
                    )
                }}
            >
                <Col align="center" justify="center" class="h-full bg-base-100">
                    <Button onClick={() => drawer.open = true}>
                        Open Drawer
                    </Button>
                </Col>
            </Drawer>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Drawer Positions

### Right Side Drawer

Use `side="right"` (adds `drawer-end` class) to open the drawer from the right:

```tsx
import { component, render } from 'sigx';
import { Drawer, Button, Card, Col, Menu, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const drawer = signal({ open: false });
    
    return () => (
        <Card class="relative h-56 overflow-hidden">
            <Drawer 
                model={() => drawer.open} 
                side="right"
                slots={{
                    side: () => (
                        <Menu padding="4" width="60" background="base-200" class="md:w-80 min-h-full">
                            <Menu.Item value="item-1">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 1</Text>
                            </Menu.Item>
                            <Menu.Item value="item-2">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 2</Text>
                            </Menu.Item>
                        </Menu>
                    )
                }}
            >
                <Col align="center" justify="center" class="h-full bg-base-100">
                    <Button onClick={() => drawer.open = true}>
                        Open Right Drawer
                    </Button>
                </Col>
            </Drawer>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Navbar with Drawer

A common pattern with navbar and drawer for mobile navigation:

```tsx
import { component, render } from 'sigx';
import { Drawer, Button, Card, Navbar, Col, Row, Menu, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const drawer = signal({ open: false });
    
    return () => (
        <Card class="relative h-56 overflow-hidden">
            <Drawer 
                model={() => drawer.open}
                slots={{
                    side: () => (
                        <Menu padding="4" width="60" background="base-200" class="md:w-80 min-h-full">
                            <Menu.Item value="item-1">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 1</Text>
                            </Menu.Item>
                            <Menu.Item value="item-2">
                                <Text as="span" onClick={() => drawer.open = false}>Sidebar Item 2</Text>
                            </Menu.Item>
                        </Menu>
                    )
                }}
            >
                <Col class="drawer-content">
                    <Navbar width="full" background="base-300">
                        <Button variant="ghost" shape="square" onClick={() => drawer.open = true}>
                            <Text as="span" size="xl">☰</Text>
                        </Button>
                        <Text as="span" weight="semibold">Navbar Title</Text>
                        <Menu horizontal class="hidden lg:flex">
                            <Menu.Item value="nav-1"><Text as="span">Navbar Item 1</Text></Menu.Item>
                            <Menu.Item value="nav-2"><Text as="span">Navbar Item 2</Text></Menu.Item>
                        </Menu>
                    </Navbar>
                    <Row justify="center" align="center" class="grow">Content</Row>
                </Col>
            </Drawer>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Responsive Drawer

Drawer that's always visible on large screens using `responsive` prop (adds `lg:drawer-open` class):

```tsx
import { component, render } from 'sigx';
import { Drawer, Button, Card, Col, Menu, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const drawer = signal({ open: false });
    
    return () => (
        <Card class="relative h-56 overflow-hidden">
            <Drawer 
                model={() => drawer.open} 
                responsive
                slots={{
                    side: () => (
                        <Menu padding="4" width="60" background="base-200" class="md:w-80 min-h-full">
                            <Menu.Item value="item-1"><Text as="span">Sidebar Item 1</Text></Menu.Item>
                            <Menu.Item value="item-2"><Text as="span">Sidebar Item 2</Text></Menu.Item>
                        </Menu>
                    )
                }}
            >
                <Col align="center" justify="center" class="h-full bg-base-100">
                    <Button class="lg:hidden" onClick={() => drawer.open = true}>
                        Open Drawer
                    </Button>
                    <Text class="hidden lg:block">Sidebar is always visible on large screens</Text>
                </Col>
            </Drawer>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Filter Drawer

A right-side filter panel commonly used in e-commerce:

```tsx
import { component, render } from 'sigx';
import { Drawer, Button, Card, Col, FormField, Heading, Range, Select, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const drawer = signal({ open: false, category: '', price: 50 });
    
    return () => (
        <Card class="relative h-64 overflow-hidden">
            <Drawer 
                model={() => drawer.open} 
                side="right"
                slots={{
                    side: () => (
                        <Col gap="4" padding="4" width="60" background="base-200" class="md:w-80 min-h-full">
                            <Heading level={2} size="xl">Filters</Heading>
                            <FormField label="Category">
                                <Select
                                    model={() => drawer.category}
                                    variant="bordered"
                                    options={[
                                        { value: 'all', label: 'All' },
                                        { value: 'electronics', label: 'Electronics' },
                                        { value: 'clothing', label: 'Clothing' },
                                    ]}
                                />
                            </FormField>
                            <FormField label="Price Range">
                                <Range model={() => drawer.price} />
                            </FormField>
                            <Button 
                                variant="primary" 
                                class="w-full"
                                onClick={() => drawer.open = false}
                            >
                                Apply Filters
                            </Button>
                        </Col>
                    )
                }}
            >
                <Col align="center" justify="center" class="h-full bg-base-100">
                    <Text as="p">Product listing content</Text>
                    <Button variant="primary" onClick={() => drawer.open = true}>
                        Open Filters
                    </Button>
                </Col>
            </Drawer>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => boolean` | - | Two-way binding for open state |
| `side` | `'left' \| 'right'` | `'left'` | Which side the drawer opens from |
| `responsive` | `boolean` | `false` | Always visible on large screens (`lg:drawer-open`) |
| `background` | `BackgroundColor` | - | Side panel (`.drawer-side`) background |
| `rounded` | `RadiusValue \| boolean` | - | Side panel rounding |
| `width` | `SizeValue` | - | Side panel width — Tailwind step (`"60"`) or unitful value |
| `padding` | `Spacing` | - | Side panel padding |
| `class` | `string` | - | Additional CSS classes (drawer root) |

## Slots

| Slot | Description |
|------|-------------|
| `default` | Main content area (goes in `drawer-content`) |
| `side` | Drawer sidebar content (goes in `drawer-side`) |

## DaisyUI Classes Reference

| Class | Description |
|-------|-------------|
| `drawer` | The wrapper for sidebar and content |
| `drawer-toggle` | Hidden checkbox that controls the state |
| `drawer-content` | Content part |
| `drawer-side` | Sidebar part |
| `drawer-overlay` | Label that covers the page when open |
| `drawer-end` | Opens drawer from the right side |
| `drawer-open` | Forces the drawer to be open |

---
url: https://sigx.dev/daisyui/docs/components/rating/
title: Rating
description: Star rating component with model binding for user ratings
---

# Rating

Rating component allows users to provide feedback using stars or other shapes. Supports sizes, half-star ratings, mask shapes, colors, and model binding.

## Import

```tsx
import { Rating, Row, Col, Text, Card } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Rating, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const rating = signal({ value: 3 });

    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Rating model={() => rating.value} />
                <Text size="sm">Rating: {rating.value} stars</Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

All five size variants: `xs`, `sm`, `md`, `lg`, `xl`.

```tsx
import { component, render } from 'sigx';
import { Rating, Text, Row, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const r1 = signal({ v: 3 });
    const r2 = signal({ v: 3 });
    const r3 = signal({ v: 3 });
    const r4 = signal({ v: 3 });
    const r5 = signal({ v: 3 });

    return () => (
        <Col gap="4">
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-16">xs:</Text>
                <Rating model={() => r1.v} size="xs" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-16">sm:</Text>
                <Rating model={() => r2.v} size="sm" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-16">md:</Text>
                <Rating model={() => r3.v} size="md" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-16">lg:</Text>
                <Rating model={() => r4.v} size="lg" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-16">xl:</Text>
                <Rating model={() => r5.v} size="xl" />
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Rating, Text, Row, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const ratings = signal({
        primary: 4,
        secondary: 3,
        accent: 5,
        info: 4,
        success: 3,
        warning: 4,
        error: 2
    });

    return () => (
        <Col gap="4">
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Primary:</Text>
                <Rating model={() => ratings.primary} color="primary" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Secondary:</Text>
                <Rating model={() => ratings.secondary} color="secondary" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Accent:</Text>
                <Rating model={() => ratings.accent} color="accent" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Info:</Text>
                <Rating model={() => ratings.info} color="info" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Success:</Text>
                <Rating model={() => ratings.success} color="success" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Warning:</Text>
                <Rating model={() => ratings.warning} color="warning" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Error:</Text>
                <Rating model={() => ratings.error} color="error" />
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Mask Shapes

Different shapes for rating icons using the `mask` prop.

```tsx
import { component, render } from 'sigx';
import { Rating, Text, Row, Col } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const ratings = signal({
        star: 4,
        star2: 4,
        heart: 3,
        circle: 5,
        diamond: 4,
        hexagon: 3,
        triangle: 4
    });

    return () => (
        <Col gap="4">
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Star:</Text>
                <Rating model={() => ratings.star} mask="star" color="warning" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Star 2:</Text>
                <Rating model={() => ratings.star2} mask="star-2" color="warning" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Heart:</Text>
                <Rating model={() => ratings.heart} mask="heart" color="error" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Circle:</Text>
                <Rating model={() => ratings.circle} mask="circle" color="primary" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Diamond:</Text>
                <Rating model={() => ratings.diamond} mask="diamond" color="accent" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Hexagon:</Text>
                <Rating model={() => ratings.hexagon} mask="hexagon" color="secondary" />
            </Row>
            <Row align="center" gap="4">
                <Text as="span" size="sm" class="w-24">Triangle:</Text>
                <Rating model={() => ratings.triangle} mask="triangle" color="info" />
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Half Stars

Enable half-star ratings for more precise feedback using the `half` prop.

```tsx
import { component, render } from 'sigx';
import { Rating, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const rating = signal({ value: 3.5 });

    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Rating model={() => rating.value} half color="warning" size="lg" />
                <Text size="sm">Rating: {rating.value} stars</Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Read-Only

Display ratings without user interaction using the `readOnly` prop.

```tsx
import { component, render } from 'sigx';
import { Rating, Col, Row, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const r1 = signal({ v: 4 });
    const r2 = signal({ v: 3 });
    const r3 = signal({ v: 5 });

    return () => (
        <Col gap="4">
            <Row align="center" gap="4">
                <Rating model={() => r1.v} readOnly color="warning" />
                <Text size="sm" class="opacity-70">4 stars (read-only)</Text>
            </Row>
            <Row align="center" gap="4">
                <Rating model={() => r2.v} readOnly mask="heart" color="error" />
                <Text size="sm" class="opacity-70">3 hearts (read-only)</Text>
            </Row>
            <Row align="center" gap="4">
                <Rating model={() => r3.v} readOnly color="primary" />
                <Text size="sm" class="opacity-70">5 stars (read-only)</Text>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Hidden (Clearable)

The component includes a hidden first radio input so the user can deselect all stars (clear the rating to 0).

```tsx
import { component, render } from 'sigx';
import { Rating, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const rating = signal({ value: 0 });

    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Rating model={() => rating.value} color="warning" size="lg" />
                <Text size="sm">
                    {rating.value === 0 ? 'No rating selected (click a star, then click the same star to clear)' : `${rating.value} out of 5`}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Max

```tsx
import { component, render } from 'sigx';
import { Rating, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const rating = signal({ value: 7 });

    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Rating model={() => rating.value} max={10} color="warning" />
                <Text size="sm">Rating: {rating.value}/10</Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for rating value |
| `max` | `number` | `5` | Maximum number of stars |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Size of the rating icons |
| `mask` | `'star' \| 'star-2' \| 'heart' \| 'circle' \| 'diamond' \| 'hexagon' \| 'decagon' \| 'triangle'` | `'star-2'` | Shape of the rating icons |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Color of filled icons (defaults to orange) |
| `half` | `boolean` | `false` | Enable half-star ratings |
| `readOnly` | `boolean` | `false` | Disable user interaction |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(value: number) => void` | Fired when rating changes |

---
url: https://sigx.dev/core/packages/runtime-core/api/
title: API reference
description: API reference for @sigx/runtime-core — every export of the SignalX Runtime Core package.
---

# API reference

<p class="lede">Exports of `@sigx/runtime-core` .</p>

All examples assume a named import from the package root:

```ts
import { component, defineApp } from '@sigx/runtime-core';
```

The package also exposes `./jsx-runtime` and `./jsx-dev-runtime` subpaths (both aliasing the main build) for TSX transpilation via `jsxImportSource`, a separate `./internals` entry for renderer authors, and an `./inspect` entry with the inspection-only topic registry for tooling (see [Inspection](#inspection-sigxruntime-coreinspect)).

## Component system

### component

Define a component from a `setup` function that returns a render (view) function. `setup` runs once; the returned function is the reactive render. Setup may be sync or async — async setup is awaited during SSR and errors on the client (`SIGX102`).

```ts
function component<
  TCombined extends Record<string, any> = {},
  TRef = ExtractExposed<TCombined>,
  TSlots = ExtractSlots<TCombined>
>(
  setup: (ctx: ComponentSetupContext<PlatformElement, StripInternalMarkers<TCombined>, TCombined, TRef, TSlots>) => ViewFn | Promise<ViewFn>,
  options?: ComponentOptions
): ComponentFactory<TCombined, TRef, TSlots>;
```

- `setup` — the setup function receiving a `ComponentSetupContext`; returns a `ViewFn` (or a promise of one).
- `options` — optional `ComponentOptions` (currently `{ name? }`).
- Returns a `ComponentFactory` usable as a JSX element.

### getCurrentInstance

Return the setup context of the currently executing component, or `null` outside setup. Used to build composables.

```ts
function getCurrentInstance(): ComponentSetupContext<any, any, any> | null;
```

- Returns the active `ComponentSetupContext`, or `null` if called outside a component's setup.

### getComponentMeta

Return the registered metadata (name and setup) for a component factory. Used by DevTools.

```ts
function getComponentMeta(factory: Function): { name?: string; setup: SetupFn<any, any, any, any> } | undefined;
```

- `factory` — a component factory.
- Returns `{ name?, setup }`, or `undefined` if the factory is not registered.

### isComponent

Type guard that returns `true` for SignalX components (functions carrying a `__setup` property), and `false` for plain function components or strings.

```ts
function isComponent(type: unknown): type is ComponentLike;
```

- `type` — the value to test.
- Returns `true` if it is a SignalX component factory.

### compound

Create a compound component by attaching sub-components as static properties. Enables the `Parent.Child` pattern (e.g. `Menu.Item`, `Card.Body`) while preserving full TypeScript inference for both the parent and its children.

```ts
function compound<
  TMain extends AnyComponentFactory,
  TSub extends Record<string, AnyComponentFactory>
>(main: TMain, sub: TSub): TMain & TSub;
```

- `main` — the main/parent component factory.
- `sub` — an object whose values are the sub-components to attach.
- Returns the main component with the sub-components attached as static properties.

## Lifecycle hooks

Each hook must be called synchronously during `setup`. Called outside a component they warn and no-op (no throw).

### onMounted

Register a callback to run after the component mounts. Receives a `MountContext` with the root element.

```ts
function onMounted(fn: (ctx: MountContext) => void): void;
```

- `fn` — callback invoked post-mount with `{ el }`.

### onUnmounted

Register a cleanup callback to run when the component unmounts. The place to clear timers and unsubscribe.

```ts
function onUnmounted(fn: (ctx: MountContext) => void): void;
```

- `fn` — cleanup callback invoked on unmount with `{ el }`.

### onCreated

Register a callback that runs immediately after setup completes, before the first render.

```ts
function onCreated(fn: () => void): void;
```

- `fn` — callback invoked once after setup, before first render.

### onUpdated

Register a callback that runs after every reactive re-render of the component.

```ts
function onUpdated(fn: () => void): void;
```

- `fn` — callback invoked after each re-render.

## Application

### defineApp

Create a renderer-agnostic application instance with a chainable `use` / `hook` / `directive` / `defineProvide` / `mount` / `unmount` API.

```ts
function defineApp<TContainer = any>(rootComponent: JSXElement): App<TContainer>;
```

- `rootComponent` — the root JSX element to render.
- Returns an `App<TContainer>` instance.

## JSX runtime

### jsx

The core JSX factory called by TSX transpilation. Builds VNodes, resolves components, and processes model bindings.

```ts
function jsx(type: string | Function | typeof Fragment, props: JSXProps | null, key?: string): JSXElement;
```

- `type` — an intrinsic tag, component factory, or `Fragment`.
- `props` — element props, or `null`.
- `key` — optional reconciliation key.
- Returns a `JSXElement`. The fast path skips props cloning unless a `model` / `model:*` prop is present.

### jsxs

JSX factory variant for elements with multiple children; delegates to `jsx`.

```ts
function jsxs(type: string | typeof Fragment | Function, props?: Record<string, unknown>, key?: string): JSXElement;
```

- `type` — an intrinsic tag, component factory, or `Fragment`.
- `props` — element props.
- `key` — optional reconciliation key.
- Returns a `JSXElement`.

### jsxDEV

Dev-mode JSX factory; an alias of `jsx`.

```ts
const jsxDEV: typeof jsx;
```

### Fragment

VNode type marker for fragments — grouping children without a wrapper element.

```ts
const Fragment: unique symbol; // Symbol.for('sigx.Fragment')
```

### Text

VNode type marker for text nodes.

```ts
const Text: unique symbol; // Symbol.for('sigx.Text')
```

### Comment

VNode type marker for comment / placeholder nodes. Falsy children become Comment placeholders so positional diffing does not shift sibling indices when conditionals toggle.

```ts
const Comment: unique symbol; // Symbol.for('sigx.Comment')
```

## Lazy loading & async

### lazy

Wrap a dynamic-import loader into a lazy component loaded on first render. Adds `preload()` and `isLoaded()`. While the chunk loads the wrapper renders null; wrap it in `<Defer>` for a fallback. A load rejection throws from render (routes to the nearest `errorScope`, then `app.onError`).

```ts
function lazy<T extends AnyComponentFactory>(loader: ComponentLoader<T>): LazyComponentFactory<T>;
```

- `loader` — a function returning a dynamic import of the component.
- Returns a `LazyComponentFactory<T>` (the component plus `preload` / `isLoaded` / `__lazy`).

### Defer

Boundary component that shows a fallback while lazy **chunks** beneath it load (a pending `useData` read renders through its own component's `match()`, not a wrapper). On SSR the fallback streams with the shell and one replacement arrives when everything pending below it — chunks *and* keyed data — resolves.

```ts
const Defer: ComponentFactory<DeferProps, void, { default?: () => JSXElement | JSXElement[] | null }>;
```

- Accepts a `fallback` prop (a node or a function returning a node) and a default slot.

### isLazyComponent

Type guard for lazy-loaded components (checks the `__lazy` marker).

```ts
function isLazyComponent(component: any): component is LazyComponentFactory<any>;
```

- `component` — the value to test.
- Returns `true` if it is a lazy component factory.

### useData

The keyed async **read**. Auto-runs its fetcher and returns a reactive `AsyncState<T>`; the render re-runs as the state changes. Every read has a key — the reactive trigger, the cache / SSR identity, and the fetcher's input. A static string key is SSR-transferable: it runs during SSR, serializes its value under the key into `window.__SIGX_ASYNC__`, restores on hydration without refetching, and dedupes per key. A getter key may return a string or a tuple (serialized to canonical JSON); a falsy result holds the read in `idle`.

```ts
// Static key: runs on the server, serialized under `key`, restored on hydration.
function useData<T>(
  key: string,
  fetcher: (arg: string, ctx: AsyncFetcherContext) => Promise<T>,
  opts?: AsyncOptions
): AsyncState<T>;
// Reactive key: string or tuple; a falsy result skips the fetch (state 'idle').
function useData<T, const K extends KeyValue>(
  key: () => K | Falsy,
  fetcher: (arg: K, ctx: AsyncFetcherContext) => Promise<T>,
  opts?: AsyncOptions
): AsyncState<T>;
```

- `key` — a static string, or a getter returning a string / tuple / falsy. A static tuple is rejected (parameters that change belong in a getter).
- `fetcher` — an async function producing the value; receives the resolved key and a context whose `signal` is an `AbortSignal`. Runs untracked.
- `opts.server` — run the fetcher during SSR. Default `true`; `server: false` renders the pending arm on the server and fetches after hydration (still keyed).
- Returns an `AsyncState<T>` — see [AsyncState](#asyncstate).

### useAction

The async **write**. The manual counterpart to `useData`: never auto-runs, triggered by `.run(input)`. `run` never rejects — it resolves a settled `RunResult<T>`. In-flight runs are never aborted; a newer `run()` or `reset()` supersedes the *observation* (the older run resolves `{ ok: false, error: SupersededError }` and never writes state).

```ts
function useAction<T, In = void>(
  fn: (input: In, ctx: AsyncFetcherContext) => Promise<T>,
  opts?: ActionOptions
): AsyncAction<T, In>;
```

- `fn` — the write; receives the `run` input and a context whose `signal` is an `AbortSignal`.
- Returns an `AsyncAction<T, In>` with `state` (`idle | pending | ready | errored`), `value`, `error`, `loading` (`state === 'pending'`), `match()`, `run(input): Promise<RunResult<T>>`, and `reset()`.

### all

Combine several `AsyncState`s into one all-or-nothing state (one `match` for a whole view). A pure derived view — no fetching. Object form gives named `value`/`errors` records; the rest-tuple form gives positional ones.

```ts
function all<S extends Record<string, AsyncState<unknown>>>(sources: S): AllState<ValuesOf<S>, ErrorsOf<S>>;
function all<S extends readonly AsyncState<unknown>[]>(...sources: S): AllState<ValuesOf<S>, ErrorsOf<S>>;
```

Derived state: any member `idle` ⇒ `idle`; else any `errored` ⇒ `errored`; else any `pending` ⇒ `pending`; else any `refreshing` ⇒ `refreshing`; else `ready`. `AllState<T, E>` extends `AsyncState<T>` with `errors: E` (collect-all; `.error` stays first-error-wins).

### useStream

Composable for progressive text (LLM-token-style). Accumulates a streamed `AsyncIterable<string>` into a reactive string; SSR-aware via the key (streams on the server, restores on hydration without re-running the source, live on client navigation).

```ts
function useStream(
  key: string,
  source: () => AsyncIterable<string>
): { readonly value: string };
```

- `key` — the serialization/restore key.
- `source` — a function returning an async iterable of text chunks.
- Returns a `{ value }` string signal that grows as chunks arrive.

## Models & two-way binding

### registerModelProcessor

Register an **extension** model processor for intrinsic-element `model` handling. Extension processors run **before** the platform processor (DOM/Lynx/Terminal), in registration order, and the first one returning `true` wins — so packs and apps can **add** model behavior for custom elements or widget libraries without replacing the platform's. Registering the same function twice is a no-op.

```ts
function registerModelProcessor(fn: ModelProcessor): void;
```

- `fn` — a `ModelProcessor`: `(type, props, modelBinding, originalProps) => boolean`. Return `true` to claim the binding (skip the fallback), `false` to defer to later processors.

`setPlatformModelProcessor` is the separate, platform-identity seam used by renderer packages and is unchanged — `registerModelProcessor` is the additive extension tier.

### createModel

Create a two-way binding `Model<T>` from a `[sourceObject, key]` tuple and an update handler.

```ts
function createModel<T>(tuple: [object, string], updateHandler: (value: T) => void): Model<T>;
```

- `tuple` — a `[sourceObject, key]` pair identifying the bound value.
- `updateHandler` — called with the new value on write.
- Returns a `Model<T>`.

### createModelFromBinding

Create a `Model<T>` from a full binding tuple `[obj, key, handler]` for forwarding scenarios.

```ts
function createModelFromBinding<T>(binding: ModelBindingTuple<T>): Model<T>;
```

- `binding` — a `[obj, key, handler]` tuple.
- Returns a `Model<T>`.

### isModel

Type guard that detects `Model<T>` objects via the `sigx.model` symbol. Used by the JSX runtime.

```ts
function isModel(value: unknown): value is Model<unknown>;
```

- `value` — the value to test.
- Returns `true` if it is a `Model`.

## Error handling

### errorScope

Setup-time error boundary for the **calling component's own subtree** — a function, not a wrapper component. Catches setup / render / reactive-re-render throws beneath it and data errors bubbled by a `match()` with no `error` arm. Does not catch fetcher rejections (those are values on `.error`) or DOM event-handler throws (those go to `app.onError`). `retry` is a real remount.

```ts
function errorScope(options: ErrorScopeOptions): void;

interface ErrorScopeOptions {
  fallback?: (error: Error, retry: () => void) => JSXElement;
  onError?: (error: Error, instance: ComponentInstance | null, info: string) => void;
}
```

- `fallback` — rendered in place of the subtree while errored; omitted ⇒ renders nothing (the scope still stops propagation).
- `onError` — observer called before the fallback renders; its own throws are swallowed.

### SupersededError

Error a superseded `useAction` run resolves with (`{ ok: false, error: SupersededError }`); never written to `.error`.

```ts
class SupersededError extends Error {
  readonly name = 'SupersededError';
}
```

### SigxError

Base error class for all runtime errors; carries a stable `code` (`SIGX###`) and an optional `suggestion`.

```ts
class SigxError extends Error {
  readonly code: string;
  readonly suggestion?: string;
  declare readonly cause?: Error;
  constructor(message: string, options: { code: string; suggestion?: string; cause?: Error });
}
```

- `code` — the stable error code.
- `suggestion` — optional remediation hint.
- `cause` — optional underlying error.

### SigxErrorCode

Frozen map of error code constants grouped by category (app / render / DI).

```ts
const SigxErrorCode: {
  readonly NO_MOUNT_FUNCTION: 'SIGX001';
  readonly RENDER_TARGET_NOT_FOUND: 'SIGX100';
  readonly MOUNT_TARGET_NOT_FOUND: 'SIGX101';
  readonly ASYNC_SETUP_CLIENT: 'SIGX102';
  readonly PROVIDE_OUTSIDE_SETUP: 'SIGX200';
  readonly PROVIDE_INVALID_INJECTABLE: 'SIGX201';
};
```

### noMountFunctionError

Construct the `SIGX001` error — no mount function provided and no platform default.

```ts
function noMountFunctionError(): SigxError;
```

- Returns the `SIGX001` `SigxError`.

### renderTargetNotFoundError

Construct the `SIGX100` error — render target selector not found.

```ts
function renderTargetNotFoundError(selector: string): SigxError;
```

- `selector` — the selector that could not be resolved.
- Returns the `SIGX100` `SigxError`.

### mountTargetNotFoundError

Construct the `SIGX101` error — mount target selector not found.

```ts
function mountTargetNotFoundError(selector: string): SigxError;
```

- `selector` — the selector that could not be resolved.
- Returns the `SIGX101` `SigxError`.

### asyncSetupClientError

Construct the `SIGX102` error — async setup attempted on the client (only supported during SSR).

```ts
function asyncSetupClientError(componentName: string): SigxError;
```

- `componentName` — the offending component's name.
- Returns the `SIGX102` `SigxError`.

### provideOutsideSetupError

Construct the `SIGX200` error — `defineProvide` called outside component setup.

```ts
function provideOutsideSetupError(): SigxError;
```

- Returns the `SIGX200` `SigxError`.

### provideInvalidInjectableError

Construct the `SIGX201` error — `defineProvide` called with a non-injectable.

```ts
function provideInvalidInjectableError(): SigxError;
```

- Returns the `SIGX201` `SigxError`.

## Dependency injection

### defineInjectable

Define an injectable service or value. The returned callable token resolves the nearest provided instance up the component tree, or lazily creates a global singleton if none was provided.

```ts
function defineInjectable<T>(factory: () => T): InjectableFunction<T>;
```

- `factory` — produces the value when an instance must be created.
- Returns an `InjectableFunction<T>` (callable token).

### defineProvide

Provide a new injectable instance at the current component level, visible to descendants. Must run during setup; otherwise throws `SIGX200` / `SIGX201`.

```ts
function defineProvide<T>(useFn: InjectableFunction<T>, factory?: () => T): T;
```

- `useFn` — the injectable token to provide.
- `factory` — optional override factory for the provided instance.
- Returns the provided instance.

### useAppContext

Return the current `AppContext` from the component tree (provided at root during mount / hydrate / SSR), or `null`.

```ts
function useAppContext(): AppContext | null;
```

- Returns the active `AppContext`, or `null`.

### defineFactory

Create a factory with managed subscriptions, disposal, and a real instance lifetime. Parameterless factories become injectables; parameterized ones return `FactoryFunction` creators (still usable with `defineProvide`).

```ts
function defineFactory<R>(
  setup: (ctx: SetupFactoryContext, ...args: unknown[]) => R,
  lifetime: Lifetime,
  typeIdentifier?: guid
): InjectableFunction<R & { dispose: () => void }>;
function defineFactory<R, T1>(setup: (ctx: SetupFactoryContext, p1: T1) => R, lifetime: Lifetime, id?: guid): FactoryFunction<[T1], R & { dispose: () => void }>;
// ...overloads up to 5 parameters
```

- `setup` — receives a `SetupFactoryContext` and any creator arguments. Must return an object or function (primitives throw).
- `lifetime` — a `Lifetime` string literal; **honored** since core `0.5.0`:
  - `'singleton'` — one instance per `AppContext`, created on first resolution and disposed on `app.unmount()`. Outside any app context, one instance per JS realm.
  - `'scoped'` — the nearest instance provided via `defineProvide` in the component tree; falls back to the app-context instance when no provider exists.
  - `'transient'` — a new instance per call, auto-disposed with the calling component (or manually via `dispose()`).
- `typeIdentifier` — optional `guid` identity.
- Returns an `InjectableFunction` (parameterless) or a `FactoryFunction` creator (parameterized).

`dispose` is attached as a non-enumerable property (a setup-returned `dispose` is delegated to) and is idempotent. Parameterized non-transient factories honor arguments at first creation only — later calls resolve the existing shared instance.

### SubscriptionHandler

Collects unsubscribe callbacks and disposes them together. Used by `defineFactory` contexts.

```ts
class SubscriptionHandler {
  add(unsub: () => void): void;
  unsubscribe(): void;
}
```

- `add(unsub)` — register an unsubscribe callback.
- `unsubscribe()` — run and clear all registered callbacks.

## Directives

### defineDirective

Identity function that marks a directive definition (with the `sigx.directive` symbol) for the `use:name` prop syntax.

```ts
function defineDirective<T = any, El = any>(definition: DirectiveDefinition<T, El>): DirectiveDefinition<T, El>;
```

- `definition` — the directive's lifecycle hooks (`created` / `mounted` / `updated` / `unmounted`).
- Returns the same definition, branded.

### isDirective

Type guard for directive definitions created by `defineDirective`.

```ts
function isDirective(value: any): value is DirectiveDefinition;
```

- `value` — the value to test.
- Returns `true` if it is a directive definition.

## Messaging

### createTopic

Create an in-memory pub/sub `Topic<T>`. `subscribe()` auto-unsubscribes via `onUnmounted` when called inside a component.

```ts
function createTopic<T>(options?: CreateTopicOptions): Topic<T>;

interface CreateTopicOptions {
  /** Tooling metadata; topics WITH a namespace register in the inspection registry. */
  namespace?: string;
  /** Tooling metadata. */
  name?: string;
  /** Called when subscriberCount transitions 0 → 1 (refCount pattern). */
  onActivate?(): void;
  /** Called when subscriberCount transitions back to 0 (last unsubscribe or destroy). */
  onDeactivate?(): void;
}
```

- `options` — metadata plus refCount lifecycle hooks.
- Returns a `Topic<T>`.

Behavior contract (Topic v2):

- `publish` **isolates subscriber errors** — a throwing handler is logged via `console.error` and neither skips later subscribers nor propagates into the publisher. Publishing to a destroyed topic is a no-op.
- `subscribe` **throws on a destroyed topic** — a handler attached after `destroy()` could never be cleaned up, so it is rejected loudly instead of leaking.
- `onActivate` / `onDeactivate` fire on the 0 → 1 and → 0 subscriber transitions, letting producers pay for work only while observed (e.g. `@sigx/store` runs its per-key state watchers only while the key's event has subscribers). Hook errors are isolated.
- Topics created **with** a `namespace` register in the inspection registry (see [Inspection](#inspection-sigxruntime-coreinspect)); `destroy()` unregisters.

### createTopicGroup

Create a typed group of topics keyed by an event map — mitt-level DX on the `Topic` primitive. Topics are created lazily per key on first access and are namespaced/registered like any other topic.

```ts
function createTopicGroup<EventMap extends Record<string, any>>(options?: { namespace?: string }): {
  topics: { [K in keyof EventMap]: Topic<EventMap[K]> };
  destroy(): void;
};
```

- `options` — optional `{ namespace? }` applied to every created topic.
- Returns `{ topics, destroy }`; `destroy()` destroys all created topics. Accessing a key on a destroyed group throws.

```ts
const group = createTopicGroup<{ loggedIn: User; loggedOut: void }>({ namespace: 'auth#1.events' });
group.topics.loggedIn.publish(user);       // payload type-checked
group.topics.loggedIn.subscribe(u => {});  // u: User
group.destroy();
```

### toSubscriber

Wrap a `Topic` as a subscribe-only view, hiding `publish` and `destroy`.

```ts
function toSubscriber<T>(topic: Topic<T>): { subscribe: (handler: (data: T) => void) => Subscription };
```

- `topic` — the topic to wrap.
- Returns an object exposing only `subscribe`.

## Inspection (@sigx/runtime-core/inspect)

A separate `./inspect` package entry exposing the **inspection-only** topic registry for tooling (devtools, diagnostics). The DX contract: **typed application code holds `Topic<T>` references; strings are tooling metadata.** The registry is deliberately `Topic<unknown>`-typed and realm-global — do not use it as an app-level lookup mechanism; share typed topic references instead. Only topics created with a `namespace` register; `destroy()` unregisters.

```ts
import { getTopic, listTopics, subscribeTopics, onTopicCreated } from '@sigx/runtime-core/inspect';
```

Patterns use `*` wildcards matched over `${namespace}.${name}` (e.g. `'todos#1.*'`, `'*.actions.*'`).

### getTopic

```ts
function getTopic(namespace: string, name: string): Topic<unknown> | undefined;
```

Look up a live registered topic by exact namespace and name.

### listTopics

```ts
function listTopics(pattern?: string): Topic<unknown>[];
```

List live registered topics, optionally filtered by a `*`-wildcard pattern.

### subscribeTopics

```ts
function subscribeTopics(
  pattern: string,
  handler: (data: unknown, meta: { namespace: string; name: string }) => void
): Subscription;
```

Subscribe to every registered topic matching a pattern — both topics that already exist **and** topics created later. One `Subscription` tears everything down. Auto-unsubscribes on component unmount when called inside a setup.

### onTopicCreated

```ts
function onTopicCreated(handler: (topic: Topic<unknown>) => void): Subscription;
```

Register a handler for every topic that registers from now on. Handler errors are isolated. Auto-unsubscribes on component unmount when called inside a setup.

## Utilities

### signal

Re-export of `signal()` from `@sigx/reactivity` for convenience. The `ComponentSetupContext` also exposes it as `ctx.signal`.

```ts
export { signal } from '@sigx/reactivity';
```

### Utils

Static utility helpers; currently exposes `isPromise`.

```ts
class Utils {
  static isPromise(value: any): boolean;
}
```

- `isPromise(value)` — thenable detection; returns `true` for promise-like values.

### guid

Generate a v4-style GUID string. `guid` is also a string type alias of the same name (both exported from `models/index`).

```ts
const guid: () => string;
type guid = string;
```

- Returns a new GUID string.

## Lifetimes

### Lifetime

Lifetime options for `defineFactory` (and consumers like `@sigx/store`'s `defineStore`). A string-literal union; the lifetime is enforced (see [defineFactory](#definefactory) for the semantics of each value).

```ts
type Lifetime = 'singleton' | 'scoped' | 'transient';
```

## Internal

### __registerComponentPlugin

Internal HMR hook (`registerComponentPlugin` re-exported under a `__`-prefixed name). **Not part of the stable public API** — listed for completeness only.

```ts
function __registerComponentPlugin(plugin: ComponentPlugin): void;
```

- `plugin` — a `ComponentPlugin` with an optional `onDefine` hook.

## Types

### Define (namespace)

The preferred, discoverable API for typing component props, events, models, slots, and expose. Combine members with the `&` intersection.

```ts
namespace Define {
  type Prop<TName extends string, TType, Required extends boolean = false> =
    Required extends false ? { [K in TName]?: TType } : { [K in TName]: TType };
  type Event<TName extends string, TDetail = void> = { [K in TName]?: EventDefinition<TDetail> };
  type Model<TNameOrType, TType = void> = /* default: model + update:modelValue; named: model:name + update:name */;
  type Slot<TName extends string, TProps = void> = {
    __slots?: { [K in TName]: TProps extends void
      ? () => JSXElement | JSXElement[] | null
      : (props: TProps) => JSXElement | JSXElement[] | null };
  };
  type Expose<T> = { __exposed?: { __type: T } };
}
```

### ComponentSetupContext

The context object passed to a component's setup function. `renderFn` / `update()` are HMR escape hatches.

```ts
interface ComponentSetupContext<TElement = PlatformElement, TProps extends Record<string, any> = {}, TEvents extends Record<string, any> = {}, TRef = any, TSlots = {}> extends SetupContext {
  el: TElement;
  signal: typeof signal;
  props: PropsAccessor<TProps>;
  slots: SlotsObject<TSlots>;
  emit: EmitFn<TEvents>;
  parent: ComponentSetupContext | null;
  onMounted(fn: (ctx: MountContext<TElement>) => void): void;
  onUnmounted(fn: (ctx: MountContext<TElement>) => void): void;
  onCreated(fn: () => void): void;
  onUpdated(fn: () => void): void;
  expose(exposed: TRef): void;
  renderFn: ViewFn | null;
  update(): void;
}
```

### ComponentFactory

Return type of `component()`. Callable as JSX, plus internal `__`-branded props used by the renderer.

```ts
type ComponentFactory<TCombined extends Record<string, any>, TRef, TSlots> =
  ((props: StripForJSX<Omit<TCombined, EventNames<TCombined>>>
    & EventHandlers<TCombined>
    & SlotProps<TSlots>
    & SyncProps<TCombined>
    & ExternalModelProps<TCombined>
    & JSX.IntrinsicAttributes
    & ComponentAttributeExtensions
    & { ref?: Ref<TRef>; children?: any }) => JSXElement)
  & { __setup: SetupFn<any, any, any, any>; __name?: string; __islandId?: string; __props: any; __events: any; __ref: TRef; __slots: TSlots };
```

### AnyComponentFactory

Structural constraint accepting any `ComponentFactory` (used by `lazy` / compound) without contravariance issues.

```ts
type AnyComponentFactory = {
  (...args: any[]): any;
  __setup: SetupFn<any, any, any, any>;
  __props: any;
  __events: any;
  __ref: any;
  __slots: any;
};
```

### Model

Two-way binding object: `.value` reads/writes, `.binding` forwards.

```ts
interface Model<T> {
  value: T;
  readonly binding: ModelBindingTuple<T>;
  readonly [MODEL_SYMBOL]: true;
}
// ModelBindingTuple<T> = readonly [object, string, (value: T) => void]
```

### App

Chainable app instance returned by `defineApp()`. The `_`-prefixed members are `@internal` for renderers.

```ts
interface App<TContainer = any> {
  config: AppConfig;
  use<Options>(plugin: Plugin<Options> | PluginInstallFn<Options>, options?: Options): App<TContainer>;
  defineProvide<T>(useFn: InjectableFunction<T>, factory?: () => T): T;
  hook(hooks: AppLifecycleHooks): App<TContainer>;
  directive(name: string, definition: DirectiveDefinition): App<TContainer>;
  directive(name: string): DirectiveDefinition | undefined;
  mount(container: TContainer, mountFn?: MountFn<TContainer>): App<TContainer>;
  unmount(): void;
  _context: AppContext;
  _isMounted: boolean;
  _container: TContainer | null;
  _rootComponent: JSXElement;
}
```

### App / plugin type cluster

The supporting types for the app and plugin system (from `app-types.ts`).

```ts
interface AppConfig {
  onError?(err: Error, instance: ComponentInstance | null, info: string): boolean | void; // usually set via app.onError(fn)
  warnHandler?(...args: any[]): void;
  performance?: boolean;
}
interface AppLifecycleHooks {
  onComponentCreated?(instance: ComponentInstance): void;
  onComponentMounted?(instance: ComponentInstance): void;
  onComponentUnmounted?(instance: ComponentInstance): void;
  onComponentUpdated?(instance: ComponentInstance): void;
  onComponentError?(err: unknown, instance: ComponentInstance, info: string): boolean | void;
}
interface AppContext {
  app: App;
  provides: Map<symbol, unknown>;
  config: AppConfig;
  hooks: AppLifecycleHooks[];
  directives: Map<string, DirectiveDefinition>;
}
interface Plugin<Options = any> { name?: string; install(app: App, options?: Options): void; }
type PluginInstallFn<Options = any> = (app: App, options?: Options) => void;
type MountFn<TContainer = any> = (element: JSXElement, container: TContainer, appContext: AppContext) => (() => void) | void;
type UnmountFn<TContainer = any> = (container: TContainer) => void;
interface ComponentInstance { name?: string; ctx: ComponentSetupContext; vnode: VNode; }
```

### VNode / JSXElement / JSXChild / JSXChildren

Core virtual-node and JSX value types.

```ts
type VNode = {
  type: string | typeof Fragment | typeof Text | typeof Comment | Function;
  props: Record<string, any>;
  key: string | number | null;
  children: VNode[];
  dom: any | null;
  text?: string | number;
  parent?: VNode | null;
  cleanup?: () => void;
};
type JSXChild = VNode | string | number | boolean | null | undefined | JSXChild[];
type JSXChildren = JSXChild;
type JSXElement = VNode | string | number | boolean | null;
```

### Component-system helper types

Helper types from `component-types.ts`. `SetupContext` and `MountContext` are augmentation points.

```ts
type ViewFn = () => JSXElement | JSXElement[] | undefined;
type SetupFn<TProps, TEvents, TRef, TSlots> =
  (ctx: ComponentSetupContext<PlatformElement, TProps, TEvents, TRef, TSlots>) => ViewFn | Promise<ViewFn>;
interface ComponentOptions { name?: string; }
type PropsAccessor<TProps> = { readonly [K in keyof TProps]: TProps[K] };
type SlotsObject<TSlots = {}> = { default: () => JSXElement[] } & TSlots;
type EmitFn<TEvents> = <TName extends keyof TEvents>(eventName: TName, ...args: any[]) => void;
interface MountContext<TElement = PlatformElement> { el: TElement; }
interface SetupContext {}
type PropsWithDefaults<TProps, D> = { readonly [K in keyof TProps]-?: K extends keyof D ? NonNullable<TProps[K]> : TProps[K] };
type Ref<T> = { current: T | null } | ((instance: T | null) => void);
type Exposed<T extends { __ref: any }> = T['__ref'];
type ComponentRef<T extends { __ref: any }> = Ref<T['__ref']>;
```

### Platform types

Module-augmentation hooks: platforms set the element type; packages add global component attributes.

```ts
interface PlatformTypes {} // platforms declaration-merge `element: HTMLElement`
type PlatformElement = PlatformTypes extends { element: infer E } ? E : any;
interface ComponentAttributeExtensions {} // augmented by SSR to add 'client:load', etc.
```

### Host namespaces (RendererOptions)

`createRenderer(nodeOps)` takes a `RendererOptions` object — the host operations a
platform implements. Three of them are optional and concern **namespaces**.

Core is namespace-agnostic: it knows nothing about SVG. It threads an **opaque
boolean flag** through the tree walk, caches it on each vnode, and hands it back to
`createElement` and `patchProp` as the `ns` parameter. What that flag *means* is the
host's business — in `@sigx/runtime-dom` it means "in the SVG namespace".

```ts
interface RendererOptions<HostNode = any, HostElement = any> {
  createElement(type: string, ns?: boolean, isCustomizedBuiltIn?: string): HostElement;
  patchProp(el: HostElement, key: string, prev: any, next: any, ns?: boolean, appContext?: AppContext | null): void;
  // …

  /** The flag for an element, given its parent's. `undefined` parentNS means the
   *  surrounding context is unknown (a hydrated subtree patched from the top) —
   *  hosts typically fall back to a tag-name heuristic there. */
  getElementNamespace?(tag: string, parentNS: boolean | undefined): boolean;

  /** The flag children inherit, given the element's own. Lets a host RESET the
   *  context at a boundary element (in the DOM, `foreignObject`). */
  getChildNamespace?(tag: string, ns: boolean): boolean;

  /** The flag of an element's CONTAINER, given its tag and cached flag. Used when
   *  replacing a node whose surrounding context is unknown. */
  getContainerNamespace?(tag: string, ns: boolean): boolean;
}
```

Defaults when a hook is **absent**:

| Hook | Absent behaviour |
|---|---|
| `getElementNamespace` | Every element resolves to the default namespace (`false`) |
| `getChildNamespace` | Children inherit the element's flag unchanged |
| `getContainerNamespace` | The container resolves to the default namespace (`false`) |

**For renderer authors:** a DOM-like custom renderer must implement these to keep
SVG working — core no longer detects SVG tags itself, so omitting them resolves
everything to the default namespace. `@sigx/runtime-dom`'s
[`nodeOps`](/core/packages/runtime-dom/api#nodeops) is the reference
implementation. Renderers with no namespace concept (terminal, lynx) simply omit
all three.

The `ns` parameter of `createElement`/`patchProp` was previously named `isSVG`;
positions are unchanged, so only the name differs.

### Directive types

Directive lifecycle hook types. `DirectiveDefinitionExtensions` is an augmentation point (e.g. SSR `getSSRProps`).

```ts
interface DirectiveBinding<T = any> { value: T; oldValue?: T; }
interface DirectiveDefinitionExtensions<T = any> {}
interface DirectiveDefinition<T = any, El = any> extends DirectiveDefinitionExtensions<T> {
  created?(el: El, binding: DirectiveBinding<T>): void;
  mounted?(el: El, binding: DirectiveBinding<T>): void;
  updated?(el: El, binding: DirectiveBinding<T>): void;
  unmounted?(el: El, binding: DirectiveBinding<T>): void;
}
type ResolvedDirective<T = any, El = any> = [DirectiveDefinition<T, El>, T];
```

### AsyncState

The reactive result of `useData` (and, via `all`, the combined state), plus the `match` arm table, the shared fetcher shape, and the read options. `value` is the best data the cell has — kept across a same-key `refresh()` **and across a failed fetch**, cleared on key change; `loading` is `state === 'pending'` only; `refresh()` never rejects (failures land on `.error`).

`AsyncState<T>` is a discriminated union, so `state`/`hasValue` checks narrow `value` without a cast. Extending it with `interface X extends AsyncState<T>` no longer compiles — intersect instead (`type X<T> = AsyncState<T> & { … }`).

```ts
type AsyncStateName = 'idle' | 'pending' | 'ready' | 'refreshing' | 'errored';

type AsyncState<T> =
  | AsyncIdle<T> | AsyncPending<T> | AsyncReady<T> | AsyncRefreshing<T> | AsyncErrored<T>;

interface AsyncStateBase<T> {                // the shared methods
  match<R>(arms: MatchArms<T, R>): R | undefined;
  refresh(): Promise<void>;                  // never rejects
}

// Each member narrows state / value / hasValue / error / loading:
interface AsyncReady<T> extends AsyncStateBase<T> {
  readonly state: 'ready';
  readonly value: T;                         // narrowed — no cast
  readonly hasValue: true;
  readonly error: null;
  readonly loading: false;
}
interface AsyncErrored<T> extends AsyncStateBase<T> {
  readonly state: 'errored';
  readonly error: Error;                     // splits on hasValue: a cell that
                                             // once succeeded still holds its value
  readonly loading: false;
}

interface MatchArms<T, R> {
  idle?: () => R;                            // defaults to `pending`
  pending?: () => R;                         // omitted ⇒ renders nothing
  error?: (e: Error, ctx: ErrorArmContext<T>) => R; // omitted ⇒ bubbles to errorScope / app onError
  ready: (v: T) => R;                        // required — the only route to a non-null T
}

type ErrorArmContext<T> =
  & { retry: () => void }
  & ({ value: T; hasValue: true } | { value: null; hasValue: false });

type Fetcher<T, Arg> = (arg: Arg, ctx: AsyncFetcherContext) => Promise<T>;
interface AsyncFetcherContext { signal: AbortSignal; } // pass to fetch(url, { signal })

interface AsyncOptions { server?: boolean; }  // default true; false ⇒ client-only keyed read
```

### AsyncAction / RunResult / AllState

The `useAction` handle, its settled result, and the combined `all()` state.

```ts
interface AsyncAction<T, In> {
  readonly state: 'idle' | 'pending' | 'ready' | 'errored';
  readonly value: T | null;
  readonly error: Error | null;
  readonly loading: boolean;                 // state === 'pending'
  match<R>(arms: MatchArms<T, R>): R | undefined;
  run(input: In): Promise<RunResult<T>>;     // never rejects
  reset(): void;
}

type RunResult<T> = { ok: true; value: T } | { ok: false; error: Error };

interface AllState<T, E> extends AsyncState<T> {
  readonly errors: E;                        // collect-all counterpart to first-error-wins `.error`
}

interface ActionOptions {}                    // open interface — empty in core; packs augment it
```

### LazyComponentFactory / DeferProps

Lazy-loading types.

```ts
type LazyComponentFactory<T extends AnyComponentFactory> = T & {
  preload: () => Promise<T>;
  isLoaded: () => boolean;
  __lazy: true;
};
type DeferProps = Define.Prop<'fallback', JSXElement | (() => JSXElement)> & Define.Slot<'default'>;
```

### InjectableFunction / SetupFactoryContext

Dependency-injection types. `InjectableFunction` is what `defineInjectable` returns and what `defineProvide` / `app.defineProvide` accept.

```ts
interface InjectableFunction<T> {
  (): T;
  _factory: () => T;
  _token: symbol;
}
type FactoryFunction<TArgs extends unknown[], TInstance> =
  ((...args: TArgs) => TInstance) & { _factory: () => TInstance; _token: symbol };
interface SetupFactoryContext {
  onDeactivated(fn: () => void): void;
  subscriptions: SubscriptionHandler;
  overrideDispose(onDispose: (fn: () => void) => void): void;
}
```

`FactoryFunction` is what a parameterized `defineFactory` returns — callable with the setup's params and carrying the provide metadata so it works with `defineProvide` / `app.defineProvide`.

### Subscription / Topic / ModelProcessor / ComponentPlugin

Messaging, model-processor, and plugin types. `ModelProcessor` is the signature of an intrinsic-element model handler — register one with [`registerModelProcessor`](#registermodelprocessor). `ComponentPlugin` is a type-only public export (its setter is internal).

```ts
interface Subscription { unsubscribe(): void; }
interface Topic<T> {
  /** Tooling metadata (set via createTopic options). */
  readonly namespace?: string;
  readonly name?: string;
  readonly subscriberCount: number;
  readonly hasSubscribers: boolean;
  readonly disposed: boolean;
  publish(data: T): void;
  subscribe(handler: (data: T) => void): Subscription;
  destroy(): void;
}
type ModelProcessor = (type: string, props: Record<string, any>, modelBinding: [Record<string, any>, string], originalProps: Record<string, any>) => boolean;
type ComponentPlugin = { onDefine?: (name: string | undefined, factory: Function, setup: Function) => void };
```

### ModelBinding / EventDefinition

```ts
type ModelBinding<_T> = [object, string];
type EventDefinition<T> = { __eventDetail: T };
```

## See also

- [Usage guide](/core/packages/runtime-core/usage) — practical patterns and examples.
- [Overview](/core/packages/runtime-core/overview) — package summary and installation.

---
url: https://sigx.dev/daisyui/docs/components/select/
title: Select
description: Dropdown select component for choosing from a list of options
---

# Select

Select component for dropdown selection with model binding support.

## Import

```tsx
import { Select, Col } from '@sigx/daisyui';
```

## Basic Usage

Use `model` for two-way binding:

```tsx
import { component, render } from 'sigx';
import { Select, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ country: '' });
    
    const countries = [
        { value: 'us', label: 'United States' },
        { value: 'uk', label: 'United Kingdom' },
        { value: 'ca', label: 'Canada' },
        { value: 'au', label: 'Australia' },
        { value: 'de', label: 'Germany' }
    ];
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Select 
                    model={() => form.country}
                    options={countries}
                    placeholder="Select a country"
                    variant="bordered"
                />
                
                <Text size="sm" class="opacity-70">
                    Selected: {form.country || '(none)'}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Select, Col } from '@sigx/daisyui';
const Demo = component(() => {
    const options = [
        { value: 'a', label: 'Option A' },
        { value: 'b', label: 'Option B' },
        { value: 'c', label: 'Option C' }
    ];
    
    return () => (
        <Col gap="4">
            <Select size="xs" options={options} placeholder="Extra small" variant="bordered" />
            <Select size="sm" options={options} placeholder="Small" variant="bordered" />
            <Select size="md" options={options} placeholder="Medium (default)" variant="bordered" />
            <Select size="lg" options={options} placeholder="Large" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Select, Col } from '@sigx/daisyui';
const Demo = component(() => {
    const options = [
        { value: 'a', label: 'Option A' },
        { value: 'b', label: 'Option B' }
    ];
    
    return () => (
        <Col gap="4">
            <Select color="primary" options={options} placeholder="Primary" variant="bordered" />
            <Select color="secondary" options={options} placeholder="Secondary" variant="bordered" />
            <Select color="accent" options={options} placeholder="Accent" variant="bordered" />
            <Select color="info" options={options} placeholder="Info" variant="bordered" />
            <Select color="success" options={options} placeholder="Success" variant="bordered" />
            <Select color="warning" options={options} placeholder="Warning" variant="bordered" />
            <Select color="error" options={options} placeholder="Error" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

```tsx
import { component, render } from 'sigx';
import { Select, Col } from '@sigx/daisyui';
const Demo = component(() => {
    const options = [
        { value: 'a', label: 'Option A' },
        { value: 'b', label: 'Option B' }
    ];
    
    return () => (
        <Col gap="4">
            <Select options={options} placeholder="Default (no variant)" />
            <Select options={options} placeholder="Bordered" variant="bordered" />
            <Select options={options} placeholder="Ghost" variant="ghost" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Disabled Options

```tsx
import { component, render } from 'sigx';
import { Select, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ plan: '' });
    
    const plans = [
        { value: 'free', label: 'Free Plan' },
        { value: 'pro', label: 'Pro Plan' },
        { value: 'enterprise', label: 'Enterprise (Coming Soon)', disabled: true }
    ];
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Select 
                    model={() => form.plan}
                    options={plans}
                    placeholder="Select a plan"
                    variant="bordered"
                />
                
                <Text size="sm" class="opacity-70">
                    Selected: {form.plan || '(none)'}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With FormField

Wrap with `FormField` for labels and validation:

```tsx
import { component, render } from 'sigx';
import { Select, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ category: '' });
    const hasError = () => !form.category;
    
    const categories = [
        { value: 'tech', label: 'Technology' },
        { value: 'design', label: 'Design' },
        { value: 'business', label: 'Business' },
        { value: 'other', label: 'Other' }
    ];
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField 
                    label="Category" 
                    required 
                    error={hasError() ? 'Please select a category' : ''}
                >
                    <Select 
                        model={() => form.category}
                        options={categories}
                        placeholder="Choose a category"
                        color={hasError() ? 'error' : undefined}
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled State

```tsx
import { component, render } from 'sigx';
import { Select } from '@sigx/daisyui';

const Demo = component(() => {
    const options = [
        { value: 'a', label: 'Option A' },
        { value: 'b', label: 'Option B' }
    ];
    
    return () => (
        <Select 
            options={options} 
            placeholder="Disabled select" 
            variant="bordered"
            disabled 
        />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for two-way sync |
| `name` | `string` | - | Select name for form submission |
| `options` | `Array<{ value, label, disabled? }>` | - | Select options |
| `placeholder` | `string` | - | Placeholder text (shown as disabled first option) |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Select size |
| `variant` | `'bordered' \| 'ghost'` | - | Visual variant |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Border color |
| `disabled` | `boolean` | `false` | Disable the select |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(value: string) => void` | Fired when selection changes |

---
url: https://sigx.dev/daisyui/docs/components/status/
title: Status
description: A small indicator to visually show the current status of an element
---

# Status

A small icon to visually show the current status of an element, like online, offline, error, etc.

## Import

```tsx
import { Status, Row, Col, Text, Avatar, Badge } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Status } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Status />
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Status, Row, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Col align="center">
                <Status size="xs" color="neutral" />
                <Text size="xs">xs</Text>
            </Col>
            <Col align="center">
                <Status size="sm" color="neutral" />
                <Text size="xs">sm</Text>
            </Col>
            <Col align="center">
                <Status size="md" color="neutral" />
                <Text size="xs">md</Text>
            </Col>
            <Col align="center">
                <Status size="lg" color="neutral" />
                <Text size="xs">lg</Text>
            </Col>
            <Col align="center">
                <Status size="xl" color="neutral" />
                <Text size="xs">xl</Text>
            </Col>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Status, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Status color="primary" />
            <Status color="secondary" />
            <Status color="accent" />
            <Status color="neutral" />
            <Status color="info" />
            <Status color="success" />
            <Status color="warning" />
            <Status color="error" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Ping Animation

Use the `animate-ping` Tailwind utility class to create a ping/pulse effect for active or alert states.

```tsx
import { component, render } from 'sigx';
import { Status, Row, Flex } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="8" align="center">
            <Flex class="inline-grid *:[grid-area:1/1]">
                <Status color="error" class="animate-ping" />
                <Status color="error" />
            </Flex>
            <Flex class="inline-grid *:[grid-area:1/1]">
                <Status color="success" class="animate-ping" />
                <Status color="success" />
            </Flex>
            <Flex class="inline-grid *:[grid-area:1/1]">
                <Status color="warning" class="animate-ping" />
                <Status color="warning" />
            </Flex>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Bounce Animation

Use the `animate-bounce` Tailwind utility class for a notification-style effect.

```tsx
import { component, render } from 'sigx';
import { Status, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Status color="info" class="animate-bounce" />
            <Status color="success" class="animate-bounce" />
            <Status color="error" class="animate-bounce" />
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Status with Avatar

```tsx
import { component, render } from 'sigx';
import { Status, Avatar, Flex, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Flex class="relative">
                <Avatar size="sm" shape="circle" src="https://img.daisyui.com/images/stock/photo-1534528741775-53994a69daeb.webp" />
                <Status color="success" size="sm" class="absolute bottom-0 right-0" />
            </Flex>
            <Flex class="relative">
                <Avatar size="sm" shape="circle" src="https://img.daisyui.com/images/stock/photo-1534528741775-53994a69daeb.webp" />
                <Status color="error" size="sm" class="absolute bottom-0 right-0" />
            </Flex>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Color variant |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `undefined` | Size of the status indicator |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/toggle/
title: Toggle
description: Toggle switch for on/off boolean states
---

# Toggle

Toggle switch component for boolean on/off states with model binding support.

## Import

```tsx
import { Toggle, Row, Col, Text, Heading } from '@sigx/daisyui';
```

## Basic Usage

Use `model` for two-way binding:

```tsx
import { component, render } from 'sigx';
import { Toggle, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const settings = signal({ enabled: false });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Toggle 
                    model={() => settings.enabled}
                    label="Enable notifications"
                />
                
                <Text size="sm" class="opacity-70">
                    Notifications: {settings.enabled ? 'On' : 'Off'}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Toggle, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Toggle size="xs" label="Extra small toggle" />
            <Toggle size="sm" label="Small toggle" />
            <Toggle size="md" label="Medium toggle (default)" />
            <Toggle size="lg" label="Large toggle" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Toggle, Col } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const toggles = signal({
        primary: true,
        secondary: true,
        accent: true,
        info: true,
        success: true,
        warning: true,
        error: true
    });
    
    return () => (
        <Col gap="4">
            <Toggle model={() => toggles.primary} color="primary" label="Primary" />
            <Toggle model={() => toggles.secondary} color="secondary" label="Secondary" />
            <Toggle model={() => toggles.accent} color="accent" label="Accent" />
            <Toggle model={() => toggles.info} color="info" label="Info" />
            <Toggle model={() => toggles.success} color="success" label="Success" />
            <Toggle model={() => toggles.warning} color="warning" label="Warning" />
            <Toggle model={() => toggles.error} color="error" label="Error" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Without Label

```tsx
import { component, render } from 'sigx';
import { Toggle, Row, Text } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const enabled = signal({ value: true });
    
    return () => (
        <Row align="center" gap="4">
            <Toggle model={() => enabled.value} color="primary" />
            <Text as="span">Toggle without built-in label</Text>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Settings Panel Example

```tsx
import { component, render } from 'sigx';
import { Toggle, Card, Divider, Col, Heading } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const settings = signal({
        notifications: true,
        darkMode: false,
        sounds: true,
        autoSave: true,
        analytics: false
    });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Heading level={3} size="lg">Settings</Heading>
                
                <Col gap="3">
                    <Toggle 
                        model={() => settings.notifications}
                        color="primary"
                        label="Push notifications"
                    />
                    <Toggle 
                        model={() => settings.darkMode}
                        color="primary"
                        label="Dark mode"
                    />
                    <Toggle 
                        model={() => settings.sounds}
                        color="primary"
                        label="Sound effects"
                    />
                </Col>
                
                <Divider />
                
                <Col gap="3">
                    <Toggle 
                        model={() => settings.autoSave}
                        color="success"
                        label="Auto-save documents"
                    />
                    <Toggle 
                        model={() => settings.analytics}
                        color="warning"
                        label="Share usage analytics"
                    />
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled State

```tsx
import { component, render } from 'sigx';
import { Toggle, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Toggle label="Disabled off" disabled />
            <Toggle label="Disabled on" disabled checked />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Toggle vs Checkbox

Use Toggle for settings that take effect immediately. Use Checkbox for selections that are submitted with a form.

```tsx
import { component, render } from 'sigx';
import { Toggle, Checkbox, Card, Divider, Text, Col, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const toggle = signal({ value: true });
    const checkbox = signal({ value: true });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Col gap="2">
                    <Heading level={4} size="md">Toggle (immediate effect)</Heading>
                    <Toggle 
                        model={() => toggle.value}
                        color="success"
                        label="Enable dark mode"
                    />
                    <Text size="xs" class="opacity-50 mt-1">Changes apply immediately</Text>
                </Col>
                
                <Divider />
                
                <Col gap="2">
                    <Heading level={4} size="md">Checkbox (form submission)</Heading>
                    <Checkbox 
                        model={() => checkbox.value}
                        color="primary"
                        label="Subscribe to newsletter"
                    />
                    <Text size="xs" class="opacity-50 mt-1">Requires form submission</Text>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for boolean value |
| `name` | `string` | - | Toggle name for form submission |
| `label` | `string` | - | Label text displayed next to toggle |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Toggle size |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Toggle color when on |
| `disabled` | `boolean` | `false` | Disable the toggle |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(checked: boolean) => void` | Fired when toggle state changes |

---
url: https://sigx.dev/deploy/packages/cloudflare/api/
title: API reference
description: API reference for @sigx/cloudflare — every export of the SignalX Cloudflare adapter.
---

# API reference

<p class="lede">Exports of `@sigx/cloudflare` .</p>

## cloudflare

Create the Workers adapter for `sigx({ ssr: { adapter } })` — `serverBuild:
'bundled'`, conditions `['workerd', 'worker']`, `runtimeExternal:
[/^cloudflare:/]`, plus the entry/wrangler scaffolding and dev-proxy hooks.

```ts
function cloudflare(options?: CloudflareAdapterOptions): SigxAdapter

interface CloudflareAdapterOptions {
  /** Platform entry (project-relative). Default 'src/entry.cloudflare.ts'. */
  entry?: string;

  /**
   * Boot wrangler's getPlatformProxy() on the dev server and expose it via
   * getDevPlatform(server) — local KV/D1/R2 simulations for binding-reliant
   * apps. Requires wrangler as a dev dependency. Default false.
   */
  devProxy?: boolean;

  /**
   * compatibility_date written into a SCAFFOLDED wrangler.jsonc. Pinned
   * (not "today") so builds are deterministic; an existing config is never
   * touched. Default: a constant bumped per release.
   */
  compatibilityDate?: string;
}
```

## getDevPlatform

Read the dev binding proxies booted by `devProxy: true` off the Vite dev server —
pass the result as the `platform` argument of `createDevRequestHandler` so
renders see `{ env, cf, ctx, caches }` in dev:

```ts
function getDevPlatform(server: ViteDevServer): DevPlatform

interface DevPlatform {
  env: unknown;      // your bindings (KV, D1, R2, …), locally simulated
  cf: unknown;       // request cf properties
  ctx: unknown;      // ExecutionContext
  caches: unknown;   // the Workers cache API
}
```

See [Deploying to Workers](/deploy/packages/cloudflare/deploying) for the full
dev-loop wiring.

---
url: https://sigx.dev/terminal/docs/components/input/
title: Input
description: Single-line text field with two-way model binding
---

# Input

<p class="lede">A focusable single-line text field with two-way <code>model</code> binding. Renders as a bordered box (accent border when focused) with a block cursor.</p>

## Import

```tsx
import { Input } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Input } from '@sigx/terminal';

const App = component(() => {
    const name = signal('');
    return () => (
        <box border="single" label="Form">
            <Input
                model={() => name}
                label="Name"
                placeholder="Type here"
                autofocus
                onInput={(v) => console.log('changed:', v)}
                onSubmit={(v) => console.log('submitted:', v)}
            />
            <br />
            <text>You typed: {name.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `model` | `Model<string>` | two-way bound value |
| `placeholder` | `string` | shown when empty |
| `autofocus` | `boolean` | grab focus on mount |
| `label` | `string` | caption above the field |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `input` | `string` | a printable character changes the value |
| `submit` | `string` | Enter |

Backspace deletes; control bytes and escape sequences (including Tab, which cascades to focus cycling) are ignored. A brief ready delay after mount prevents the activating Enter from a previous focus from triggering submit.

## See also

- [TextArea](/terminal/docs/components/textarea) — multi-line input.
- [Input & Interactive Components](/terminal/docs/input-and-components) — focus and key dispatch.

---
url: https://sigx.dev/terminal/docs/components/badge/
title: Badge
description: A small labelled tag in solid, accent or bracket styles
---

# Badge

<p class="lede">A small labelled tag — a status pill or count. Three styles via <code>variant</code>.</p>

## Import

```tsx
import { Badge } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Badge } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box>
            <Badge label="NEW" variant="solid" color="accent" />
            <text> </text>
            <Badge label="beta" variant="accent" color="info" />
            <text> </text>
            <Badge label="3" variant="bracket" color="warn" />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | **required** — the badge text |
| `variant` | `'solid' \| 'accent' \| 'bracket'` | visual style |
| `color` | token \| `#hex` | badge color |

## See also

- [StatusBar](/terminal/docs/components/statusbar) — a row of keyed status chips.

---
url: https://sigx.dev/terminal/docs/components/meter/
title: Meter
description: A bare gauge for a single ratio, sized to sit in a table cell
---

# Meter

<p class="lede">A bare gauge — <code>████████░░░░</code> for a single ratio, with an optional label and trailing text.</p>

## Import

```tsx
import { Meter } from '@sigx/terminal';
```

## Usage

```tsx
<Meter label="heap" value={used} max={total} text={`${pct}%`} width={16} />
```

[`ProgressBar`](/terminal/docs/components/progressbar) covers determinate progress and owns the percentage readout and the gradient variants. This is the compact shape — no chrome, sized to sit in a table cell or a row of stats.

**A non-zero ratio always shows at least one cell.** Rounding a real 2% down to an empty bar reads as "nothing", which is a different fact.

`thresholds` colour the bar by how far along it is, so a gauge can go amber at 80% and red at 95% without the app re-deriving that every frame.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `value` | `number` | **required** |
| `max` | `number` | denominator |
| `width` | `number` | bar width in cells |
| `label` / `labelWidth` | `string` / `number` | leading label, fitted to a column |
| `text` | `string` | trailing readout |
| `smooth` | `boolean` | sub-cell resolution |
| `color` | `string` | theme token |
| `thresholds` | `Threshold[]` | colour by fill |

## See also

- [ProgressBar](/terminal/docs/components/progressbar) — determinate progress with chrome.
- [Sparkline](/terminal/docs/components/sparkline) — a series rather than one ratio.

---
url: https://sigx.dev/terminal/docs/components/radio/
title: Radio
description: Single-choice group with every option always visible
---

# Radio

<p class="lede">A single-choice group like <a href="/terminal/docs/components/select">Select</a>, but every option stays visible with a <code>●</code> / <code>○</code> marker. Arrow keys (or <code>j</code>/<code>k</code>) move the selection.</p>

## Import

```tsx
import { Radio } from '@sigx/terminal';
import type { RadioOption } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Radio } from '@sigx/terminal';
import type { RadioOption } from '@sigx/terminal';

const options: RadioOption[] = [
    { label: 'Small', value: 's' },
    { label: 'Medium', value: 'm' },
    { label: 'Large', value: 'l' },
];

const App = component(() => {
    const size = signal('m');
    return () => (
        <box border="single" label="Size">
            <Radio
                options={options}
                model={() => size}
                label="Pick a size"
                autofocus
                onChange={(v) => console.log('size:', v)}
            />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `RadioOption[]` | **required** — the choices |
| `model` | `Model<string>` | two-way bound selected value |
| `label` | `string` | caption above the group |
| `autofocus` | `boolean` | grab focus on mount |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `string` | selection moves |

## RadioOption

```ts
interface RadioOption<T = string> {
    label: string;
    value: T;
}
```

## See also

- [Select](/terminal/docs/components/select) — a scrolling single-choice menu.
- [MultiSelect](/terminal/docs/components/multiselect) — choose several.

---
url: https://sigx.dev/terminal/docs/components/shell/
title: Shell
description: A dashboard frame that owns the chrome and tells the body what is left
---

# Shell

<p class="lede">A dashboard frame with exactly one job: own the chrome, and tell the body what is left.</p>

## Import

```tsx
import { Shell } from '@sigx/terminal';
```

## Usage

The body is a **scoped slot** receiving `{ width, height }` — the content box inside the frame:

```tsx
import { component, defineApp, Shell, DataTable } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <Shell
            title="sigx actors"
            version="0.1.0"
            tabs={TABS}
            activeTab={tab.value}
            status={STATUS}
        >
            {(pane) => (
                <DataTable width={pane.width} height={pane.height} columns={COLS} rows={rows.value} />
            )}
        </Shell>
    );
});
```

That slot is the whole point of the component. `getTerminalSize()` reports the *terminal*; what a body needs is that minus whatever chrome the frame drew — which is a private detail of the frame's own layout. Without it, every caller hardcodes a guess (`rows - 12`, `rows - 13`, `- 4`) that goes wrong the moment the frame changes shape.

## A budget, not a reservation

`pane` is the **maximum** a body may emit, not an enforced box.

The renderer's layout is content-driven end to end — there is no clipping primitive and no way to measure an opaque child — so `<Shell>` cannot hold the box on the body's behalf. A body that emits fewer rows leaves the frame short; one that emits more pushes the footer off the bottom. (The renderer clamps a fullscreen frame to the viewport, so the damage stops there rather than shearing the screen.)

Comply by fitting content to the pane, which [`fitLines`](/terminal/docs/api#fitlines) does in one call:

```tsx
{(pane) => <text>{fitLines(visible, pane).join('\n')}</text>}
```

## What it deliberately does not do

No state, no key handling, no lifecycle. Tab switching, a command palette, a view stack, single-key shortcuts, exit ordering and the non-TTY fallback are each a few lines in the app, and every app wants to vary them — bundling them is what turns a frame into a cage.

`activeTab` is a plain value rather than a `Model` for the same reason: nothing here ever writes it. It marks the current chip; the app owns the signal and switches the body itself.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | frame title |
| `version` | `string` | shown beside the title |
| `subtitle` | `string` | secondary line |
| `header` | `'boxed' \| 'gradient' \| 'plain'` | header style |
| `tabs` | `TabOption<string>[]` | the tab strip |
| `activeTab` | `string` | which chip is marked current — read-only to the frame |
| `body` | `'boxed' \| 'plain'` | body frame style |
| `bodyTitle` | `string` | title on the body frame |
| `status` | `StatusItem[]` | the status line |
| `hints` | `KeyHint[]` | the key-hint footer |

### Slot

| Slot | Scope | Notes |
| --- | --- | --- |
| `default` | `ShellPane` — `{ width, height }` | the content box inside the frame |

## See also

- [DataTable](/terminal/docs/components/datatable) — takes `width`/`height` directly.
- [Card](/terminal/docs/components/card) — a titled panel, without the frame arithmetic.

---
url: https://sigx.dev/terminal/docs/components/trend/
title: Trend
description: A value with its direction of travel — and whether that direction is good news
---

# Trend

<p class="lede">A value with its direction of travel against the previous reading: <code>▲</code>, <code>▼</code> or <code>·</code>.</p>

## Import

```tsx
import { Trend } from '@sigx/terminal';
```

## Usage

```tsx
<Trend current={p99} previous={prevP99} value={`${p99}ms`} />
<Trend current={rps} previous={prevRps} value={`${rps}/s`} polarity="higher-is-better" />
```

## `polarity` is not decoration

Whether "up" is good news depends entirely on the metric. Rising latency is a problem; rising throughput is not. A component that hardcoded `▲ = warning` would be lying about half the numbers on a dashboard — so the metric has to say which it is:

| `polarity` | Up | Down | For |
| --- | --- | --- | --- |
| `higher-is-worse` *(default)* | `warn` | `success` | latency, error rate, queue depth, memory |
| `higher-is-better` | `success` | `warn` | throughput, hit rate, healthy replicas |
| `neutral` | — | — | direction only, no judgement |

**A `null` on either side is a gap, not a direction.** Comparing across a counter reset would report a crash that never happened.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `current` | `number \| null` | **required** — `null` is a gap |
| `previous` | `number \| null` | the reading to compare against |
| `value` | `string` | the text shown; defaults to the number |
| `polarity` | `'higher-is-worse' \| 'higher-is-better' \| 'neutral'` | default `'higher-is-worse'` |
| `color` | `string` | override the polarity tone |

## See also

- [Sparkline](/terminal/docs/components/sparkline) — the whole series behind the direction.

---
url: https://sigx.dev/terminal/docs/components/table/
title: Table
description: Columns and rows of text data
---

# Table

<p class="lede">A simple text table — a header row of <code>columns</code> over a grid of <code>rows</code>.</p>

## Import

```tsx
import { Table } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Table } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box border="single" label="Packages">
            <Table
                columns={['Package', 'Version', 'Status']}
                rows={[
                    ['@sigx/terminal', '0.6.1', 'latest'],
                    ['@sigx/args', '0.6.1', 'latest'],
                    ['@sigx/terminal-dev', '0.6.1', 'latest'],
                ]}
            />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `columns` | `string[]` | **required** — header labels |
| `rows` | `string[][]` | row cells, in column order |

## See also

- [QRCode](/terminal/docs/components/qrcode) — render a scannable code.

---
url: https://sigx.dev/actors/packages/actors-pg/api/
title: API reference
description: Exports of @sigx/actors-pg — pgStorage, pgMembership, pgDirectory, pgReminders, pgCluster — with the table layout and CAS semantics
---

# API reference

<p class="lede">Exports of `@sigx/actors-pg` .</p>

## Providers

| Export | Returns | Role |
|---|---|---|
| `pgCluster(options)` | `ClusterProviders` | membership + directory |
| `pgMembership(pool, options?)` | `ClusterMembership` | liveness on the database clock |
| `pgDirectory(pool, options?)` | `ActorDirectory` | single-activation claims |
| `pgStorage(options)` | `ActorStorage` | etag-CAS `text` rows |
| `pgReminders(options)` | `ActorReminders` | `SKIP LOCKED` durable reminders |

## Schema helpers

```ts
// ensurePgSchema(pool: PgPoolLike, options?: { schema?: string }): Promise<void>
// pgSchemaSql(schema?: string): string

await ensurePgSchema(pool);                  // issues the DDL under an advisory xact lock
await ensurePgSchema(pool, { schema: 'app' });

console.log(pgSchemaSql());                  // returns it, for your migration tool
```

## Encoding helpers

`pgText(value)` and `pgTextDecode(value)` — the text encoding used for stored values, exported
for tooling that needs to read or write the tables directly.

## Types

`PgQueryable`, `PgPoolLike`, `PgClusterOptions`, `PgStorageOptions`, `PgRemindersOptions`.

## Table layout

All under the configured schema, `sigx` by default.

```sql
state(type, key, etag, state)                       -- state is text
directory(actor_id, host_id, activation_id)         -- + directory_host_id index
hosts(host_id, descriptor, expires_at)
membership_version(id, version)
reminders(type, key, name, next_due, period_ms)     -- + reminders_due index
```

## Semantics worth knowing

**Etags are client-minted UUIDs**, equality-compared only. Every CAS is a single statement
whose row count is the verdict — no transactions, no advisory locks.

**State is `text`, not `jsonb`** — deliberately. Actor state may contain NUL, which `jsonb`
rejects outright, so the column stores the encoded string verbatim and Postgres never parses
it. A top-level array state therefore cannot be silently coerced into a Postgres `ARRAY`
either.

**Directory entries carry no TTL.** There is one heartbeat per host, not per activation; entry
validity is the owner's liveness in the membership view, and the storage etag CAS remains the
integrity floor underneath.

**Membership change detection compares host signatures**, not just the version counter — a
host that dies silently expires on the database clock without anyone bumping a version, and
views still converge.

**Push is best-effort.** `LISTEN` rides a connection checked out of the pool; if the pool
cannot dedicate one, or the connection drops, the poll is the guarantee and `pollMs` is the
propagation bound.

**Reminders commit before delivery.** The advance-or-delete is committed *before* the handler
runs, which is what makes delivery at-most-once and prevents catch-up bursts after an outage.

## Next steps

- [Overview](/actors/packages/actors-pg/overview) — what each provider is for.
- [Installation](/actors/packages/actors-pg/installation) — schema and wiring.
- [Storage](/actors/docs/storage) — the seam and the alternatives.

---
url: https://sigx.dev/actors/packages/actors-ws/api/
title: API
description: Exports of @sigx/actors-ws — socketTransport on ./client, attachActorSocket and toRequest on ./node
---

# API

<p class="lede">Exports of `@sigx/actors-ws` .</p>

Three entries. The root re-exports the client half, which is WinterCG-clean; `./node` is the
only one that touches Node built-ins.

| Entry | Contents |
|---|---|
| `@sigx/actors-ws` | `socketTransport` and its types — runtime-neutral re-exports of `./client` |
| `@sigx/actors-ws/client` | the same, at its source |
| `@sigx/actors-ws/node` | `attachActorSocket`, `toRequest`, `DEFAULT_SOCKET_PATH` |

## `./client`

```ts
function socketTransport(options?: SocketTransportOptions): ActorTransport;

interface SocketTransportOptions {
    connect?(handlers: SocketHandlers): SocketLink;
    url?: string;
    retryMs?: number;        // default 300
    maxRetryMs?: number;     // default 10_000
}

interface SocketLink {
    send(message: string): void;
    close(): void;
}

interface SocketHandlers {
    onOpen(): void;          // gates the first send
    onMessage(message: string): void;
    onClose(): void;
}
```

`connect` is called again after a drop — each call is one fresh attempt. Passing `url` on a
runtime with no global `WebSocket` constructor throws with a message telling you to pass
`connect` instead.

The returned value is an ordinary [`ActorTransport`](/actors/docs/wire-protocol), so it also
carries `live()` — the incremental subscription channel — and a `close()` that is
**idempotent by contract**, since either the plugin or the live channel may release it first.

## `./node`

```ts
function attachActorSocket(server: Server, options: AttachActorSocketOptions): () => void;

interface AttachActorSocketOptions
    extends Omit<ActorSocketSessionOptions, 'request' | 'send' | 'close'> {
    path?: string;              // default '/_sigx/socket', matched exactly
    wss?: WebSocketServerLike;  // bring your own noServer WebSocketServer
}

function toRequest(request: IncomingMessage): Request;

const DEFAULT_SOCKET_PATH = '/_sigx/socket';
```

`attachActorSocket` returns a **detach** function. `toRequest` builds the WinterCG `Request` a
Node upgrade does not come with — scheme `http` (the session folds `ws:`/`http:` when checking
origin), headers including cookies and `Origin` carried over verbatim.

Everything `AttachActorSocketOptions` inherits — `host`, `origin`, `maxMessageBytes`,
`maxConcurrent`, `maxSubscriptions`, `pingMs`, `revalidateMs`, `maxConnectionMs`, `onError`,
`stats` — is documented under [Socket sessions](/actors/docs/socket-sessions).

### Structural types

`WebSocketServerLike` and `MinimalWebSocket` describe only the slices of `ws` the adapter
actually drives, so a compatible implementation satisfies them without `ws` being installed:

```ts
interface WebSocketServerLike {
    handleUpgrade(
        request: IncomingMessage, socket: Duplex, head: Buffer,
        done: (client: MinimalWebSocket) => void,
    ): void;
}

interface MinimalWebSocket {
    send(message: string): void;
    close(code?: number, reason?: string): void;
    on(event: 'message', listener: (data: unknown, isBinary: boolean) => void): void;
    on(event: 'close', listener: () => void): void;
}
```

## The wire

Both halves speak [`@sigx/actors/socket-wire`](/actors/docs/wire-protocol#the-socket-wire),
which is a published subpath of `@sigx/actors` rather than something this package owns — so an
adapter written outside this repo reaches the same protocol.

## Next steps

- [Overview](/actors/packages/actors-ws/overview) — what the transport is for.
- [Installation](/actors/packages/actors-ws/installation) — wiring and interop recipes.
- [Socket sessions](/actors/docs/socket-sessions) — the server session in full.

---
url: https://sigx.dev/core/packages/runtime-dom/api/
title: API reference
description: API reference for @sigx/runtime-dom — every export of the SignalX Runtime DOM package.
---

# API reference

<p class="lede">Exports of `@sigx/runtime-dom` . Import from `@sigx/runtime-dom`; low-level renderer primitives also re-export from `@sigx/runtime-dom/internals`.</p>

## Side effects on import

Importing the package entry is impure by design (`package.json` marks `index` as having side effects). Loading it installs global JSX type augmentation, sets `HTMLElement` as the default element type for `@sigx/runtime-core`, registers the DOM renderer as core's default mount target, enables v-model on form elements, and auto-registers the built-in `show` directive. Merely importing `@sigx/runtime-dom` wires up the DOM platform globally.

## Rendering

### `render`

```ts
export const render: (
  element: JSXElement,
  container: Element | string,
  appContext?: AppContext,
) => void
```

Mounts a SignalX element tree into a DOM container.

- `element` — the JSX element tree to mount. Pass `null` to unmount and clear the container.
- `container` — an `Element` reference or a CSS selector string.
- `appContext` — optional app context (directives, plugins) to render under.
- **Returns** `void`. Throws a render-target-not-found error if `container` resolves to nothing.

## Components

### `Portal`

```ts
export const Portal: ComponentFactory<PortalProps, void, {}>
// PortalProps = Define.Prop<'to', string | Element> & Define.Prop<'disabled', boolean>
```

Renders its children into a different DOM container.

- `to` — target container as an `Element` or CSS selector string. Defaults to `document.body`. If a selector is not found, `Portal` warns and falls back to `document.body`.
- `disabled` — when `true`, renders children in place (via a Fragment) instead of portaling.

Children are placed inside a generated `<div data-sigx-portal>` appended to the target. Moves are state-preserving when `moveBefore` is available (see `supportsMoveBefore`); otherwise `insertBefore` is used. On unmount, the effect is stopped, content is unmounted and the container `<div>` is removed.

## Directives

### `show`

```ts
export const show: DirectiveDefinition<boolean, HTMLElement>
```

Built-in directive that toggles element visibility via the CSS `display` property while keeping the element in the DOM. Auto-registered on import, so `use:show={visible}` resolves it by name. Also accepts the explicit tuple form `use:show={[show, visible]}`.

## Custom directives

### `patchDirective`

```ts
export function patchDirective(
  el: Element,
  name: string,
  prevValue: any,
  nextValue: any,
  appContext: AppContext | null,
): void
```

Processes a `use:*` prop, running directive `created`/`updated` lifecycle hooks. Resolves the directive from the value (definition, `[definition, value]` tuple, or name lookup against built-ins then `appContext.directives`). Unresolvable names log a warning and are skipped. Marked `@internal` in source.

### `onElementMounted`

```ts
export function onElementMounted(el: Element): void
```

Invokes the `mounted` hook for all directives attached to an element after DOM insertion. Marked `@internal` in source.

### `registerBuiltInDirective`

```ts
export function registerBuiltInDirective(name: string, def: DirectiveDefinition): void
```

Register a directive into the built-in tier so the `use:<name>={value}` shorthand resolves it globally — across every app and `render()` call, with no per-app `app.directive()` wiring. The standard built-in `show` registers itself this way on import; reach for it when shipping a directive pack that should be available everywhere.

- `name` — the directive name used in `use:<name>`.
- `def` — the directive definition (from `defineDirective`).

### `resolveBuiltInDirective`

```ts
export function resolveBuiltInDirective(name: string): DirectiveDefinition | undefined
```

Looks up a registered built-in directive by name; used by the SSR renderer. Returns the definition or `undefined`. Marked `@internal` in source.

## DOM properties

### `patchProp`

```ts
export function patchProp(
  dom: Element,
  key: string,
  prevValue: any,
  nextValue: any,
  isSVG?: boolean,
): void
```

Sets or updates a single DOM property on an element.

- `dom` — the target element.
- `key` — the prop key. `children`, `key` and `ref` are skipped. `style` accepts an object (with `--custom-prop` support) or a `cssText` string. `on*` keys add event listeners (a `CustomEvent` passes `e.detail`, otherwise the event). `className` is applied via `setAttribute('class')`. Keys starting with `.` or `prop:` force property assignment. SVG elements use case-preserving `setAttribute` and `xlink:` namespace handling. Form `value`/`checked` are set as properties; a `<select>` value is deferred via `queueMicrotask` until options mount (supports multi-select arrays).
- `prevValue` — the previous value, used to remove stale listeners/attributes.
- `nextValue` — the value to apply.
- `isSVG` — optional flag selecting SVG attribute handling.

## Low-level node operations

### `moveNode`

```ts
export function moveNode(parent: Element, node: Node, anchor?: Node | null): void
```

Moves or inserts a node into a parent. Uses `moveBefore` for state-preserving moves when available, otherwise `insertBefore`.

- `parent` — the destination element.
- `node` — the node to move/insert.
- `anchor` — optional node to insert before; appends when omitted or `null`.

### `supportsMoveBefore`

```ts
export function supportsMoveBefore(): boolean
```

Returns `true` if the browser supports the state-preserving `Node.prototype.moveBefore` API (Chrome 133+).

### `nodeOps`

```ts
export const nodeOps: RendererOptions<Node, Element>
```

Complete `RendererOptions` implementation for the DOM platform: create/insert/remove nodes, text handling, SVG namespace, customized built-in elements via the `is` option, and focus preservation (`restoreFocus` refocuses with `preventScroll` and suppresses focus/blur events during restoration). Used to construct the DOM renderer.

**SVG lives here, not in core.** `@sigx/runtime-core` is namespace-agnostic — it threads an opaque boolean flag and asks the host what it means. `nodeOps` supplies the three [namespace host ops](/core/packages/runtime-core/api#host-namespaces-rendereroptions): the SVG tag-name set in `getElementNamespace`, the `foreignObject` reset in `getChildNamespace`, and the container rule in `getContainerNamespace`. It is the reference implementation for anyone writing a DOM-like custom renderer.

## Renderer primitives (SSR/hydration)

These are low-level primitives, exported for SSR/hydration plugins and extensions. They are also available from `@sigx/runtime-dom/internals`, are not stable public API, and may change without notice.

### `patch`

```ts
export const patch: RendererPatchFn<Node, Element>
```

Diffs and patches an old VNode into a new one.

### `mount`

```ts
export const mount: RendererMountFn<Node, Element>
```

Mounts a VNode into a container.

### `unmount`

```ts
export const unmount: RendererUnmountFn<Node, Element>
```

Unmounts a VNode from a container.

### `mountComponent`

```ts
export const mountComponent: RendererMountComponentFn<Node, Element>
```

Mounts a component VNode.

## Types

### `DOMDirective`

```ts
export type DOMDirective<T = any> = DirectiveDefinition<T, HTMLElement>
```

A directive definition narrowed to `HTMLElement`, for typing custom DOM directives. The type parameter `T` is the directive's value type.

```ts
import { defineDirective } from 'sigx';
import type { DOMDirective } from '@sigx/runtime-dom';

const tooltip: DOMDirective<string> = defineDirective<string, HTMLElement>({
  mounted(el, { value }) {
    el.title = value;
  },
});
```

## See also

- [Usage](/core/packages/runtime-dom/usage) — practical guide.
- [Directives](/core/docs/directives) and [DOM properties](/core/docs/dom-properties) — the underlying models.
- [Portals](/core/docs/portal) and [Two-way binding](/core/docs/two-way-binding).

---
url: https://sigx.dev/daisyui/docs/components/alert/
title: Alert
description: Alerts inform users about important events
---

# Alert

Alert informs users about important events.

## Import

```tsx
import { Alert } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Alert } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Alert>A simple alert message.</Alert>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

```tsx
import { component, render } from 'sigx';
import { Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Alert variant="info">New software update available.</Alert>
            <Alert variant="success">Your purchase has been confirmed!</Alert>
            <Alert variant="warning">Warning: Invalid email address!</Alert>
            <Alert variant="error">Error! Task failed successfully.</Alert>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Soft Style

```tsx
import { component, render } from 'sigx';
import { Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Alert variant="info" alertStyle="soft">Info with soft style.</Alert>
            <Alert variant="success" alertStyle="soft">Success with soft style.</Alert>
            <Alert variant="warning" alertStyle="soft">Warning with soft style.</Alert>
            <Alert variant="error" alertStyle="soft">Error with soft style.</Alert>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Outline Style

```tsx
import { component, render } from 'sigx';
import { Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Alert variant="info" alertStyle="outline">Info with outline style.</Alert>
            <Alert variant="success" alertStyle="outline">Success with outline style.</Alert>
            <Alert variant="warning" alertStyle="outline">Warning with outline style.</Alert>
            <Alert variant="error" alertStyle="outline">Error with outline style.</Alert>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Dash Style

```tsx
import { component, render } from 'sigx';
import { Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Alert variant="info" alertStyle="dash">Info with dash style.</Alert>
            <Alert variant="success" alertStyle="dash">Success with dash style.</Alert>
            <Alert variant="warning" alertStyle="dash">Warning with dash style.</Alert>
            <Alert variant="error" alertStyle="dash">Error with dash style.</Alert>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Layout

Use `layout` to control the direction of content inside the alert.

```tsx
import { component, render } from 'sigx';
import { Alert, Button, Col, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Alert variant="warning" layout="vertical">
                <Row gap="2" align="center">We use cookies for no reason.</Row>
                <Row gap="2">
                    <Button size="sm">Deny</Button>
                    <Button size="sm" variant="primary">Accept</Button>
                </Row>
            </Alert>
            <Alert variant="success" layout="horizontal">
                Your purchase has been confirmed!
            </Alert>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `undefined` | Alert color variant |
| `alertStyle` | `'outline' \| 'dash' \| 'soft'` | `undefined` | Alert style modifier |
| `layout` | `'vertical' \| 'horizontal'` | `undefined` | Layout direction |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/core/docs/advanced/reactivity/
title: Advanced Reactivity
description: Advanced reactivity utilities in SignalX - batch, untrack, effectScope, and more
---

# Advanced Reactivity

SignalX provides advanced utilities for fine-grained control over reactivity. These are escape hatches for performance optimization and edge cases.

## Batching Updates

Use `batch()` to group multiple signal updates into a single reactive flush:

```tsx
import { signal, batch, effect } from 'sigx';

const state = signal({ 
    firstName: 'John', 
    lastName: 'Doe', 
    age: 30 
});

// Effect will log on each update
effect(() => {
    console.log(`Name: ${state.firstName} ${state.lastName}, Age: ${state.age}`);
});

console.log('--- Without batch (effect runs 3 times) ---');
state.firstName = 'Jane';
state.lastName = 'Smith';
state.age = 25;

console.log('--- With batch (effect runs once) ---');
batch(() => {
    state.firstName = 'John';
    state.lastName = 'Doe';
    state.age = 30;
});
```

### When to Use Batch

- **Multiple related updates** - Updating several properties at once
- **Loop updates** - Modifying signals in a loop
- **Performance** - Reducing effect re-runs

```tsx
// Efficient bulk update
batch(() => {
    items.forEach((item, i) => {
        state.items[i] = processItem(item);
    });
    state.lastUpdated = Date.now();
});
```

### Nested Batching

Batches can be nested - effects only run after the outermost batch completes:

```tsx
import { signal, batch, effect } from 'sigx';

const state = signal({ a: 0, b: 0, c: 0, d: 0 });

effect(() => {
    console.log(`State: a=${state.a}, b=${state.b}, c=${state.c}, d=${state.d}`);
});

console.log('--- Starting nested batch ---');
batch(() => {
    state.a = 1;
    console.log('Set a=1 (inside outer batch)');
    batch(() => {
        state.b = 2;
        state.c = 3;
        console.log('Set b=2, c=3 (inside inner batch)');
    });
    console.log('Inner batch complete, effect still pending...');
    state.d = 4;
    console.log('Set d=4 (still inside outer batch)');
});
console.log('Outer batch complete - effect ran once!');
```

## Enumerating Reactive Objects

Enumerating a reactive object inside an effect or a computed subscribes to its
**key set**, so a key appearing or disappearing re-runs the reader. That covers
`Object.keys()`, `for…in`, object spread and rest destructuring:

```tsx
import { signal, effect } from 'sigx';

const state = signal<Record<string, number>>({ a: 1 });

effect(() => {
    console.log(Object.keys(state).join(', '));
});

state.b = 2;      // re-runs — the key set changed
delete state.a;   // re-runs — so does removal
state.b = 99;     // no re-run — Object.keys reads no values
```

The key-set subscription is **on top of** the per-key ones, which is what makes
the two enumeration styles differ:

- `Object.keys()` reads no values, so it depends on the key set alone. Changing
  `state.a` from `1` to `2` doesn't re-run it.
- A spread copies every value, so it depends on the key set *and* every key —
  it re-runs when any of them changes.

`'x' in state` subscribes to the same per-key dependency a read of `state.x`
would, so presence and value always agree.

Arrays carry their enumeration dependency on `length` rather than a separate
one, and every change to an array's key set is routed there — including the two
cases where the key set moves but the length doesn't, `delete list[i]` and
filling the hole it leaves. Maps and Sets have always tracked their own
iteration and `.size`.

Plain property access is unaffected. Reading `state.foo` goes through the proxy
as it always has, but it never reaches the enumeration trap, so it creates no
key-set dependency and the common path costs nothing extra.

### Bulk Key Insertion

Because each new key re-runs every reader that enumerates the object, adding
keys one at a time is quadratic. Wrap the loop in `batch()`:

```tsx
// One re-run, not one per key.
batch(() => {
    for (const [key, value] of entries) state[key] = value;
});
```

This is worth knowing about any object something enumerates for a side effect —
it now runs more often than a reader that only touched individual keys.

## Reading Without Tracking

Use `untrack()` to read signal values without creating a dependency:

```tsx
import { signal, effect, untrack } from 'sigx';

const state = signal({ count: 1, multiplier: 2 });

effect(() => {
    // This effect depends on count but NOT multiplier
    const mult = untrack(() => state.multiplier);
    console.log(`count(${state.count}) * multiplier(${mult}) = ${state.count * mult}`);
});

console.log('--- Incrementing count (effect WILL run) ---');
state.count++;

console.log('--- Incrementing multiplier (effect will NOT run) ---');
state.multiplier++;
console.log('Multiplier changed but effect did not re-run');
```

### Use Cases

1. **One-time reads** - Read initial/default values:
   ```tsx
   const initialValue = untrack(() => config.defaultValue);
   ```

2. **Avoid circular dependencies**:
   ```tsx
   effect(() => {
       const current = state.value;
       // Use untrack to avoid triggering this effect again
       untrack(() => history.push(current));
   });
   ```

3. **Conditional dependencies**:
   ```tsx
   effect(() => {
       if (state.useAdvanced) {
           // Only track advancedData when useAdvanced is true
           console.log(state.advancedData);
       } else {
           // Don't track advancedData when not needed
           untrack(() => console.log(state.advancedData));
       }
   });
   ```

## Getting Raw Objects

Use `toRaw()` to get the underlying non-reactive object from a signal:

```tsx
import { signal, toRaw, isReactive } from 'sigx';

const state = signal({ 
    users: ['Alice', 'Bob'], 
    settings: { theme: 'dark' } 
});

console.log('state is reactive:', isReactive(state));

// Get the raw, non-reactive object
const raw = toRaw(state);

console.log('raw is reactive:', isReactive(raw));
console.log('Raw object:', JSON.stringify(raw, null, 2));
```

### Nested Objects

`toRaw()` only unwraps the immediate proxy. For nested objects:

```tsx
const state = signal({ 
    user: { 
        profile: { name: 'John' } 
    } 
});

// Only unwraps outer proxy
const raw = toRaw(state);
// raw.user is still reactive if accessed through the original proxy

// For deep unwrapping, use structuredClone or manual deep copy
const deepRaw = JSON.parse(JSON.stringify(toRaw(state)));
```

## Checking Reactivity

Use `isReactive()` to check if a value is a reactive proxy:

```tsx
import { signal, isReactive, toRaw } from 'sigx';

const state = signal({ count: 0 });
const plain = { count: 0 };

console.log('state is reactive:', isReactive(state));
console.log('plain is reactive:', isReactive(plain));

// Useful for debugging or conditional logic
function logValue(value: any) {
    if (isReactive(value)) {
        console.log('Reactive:', JSON.stringify(toRaw(value)));
    } else {
        console.log('Plain:', JSON.stringify(value));
    }
}

logValue(state);
logValue(plain);
```

## Effect Scopes

Use `effectScope()` to group effects and stop them together:

```tsx
import { signal, effect, effectScope } from 'sigx';

const scope = effectScope();
const state = signal({ count: 0 });

scope.run(() => {
    // These effects are tracked by the scope
    effect(() => console.log('Count:', state.count));
    effect(() => console.log('Double:', state.count * 2));
});

console.log('--- Updating count (effects run) ---');
state.count = 5;

console.log('--- Stopping scope ---');
scope.stop();

console.log('--- Updating count again (effects do NOT run) ---');
state.count = 10;
console.log('Count is now', state.count, 'but effects were stopped');
```

### Detached Scopes

Create a detached scope that doesn't stop when its parent stops:

```tsx
import { signal, effect, effectScope } from 'sigx';

const state = signal({ value: 0 });
const parentScope = effectScope();
let detachedScope: ReturnType<typeof effectScope>;

parentScope.run(() => {
    // Detached scope - independent lifetime
    detachedScope = effectScope(true);
    
    effect(() => console.log('Parent effect - value:', state.value));
    
    detachedScope.run(() => {
        // This effect survives parent.stop()
        effect(() => console.log('Detached effect - value:', state.value));
    });
});

console.log('--- Updating value (both effects run) ---');
state.value = 1;

console.log('--- Stopping parent scope ---');
parentScope.stop();

console.log('--- Updating value (only detached runs) ---');
state.value = 2;
```

### Use Cases

1. **Component cleanup** - Group all component effects:
   ```tsx
   const MyComponent = component((ctx) => {
       const scope = effectScope();
       
       ctx.onMounted(() => {
           scope.run(() => {
               effect(() => { /* ... */ });
               effect(() => { /* ... */ });
           });
       });
       
       ctx.onUnmounted(() => {
           scope.stop();
       });
   });
   ```

2. **Feature modules** - Enable/disable features:
   ```tsx
   let featureScope: EffectScope | null = null;
   
   function enableFeature() {
       featureScope = effectScope();
       featureScope.run(() => {
           // All feature effects
       });
   }
   
   function disableFeature() {
       featureScope?.stop();
       featureScope = null;
   }
   ```

## API Reference

### `batch(fn)`

Batch multiple reactive updates into a single flush.

| Parameter | Type | Description |
|-----------|------|-------------|
| `fn` | `() => void` | Function containing signal updates |

### `untrack(fn)`

Execute a function without tracking dependencies.

| Parameter | Type | Description |
|-----------|------|-------------|
| `fn` | `() => T` | Function to execute |

**Returns:** The return value of `fn`

### `toRaw(proxy)`

Get the raw object from a reactive proxy.

| Parameter | Type | Description |
|-----------|------|-------------|
| `proxy` | `T` | A reactive proxy |

**Returns:** The underlying raw object, or the value itself if not reactive

### `isReactive(value)`

Check if a value is a reactive proxy.

| Parameter | Type | Description |
|-----------|------|-------------|
| `value` | `unknown` | Value to check |

**Returns:** `boolean`

### `effectScope(detached?)`

Create a scope for grouping effects.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `detached` | `boolean` | `false` | If true, scope is independent of parent |

**Returns:** `EffectScope` with `run()` and `stop()` methods

## Best Practices

1. **Use batch for bulk operations**:
   ```tsx
   // Good
   batch(() => {
       state.items = newItems;
       state.count = newItems.length;
       state.lastModified = Date.now();
   });
   ```

2. **Use untrack for initial reads**:
   ```tsx
   effect(() => {
       const initial = untrack(() => state.initialValue);
       // Only track changes to state.current
       if (state.current !== initial) {
           // Handle change
       }
   });
   ```

3. **Use toRaw for external APIs**:
   ```tsx
   // Always use toRaw when passing to non-SignalX code
   thirdPartyLib.process(toRaw(state.data));
   ```

4. **Scope effects appropriately**:
   ```tsx
   // Group related effects for easy cleanup
   const featureScope = effectScope();
   featureScope.run(() => {
       // Feature effects
   });
   // One call stops everything
   featureScope.stop();
   ```

## Next Steps

- [Factories](/core/docs/advanced/factories) - Injectable service pattern
- [Messaging](/core/docs/advanced/messaging) - Pub/sub communication
- [Effects](/core/docs/effects) - Basic effect usage

---
url: https://sigx.dev/daisyui/docs/components/badge/
title: Badge
description: Badges are used to inform the user of the status of specific data
---

# Badge

Badge is used to inform the user of the status of specific data.

## Import

```tsx
import { Badge } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Badge } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Badge>Badge</Badge>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Badge>default</Badge>
            <Badge variant="neutral">neutral</Badge>
            <Badge variant="primary">primary</Badge>
            <Badge variant="secondary">secondary</Badge>
            <Badge variant="accent">accent</Badge>
            <Badge variant="ghost">ghost</Badge>
            <Badge variant="info">info</Badge>
            <Badge variant="success">success</Badge>
            <Badge variant="warning">warning</Badge>
            <Badge variant="error">error</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Outline

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Badge badgeStyle="outline">default</Badge>
            <Badge variant="primary" badgeStyle="outline">primary</Badge>
            <Badge variant="secondary" badgeStyle="outline">secondary</Badge>
            <Badge variant="accent" badgeStyle="outline">accent</Badge>
            <Badge variant="info" badgeStyle="outline">info</Badge>
            <Badge variant="success" badgeStyle="outline">success</Badge>
            <Badge variant="warning" badgeStyle="outline">warning</Badge>
            <Badge variant="error" badgeStyle="outline">error</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Soft

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Badge badgeStyle="soft">default</Badge>
            <Badge variant="primary" badgeStyle="soft">primary</Badge>
            <Badge variant="secondary" badgeStyle="soft">secondary</Badge>
            <Badge variant="accent" badgeStyle="soft">accent</Badge>
            <Badge variant="info" badgeStyle="soft">info</Badge>
            <Badge variant="success" badgeStyle="soft">success</Badge>
            <Badge variant="warning" badgeStyle="soft">warning</Badge>
            <Badge variant="error" badgeStyle="soft">error</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Dash

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap>
            <Badge badgeStyle="dash">default</Badge>
            <Badge variant="primary" badgeStyle="dash">primary</Badge>
            <Badge variant="secondary" badgeStyle="dash">secondary</Badge>
            <Badge variant="accent" badgeStyle="dash">accent</Badge>
            <Badge variant="info" badgeStyle="dash">info</Badge>
            <Badge variant="success" badgeStyle="dash">success</Badge>
            <Badge variant="warning" badgeStyle="dash">warning</Badge>
            <Badge variant="error" badgeStyle="dash">error</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" align="center">
            <Badge size="xl">xl</Badge>
            <Badge size="lg">lg</Badge>
            <Badge size="md">md</Badge>
            <Badge size="sm">sm</Badge>
            <Badge size="xs">xs</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Empty Badges

Empty badges can be used as status indicators or dot badges.

```tsx
import { component, render } from 'sigx';
import { Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" align="center">
            <Badge size="xs" variant="primary">{""}</Badge>
            <Badge size="sm" variant="secondary">{""}</Badge>
            <Badge size="md" variant="accent">{""}</Badge>
            <Badge size="lg" variant="neutral">{""}</Badge>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Badge in Text

```tsx
import { component, render } from 'sigx';
import { Badge, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Row gap="2" align="center">
                <Text>Inbox</Text>
                <Badge size="sm" variant="primary">+99</Badge>
            </Row>
            <Row gap="2" align="center">
                <Text>Updates</Text>
                <Badge size="sm" variant="secondary">NEW</Badge>
            </Row>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error' \| 'ghost' \| 'neutral'` | `undefined` | Badge color variant |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `undefined` | Badge size |
| `badgeStyle` | `'outline' \| 'soft' \| 'dash' \| 'ghost'` | `undefined` | Badge style modifier |
| `outline` | `boolean` | `false` | Shorthand for outline style (overridden by `badgeStyle`) |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/input/
title: Input
description: Text input fields for forms with model binding, validation states, and sizes
---

# Input

Text input component for single-line text entry with model binding support.

## Import

```tsx
import { Input, Col } from '@sigx/daisyui';
```

## Basic Usage

Use `model` for two-way binding:

```tsx
import { component, render } from 'sigx';
import { Input, Card, Col, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ 
        name: '',
        email: ''
    });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Input 
                    model={() => form.name}
                    placeholder="Enter your name"
                    variant="bordered"
                />
                <Input 
                    model={() => form.email}
                    type="email"
                    placeholder="Enter your email"
                    variant="bordered"
                />
                <Col gap="1">
                    <Text size="sm" class="opacity-70">Name: {form.name || '(empty)'}</Text>
                    <Text size="sm" class="opacity-70">Email: {form.email || '(empty)'}</Text>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Input Types

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ 
        text: '',
        email: '',
        password: '',
        search: '',
        url: ''
    });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField label="Text">
                    <Input model={() => form.text} type="text" placeholder="Plain text" variant="bordered" />
                </FormField>
                <FormField label="Email">
                    <Input model={() => form.email} type="email" placeholder="you@example.com" variant="bordered" />
                </FormField>
                <FormField label="Password">
                    <Input model={() => form.password} type="password" placeholder="••••••••" variant="bordered" />
                </FormField>
                <FormField label="Search">
                    <Input model={() => form.search} type="search" placeholder="Search..." variant="bordered" />
                </FormField>
                <FormField label="URL">
                    <Input model={() => form.url} type="url" placeholder="https://example.com" variant="bordered" />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Input, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Input size="xs" placeholder="Extra small" variant="bordered" />
            <Input size="sm" placeholder="Small" variant="bordered" />
            <Input size="md" placeholder="Medium (default)" variant="bordered" />
            <Input size="lg" placeholder="Large" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Input, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Input color="primary" placeholder="Primary" variant="bordered" />
            <Input color="secondary" placeholder="Secondary" variant="bordered" />
            <Input color="accent" placeholder="Accent" variant="bordered" />
            <Input color="info" placeholder="Info" variant="bordered" />
            <Input color="success" placeholder="Success" variant="bordered" />
            <Input color="warning" placeholder="Warning" variant="bordered" />
            <Input color="error" placeholder="Error" variant="bordered" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

```tsx
import { component, render } from 'sigx';
import { Input, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Input placeholder="Default (no variant)" />
            <Input placeholder="Bordered" variant="bordered" />
            <Input placeholder="Ghost" variant="ghost" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With FormField

Wrap inputs with `FormField` for labels, helper text, and error messages:

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ email: '', password: '' });
    const emailError = () => form.email && !form.email.includes('@') ? 'Please enter a valid email' : '';
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField 
                    label="Email" 
                    required 
                    error={emailError()}
                >
                    <Input 
                        model={() => form.email}
                        type="email"
                        placeholder="you@example.com"
                        color={emailError() ? 'error' : undefined}
                        variant="bordered"
                    />
                </FormField>
                
                <FormField 
                    label="Password" 
                    hint="Must be at least 8 characters"
                >
                    <Input 
                        model={() => form.password}
                        type="password" 
                        placeholder="••••••••" 
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Number Input

For number inputs, the model value is automatically converted to a number:

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ quantity: 1, price: 9.99 });
    const total = () => form.quantity * form.price;
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField label="Quantity">
                    <Input 
                        model={() => form.quantity}
                        type="number" 
                        variant="bordered"
                    />
                </FormField>
                
                <FormField label="Price">
                    <Input 
                        model={() => form.price}
                        type="number" 
                        variant="bordered"
                    />
                </FormField>
                
                <Text size="lg" weight="bold">
                    Total: ${total().toFixed(2)}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled and ReadOnly

```tsx
import { component, render } from 'sigx';
import { Input, Col } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Input placeholder="Disabled input" variant="bordered" disabled />
            <Input value="Read-only value" variant="bordered" readOnly />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Max Length

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ username: '' });
    
    return () => (
        <Card>
            <Card.Body>
                <FormField 
                    label="Username" 
                    hint={`${form.username.length}/20 characters`}
                >
                    <Input 
                        model={() => form.username}
                        placeholder="Choose a username"
                        maxLength={20}
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Login Form Example

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Button, Card, Checkbox, Divider, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ 
        email: '', 
        password: '',
        remember: false
    });
    
    const errors = signal({
        email: '',
        password: ''
    });
    
    const validate = () => {
        let valid = true;
        
        if (!form.email) {
            errors.email = 'Email is required';
            valid = false;
        } else if (!form.email.includes('@')) {
            errors.email = 'Invalid email format';
            valid = false;
        } else {
            errors.email = '';
        }
        
        if (!form.password) {
            errors.password = 'Password is required';
            valid = false;
        } else if (form.password.length < 8) {
            errors.password = 'Password must be at least 8 characters';
            valid = false;
        } else {
            errors.password = '';
        }
        
        return valid;
    };
    
    const handleSubmit = () => {
        if (validate()) {
            alert('Login successful!');
        }
    };
    
    return () => (
        <Card class="max-w-md mx-auto">
            <Card.Body class="space-y-4">
                <Heading level={2} size="xl" align="center">Sign In</Heading>
                
                <FormField label="Email" required error={errors.email}>
                    <Input 
                        model={() => form.email}
                        type="email"
                        placeholder="you@example.com"
                        color={errors.email ? 'error' : undefined}
                        variant="bordered"
                    />
                </FormField>
                
                <FormField label="Password" required error={errors.password}>
                    <Input 
                        model={() => form.password}
                        type="password"
                        placeholder="••••••••"
                        color={errors.password ? 'error' : undefined}
                        variant="bordered"
                    />
                </FormField>
                
                <Checkbox 
                    model={() => form.remember}
                    label="Remember me"
                    color="primary"
                />
                
                <Button variant="primary" block onClick={handleSubmit}>
                    Sign In
                </Button>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Autocomplete Control

Use `autoComplete` to control browser autofill behavior:

```tsx
import { component, render } from 'sigx';
import { Input, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ email: '', password: '' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField label="Email">
                    <Input 
                        model={() => form.email}
                        type="email"
                        placeholder="user@example.com"
                        autoComplete="off"
                        variant="bordered"
                    />
                </FormField>
                
                <FormField label="New Password">
                    <Input 
                        model={() => form.password}
                        type="password"
                        placeholder="(unchanged)"
                        autoComplete="new-password"
                        variant="bordered"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

Common `autoComplete` values: `'off'`, `'on'`, `'email'`, `'username'`, `'current-password'`, `'new-password'`, `'name'`, `'tel'`, `'address-line1'`.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for two-way sync |
| `name` | `string` | - | Input name for form submission |
| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'search' \| 'url' \| 'tel'` | `'text'` | Input type |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
| `variant` | `'bordered' \| 'ghost'` | - | Visual variant |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Border color |
| `placeholder` | `string` | - | Placeholder text |
| `disabled` | `boolean` | `false` | Disable the input |
| `readOnly` | `boolean` | `false` | Read-only state |
| `maxLength` | `number` | - | Maximum character length |
| `autoComplete` | `string` | - | Browser autocomplete hint (`'off'`, `'new-password'`, `'email'`, etc.) |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onInput` | `(e: InputEvent) => void` | Fired on each keystroke (raw DOM event) |
| `onChange` | `(e: Event) => void` | Fired when focus leaves the input |
| `onFocus` | `(e: FocusEvent) => void` | Fired when input gains focus |
| `onBlur` | `(e: FocusEvent) => void` | Fired when input loses focus |

## Related Components

- [Textarea](./textarea) - Multi-line text input
- [Select](./select) - Dropdown selection
- [Checkbox](./checkbox) - Boolean checkbox
- [Toggle](./toggle) - Toggle switch
- [Radio](./radio) - Radio button group
- [Range](./range) - Range slider
- [FormField](./form-field) - Form field wrapper
- [File Input](./file-input) - File upload input

---
url: https://sigx.dev/daisyui/docs/components/modal/
title: Modal
description: Modal dialog for focused content or user confirmation
---

# Modal

Modal is used to show a dialog or a box when you click a button.

## Import

```tsx
import { Modal } from '@sigx/daisyui';
```

## Basic Usage

A basic modal with header, body, and action buttons.

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button variant="primary" onClick={() => isOpen.value = true}>Open Modal</Button>
            <Modal model={isOpen}>
                <Modal.Header>Hello!</Modal.Header>
                <Modal.Body>Press ESC key or click the button below to close.</Modal.Body>
                <Modal.Actions>
                    <Button onClick={() => isOpen.value = false}>Close</Button>
                </Modal.Actions>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Close on Backdrop Click

By default, the modal includes a backdrop. Clicking outside the modal-box closes it.

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button onClick={() => isOpen.value = true}>Open Modal</Button>
            <Modal model={isOpen}>
                <Modal.Header>Hello!</Modal.Header>
                <Modal.Body>
                    <Text>Press ESC key or click outside to close.</Text>
                </Modal.Body>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Width

Pass a custom class to control the modal-box width.

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button onClick={() => isOpen.value = true}>Open Wide Modal</Button>
            <Modal model={isOpen} class="w-11/12 max-w-5xl">
                <Modal.Header>Wide Modal</Modal.Header>
                <Modal.Body>
                    <Text>This modal has a custom width using w-11/12 max-w-5xl classes.</Text>
                </Modal.Body>
                <Modal.Actions>
                    <Button onClick={() => isOpen.value = false}>Close</Button>
                </Modal.Actions>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Position: Top

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button onClick={() => isOpen.value = true}>Open Top Modal</Button>
            <Modal model={isOpen} position="top">
                <Modal.Header>Top Position</Modal.Header>
                <Modal.Body>
                    <Text>This modal is positioned at the top of the viewport.</Text>
                </Modal.Body>
                <Modal.Actions>
                    <Button onClick={() => isOpen.value = false}>Close</Button>
                </Modal.Actions>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Position: Bottom

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button onClick={() => isOpen.value = true}>Open Bottom Modal</Button>
            <Modal model={isOpen} position="bottom">
                <Modal.Header>Bottom Position</Modal.Header>
                <Modal.Body>
                    <Text>This modal is positioned at the bottom of the viewport.</Text>
                </Modal.Body>
                <Modal.Actions>
                    <Button onClick={() => isOpen.value = false}>Close</Button>
                </Modal.Actions>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Without Backdrop

Set `backdrop={false}` to drop the dimming backdrop. The modal opens
non-modally, so the rest of the page stays interactive — close it with the
button or <kbd>Esc</kbd> (clicking outside does nothing).

```tsx
import { component, render, signal } from 'sigx';
import { Modal, Button, Text, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const isOpen = signal(false);
    return () => (
        <Col align="start">
            <Button onClick={() => isOpen.value = true}>Open (No Backdrop)</Button>
            <Modal model={isOpen} backdrop={false}>
                <Modal.Header>No Backdrop</Modal.Header>
                <Modal.Body>
                    <Text>This modal has no backdrop. Use the close button or press ESC.</Text>
                </Modal.Body>
                <Modal.Actions>
                    <Button variant="primary" onClick={() => isOpen.value = false}>Close</Button>
                </Modal.Actions>
            </Modal>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `Signal<boolean>` | `undefined` | Two-way binding for open/close state |
| `position` | `'top' \| 'middle' \| 'bottom'` | `undefined` | Vertical position of the modal |
| `align` | `'start' \| 'end'` | `undefined` | Horizontal alignment of the modal |
| `backdrop` | `boolean` | `true` | Show a dimming, click-to-close backdrop. `false` opens the modal non-modally (no dim, page stays interactive; close via button/Esc) |
| `background` | `BackgroundColor` | - | Modal-box background |
| `rounded` | `RadiusValue \| boolean` | - | Modal-box rounding (`true` → theme `rounded-box`) |
| `width` | `SizeValue` | - | Modal-box width — Tailwind step or unitful value (`"560px"`, `"50%"`) |
| `height` | `SizeValue` | - | Modal-box height — same value format as `width` |
| `padding` | `Spacing` | - | Modal-box padding |
| `class` | `string` | `undefined` | Additional CSS classes applied to the modal-box |

## Sub-components

| Component | Description |
|-----------|-------------|
| `Modal.Header` | Title area with an automatic close button |
| `Modal.Body` | Content area with vertical padding |
| `Modal.Actions` | Action buttons area (uses `modal-action` class) |

---
url: https://sigx.dev/daisyui/docs/components/radio/
title: Radio
description: Radio button group for single selection from multiple options
---

# Radio

Radio button component for selecting one option from a group. Supports both compound pattern with `Radio.Item` and standalone usage.

## Import

```tsx
import { Radio, Col, Card, Heading, Row, Text } from '@sigx/daisyui';
```

## Basic Usage (Compound Pattern)

Use `Radio` with `Radio.Item` children for grouped radio buttons:

```tsx
import { component, render } from 'sigx';
import { Radio, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ color: 'red' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Radio model={() => form.color} name="color">
                    <Radio.Item value="red" label="Red" />
                    <Radio.Item value="blue" label="Blue" />
                    <Radio.Item value="green" label="Green" />
                </Radio>
                
                <Text size="sm" class="opacity-70">
                    Selected: {form.color}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Radio, Col, Heading } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const sizes = signal({ xs: 'a', sm: 'a', md: 'a', lg: 'a' });
    
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Heading level={4} size="sm">Extra Small</Heading>
                <Radio model={() => sizes.xs} name="size-xs" size="xs">
                    <Radio.Item value="a" label="Option A" />
                    <Radio.Item value="b" label="Option B" />
                </Radio>
            </Col>
            
            <Col gap="2">
                <Heading level={4} size="sm">Small</Heading>
                <Radio model={() => sizes.sm} name="size-sm" size="sm">
                    <Radio.Item value="a" label="Option A" />
                    <Radio.Item value="b" label="Option B" />
                </Radio>
            </Col>
            
            <Col gap="2">
                <Heading level={4} size="sm">Medium (default)</Heading>
                <Radio model={() => sizes.md} name="size-md" size="md">
                    <Radio.Item value="a" label="Option A" />
                    <Radio.Item value="b" label="Option B" />
                </Radio>
            </Col>
            
            <Col gap="2">
                <Heading level={4} size="sm">Large</Heading>
                <Radio model={() => sizes.lg} name="size-lg" size="lg">
                    <Radio.Item value="a" label="Option A" />
                    <Radio.Item value="b" label="Option B" />
                </Radio>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Radio, Col, Row } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const colors = signal({
        primary: 'a',
        secondary: 'a',
        accent: 'a',
        success: 'a',
        warning: 'a',
        error: 'a'
    });
    
    return () => (
        <Row gap="4" wrap>
            <Col class="min-w-56">
                <Radio model={() => colors.primary} name="c-primary" color="primary">
                    <Radio.Item value="a" label="Primary A" />
                    <Radio.Item value="b" label="Primary B" />
                </Radio>
            </Col>
            <Col class="min-w-56">
                <Radio model={() => colors.secondary} name="c-secondary" color="secondary">
                    <Radio.Item value="a" label="Secondary A" />
                    <Radio.Item value="b" label="Secondary B" />
                </Radio>
            </Col>
            <Col class="min-w-56">
                <Radio model={() => colors.accent} name="c-accent" color="accent">
                    <Radio.Item value="a" label="Accent A" />
                    <Radio.Item value="b" label="Accent B" />
                </Radio>
            </Col>
            <Col class="min-w-56">
                <Radio model={() => colors.success} name="c-success" color="success">
                    <Radio.Item value="a" label="Success A" />
                    <Radio.Item value="b" label="Success B" />
                </Radio>
            </Col>
            <Col class="min-w-56">
                <Radio model={() => colors.warning} name="c-warning" color="warning">
                    <Radio.Item value="a" label="Warning A" />
                    <Radio.Item value="b" label="Warning B" />
                </Radio>
            </Col>
            <Col class="min-w-56">
                <Radio model={() => colors.error} name="c-error" color="error">
                    <Radio.Item value="a" label="Error A" />
                    <Radio.Item value="b" label="Error B" />
                </Radio>
            </Col>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Horizontal Direction

```tsx
import { component, render } from 'sigx';
import { Radio, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ plan: 'free' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Radio model={() => form.plan} name="plan" direction="horizontal" color="primary">
                    <Radio.Item value="free" label="Free" />
                    <Radio.Item value="pro" label="Pro" />
                    <Radio.Item value="enterprise" label="Enterprise" />
                </Radio>
                
                <Text size="sm" class="opacity-70">
                    Selected plan: {form.plan}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Standalone Radio

For cases where you need more control, use `Radio.Standalone`:

```tsx
import { component, render } from 'sigx';
import { Radio, Card, Text, Col } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const form = signal({ theme: 'light' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Col gap="2">
                    <Radio.Standalone 
                        name="theme" 
                        value="light" 
                        label="Light mode"
                        checked={form.theme === 'light'}
                        onChange={() => form.theme = 'light'}
                        color="primary"
                    />
                    <Radio.Standalone 
                        name="theme" 
                        value="dark" 
                        label="Dark mode"
                        checked={form.theme === 'dark'}
                        onChange={() => form.theme = 'dark'}
                        color="primary"
                    />
                    <Radio.Standalone 
                        name="theme" 
                        value="system" 
                        label="System preference"
                        checked={form.theme === 'system'}
                        onChange={() => form.theme = 'system'}
                        color="primary"
                    />
                </Col>
                
                <Text size="sm" class="opacity-70">
                    Theme: {form.theme}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With Disabled Options

```tsx
import { component, render } from 'sigx';
import { Radio, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ tier: 'basic' });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Radio model={() => form.tier} name="tier" color="primary">
                    <Radio.Item value="basic" label="Basic (Free)" />
                    <Radio.Item value="pro" label="Pro ($9/mo)" />
                    <Radio.Item value="enterprise" label="Enterprise (Coming Soon)" disabled />
                </Radio>
                
                <Text size="sm" class="opacity-70">
                    Selected tier: {form.tier}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Survey Example

```tsx
import { component, render } from 'sigx';
import { Radio, Card, Button, Divider, Text, Col, Heading } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const survey = signal({
        satisfaction: '',
        recommend: ''
    });
    
    const handleSubmit = () => {
        alert(`Satisfaction: ${survey.satisfaction}\nWould recommend: ${survey.recommend}`);
    };
    
    return () => (
        <Card>
            <Card.Body class="space-y-6">
                <Heading level={3} size="lg">Customer Survey</Heading>
                
                <Col gap="2">
                    <Text weight="medium" class="mb-2">How satisfied are you with our service?</Text>
                    <Radio model={() => survey.satisfaction} name="satisfaction" color="primary">
                        <Radio.Item value="very-satisfied" label="Very satisfied" />
                        <Radio.Item value="satisfied" label="Satisfied" />
                        <Radio.Item value="neutral" label="Neutral" />
                        <Radio.Item value="dissatisfied" label="Dissatisfied" />
                        <Radio.Item value="very-dissatisfied" label="Very dissatisfied" />
                    </Radio>
                </Col>
                
                <Divider />
                
                <Col gap="2">
                    <Text weight="medium" class="mb-2">Would you recommend us to others?</Text>
                    <Radio model={() => survey.recommend} name="recommend" direction="horizontal" color="primary">
                        <Radio.Item value="yes" label="Yes" />
                        <Radio.Item value="maybe" label="Maybe" />
                        <Radio.Item value="no" label="No" />
                    </Radio>
                </Col>
                
                <Button variant="primary" onClick={handleSubmit}>
                    Submit Survey
                </Button>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Radio (RadioGroup) Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for selected value |
| `name` | `string` | **required** | HTML name attribute for the radio group |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size of all radio buttons |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Color of all radio buttons |
| `direction` | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction |
| `disabled` | `boolean` | `false` | Disable all radio buttons |
| `class` | `string` | - | Additional CSS classes |

### Radio.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | **required** | Value when this option is selected |
| `label` | `string` | - | Label text |
| `disabled` | `boolean` | `false` | Disable this specific option |
| `class` | `string` | - | Additional CSS classes |

### Radio.Standalone Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | **required** | HTML name attribute |
| `value` | `string` | **required** | Value of this radio button |
| `checked` | `boolean` | `false` | Whether this radio is selected |
| `label` | `string` | - | Label text |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Size |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Color |
| `disabled` | `boolean` | `false` | Disable the radio |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(value: string) => void` | Fired when selection changes |

---
url: https://sigx.dev/daisyui/docs/components/stack/
title: Stack
description: Stack visually puts elements on top of each other, creating a layered card effect
---

# Stack

Stack visually puts elements on top of each other, like stacked papers or cards.

## Import

```tsx
import { Stack } from '@sigx/daisyui';
```

## Basic Usage

Use `w-*` and `h-*` classes on the Stack to set the size of all stacked items.

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack width="32" height="20">
            <Card class="bg-primary text-primary-content">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">1</Text>
                </Card.Body>
            </Card>
            <Card class="bg-accent text-accent-content">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">2</Text>
                </Card.Body>
            </Card>
            <Card class="bg-secondary text-secondary-content">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">3</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## Stacked Images

```tsx
import { component, render } from 'sigx';
import { Stack } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack width="48">
            <img src="https://img.daisyui.com/images/stock/photo-1572635148818-ef6fd45eb394.webp" alt="Example 1" class="rounded-box" />
            <img src="https://img.daisyui.com/images/stock/photo-1565098772267-60af42b81ef2.webp" alt="Example 2" class="rounded-box" />
            <img src="https://img.daisyui.com/images/stock/photo-1559703248-dcaaec9fab78.webp" alt="Example 3" class="rounded-box" />
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## Stacked Cards

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack class="size-28">
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">A</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">B</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">C</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## Directions

Use the `direction` prop to control the alignment of stacked elements.

### Top Direction

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack direction="top" class="size-28">
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">A</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">B</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">C</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

### Start Direction

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack direction="start" class="size-28">
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">A</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">B</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">C</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

### End Direction

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack direction="end" class="size-28">
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">A</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">B</Text>
                </Card.Body>
            </Card>
            <Card class="border border-base-content bg-base-100 text-center">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">C</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## With Shadows

Add shadows to create depth in the stack.

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack class="size-28">
            <Card class="bg-base-200 text-center shadow-md">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">A</Text>
                </Card.Body>
            </Card>
            <Card class="bg-base-200 text-center shadow">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">B</Text>
                </Card.Body>
            </Card>
            <Card class="bg-base-200 text-center shadow-sm">
                <Card.Body class="items-center justify-center">
                    <Text weight="bold">C</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## Notification Cards

A practical example showing notification cards in a stack.

```tsx
import { component, render } from 'sigx';
import { Stack, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stack>
            <Card class="shadow-md bg-base-100">
                <Card.Body>
                    <Card.Title>Notification 1</Card.Title>
                    <Text>You have 3 unread messages. Tap here to see.</Text>
                </Card.Body>
            </Card>
            <Card class="shadow-md bg-base-100">
                <Card.Body>
                    <Card.Title>Notification 2</Card.Title>
                    <Text>You have 3 unread messages. Tap here to see.</Text>
                </Card.Body>
            </Card>
            <Card class="shadow-md bg-base-100">
                <Card.Body>
                    <Card.Title>Notification 3</Card.Title>
                    <Text>You have 3 unread messages. Tap here to see.</Text>
                </Card.Body>
            </Card>
        </Stack>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `direction` | `'top' \| 'bottom' \| 'start' \| 'end'` | `'bottom'` | Alignment direction of the stacked elements |
| `width` | `SizeValue` | - | Stack width — Tailwind step (`"32"`) or unitful value (`"320px"`) |
| `height` | `SizeValue` | - | Stack height — same value format as `width` |
| `background` | `BackgroundColor` | - | Theme-aware background |
| `rounded` | `RadiusValue \| boolean` | - | Corner rounding (theme `box`/`field`/`selector`, or fixed scale) |
| `padding` | `Spacing` | - | Inner padding |
| `class` | `string` | - | Additional CSS classes |

## CSS Classes

The Stack component uses DaisyUI's `stack` CSS class under the hood:

| Class | Description |
|-------|-------------|
| `stack` | Main component class - puts children on top of each other |
| `stack-top` | Aligns children to the top |
| `stack-bottom` | Aligns children to the bottom (default) |
| `stack-start` | Aligns children to the start (horizontally) |
| `stack-end` | Aligns children to the end (horizontally) |

---
url: https://sigx.dev/daisyui/docs/components/range/
title: Range
description: Range slider for selecting numeric values within a range
---

# Range

Range slider component for selecting numeric values with model binding support.

## Import

```tsx
import { Range, Row, Col, Heading, Text } from '@sigx/daisyui';
```

## Basic Usage

Use `model` for two-way binding:

```tsx
import { component, render } from 'sigx';
import { Range, Card, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ value: 50 });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <Range 
                    model={() => form.value}
                    color="primary"
                />
                
                <Text size="sm" class="opacity-70">
                    Value: {form.value}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, render } from 'sigx';
import { Range, Col, Heading } from '@sigx/daisyui';
const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Heading level={4} size="sm">Extra Small</Heading>
                <Range size="xs" color="primary" />
            </Col>
            <Col gap="2">
                <Heading level={4} size="sm">Small</Heading>
                <Range size="sm" color="primary" />
            </Col>
            <Col gap="2">
                <Heading level={4} size="sm">Medium (default)</Heading>
                <Range size="md" color="primary" />
            </Col>
            <Col gap="2">
                <Heading level={4} size="sm">Large</Heading>
                <Range size="lg" color="primary" />
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

```tsx
import { component, render } from 'sigx';
import { Range, Col } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const values = signal({
        primary: 60,
        secondary: 60,
        accent: 60,
        info: 60,
        success: 60,
        warning: 60,
        error: 60
    });
    
    return () => (
        <Col gap="4">
            <Range model={() => values.primary} color="primary" />
            <Range model={() => values.secondary} color="secondary" />
            <Range model={() => values.accent} color="accent" />
            <Range model={() => values.info} color="info" />
            <Range model={() => values.success} color="success" />
            <Range model={() => values.warning} color="warning" />
            <Range model={() => values.error} color="error" />
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Min/Max

```tsx
import { component, render } from 'sigx';
import { Range, Card, FormField, Row, Text } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const form = signal({ temperature: 20 });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField label={`Temperature: ${form.temperature}°C`}>
                    <Range 
                        model={() => form.temperature}
                        min={-10}
                        max={40}
                        color="warning"
                    />
                </FormField>
                
                <Row justify="between" class="text-xs opacity-50">
                    <Text as="span" size="xs">-10°C</Text>
                    <Text as="span" size="xs">40°C</Text>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Step

```tsx
import { component, render } from 'sigx';
import { Range, Card, FormField, Row, Text } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const form = signal({ quantity: 10 });
    
    return () => (
        <Card>
            <Card.Body class="space-y-4">
                <FormField label={`Quantity: ${form.quantity} items`}>
                    <Range 
                        model={() => form.quantity}
                        min={0}
                        max={100}
                        step={10}
                        color="primary"
                    />
                </FormField>
                
                <Row justify="between" class="text-xs opacity-50">
                    <Text as="span" size="xs">0</Text>
                    <Text as="span" size="xs">50</Text>
                    <Text as="span" size="xs">100</Text>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With FormField

```tsx
import { component, render } from 'sigx';
import { Range, FormField, Card } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ volume: 50, brightness: 75 });
    
    return () => (
        <Card>
            <Card.Body class="space-y-6">
                <FormField label={`Volume: ${form.volume}%`}>
                    <Range 
                        model={() => form.volume}
                        min={0}
                        max={100}
                        color="primary"
                    />
                </FormField>
                
                <FormField label={`Brightness: ${form.brightness}%`}>
                    <Range 
                        model={() => form.brightness}
                        min={0}
                        max={100}
                        color="warning"
                    />
                </FormField>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Price Range Filter

```tsx
import { component, render } from 'sigx';
import { Range, Card, Badge, Text, Row, Col, Heading } from '@sigx/daisyui';
const Demo = component(({ signal }) => {
    const filter = signal({ minPrice: 0, maxPrice: 500 });
    
    return () => (
        <Card>
            <Card.Body class="space-y-6">
                <Heading level={3} size="lg">Price Filter</Heading>
                
                <Col gap="4">
                    <Col gap="2">
                        <Row justify="between" class="mb-2">
                            <Text as="span" size="sm">Min Price</Text>
                            <Badge variant="ghost">${filter.minPrice}</Badge>
                        </Row>
                        <Range 
                            model={() => filter.minPrice}
                            min={0}
                            max={filter.maxPrice}
                            step={10}
                            color="primary"
                        />
                    </Col>
                    
                    <Col gap="2">
                        <Row justify="between" class="mb-2">
                            <Text as="span" size="sm">Max Price</Text>
                            <Badge variant="ghost">${filter.maxPrice}</Badge>
                        </Row>
                        <Range 
                            model={() => filter.maxPrice}
                            min={filter.minPrice}
                            max={1000}
                            step={10}
                            color="primary"
                        />
                    </Col>
                </Col>
                
                <Text align="center" weight="medium">
                    ${filter.minPrice} - ${filter.maxPrice}
                </Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled State

```tsx
import { component, render } from 'sigx';
import { Range } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Range 
            min={0}
            max={100}
            color="primary"
            disabled
        />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => signal.property` | - | Model binding for numeric value |
| `name` | `string` | - | Range name for form submission |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `step` | `number` | `1` | Step increment |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Range slider size |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Slider color |
| `disabled` | `boolean` | `false` | Disable the range slider |
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `onChange` | `(value: number) => void` | Fired when value changes |

---
url: https://sigx.dev/daisyui/docs/components/steps/
title: Steps
description: Steps component for showing progress through a multi-step process
---

# Steps

Display progress through a multi-step process with numbered or custom-content step indicators.

## Import

```tsx
import { Steps, Card, Row, Button } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps>
            <Steps.Step color="primary">Register</Steps.Step>
            <Steps.Step color="primary">Choose plan</Steps.Step>
            <Steps.Step>Purchase</Steps.Step>
            <Steps.Step>Receive product</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

Each step can have a different color to indicate status.

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps>
            <Steps.Step color="neutral">Neutral</Steps.Step>
            <Steps.Step color="primary">Primary</Steps.Step>
            <Steps.Step color="secondary">Secondary</Steps.Step>
            <Steps.Step color="accent">Accent</Steps.Step>
            <Steps.Step color="info">Info</Steps.Step>
            <Steps.Step color="success">Success</Steps.Step>
            <Steps.Step color="warning">Warning</Steps.Step>
            <Steps.Step color="error">Error</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Content (data-content)

Use the `content` prop to display custom symbols in the step circle.

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps>
            <Steps.Step color="neutral" content="?">Step 1</Steps.Step>
            <Steps.Step color="neutral" content="!">Step 2</Steps.Step>
            <Steps.Step color="neutral" content="✓">Step 3</Steps.Step>
            <Steps.Step color="neutral" content="✕">Step 4</Steps.Step>
            <Steps.Step color="neutral" content="★">Step 5</Steps.Step>
            <Steps.Step color="neutral" content="●">Step 6</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Vertical Steps

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps vertical>
            <Steps.Step color="primary">Register</Steps.Step>
            <Steps.Step color="primary">Choose plan</Steps.Step>
            <Steps.Step>Purchase</Steps.Step>
            <Steps.Step>Receive product</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Responsive (Vertical on Mobile, Horizontal on Large Screens)

Use `vertical` with a responsive class override to switch layout at breakpoints.

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps vertical class="lg:steps-horizontal">
            <Steps.Step color="primary">Register</Steps.Step>
            <Steps.Step color="primary">Choose plan</Steps.Step>
            <Steps.Step>Purchase</Steps.Step>
            <Steps.Step>Receive product</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Mixed Colors

Combine different colors to show progress status.

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps>
            <Steps.Step color="info">Ordered</Steps.Step>
            <Steps.Step color="info">Shipped</Steps.Step>
            <Steps.Step color="warning">In transit</Steps.Step>
            <Steps.Step color="error">Delayed</Steps.Step>
            <Steps.Step>Delivered</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Scrollable Horizontal Steps

Wrap with overflow utility for many steps.

```tsx
import { component, render } from 'sigx';
import { Steps } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Steps class="overflow-x-auto">
            <Steps.Step>Start</Steps.Step>
            <Steps.Step color="secondary">Step 2</Steps.Step>
            <Steps.Step color="secondary">Step 3</Steps.Step>
            <Steps.Step color="secondary">Step 4</Steps.Step>
            <Steps.Step color="secondary">Step 5</Steps.Step>
            <Steps.Step color="secondary">Step 6</Steps.Step>
            <Steps.Step color="secondary">Step 7</Steps.Step>
            <Steps.Step>Step 8</Steps.Step>
            <Steps.Step>Step 9</Steps.Step>
            <Steps.Step>End</Steps.Step>
        </Steps>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Steps Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `StepItem[]` | - | Step items (alternative to compound pattern) |
| `model` | `Signal<string>` | - | Current step ID (for items mode) |
| `vertical` | `boolean` | `false` | Vertical layout (`steps-vertical`) |
| `horizontal` | `boolean` | `false` | Horizontal layout (`steps-horizontal`) |
| `class` | `string` | - | Additional CSS classes |

### Steps.Step Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `color` | `'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Step color |
| `content` | `string` | - | Custom content in step circle (`data-content` attribute) |
| `class` | `string` | - | Additional CSS classes |

### Steps.Step Slots

| Slot | Description |
|------|-------------|
| `default` | Step label text |

---
url: https://sigx.dev/daisyui/docs/components/toast/
title: Toast
description: Toast positions notifications at the corner of the page
---

# Toast

Toast is a container for positioning alert notifications at the edges of the page.

> A `Toast` is `position: fixed` to a corner of the **viewport**. The previews below wrap each example in a bordered box that acts as the positioning context, so the toasts stay inside their example instead of stacking in the page corner — in your app, drop the wrapper and the toast will anchor to the viewport.

## Import

```tsx
import { Toast, Alert } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="140px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="bottom-end">
                <Alert variant="info">New message arrived.</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Top Positions

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="180px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="top-start">
                <Alert variant="info">Top start</Alert>
            </Toast>
            <Toast position="top-center">
                <Alert variant="success">Top center</Alert>
            </Toast>
            <Toast position="top-end">
                <Alert variant="warning">Top end</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Middle Positions

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="180px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="middle-start">
                <Alert variant="info">Middle start</Alert>
            </Toast>
            <Toast position="middle-center">
                <Alert variant="success">Middle center</Alert>
            </Toast>
            <Toast position="middle-end">
                <Alert variant="warning">Middle end</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Bottom Positions

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="180px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="bottom-start">
                <Alert variant="info">Bottom start</Alert>
            </Toast>
            <Toast position="bottom-center">
                <Alert variant="success">Bottom center</Alert>
            </Toast>
            <Toast position="bottom-end">
                <Alert variant="warning">Bottom end</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Multiple Alerts

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="200px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="bottom-end">
                <Alert variant="info">New mail arrived.</Alert>
                <Alert variant="success">Message sent successfully.</Alert>
                <Alert variant="warning">Connection is slow.</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Custom Class

```tsx
import { component, render } from 'sigx';
import { Toast, Alert, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col width="full" minHeight="140px" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Toast position="top-end" class="z-50">
                <Alert variant="error">Something went wrong!</Alert>
            </Toast>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Interactive (Trigger on Click)

Toasts are usually shown in response to an action and dismissed after a delay. Click the button to show one:

```tsx
import { component, render, signal } from 'sigx';
import { Toast, Alert, Button, Col } from '@sigx/daisyui';

const Demo = component(() => {
    const visible = signal(false);
    let timer;

    const showToast = () => {
        visible.value = true;
        clearTimeout(timer);
        timer = setTimeout(() => { visible.value = false; }, 3000);
    };

    return () => (
        <Col width="full" minHeight="160px" align="start" padding="4" background="base-200" rounded class="border border-base-content/20 overflow-hidden [transform:translateZ(0)]">
            <Button variant="primary" onClick={showToast}>Show toast</Button>
            {visible.value && (
                <Toast position="bottom-end">
                    <Alert variant="success">Saved successfully!</Alert>
                </Toast>
            )}
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop       | Type             | Default        | Description                          |
|------------|------------------|----------------|--------------------------------------|
| `position` | `ToastPosition`  | `"bottom-end"` | Position of the toast container      |
| `class`    | `string`         | —              | Additional CSS classes               |

### ToastPosition

`"top-start"` | `"top-center"` | `"top-end"` | `"middle-start"` | `"middle-center"` | `"middle-end"` | `"bottom-start"` | `"bottom-center"` | `"bottom-end"`

---
url: https://sigx.dev/daisyui/docs/components/table/
title: Table
description: Data table components for displaying structured data with zebra striping, pinned rows/columns, and size variants
---

# Table

Tables display structured data in rows and columns using a compound component pattern.

## Import

```tsx
import { Table } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                    <Table.Th>Favorite Color</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Cy Ganderton</Table.Td>
                    <Table.Td>Quality Control Specialist</Table.Td>
                    <Table.Td>Blue</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Hart Hagerty</Table.Td>
                    <Table.Td>Desktop Support Technician</Table.Td>
                    <Table.Td>Purple</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Brice Swyre</Table.Td>
                    <Table.Td>Tax Accountant</Table.Td>
                    <Table.Td>Red</Table.Td>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Active Row

Use the `active` prop on `Table.Row` to highlight a row.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Cy Ganderton</Table.Td>
                    <Table.Td>Quality Control Specialist</Table.Td>
                </Table.Row>
                <Table.Row active>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Hart Hagerty</Table.Td>
                    <Table.Td>Desktop Support Technician</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Brice Swyre</Table.Td>
                    <Table.Td>Tax Accountant</Table.Td>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Hover Row

Use the `hover` prop on `Table.Row` to highlight rows on hover.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row hover>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Cy Ganderton</Table.Td>
                    <Table.Td>Quality Control Specialist</Table.Td>
                </Table.Row>
                <Table.Row hover>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Hart Hagerty</Table.Td>
                    <Table.Td>Desktop Support Technician</Table.Td>
                </Table.Row>
                <Table.Row hover>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Brice Swyre</Table.Td>
                    <Table.Td>Tax Accountant</Table.Td>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Zebra Striping

Use the `zebra` prop to add alternating row backgrounds.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table zebra>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Cy Ganderton</Table.Td>
                    <Table.Td>Quality Control Specialist</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Hart Hagerty</Table.Td>
                    <Table.Td>Desktop Support Technician</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Brice Swyre</Table.Td>
                    <Table.Td>Tax Accountant</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>4</Table.Th>
                    <Table.Td>Marjy Ferencz</Table.Td>
                    <Table.Td>Office Assistant I</Table.Td>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## With Footer

Use `Table.Foot` to add a footer section with pinned rows.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Cy Ganderton</Table.Td>
                    <Table.Td>Quality Control Specialist</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Hart Hagerty</Table.Td>
                    <Table.Td>Desktop Support Technician</Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Brice Swyre</Table.Td>
                    <Table.Td>Tax Accountant</Table.Td>
                </Table.Row>
            </Table.Body>
            <Table.Foot>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Foot>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Pinned Rows

Use `pinRows` to make header and footer rows sticky when scrolling vertically.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table pinRows>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row><Table.Th>1</Table.Th><Table.Td>Cy Ganderton</Table.Td><Table.Td>Quality Control Specialist</Table.Td></Table.Row>
                <Table.Row><Table.Th>2</Table.Th><Table.Td>Hart Hagerty</Table.Td><Table.Td>Desktop Support Technician</Table.Td></Table.Row>
                <Table.Row><Table.Th>3</Table.Th><Table.Td>Brice Swyre</Table.Td><Table.Td>Tax Accountant</Table.Td></Table.Row>
                <Table.Row><Table.Th>4</Table.Th><Table.Td>Marjy Ferencz</Table.Td><Table.Td>Office Assistant I</Table.Td></Table.Row>
                <Table.Row><Table.Th>5</Table.Th><Table.Td>Yancy Tear</Table.Td><Table.Td>Community Outreach Specialist</Table.Td></Table.Row>
                <Table.Row><Table.Th>6</Table.Th><Table.Td>Irma Vadarlis</Table.Td><Table.Td>Editor</Table.Td></Table.Row>
                <Table.Row><Table.Th>7</Table.Th><Table.Td>Meghann Deatley</Table.Td><Table.Td>Staff Accountant IV</Table.Td></Table.Row>
                <Table.Row><Table.Th>8</Table.Th><Table.Td>Samber Closson</Table.Td><Table.Td>Accounting Assistant I</Table.Td></Table.Row>
                <Table.Row><Table.Th>9</Table.Th><Table.Td>Lesly Vivyan</Table.Td><Table.Td>Nurse Practitioner</Table.Td></Table.Row>
                <Table.Row><Table.Th>10</Table.Th><Table.Td>Zaneta Tetter</Table.Td><Table.Td>VP Quality Control</Table.Td></Table.Row>
            </Table.Body>
            <Table.Foot>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Job</Table.Th>
                </Table.Row>
            </Table.Foot>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Pinned Columns

Use `pinCols` to make `<th>` columns sticky when scrolling horizontally.

```tsx
import { component, render } from 'sigx';
import { Table } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table pinCols size="xs">
            <Table.Head>
                <Table.Row>
                    <Table.Th>Name</Table.Th>
                    <Table.Td>A</Table.Td>
                    <Table.Td>B</Table.Td>
                    <Table.Td>C</Table.Td>
                    <Table.Td>D</Table.Td>
                    <Table.Td>E</Table.Td>
                    <Table.Td>F</Table.Td>
                    <Table.Td>G</Table.Td>
                    <Table.Td>H</Table.Td>
                    <Table.Th>Name</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>Alice</Table.Th>
                    <Table.Td>90</Table.Td>
                    <Table.Td>85</Table.Td>
                    <Table.Td>78</Table.Td>
                    <Table.Td>92</Table.Td>
                    <Table.Td>88</Table.Td>
                    <Table.Td>95</Table.Td>
                    <Table.Td>80</Table.Td>
                    <Table.Td>87</Table.Td>
                    <Table.Th>Alice</Table.Th>
                </Table.Row>
                <Table.Row>
                    <Table.Th>Bob</Table.Th>
                    <Table.Td>72</Table.Td>
                    <Table.Td>68</Table.Td>
                    <Table.Td>95</Table.Td>
                    <Table.Td>83</Table.Td>
                    <Table.Td>76</Table.Td>
                    <Table.Td>91</Table.Td>
                    <Table.Td>89</Table.Td>
                    <Table.Td>74</Table.Td>
                    <Table.Th>Bob</Table.Th>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

Available sizes: `xs`, `sm`, `md` (default), `lg`, and `xl`.

```tsx
import { component, render } from 'sigx';
import { Table, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Text size="sm" weight="medium">xs</Text>
                <Table size="xs">
                    <Table.Head><Table.Row><Table.Th>#</Table.Th><Table.Th>Name</Table.Th><Table.Th>Value</Table.Th></Table.Row></Table.Head>
                    <Table.Body>
                        <Table.Row><Table.Th>1</Table.Th><Table.Td>Item A</Table.Td><Table.Td>100</Table.Td></Table.Row>
                        <Table.Row><Table.Th>2</Table.Th><Table.Td>Item B</Table.Td><Table.Td>200</Table.Td></Table.Row>
                    </Table.Body>
                </Table>
            </Col>
            <Col gap="2">
                <Text size="sm" weight="medium">sm</Text>
                <Table size="sm">
                    <Table.Head><Table.Row><Table.Th>#</Table.Th><Table.Th>Name</Table.Th><Table.Th>Value</Table.Th></Table.Row></Table.Head>
                    <Table.Body>
                        <Table.Row><Table.Th>1</Table.Th><Table.Td>Item A</Table.Td><Table.Td>100</Table.Td></Table.Row>
                        <Table.Row><Table.Th>2</Table.Th><Table.Td>Item B</Table.Td><Table.Td>200</Table.Td></Table.Row>
                    </Table.Body>
                </Table>
            </Col>
            <Col gap="2">
                <Text size="sm" weight="medium">md (default)</Text>
                <Table size="md">
                    <Table.Head><Table.Row><Table.Th>#</Table.Th><Table.Th>Name</Table.Th><Table.Th>Value</Table.Th></Table.Row></Table.Head>
                    <Table.Body>
                        <Table.Row><Table.Th>1</Table.Th><Table.Td>Item A</Table.Td><Table.Td>100</Table.Td></Table.Row>
                        <Table.Row><Table.Th>2</Table.Th><Table.Td>Item B</Table.Td><Table.Td>200</Table.Td></Table.Row>
                    </Table.Body>
                </Table>
            </Col>
            <Col gap="2">
                <Text size="sm" weight="medium">lg</Text>
                <Table size="lg">
                    <Table.Head><Table.Row><Table.Th>#</Table.Th><Table.Th>Name</Table.Th><Table.Th>Value</Table.Th></Table.Row></Table.Head>
                    <Table.Body>
                        <Table.Row><Table.Th>1</Table.Th><Table.Td>Item A</Table.Td><Table.Td>100</Table.Td></Table.Row>
                        <Table.Row><Table.Th>2</Table.Th><Table.Td>Item B</Table.Td><Table.Td>200</Table.Td></Table.Row>
                    </Table.Body>
                </Table>
            </Col>
            <Col gap="2">
                <Text size="sm" weight="medium">xl</Text>
                <Table size="xl">
                    <Table.Head><Table.Row><Table.Th>#</Table.Th><Table.Th>Name</Table.Th><Table.Th>Value</Table.Th></Table.Row></Table.Head>
                    <Table.Body>
                        <Table.Row><Table.Th>1</Table.Th><Table.Td>Item A</Table.Td><Table.Td>100</Table.Td></Table.Row>
                        <Table.Row><Table.Th>2</Table.Th><Table.Td>Item B</Table.Td><Table.Td>200</Table.Td></Table.Row>
                    </Table.Body>
                </Table>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Actions

```tsx
import { component, render } from 'sigx';
import { Table, Button, Badge, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Table>
            <Table.Head>
                <Table.Row>
                    <Table.Th>#</Table.Th>
                    <Table.Th>Name</Table.Th>
                    <Table.Th>Status</Table.Th>
                    <Table.Th>Actions</Table.Th>
                </Table.Row>
            </Table.Head>
            <Table.Body>
                <Table.Row>
                    <Table.Th>1</Table.Th>
                    <Table.Td>Alice Johnson</Table.Td>
                    <Table.Td><Badge variant="success" size="sm">active</Badge></Table.Td>
                    <Table.Td>
                        <Row gap="2">
                            <Button size="xs">Edit</Button>
                            <Button size="xs" variant="ghost">Delete</Button>
                        </Row>
                    </Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>2</Table.Th>
                    <Table.Td>Bob Smith</Table.Td>
                    <Table.Td><Badge variant="warning" size="sm">pending</Badge></Table.Td>
                    <Table.Td>
                        <Row gap="2">
                            <Button size="xs">Edit</Button>
                            <Button size="xs" variant="ghost">Delete</Button>
                        </Row>
                    </Table.Td>
                </Table.Row>
                <Table.Row>
                    <Table.Th>3</Table.Th>
                    <Table.Td>Carol White</Table.Td>
                    <Table.Td><Badge variant="error" size="sm">inactive</Badge></Table.Td>
                    <Table.Td>
                        <Row gap="2">
                            <Button size="xs">Edit</Button>
                            <Button size="xs" variant="ghost">Delete</Button>
                        </Row>
                    </Table.Td>
                </Table.Row>
            </Table.Body>
        </Table>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Table Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `zebra` | `boolean` | `false` | Alternate row background colors |
| `pinRows` | `boolean` | `false` | Make header/footer rows sticky when scrolling vertically |
| `pinCols` | `boolean` | `false` | Make `<th>` columns sticky when scrolling horizontally |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — | Table size |
| `class` | `string` | — | Additional CSS classes |

### Table.Row Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `hover` | `boolean` | `false` | Highlight row on hover |
| `active` | `boolean` | `false` | Highlight row as active |
| `class` | `string` | — | Additional CSS classes |

### Sub-Components

| Component | Description |
|-----------|-------------|
| `Table.Head` | Table header section (`<thead>`) |
| `Table.Body` | Table body section (`<tbody>`) |
| `Table.Foot` | Table footer section (`<tfoot>`) |
| `Table.Row` | Table row (`<tr>`) — supports `hover` and `active` props |
| `Table.Th` | Table header cell (`<th>`) |
| `Table.Td` | Table data cell (`<td>`) |

---
url: https://sigx.dev/server/packages/serialize/api/
title: API reference
description: Serialize — defineTypeHandler, encodeWithHandlers, reviveWithHandlers, TypeHandler and the built-ins
---

# API reference

<p class="lede">Exports of `@sigx/serialize` . A single entry point — no subpaths.</p>

## defineTypeHandler

Author a handler with type-guard-driven inference. Runtime it is the identity function; it exists purely to drive the types.

```ts
function defineTypeHandler<T, Encoded = unknown>(handler: {
  name: string;
  tag?: string;
  test(value: unknown): value is T;      // type guard → drives serialize/revive inference
  serialize(value: T): Encoded;
  revive?(encoded: Encoded): T;
}): TypeHandler<T, Encoded>;
```

The `test` guard must be a bare `instanceof` / `typeof` arrow to infer `T`; annotate a compound predicate explicitly (`(v): v is URL => …`).

## encodeWithHandlers

```ts
function encodeWithHandlers(value: unknown, handlers?: readonly TypeHandler[]): unknown;
```

Walk a value into a JSON-safe tree, applying registered `handlers` first, then the built-ins. Handlers see **raw** values (the walk runs before `toJSON`, which is why `Date` matches). Throws `TypeError('Converting circular structure to JSON')` on cycles, like `JSON.stringify`.

A plain object or array reachable through several paths (a diamond, a DAG) is encoded **once** rather than once per path — two-way sharing N levels deep used to be 2<sup>N</sup> work. The wire text is byte-for-byte identical, since `JSON.stringify` re-expands each reference. Two edges follow: the return value now carries shared object identity where the input did, and a handler's `test`/`serialize` run once per unique subtree rather than once per path.

### The dev warning for lossy values

Some values encode "successfully" while losing what made them themselves — a class instance loses its prototype, a typed array becomes `{"0":…,"1":…}`, `Error`/`Promise`/`WeakMap` become `{}`, and `NaN`/`±Infinity` become `null`. Every one is a **lossy success**: the encode returns, the result looks like data, and nothing downstream can notice.

In development the encoder walks the value and reports the offending property paths in one warning (up to three, node-budgeted so a large payload cannot stall the dev server). It consults the same handler chain the encoder does, so a type you have taught the codec is never flagged. Production pays nothing — the walk is behind `__DEV__` and is stripped from the built dist.

Circular structures are deliberately *not* reported here: they already throw, and callers that encode speculatively to test admissibility catch that throw and report their own message.

## reviveWithHandlers

```ts
function reviveWithHandlers<T = unknown>(value: unknown, handlers?: readonly TypeHandler[]): T;
```

The inverse — turns `{ [tag]: payload }` back into live values. `T` is an **assertion, not validation** (it types the result; nothing checks wire data). Apply only to trees `encodeWithHandlers` produced. Idempotent over already-live values; an unknown `$`-tag is left encoded (forward-compat) with a dev warning.

`__proto__` is dropped at both of revive's object rebuilds, with a dev warning naming the drop. `out[key] = value` with the key `__proto__` does not create an own property — it silently sets the prototype of the object being rebuilt, invisible to `Object.keys`, `JSON.stringify` and a `toEqual` assertion. The guard lives **in the codec**, which is the one place that sees every boundary: the SSR state blob, resume boundary props, the cache seed and the RPC wire.

`constructor` and `prototype` are **plain data keys** and are not filtered — assigning them creates ordinary own properties and swaps nothing.

## Depth cap

Both halves refuse values nesting deeper than **256 levels**, throwing `TypeError('Value nests deeper than 256 levels')`.

`encode` and `revive` are recursive where `JSON.parse`/`JSON.stringify` are not, and wire data is attacker-typable — roughly 1 MiB of `[[[[…` spells hundreds of thousands of levels and used to overflow the stack. For scale: the deepest fixture in the source repo's benchmarks nests 12 levels, and boundary records nest single digits, so a legitimate payload is orders of magnitude clear of the cap.

The cap also turns a cyclic *live* value handed to `reviveWithHandlers` — reachable through the mixed hydration blob, which revive walks idempotently — from infinite recursion into that same clean throw.

## TypeHandler

```ts
interface TypeHandler<T = unknown, Encoded = unknown> {
  name: string;                    // identifies the handler (dev warnings, dedupe)
  tag?: string;                    // wire discriminator, e.g. '$date' → { [tag]: payload }
  test(value: unknown): boolean;   // owns the value? — receives the raw value
  serialize(value: T): Encoded;    // JSON-safe payload (itself re-walked)
  revive?(encoded: Encoded): T;    // payload → live value (omit for serialize-only)
}
```

`test` is intentionally typed `boolean`, not a type predicate (a predicate member would reject boolean-returning tests) — the guard lives on `defineTypeHandler`'s parameter instead. Bare `TypeHandler` is `TypeHandler<unknown, unknown>`, so pre-generic handlers compile unchanged.

## BUILTIN_TYPE_HANDLERS

```ts
const BUILTIN_TYPE_HANDLERS: readonly TypeHandler[];
```

The zero-config vocabulary, consulted **after** any registered handlers:

| name | tag | type → encoded |
|---|---|---|
| `date` | `$date` | `Date` → epoch ms (`NaN` → `null`; revives to Invalid Date) |
| `map` | `$map` | `Map` → array of `[k, v]` |
| `set` | `$set` | `Set` → array |
| `bigint` | `$bigint` | `bigint` → decimal string |
| `url` | `$url` | `URL` → `href` |
| `regexp` | `$regexp` | `RegExp` → `[source, flags]` |
| `undefined` | `$undef` | `=== undefined` → `0` (so explicit `undefined` survives) |

A user object whose sole key starts with `$` is escaped as `{ "$esc": original }` and unwrapped on revive, so a literal `{ "$date": "hi" }` never wrongly revives to a `Date`.

## Registration

`@sigx/serialize` exports no registration function. Register handlers through the runtime:

- **`provideTypeHandlers(app._context, handlers)`** — from `sigx/internals`; the per-app DI registry (consulted before built-ins).
- **`serverPlugin({ types })`** — from [`@sigx/server/plugin`](/server/packages/server/api); one call registers both the RPC wire codec and the per-app registry.

## Binary — `@sigx/serialize/bytes`

An **opt-in** subpath carrying one handler, `bytesHandler` (tag `$bytes`):

```ts
import { bytesHandler } from '@sigx/serialize/bytes';
import { serverPlugin } from '@sigx/server/plugin';

serverPlugin({ types: [bytesHandler] });
```

It round-trips `Uint8Array` (Node's `Buffer` included — it revives as a plain `Uint8Array`), every standard typed-array kind, `DataView`, and a bare `ArrayBuffer`, each back to its exact constructor. The encoding is base64: `{"$bytes":"AQID"}` for a `Uint8Array`, a `[kind, base64]` tuple for the rest. A **view encodes its window**, never the whole backing buffer, and multi-byte kinds carry raw host-order bytes.

Opt-in rather than built-in, deliberately. The root entry is bundled by `@sigx/server/client`'s dependency-free stubs under a 1 KB budget with no ignore list possible, so a built-in `$bytes` would tax every client bundle — and would quietly start admitting binary into the SSR state blob.

Registering it silences the lossy-value dev warning for exactly the types it claims. `Blob` and `File` stay out of scope because the codec is synchronous, and `SharedArrayBuffer` and `Float16Array` keep warning.

---
url: https://sigx.dev/terminal/docs/components/card/
title: Card
description: A titled panel container
---

# Card

<p class="lede">A titled panel — a themed bordered container with an optional <code>title</code> and drop shadow. Children go in its default slot.</p>

## Import

```tsx
import { Card } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, Card } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <Card title="Summary" dropShadow>
            <text>Build completed in 1.2s.</text>
            <br />
            <text>3 warnings, 0 errors.</text>
        </Card>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `title` | `string` | caption in the top border |
| `dropShadow` | `boolean` | cast a shadow on the right/bottom edges |

The card's content is its default slot.

## See also

- [Layout & Styling](/terminal/docs/layout-and-styling) — the `Box`, `Row` and `Col` primitives.

---
url: https://sigx.dev/terminal/docs/components/tabs/
title: Tabs
description: Horizontal tab switcher with two-way model binding
---

# Tabs

<p class="lede">A focusable horizontal tab switcher. The active tab fills with the accent; ←/→ (or <code>h</code>/<code>l</code>) switch.</p>

## Import

```tsx
import { Tabs } from '@sigx/terminal';
import type { TabOption } from '@sigx/terminal';
```

## Usage

```tsx
import { component, defineApp, signal, Tabs } from '@sigx/terminal';
import type { TabOption } from '@sigx/terminal';

const tabs: TabOption[] = [
    { label: 'Overview', value: 'overview' },
    { label: 'Logs', value: 'logs' },
    { label: 'Settings', value: 'settings' },
];

const App = component(() => {
    const active = signal('overview');
    return () => (
        <box border="rounded" label="Panel">
            <Tabs options={tabs} model={() => active} autofocus onChange={(v) => console.log(v)} />
            <br />
            <text>Active: {active.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `options` | `TabOption[]` | **required** — the tabs |
| `model` | `Model<string>` | two-way bound active value |
| `autofocus` | `boolean` | grab focus on mount |

## Events

| Event | Payload | When |
| --- | --- | --- |
| `change` | `string` | active tab changes |

## TabOption

```ts
interface TabOption<T = string> {
    label: string;
    value: T;
}
```

## See also

- [StatusBar](/terminal/docs/components/statusbar) — a status footer.
- [Select](/terminal/docs/components/select) — a vertical single-choice menu.

---
url: https://sigx.dev/core/packages/cache/overview/
title: Overview
description: "@sigx/cache — cache policy for SignalX's value-first async: staleTime, revalidation, invalidate and optimistic mutate"
---

# Cache

<p class="lede">A cache-policy pack for <code>useData</code> and <code>useAction</code> — <code>staleTime</code>, focus and interval revalidation, <code>keepPreviousData</code>, cache-aware <code>invalidate()</code> and optimistic <code>mutate()</code>. It installs as one plugin and leaves your call sites alone.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

## Why it exists

SignalX's async is [value-first](/core/docs/data-loading): `useData` returns reactive state you render through `.match()`, not a promise you throw to a wrapper. Core ships the *mechanism* — keyed reads, deduplication, SSR transfer, and key-addressable refresh — and deliberately stops there. Everything about **policy** — how long a value stays fresh, when to revalidate, how long to keep it after the last consumer leaves — lives in a pack.

`@sigx/cache` is that pack. It rides core's async-engine seam (the `rfc-async` §7 contract), so it's a drop-in equal of any third-party pack with no privileged access. Installing it changes one line, not your components:

```ts
import { cachePlugin } from '@sigx/cache';

app.use(cachePlugin({ staleTime: 30_000 }));   // app-wide defaults (all optional)
```

From then on, `useData` and `useAction` gain a `cache` option — added by module augmentation of core's open interfaces, so it appears exactly when the pack is in your project:

```tsx
const user = useData('user', fetchUser, {
    cache: { staleTime: 60_000, revalidateOnFocus: true },
});

user.invalidate();                      // drop the entry + refetch everywhere
user.mutate((u) => ({ ...u, name }));   // optimistic write-through
```

## What you get

| Policy | Effect |
|---|---|
| `staleTime` | A fresh value is served without fetching; a stale one is served immediately and revalidated in the background (state `refreshing`, so your `ready` arm keeps rendering). |
| `gcTime` | Entries are retained after the last consumer unmounts (default 5 minutes) — navigating back is instant. |
| `revalidateOnFocus` / `revalidateOnInterval` | Mounted reads refetch on window focus/visibility, or on a timer. |
| `keepPreviousData` | Across a key change with nothing cached yet, the previous value keeps rendering instead of resetting to `pending` — pagination without skeleton flashes. |
| `invalidate()` | Drop an entry's **freshness** and refetch for every mounted consumer. Actions can invalidate exact keys or tuple prefixes. |
| `mutate()` / `optimistic` | Write through the cache immediately; a failed action rolls back, unless something newer wrote in the meantime. |

## What it inherits, not invents

The pack is additive — it never changes the rules you already rely on:

- Reads and actions **without** a `cache` option keep core's default-engine behavior verbatim (the pack delegates to it) — including invalidation, which is core's own key-addressable refresh and reaches an uncached read just the same. What the pack adds on top is freshness, `staleTime` and retention.
- Keys are core's canonical identities — strings, or tuples as canonical JSON — so the cache store and core's SSR blob speak the same language.
- **SSR and hydration**: the pack adopts `window.__SIGX_ASYNC__` as its *initial* cache state, so server-fetched values hydrate as fresh entries and nothing refetches on load. Server rendering itself is untouched — the SSR provider seam outranks any engine.
- Core's pinned guarantees hold: `loading === (state === 'pending')`, value and error are mutually exclusive, `refresh()` / `run()` never reject.

## Renderer-portable

`@sigx/cache` depends on `@sigx/runtime-core` and `@sigx/reactivity` only — never the `sigx` umbrella — so it works on any renderer: web, [Lynx](/lynx/docs/overview) native, or the [terminal](/terminal/docs/getting-started). On a platform with no DOM, hand the plugin your own attention event via `revalidateTrigger`. See [Usage](/core/packages/cache/usage#renderer-portability).

## Next steps

- [Installation](/core/packages/cache/installation) — add the package and register the plugin
- [Usage](/core/packages/cache/usage) — the policy options, worked through
- [API reference](/core/packages/cache/api) — the full typed surface

---
url: https://sigx.dev/core/docs/advanced/factories/
title: Factories
description: Injectable factory pattern for services in SignalX
---

# Factories

SignalX provides `defineFactory()` for creating injectable services with managed subscriptions, disposal, and a real instance lifetime. Factories are ideal for shared logic, API clients, and stateful services.

## Basic Factory

```tsx
import { defineFactory } from 'sigx';

const useLogger = defineFactory((ctx) => {
    const logs: string[] = [];

    const log = (message: string) => {
        logs.push(`[${Date.now()}] ${message}`);
        console.log(message);
    };

    const getLogs = () => [...logs];

    ctx.onDeactivated(() => {
        console.log('Logger deactivated');
    });

    return { log, getLogs };
}, 'singleton');

// Usage in component
const MyComponent = component(() => {
    const logger = useLogger();
    
    logger.log('Component mounted');
    
    return () => <div>Check console</div>;
});
```

The setup function must return an object or a function — returning a primitive throws.

## Instance Lifetimes

The second argument is a `Lifetime` string literal — `'singleton'`, `'scoped'`, or `'transient'`. The lifetime is **enforced**: it determines how many instances exist and when each is disposed.

```tsx
import { defineFactory } from 'sigx';

// New instance every call
defineFactory(setup, 'transient');

// Nearest defineProvide provider in the tree, falling back to the app instance
defineFactory(setup, 'scoped');

// One instance per app
defineFactory(setup, 'singleton');
```

### Lifetime Comparison

| Lifetime | Instances | Semantics |
|----------|-----------|-----------|
| `'singleton'` | One per app | Created on first resolution per `AppContext`, disposed on `app.unmount()`. Outside any app context, one instance per JS realm |
| `'scoped'` | Per provider | The nearest instance provided via `defineProvide` in the component tree; falls back to the app-context instance (and outside any app/component context to the per-realm instance) |
| `'transient'` | Per call | A new instance each call, disposed with the calling component — or owned by the caller via `dispose()` |

## Disposal

Every factory instance gets a `dispose()` method attached — **non-enumerable** (it never shows up when iterating or serializing the instance) and **idempotent** (safe to call twice). If the setup returns its own `dispose`, the generated one delegates to it.

Disposal runs the `onDeactivated` callbacks and the `ctx.subscriptions` cleanups:

- `'singleton'` instances are disposed when their app is unmounted (`app.unmount()`).
- `'scoped'` instances are disposed when their provider component unmounts.
- `'transient'` instances are disposed with the calling component; created outside a component, the caller owns disposal and calls `dispose()` manually.

```tsx
const transient = useThing();   // inside a component: auto-disposed on unmount

const standalone = useThing();  // outside a component: you own it
standalone.dispose();           // idempotent — safe to call again
```

## Factory Context

The factory setup function receives a context with lifecycle hooks:

```tsx
const useService = defineFactory((ctx) => {
    // Called when the factory instance is disposed
    ctx.onDeactivated(() => {
        console.log('Cleaning up...');
    });

    // Subscription helper for auto-cleanup
    ctx.subscriptions.add(() => {
        // This runs on disposal
    });

    // Override default dispose behavior
    ctx.overrideDispose((defaultDispose) => {
        // Custom cleanup logic
        defaultDispose();
    });

    return { /* service API */ };
}, 'singleton');
```

## API Client Example

```tsx
import { defineFactory, signal } from 'sigx';

interface User {
    id: number;
    name: string;
    email: string;
}

const useUserApi = defineFactory((ctx) => {
    const cache = signal(new Map<number, User>());
    const loading = signal({ value: false });
    
    const fetchUser = async (id: number): Promise<User> => {
        // Check cache first
        const cached = cache.get(id);
        if (cached) return cached;
        
        loading.value = true;
        try {
            const response = await fetch(`/api/users/${id}`);
            const user = await response.json();
            cache.set(id, user);
            return user;
        } finally {
            loading.value = false;
        }
    };
    
    const invalidateCache = () => {
        cache.$set(new Map());
    };
    
    ctx.onDeactivated(() => {
        invalidateCache();
    });
    
    return {
        fetchUser,
        invalidateCache,
        isLoading: () => loading.value
    };
}, 'singleton');

// Usage
const UserProfile = component(({ props }) => {
    const userApi = useUserApi();
    const state = signal({ user: null as User | null });
    
    onMounted(async () => {
        state.user = await userApi.fetchUser(props.userId);
    });
    
    return () => (
        <div>
            {userApi.isLoading() && <Spinner />}
            {state.user && <h1>{state.user.name}</h1>}
        </div>
    );
});
```

## Factories with Parameters

Factories can accept parameters for dynamic creation. A parameterized factory returns a `FactoryFunction` creator (typed overloads up to 5 parameters):

```tsx
const useRepository = defineFactory((ctx, entityName: string) => {
    const baseUrl = `/api/${entityName}`;
    
    const getAll = () => fetch(baseUrl).then(r => r.json());
    const getById = (id: number) => fetch(`${baseUrl}/${id}`).then(r => r.json());
    const create = (data: any) => fetch(baseUrl, {
        method: 'POST',
        body: JSON.stringify(data)
    });
    
    return { getAll, getById, create };
}, 'transient');

// Usage — each call creates a fresh instance (transient)
const usersRepo = useRepository('users');
const postsRepo = useRepository('posts');
```

For **non-transient** parameterized factories, arguments are honored at **first creation only** — later calls resolve the existing shared instance, whatever arguments they pass. If different argument sets must yield different instances, use `'transient'` (or provide per-subtree instances with `defineProvide`).

## Subscription Management

Use the built-in `SubscriptionHandler` for managing subscriptions:

```tsx
const useWebSocket = defineFactory((ctx) => {
    let ws: WebSocket | null = null;
    
    const connect = (url: string) => {
        ws = new WebSocket(url);
        
        // Auto-cleanup on factory disposal
        ctx.subscriptions.add(() => {
            ws?.close();
        });
    };
    
    const send = (data: any) => {
        ws?.send(JSON.stringify(data));
    };
    
    return { connect, send };
}, 'singleton');
```

## Combining with Dependency Injection

Factory use-functions satisfy `Providable<T>`, so they work with `defineProvide` / `app.defineProvide` exactly like `defineInjectable` tokens — including parameterized creators. Providing a `'scoped'` factory gives a subtree its own instance; the provider component owns it and disposes it on unmount.

```tsx
import { component, defineFactory, defineProvide, signal } from 'sigx';

// Define the factory
const useAuthService = defineFactory((ctx) => {
    const state = signal({ 
        user: null as User | null,
        token: null as string | null
    });
    
    const login = async (email: string, password: string) => {
        const response = await fetch('/auth/login', {
            method: 'POST',
            body: JSON.stringify({ email, password })
        });
        const data = await response.json();
        state.user = data.user;
        state.token = data.token;
    };
    
    const logout = () => {
        state.user = null;
        state.token = null;
    };
    
    return {
        get user() { return state.user; },
        get isAuthenticated() { return !!state.token; },
        login,
        logout
    };
}, 'scoped');

// Provide a fresh instance for a subtree (disposed when the provider unmounts)
const AccountArea = component(({ slots }) => {
    defineProvide(useAuthService);
    return () => <>{slots.default?.()}</>;
});

// Usage in components
const LoginForm = component(({ signal }) => {
    const auth = useAuthService();   // nearest provided instance
    const form = signal({ email: '', password: '' });
    
    const handleSubmit = async () => {
        await auth.login(form.email, form.password);
    };
    
    return () => (
        <form onSubmit={handleSubmit}>
            <input 
                type="email" 
                value={form.email}
                onInput={(e) => form.email = e.target.value}
            />
            <input 
                type="password"
                value={form.password}
                onInput={(e) => form.password = e.target.value}
            />
            <button type="submit">Login</button>
        </form>
    );
});

const UserStatus = component(() => {
    const auth = useAuthService();
    
    return () => (
        <div>
            {auth.isAuthenticated 
                ? <span>Welcome, {auth.user?.name}</span>
                : <span>Not logged in</span>
            }
        </div>
    );
});
```

## API Reference

### `defineFactory(setup, lifetime, typeIdentifier?)`

Create an injectable factory function.

| Parameter | Type | Description |
|-----------|------|-------------|
| `setup` | `(ctx: SetupFactoryContext, ...args) => T` | Factory setup function. Must return an object or function |
| `lifetime` | `Lifetime` | `'singleton'`, `'scoped'`, or `'transient'` |
| `typeIdentifier` | `guid` | Optional unique identifier |

**Returns:** An `InjectableFunction<T & { dispose: () => void }>` for parameterless setups, or a `FactoryFunction` creator for parameterized setups. Both work with `defineProvide` / `app.defineProvide`.

### `SetupFactoryContext`

Context passed to factory setup functions.

| Property | Type | Description |
|----------|------|-------------|
| `onDeactivated` | `(fn: () => void) => void` | Register cleanup callback |
| `subscriptions` | `SubscriptionHandler` | Helper for managing subscriptions |
| `overrideDispose` | `(fn: (dispose: () => void) => void) => void` | Custom disposal logic |

### `Lifetime`

String-literal union for factory instance lifetimes.

```tsx
type Lifetime = 'singleton' | 'scoped' | 'transient';
```

| Value | Description |
|-------|-------------|
| `'singleton'` | One instance per app (`AppContext`), disposed on `app.unmount()`; per-realm fallback outside apps |
| `'scoped'` | Nearest `defineProvide` provider, falling back to the app instance |
| `'transient'` | New instance every invocation, disposed with the calling component or via `dispose()` |

### `SubscriptionHandler`

Helper class for managing cleanup subscriptions.

```tsx
ctx.subscriptions.add(() => cleanup());
ctx.subscriptions.unsubscribe(); // Call all cleanup functions
```

## Best Practices

1. **Use `'singleton'` for app-wide shared state**:
   ```tsx
   const useStore = defineFactory(setup, 'singleton');
   ```

2. **Clean up resources**:
   ```tsx
   ctx.onDeactivated(() => {
       socket.close();
       subscription.unsubscribe();
   });
   ```

3. **Keep factories focused**:
   ```tsx
   // Good: Single responsibility
   const useUserApi = defineFactory(/* user API only */);
   const usePostApi = defineFactory(/* post API only */);
   
   // Avoid: Kitchen sink
   const useApi = defineFactory(/* everything */);
   ```

4. **Expose reactive getters**:
   ```tsx
   return {
       get user() { return state.user; },  // Reactive
       getUser: () => state.user           // Also reactive
   };
   ```

5. **Dispose transient instances you create outside components**:
   ```tsx
   const job = useJob();
   try { await job.run(); } finally { job.dispose(); }
   ```

## Next Steps

- [Messaging](/core/docs/advanced/messaging) - Pub/sub communication
- [Dependency Injection](/core/docs/app-plugins) - DI with provide/inject
- [Components](/core/docs/components) - Component patterns

---
url: https://sigx.dev/core/docs/advanced/messaging/
title: Messaging
description: Pub/sub communication pattern in SignalX
---

# Messaging

SignalX provides a lightweight pub/sub messaging system with `createTopic()`. Topics enable decoupled communication between components without prop drilling or global state.

## Creating Topics

```tsx
import { createTopic } from 'sigx';

// Create a typed topic
const userUpdated = createTopic<{ id: number; name: string }>();

// Publish a message
userUpdated.publish({ id: 1, name: 'John' });

// Subscribe to messages
const subscription = userUpdated.subscribe((user) => {
    console.log('User updated:', user.name);
});

// Unsubscribe when done
subscription.unsubscribe();
```

## Delivery Guarantees

Topics have a strict behavior contract:

- **Publishing is error-isolated.** A throwing subscriber is logged via `console.error` and neither skips later subscribers nor propagates into the publisher.
- **Subscribing to a destroyed topic throws.** A handler attached after `destroy()` could never be cleaned up, so it is rejected loudly instead of silently leaking.
- **Publishing to a destroyed topic is a no-op**, and `destroy()` itself is idempotent.

Topics also expose live state — `subscriberCount`, `hasSubscribers`, and `disposed` — so publishers can skip building payloads nobody will see:

```tsx
if (userUpdated.hasSubscribers) {
    userUpdated.publish(buildExpensivePayload());
}
```

## Auto-Cleanup in Components

When subscribing inside a component, subscriptions are automatically cleaned up on unmount:

```tsx
import { component, createTopic } from 'sigx';

// Define topic outside component (shared)
const notifications = createTopic<{ message: string; type: 'info' | 'error' }>();

const NotificationDisplay = component(({ signal }) => {
    const state = signal({ messages: [] as string[] });

    // Auto-unsubscribes when component unmounts
    notifications.subscribe((notification) => {
        state.messages = [...state.messages, notification.message];
    });

    return () => (
        <div class="notifications">
            {state.messages.map(msg => (
                <div class="notification">{msg}</div>
            ))}
        </div>
    );
});

// Any component can publish
const ActionButton = component(() => {
    const handleClick = () => {
        notifications.publish({ 
            message: 'Action completed!', 
            type: 'info' 
        });
    };

    return () => (
        <button onClick={handleClick}>Do Action</button>
    );
});
```

## Topic Options

Topics accept metadata and refCount lifecycle hooks:

```tsx
const userEvents = createTopic<UserEvent>({
    namespace: 'user',                  // tooling metadata
    name: 'events',                     // tooling metadata
    onActivate: () => startPolling(),   // subscriberCount went 0 → 1
    onDeactivate: () => stopPolling()   // subscriberCount went back to 0
});
```

`namespace` and `name` are exposed read-only on the topic. Topics created **with** a `namespace` also register in the [inspection registry](#inspecting-topics-from-tooling) for devtools; `destroy()` unregisters.

`onActivate` / `onDeactivate` implement the refCount pattern: pay for upstream work (polling, websocket connections, state watchers) only while someone is listening. `onDeactivate` fires on the last unsubscribe or on destroy. Hook errors are isolated, like subscriber errors.

## Read-Only Subscribers

Use `toSubscriber()` to create a read-only version of a topic:

```tsx
import { createTopic, toSubscriber } from 'sigx';

// Full topic (can publish and subscribe)
const internalEvents = createTopic<Event>();

// Read-only subscriber (can only subscribe)
export const events = toSubscriber(internalEvents);

// In another module:
events.subscribe((e) => console.log(e));
events.publish(); // Error: publish doesn't exist
```

This is useful for exposing topics from services while keeping publish control internal.

## Typed Topic Groups

For a set of related events, `createTopicGroup<EventMap>()` gives mitt-level DX on the `Topic` primitive — one typed topic per event key, created lazily on first access and destroyed together:

```tsx
import { createTopicGroup } from 'sigx';

// One typed topic per event key
const eventBus = createTopicGroup<{
    userLogin: { userId: number };
    userLogout: void;
    cartAdd: { productId: number; quantity: number };
    cartClear: void;
}>({ namespace: 'app' });

export default eventBus;

// Usage
import eventBus from './eventBus';

// Subscribe (payload typed per key)
eventBus.topics.userLogin.subscribe(({ userId }) => {
    console.log('User logged in:', userId);
});

// Publish (type-checked)
eventBus.topics.userLogin.publish({ userId: 123 });

// Tear down every created topic at once
eventBus.destroy();
```

The `namespace` is applied to every created topic (each topic's `name` is its event key), so the whole group is discoverable by tooling. Accessing a key on a destroyed group throws.

## Component Communication Example

```tsx
import { component, createTopic, signal } from 'sigx';

// Shared topic for cart updates
const cartUpdated = createTopic<{ itemCount: number }>();

// Cart service
const cartItems = signal({ items: [] as string[] });

function addToCart(item: string) {
    cartItems.items = [...cartItems.items, item];
    cartUpdated.publish({ itemCount: cartItems.items.length });
}

// Header shows cart count
const Header = component(({ signal }) => {
    const state = signal({ cartCount: 0 });

    cartUpdated.subscribe(({ itemCount }) => {
        state.cartCount = itemCount;
    });

    return () => (
        <header>
            <span>Cart ({state.cartCount})</span>
        </header>
    );
});

// Product can add to cart
const Product = component<{ name: string }>(({ props }) => {
    return () => (
        <div class="product">
            <span>{props.name}</span>
            <button onClick={() => addToCart(props.name)}>
                Add to Cart
            </button>
        </div>
    );
});

// App combines them
const App = component(() => {
    return () => (
        <div>
            <Header />
            <Product name="Widget" />
            <Product name="Gadget" />
        </div>
    );
});
```

## Using with Factories

Combine topics with factories for complex event handling:

```tsx
import { defineFactory, createTopic } from 'sigx';

interface AnalyticsEvent {
    event: string;
    properties: Record<string, any>;
}

const useAnalytics = defineFactory((ctx) => {
    const eventTopic = createTopic<AnalyticsEvent>();
    const eventQueue: AnalyticsEvent[] = [];
    let flushTimer: number | null = null;

    const track = (event: string, properties: Record<string, any> = {}) => {
        const analyticsEvent = { event, properties };
        eventQueue.push(analyticsEvent);
        eventTopic.publish(analyticsEvent);
        scheduleFlush();
    };

    const scheduleFlush = () => {
        if (flushTimer) return;
        flushTimer = window.setTimeout(flush, 1000);
    };

    const flush = async () => {
        if (eventQueue.length === 0) return;
        
        const events = [...eventQueue];
        eventQueue.length = 0;
        
        await fetch('/api/analytics', {
            method: 'POST',
            body: JSON.stringify({ events })
        });
        
        flushTimer = null;
    };

    ctx.onDeactivated(() => {
        if (flushTimer) {
            clearTimeout(flushTimer);
            flush(); // Flush remaining events
        }
        eventTopic.destroy();
    });

    return {
        track,
        onEvent: (handler: (event: AnalyticsEvent) => void) => 
            eventTopic.subscribe(handler)
    };
}, 'singleton');

// Usage
const analytics = useAnalytics();
analytics.track('page_view', { path: '/home' });
analytics.track('button_click', { button: 'signup' });
```

## Inspecting Topics from Tooling

Topics created with a `namespace` register in a realm-global inspection registry, exposed through the dedicated `@sigx/runtime-core/inspect` entry. This is how devtools discover and trace topics — it is **inspection-only**: the registry is deliberately `Topic<unknown>`-typed, so it is not a substitute for sharing typed topic references. **Typed code holds `Topic<T>` references; the strings are tooling metadata.**

```tsx
import { getTopic, listTopics, subscribeTopics, onTopicCreated } from '@sigx/runtime-core/inspect';

// Exact lookup
const topic = getTopic('app', 'userLogin');

// Wildcards match over `${namespace}.${name}`
listTopics('app.*');
listTopics('*.actions.*');

// Tap every matching topic — existing AND created later;
// one Subscription tears the whole tap down
const tap = subscribeTopics('app.*', (data, { namespace, name }) => {
    console.log(`[${namespace}.${name}]`, data);
});
tap.unsubscribe();

// React to topics registering from now on
onTopicCreated((topic) => console.log('new topic:', topic.namespace, topic.name));
```

`subscribeTopics` and `onTopicCreated` auto-unsubscribe on component unmount when called inside a setup. This registry is what `@sigx/devtools` builds on to auto-discover stores and topics.

## API Reference

### `createTopic<T>(options?)`

Create a new pub/sub topic.

| Parameter | Type | Description |
|-----------|------|-------------|
| `options.namespace` | `string` | Tooling metadata; topics with a namespace register in the inspection registry |
| `options.name` | `string` | Tooling metadata |
| `options.onActivate` | `() => void` | Called when `subscriberCount` transitions 0 → 1 |
| `options.onDeactivate` | `() => void` | Called when `subscriberCount` transitions back to 0 |

**Returns:** `Topic<T>`

### `Topic<T>`

| Member | Type | Description |
|--------|------|-------------|
| `namespace` | `string \| undefined` (readonly) | Tooling metadata |
| `name` | `string \| undefined` (readonly) | Tooling metadata |
| `subscriberCount` | `number` (readonly) | Current number of subscribers |
| `hasSubscribers` | `boolean` (readonly) | `subscriberCount > 0` |
| `disposed` | `boolean` (readonly) | `true` after `destroy()` |
| `publish` | `(data: T) => void` | Deliver to all subscribers; handler errors are isolated; no-op when disposed |
| `subscribe` | `(handler: (data: T) => void) => Subscription` | Register a handler; throws if the topic is destroyed |
| `destroy` | `() => void` | Remove all subscribers and unregister; idempotent |

### `createTopicGroup<EventMap>(options?)`

Create a typed group of topics keyed by an event map.

| Parameter | Type | Description |
|-----------|------|-------------|
| `options.namespace` | `string` | Applied to every created topic |

**Returns:** `{ topics: { [K in keyof EventMap]: Topic<EventMap[K]> }; destroy(): void }` — topics are created lazily per key; `destroy()` destroys them all.

### `toSubscriber<T>(topic)`

Create a read-only subscriber from a topic.

| Parameter | Type | Description |
|-----------|------|-------------|
| `topic` | `Topic<T>` | The topic to wrap |

**Returns:** `{ subscribe: (handler: (data: T) => void) => Subscription }`

### `Subscription`

| Method | Type | Description |
|--------|------|-------------|
| `unsubscribe` | `() => void` | Remove the subscription |

### `@sigx/runtime-core/inspect`

Inspection-only registry for tooling. Patterns use `*` wildcards matched over `${namespace}.${name}`.

| Function | Signature | Description |
|----------|-----------|-------------|
| `getTopic` | `(namespace: string, name: string) => Topic<unknown> \| undefined` | Exact lookup of a live registered topic |
| `listTopics` | `(pattern?: string) => Topic<unknown>[]` | List live registered topics, optionally filtered |
| `subscribeTopics` | `(pattern: string, handler: (data, meta) => void) => Subscription` | Subscribe to every matching topic, existing and future |
| `onTopicCreated` | `(handler: (topic: Topic<unknown>) => void) => Subscription` | Handler for every topic registering from now on |

## Best Practices

1. **Define topics at module level** for sharing:
   ```tsx
   // events.ts
   export const userEvents = createTopic<UserEvent>();
   ```

2. **Use TypeScript for type safety**:
   ```tsx
   const topic = createTopic<{ id: number; name: string }>();
   topic.publish({ id: 1, name: 'Test' }); // Type-checked
   ```

3. **Clean up manual subscriptions**:
   ```tsx
   const sub = topic.subscribe(handler);
   // Later:
   sub.unsubscribe();
   ```

4. **Use toSubscriber for encapsulation**:
   ```tsx
   // Internal: full control
   const _events = createTopic<Event>();
   // External: read-only
   export const events = toSubscriber(_events);
   ```

5. **Destroy topics when no longer needed** (and remember: subscribing after destroy throws):
   ```tsx
   ctx.onDeactivated(() => {
       topic.destroy();
   });
   ```

6. **Gate expensive work on listeners**:
   ```tsx
   const topic = createTopic<Frame>({
       onActivate: () => startCapture(),
       onDeactivate: () => stopCapture()
   });
   if (topic.hasSubscribers) topic.publish(captureFrame());
   ```

7. **Keep the inspection registry for tooling.** Share typed `Topic<T>` references between modules; reach for `@sigx/runtime-core/inspect` only in devtools/diagnostic code.

## When to Use Topics vs Props

| Use Props When | Use Topics When |
|----------------|-----------------|
| Parent-child communication | Sibling communication |
| Data flows down | Events flow laterally |
| Tight coupling is fine | Loose coupling needed |
| Simple component trees | Complex/deep trees |

## Next Steps

- [Factories](/core/docs/advanced/factories) - Injectable services
- [Components](/core/docs/components) - Component patterns
- [App & Plugins](/core/docs/app-plugins) - Application structure

---
url: https://sigx.dev/daisyui/docs/components/card/
title: Card
description: Flexible container component for grouping related content
---

# Card

Cards are flexible containers for grouping related content and actions.

## Import

```tsx
import { Card } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Card, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card width="80">
            <Card.Body>
                <Card.Title>Card Title</Card.Title>
                <Text as="p">This is a basic card with some content.</Text>
                <Card.Actions>
                    <Button variant="primary">Action</Button>
                </Card.Actions>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## With Image

```tsx
import { component, render } from 'sigx';
import { Card, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card width="80">
            <Card.Image 
                src="https://picsum.photos/400/200" 
                alt="Random image"
                class="w-full h-48 object-cover"
            />
            <Card.Body>
                <Card.Title>Photo Card</Card.Title>
                <Text as="p">A card with an image at the top.</Text>
                <Card.Actions>
                    <Button variant="primary" size="sm">View</Button>
                </Card.Actions>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Variants

### Bordered

```tsx
import { component, render } from 'sigx';
import { Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card bordered width="80">
            <Card.Body>
                <Card.Title>Bordered Card</Card.Title>
                <Text as="p">This card has a visible border.</Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

### Compact

```tsx
import { component, render } from 'sigx';
import { Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card variant="compact" width="80">
            <Card.Body>
                <Card.Title>Compact Card</Card.Title>
                <Text as="p">Less padding for compact layouts.</Text>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Card Grid

```tsx
import { component, render } from 'sigx';
import { Card, Button, Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [
        { title: 'Project Alpha', desc: 'A cutting-edge web application' },
        { title: 'Project Beta', desc: 'Mobile-first design system' },
        { title: 'Project Gamma', desc: 'Backend API service' },
    ];
    
    return () => (
        <Row gap="4" wrap>
            {items.map(item => (
                <Card bordered width="72">
                    <Card.Body>
                        <Col gap="3">
                            <Card.Title>{item.title}</Card.Title>
                            <Text color="muted">{item.desc}</Text>
                            <Card.Actions>
                                <Button size="sm">Details</Button>
                            </Card.Actions>
                        </Col>
                    </Card.Body>
                </Card>
            ))}
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Card Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'normal' \| 'compact' \| 'side' \| 'bordered' \| 'image-full'` | `'normal'` | Card style variant |
| `shadow` | `boolean \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `true` | Shadow style |
| `bordered` | `boolean` | `false` | Add border style (`card-bordered`) |
| `glass` | `boolean` | `false` | Glassmorphism style |
| `imageFull` | `boolean` | `false` | Full-image overlay style |
| `bgColor` | `string` | `'bg-base-100'` | **Deprecated** — prefer `background`. Raw bg utility class |
| `background` | `BackgroundColor` | - | Theme-aware background, e.g. `"base-200"` |
| `rounded` | `RadiusValue \| boolean` | - | Corner rounding (`true` → theme `rounded-box`) |
| `width` | `SizeValue` | - | Tailwind step (`"56"`=14rem/224px) or unitful value (`"560px"`, `"50%"`) |
| `height` | `SizeValue` | - | Same value format as `width` |
| `padding` | `Spacing` | - | Inner padding |
| `class` | `string` | `undefined` | Additional CSS classes |

### Card.Body Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `center` | `boolean` | `false` | Center content horizontally |
| `class` | `string` | `undefined` | Additional CSS classes |

### Card.Title Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

### Card.Actions Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `justify` | `'start' \| 'center' \| 'end'` | `'end'` | Actions alignment |
| `class` | `string` | `undefined` | Additional CSS classes |

### Card.Image Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | - | Image source URL |
| `alt` | `string` | `''` | Alt text |
| `class` | `string` | `undefined` | Additional classes for the `figure` wrapper |

---
url: https://sigx.dev/daisyui/docs/components/chat/
title: Chat
description: Chat bubble components for messaging interfaces
---

# Chat

Chat bubbles and messaging UI components for building chat interfaces.

## Import

```tsx
import { Chat, ChatImage, ChatHeader, ChatBubble, ChatFooter } from '@sigx/daisyui';
```

## Basic Chat

```tsx
import { component, render } from 'sigx';
import { Chat, ChatBubble, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatBubble>Hey! How are you?</ChatBubble>
                    </Chat>
                    
                    <Chat align="end">
                        <ChatBubble>I'm doing great, thanks for asking!</ChatBubble>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Chat with Avatar

```tsx
import { component, render } from 'sigx';
import { Chat, ChatImage, ChatBubble, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatImage placeholder="JD" />
                        <ChatBubble>Good morning! Ready for the meeting?</ChatBubble>
                    </Chat>
                    
                    <Chat align="end">
                        <ChatImage placeholder="ME" bgColor="secondary" />
                        <ChatBubble>Yes, just grabbing coffee first ☕</ChatBubble>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Chat with Header and Footer

```tsx
import { component, render } from 'sigx';
import { Chat, ChatImage, ChatHeader, ChatBubble, ChatFooter, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatImage placeholder="JD" />
                        <ChatHeader name="John Doe" time="12:45" />
                        <ChatBubble>Can you review my pull request?</ChatBubble>
                        <ChatFooter>Delivered</ChatFooter>
                    </Chat>
                    
                    <Chat align="end">
                        <ChatImage placeholder="ME" bgColor="secondary" />
                        <ChatHeader name="Me" time="12:46" />
                        <ChatBubble>Sure! I'll check it out now.</ChatBubble>
                        <ChatFooter>Seen at 12:46</ChatFooter>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Chat Bubble Colors

```tsx
import { component, render } from 'sigx';
import { Chat, ChatBubble, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatBubble color="primary">Primary bubble</ChatBubble>
                    </Chat>
                    <Chat align="end">
                        <ChatBubble color="secondary">Secondary bubble</ChatBubble>
                    </Chat>
                    <Chat align="start">
                        <ChatBubble color="accent">Accent bubble</ChatBubble>
                    </Chat>
                    <Chat align="end">
                        <ChatBubble color="info">Info bubble</ChatBubble>
                    </Chat>
                    <Chat align="start">
                        <ChatBubble color="success">Success bubble</ChatBubble>
                    </Chat>
                    <Chat align="end">
                        <ChatBubble color="warning">Warning bubble</ChatBubble>
                    </Chat>
                    <Chat align="start">
                        <ChatBubble color="error">Error bubble</ChatBubble>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Conversation Example

```tsx
import { component, render } from 'sigx';
import { Chat, ChatImage, ChatHeader, ChatBubble, Card, Input, Button, Row, Divider, Col, Flex } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const chat = signal({ 
        newMessage: '',
        messages: [
            { id: 1, sender: 'Alice', avatar: 'A', text: 'Hey! Have you seen the new design?', time: '10:30', mine: false },
            { id: 2, sender: 'Me', avatar: 'M', text: 'Not yet, can you share it?', time: '10:31', mine: true },
            { id: 3, sender: 'Alice', avatar: 'A', text: 'Sure, here it is! Let me know what you think.', time: '10:32', mine: false },
            { id: 4, sender: 'Me', avatar: 'M', text: 'Wow, this looks amazing! 🎉', time: '10:33', mine: true }
        ]
    });
    
    const sendMessage = () => {
        if (!chat.newMessage.trim()) return;
        
        chat.messages = [...chat.messages, {
            id: Date.now(),
            sender: 'Me',
            avatar: 'M',
            text: chat.newMessage,
            time: new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }),
            mine: true
        }];
        chat.newMessage = '';
    };
    
    const handleKeyPress = (e) => {
        if (e.key === 'Enter') sendMessage();
    };
    
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4" maxHeight="400px" class="overflow-y-auto">
                    {chat.messages.map(msg => (
                        <Chat align={msg.mine ? 'end' : 'start'}>
                            <ChatImage placeholder={msg.avatar} bgColor={msg.mine ? 'primary' : 'secondary'} />
                            <ChatHeader name={msg.sender} time={msg.time} />
                            <ChatBubble color={msg.mine ? 'primary' : undefined}>
                                {msg.text}
                            </ChatBubble>
                        </Chat>
                    ))}
                </Col>
            </Card.Body>
            
            <Divider />
            <Row gap="2" padding="4">
                <Flex grow>
                    <Input 
                        model={() => chat.newMessage}
                        placeholder="Type a message..."
                        onKeyPress={handleKeyPress}
                    />
                </Flex>
                <Button variant="primary" onClick={sendMessage}>Send</Button>
            </Row>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Multiple Bubbles

```tsx
import { component, render } from 'sigx';
import { Chat, ChatImage, ChatBubble, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatImage placeholder="JD" />
                        <ChatBubble>Hey!</ChatBubble>
                        <ChatBubble>I have a question about the project.</ChatBubble>
                        <ChatBubble>Are you available for a quick call?</ChatBubble>
                    </Chat>
                    
                    <Chat align="end">
                        <ChatImage placeholder="ME" bgColor="secondary" />
                        <ChatBubble>Hi!</ChatBubble>
                        <ChatBubble>Yes, give me 5 minutes.</ChatBubble>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Image in Chat

```tsx
import { component, render } from 'sigx';
import { Chat, ChatImage, ChatBubble, ChatHeader, ChatFooter, Card, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Chat align="start">
                        <ChatImage placeholder="JD" />
                        <ChatHeader>John Doe</ChatHeader>
                        <ChatBubble>Check out this view from my hike!</ChatBubble>
                        <ChatBubble class="p-0 overflow-hidden">
                            <img 
                                src="https://picsum.photos/300/200" 
                                alt="Shared image"
                                class="max-w-xs"
                            />
                        </ChatBubble>
                        <ChatFooter>Sent at 3:45 PM</ChatFooter>
                    </Chat>
                    
                    <Chat align="end">
                        <ChatImage placeholder="ME" bgColor="secondary" />
                        <ChatBubble color="primary">That's beautiful! 😍</ChatBubble>
                    </Chat>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Chat Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `align` | `'start' \| 'end'` | `'start'` | Bubble alignment |
| `class` | `string` | - | Additional CSS classes |

### Chat Slots

| Slot | Description |
|------|-------------|
| `default` | ChatImage, ChatHeader, ChatBubble, ChatFooter components |

### ChatBubble Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Bubble color |
| `class` | `string` | - | Additional CSS classes |

### ChatImage Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | - | Image URL for avatar |
| `alt` | `string` | `'Avatar'` | Alt text for image avatar |
| `placeholder` | `string` | - | Initials text; renders a colored circle instead of an image |
| `bgColor` | `string` | `'primary'` | Background color for placeholder circle (e.g. `'secondary'`, `'accent'`) |
| `class` | `string` | - | Additional CSS classes |

### ChatHeader/ChatFooter Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | - | Additional CSS classes |

---
url: https://sigx.dev/core/packages/reactivity/api/
title: API reference
description: API reference for @sigx/reactivity — every export of the SignalX Reactivity package.
---

# API reference

<p class="lede">Exports of `@sigx/reactivity` .</p>

All examples assume a named import from the package root:

```ts
import { signal, computed, effect } from '@sigx/reactivity';
```

## Functions

### signal

Create a reactive signal. Primitives are wrapped in a `{ value }` box accessed via `.value`; objects and arrays become deeply reactive proxies you mutate directly, plus a `$set` method to replace the whole value.

```ts
export function signal<T extends Primitive>(target: T): PrimitiveSignal<T>;
export function signal<T extends object>(target: T): Signal<T>;
```

- `target` — the initial value. A `Primitive` returns a `PrimitiveSignal<T>`; an `object` returns a `Signal<T>` (deep reactive proxy).
- Returns a `PrimitiveSignal<T>` or `Signal<T>` depending on the input.

`signal` is idempotent: passing an already-reactive proxy (or a raw object that already has a proxy) returns the existing proxy. Exotic built-ins such as `Date` and `RegExp` are returned unwrapped and are not reactive.

### computed

Create a lazy, cached, reactive derived value. Pass a getter for a read-only `Computed<T>`, or a `{ get, set }` options object for a `WritableComputed<T>`.

```ts
export function computed<T>(getter: ComputedGetter<T>): Computed<T>;
export function computed<T>(options: WritableComputedOptions<T>): WritableComputed<T>;
```

- `getter` — a function returning the derived value; produces a read-only `Computed<T>`.
- `options` — a `WritableComputedOptions<T>` (`{ get, set }`); produces a `WritableComputed<T>`.
- Returns a computed signal read (and, when writable, written) via `.value`.

Recomputes only on access after a dependency changed. Reads are tracked like any other signal.

### effect

Run a side-effect function immediately and re-run it whenever its tracked reactive dependencies change.

```ts
export function effect(fn: EffectFn): EffectRunner;
```

- `fn` — the effect body; runs once immediately and on every dependency change.
- Returns an `EffectRunner` — a callable that re-runs the effect, with a `.stop()` method to dispose it.

Effects have a re-entrancy guard: a synchronous self-trigger during a run is ignored rather than recursing.

### batch

Batch multiple reactive updates so dependent effects flush only once after the function completes.

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

- `fn` — a function containing the writes to batch.
- Returns nothing.

Nestable via an internal depth counter; only the outermost batch flushes pending effects.

### untrack

Run `fn` while suppressing dependency tracking, so reactive reads inside it do not create subscriptions.

```ts
export function untrack<T>(fn: () => T): T;
```

- `fn` — a function to run without tracking its reactive reads.
- Returns the result of `fn`.

### effectScope

Create a scope object to run reactive work and dispose it in bulk.

```ts
export function effectScope(detached?: boolean): {
  run<T>(fn: () => T): T | undefined;
  stop(fromParent?: boolean): void;
};
```

- `detached` — when `true`, the scope is not collected by (and not stopped with) a surrounding parent scope.
- Returns an object with `run(fn)` (executes `fn` within the scope, returning its result or `undefined` if the scope is stopped) and `stop()` (disposes everything created inside `run()`).

`stop()` disposes the effects and watchers created inside `run()`. Nested scopes are stopped with their parent unless created detached (`effectScope(true)`).

### onScopeDispose

Register an arbitrary teardown callback with the currently-active scope — the component setup being collected, or the innermost running `effectScope()`. It uses the same registration path `effect()` and `watch()` use for their own disposers, exposed for non-reactive resources (event listeners, timers, observers) whose lifetime must match the owning scope's.

```ts
export function onScopeDispose(fn: () => void): boolean;
```

- `fn` — a disposer to run when the active scope stops.
- Returns `true` if a scope captured the disposer, or `false` (without retaining `fn`) when no scope is active — the caller owns the teardown itself in that case.

```ts
function useIntervalFn(fn: () => void, ms: number) {
  const id = setInterval(fn, ms);
  onScopeDispose(() => clearInterval(id));
}

const tick = () => console.log('tick');
const scope = effectScope();
scope.run(() => useIntervalFn(tick, 1000));
scope.stop(); // interval cleared
```

This is the primitive that composables build teardown on: a `use*` helper registers its own cleanup with whatever scope is active — no disposer argument to thread through. The boolean return reports whether a scope actually captured it, so a helper meant to also work outside a scope can check it and fall back to returning a manual disposer.

### watch

Watch a reactive source and invoke a callback when it changes.

```ts
export function watch<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>,
  options?: WatchOptions
): WatchHandle;
```

- `source` — a getter function or a value (`WatchSource<T>`).
- `cb` — a `WatchCallback<T>` receiving `(newValue, oldValue, onCleanup)`.
- `options` — optional `WatchOptions`: `immediate`, `deep` (boolean or depth number), and `once`.
- Returns a `WatchHandle` that is itself callable to stop, plus `stop`, `pause`, and `resume` methods.

`immediate` fires the callback once at setup with `oldValue` undefined. While paused, changes are buffered and the latest is delivered on resume if it differs from the old value (`Object.is`). `onCleanup` runs before each subsequent callback and on stop.

### toRaw

Return the original raw object underlying a reactive proxy.

```ts
export function toRaw<T>(observed: T): T;
```

- `observed` — a reactive proxy (or any value).
- Returns the underlying raw object, recursively unwrapped; returns the value unchanged if it is not a proxy.

### toSignal

Create a signal-shaped view over one property of a reactive object. Unlike destructuring (which snapshots the value), the returned object reads and writes through to the source, so tracking and triggering work.

```ts
export function toSignal<T extends object, K extends SignalKey<T>>(
  source: T,
  key: K
): PropertySignal<T[K]>;
```

- `source` — a reactive object (e.g. from `signal({...})`).
- `key` — the property to view. Any string key except `$set`.
- Returns a `PropertySignal<T[K]>` — a `{ value }` box delegating to the source.

```ts
const state = signal({ count: 0 });
const count = toSignal(state, 'count');
count.value++; // triggers effects watching state.count
```

Writes go through `Reflect.set`, so a rejected write (read-only property, refusing proxy) throws instead of failing silently.

### toSignals

Create signal-shaped views for every own enumerable property of a reactive object, so it can be destructured without losing reactivity.

```ts
export function toSignals<T extends object>(source: T): ToSignals<T>;
```

- `source` — a reactive object.
- Returns a `ToSignals<T>` — one `PropertySignal` per own enumerable string key (`$set` excluded).

```ts
const state = signal({ count: 0, name: 'Ada' });
const { count, name } = toSignals(state);
count.value++; // still reactive
```

### isReactive

Check whether a value is a reactive proxy created by `signal()`.

```ts
export function isReactive(value: unknown): boolean;
```

- `value` — the value to test.
- Returns `true` if it is a reactive proxy.

### isComputed

Type guard for computed signals.

```ts
export function isComputed(value: unknown): value is Computed<unknown>;
```

- `value` — the value to test.
- Returns `true` if the value carries the internal `ComputedSymbol`, narrowing it to `Computed<unknown>`.

### isSignal

Check whether a value is a signal-shaped `{ value }` handle: a primitive-wrapper signal from `signal(primitive)`, or a property view from `toSignal` / `toSignals`. Orthogonal to `isReactive` and `isComputed` — it matches the `{ value }` box shape, not object proxies or computeds.

```ts
export function isSignal(value: unknown): value is { value: unknown };
```

- `value` — the value to test.
- Returns `true` for primitive-wrapper and property-view signals, narrowing to `{ value: unknown }`; `false` for object signals (use `isReactive`), computeds (use `isComputed`), and unbranded plain `{ value }` objects.

```ts
const state = signal({ x: 1 });

isSignal(signal(0));            // true  — primitive-wrapper signal
isSignal(toSignal(state, 'x')); // true  — property view
isSignal(state);                // false — object signal (use isReactive)
isSignal({ value: 1 });         // false — plain object
```

### detectAccess

Run a selector while observing property accesses and return the last `[target, key]` pair read.

```ts
export function detectAccess(selector: () => any): [any, string | symbol] | null;
```

- `selector` — a function whose property accesses are observed.
- Returns the last `[target, key]` pair read, or `null` if none.

Used internally by the model / two-way-binding system; computed getters suspend the observer to prevent leakage.

## Constants

### ComputedSymbol

```ts
export const ComputedSymbol: unique symbol = Symbol('computed');
```

Unique symbol used to brand computed signals. It is the key behind `isComputed` and the `Computed` / `WritableComputed` interfaces.

## Types

### Primitive

```ts
export type Primitive = string | number | boolean | symbol | bigint | null | undefined;
```

Union of primitive value types that `signal()` wraps in a `{ value: T }` box.

### Widen

```ts
export type Widen<T> =
  T extends boolean ? boolean :
  T extends number ? number :
  T extends string ? string :
  T extends bigint ? bigint :
  T extends symbol ? symbol :
  T;
```

Widens literal types to their base primitive (e.g. `false` to `boolean`, `'hello'` to `string`). Applied to the `value` of a `PrimitiveSignal`.

### PrimitiveSignal

```ts
export type PrimitiveSignal<T> = { value: Widen<T> };
```

Type of a primitive signal: a `{ value }` box whose value is widened to its base primitive type. No `$set`.

### Signal

```ts
export type Signal<T> = T & {
  $set: (newValue: T) => void;
};
```

Type of an object/array signal: the original shape `T` plus a `$set(newValue)` method for replacing the whole object reactively.

### PropertySignal

```ts
export type PropertySignal<T> = { value: T };
```

A signal-shaped live view over a single property of a reactive object, returned by `toSignal`. Reads and writes delegate to the source, so reactivity is preserved.

### ToSignals

```ts
export type ToSignals<T extends object> = {
  [K in keyof T as K extends SignalKey<T> ? K : never]: PropertySignal<T[K]>;
};
```

Return type of `toSignals` — per-key `PropertySignal` views. `SignalKey<T>` is the (non-exported) constraint behind both functions: string keys of `T` excluding `$set`. At runtime, views exist only for keys `Object.keys` yields (own enumerable string keys).

### EffectFn

```ts
export type EffectFn = () => void;
```

Signature of an effect body: a zero-argument function returning `void`.

### EffectScope

```ts
export type EffectScope = {
  run<T>(fn: () => T): T | undefined;
  stop(fromParent?: boolean): void;
};
```

Shape of an effect scope. Note that `effectScope()` returns a structurally-identical inline object literal rather than being annotated with this named type.

### Widen, Signal, and PrimitiveSignal together

`signal()` has two overloads. For `Primitive` inputs it returns `PrimitiveSignal<T>` — read/write through `.value`, no `$set`, with literal types widened. For object inputs it returns `Signal<T>` — a deep reactive proxy where you mutate properties directly and call `$set()` to replace the whole object.

### WatchSource

```ts
export type WatchSource<T = any> = T | (() => T);
```

A watch source: either a raw value or a getter function that returns the watched value.

### WatchCallback

```ts
export type WatchCallback<V = any, OV = any> =
  (value: V, oldValue: OV, onCleanup: (fn: () => void) => void) => any;
```

Watch callback receiving the new value, the old value, and an `onCleanup` registrar invoked before the next run and on stop.

## Interfaces

### EffectRunner

```ts
export interface EffectRunner<T = void> {
  (): T;
  stop: () => void;
}
```

Callable returned by `effect()`. Invoking it re-runs the effect; `.stop()` disposes it and cleans up its dependencies.

### Subscriber

```ts
export interface Subscriber extends EffectFn {
  deps: Set<Subscriber>[];
}
```

Internal reactive subscriber: an effect function carrying its list of dependency sets. Exported as a type but primarily an implementation detail.

### WatchOptions

```ts
export interface WatchOptions<Immediate = boolean> {
  immediate?: Immediate;
  deep?: boolean | number;
  once?: boolean;
}
```

Options for `watch()`. `immediate` fires the callback on setup; `deep` enables deep traversal (`true` for Infinity depth, a number for limited depth); `once` stops after the first callback.

### WatchHandle

```ts
export interface WatchHandle {
  (): void; // callable to stop
  stop: () => void;
  pause: () => void;
  resume: () => void;
}
```

Handle returned by `watch()`: callable to stop, plus `stop`/`pause`/`resume` methods. While paused, changes are buffered and the latest is delivered on resume if it differs from the old value.

### Computed

```ts
export interface Computed<T> {
  readonly value: T;
  readonly [ComputedSymbol]: true;
}
```

Read-only computed signal. Access the derived value via the readonly `.value` getter.

### WritableComputed

```ts
export interface WritableComputed<T> {
  value: T;
  readonly [ComputedSymbol]: true;
}
```

Writable computed signal. `.value` is both readable (computed) and assignable (routes to the provided setter).

### ComputedGetter

```ts
export interface ComputedGetter<T> {
  (): T;
}
```

Getter function for a computed: returns the derived value of type `T`.

### ComputedSetter

```ts
export interface ComputedSetter<T> {
  (value: T): void;
}
```

Setter function for a writable computed: receives the assigned value.

### WritableComputedOptions

```ts
export interface WritableComputedOptions<T> {
  get: ComputedGetter<T>;
  set: ComputedSetter<T>;
}
```

Options object passed to `computed()` to create a writable computed, supplying both `get` and `set`.

## See also

- [Usage guide](/core/packages/reactivity/usage) — practical patterns and examples.
- [Overview](/core/packages/reactivity/overview) — package summary and installation.

---
url: https://sigx.dev/daisyui/docs/components/diff/
title: Diff
description: Diff component shows a comparison between two items with a draggable resizer
---

# Diff

Diff component shows a side-by-side comparison between two items with a draggable resizer. Built with `Diff.Item1`, `Diff.Item2`, and `Diff.Resizer` sub-components.

## Import

```tsx
import { Diff } from '@sigx/daisyui';
```

## Basic Usage

A simple diff comparing two text blocks.

```tsx
import { component, render } from 'sigx';
import { Diff, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Diff class="aspect-[16/9] border border-base-300 rounded-xl">
            <Diff.Item1>
                <Text class="grid place-content-center w-full h-full bg-primary text-primary-content text-4xl font-bold">DAISY</Text>
            </Diff.Item1>
            <Diff.Item2>
                <Text class="grid place-content-center w-full h-full bg-secondary text-secondary-content text-4xl font-bold">DAISY</Text>
            </Diff.Item2>
            <Diff.Resizer />
        </Diff>
    );
});

render(<Demo />, "#sandbox");
```

## Aspect Ratio

Use Tailwind aspect ratio utilities on the container class.

```tsx
import { component, render } from 'sigx';
import { Diff, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Diff class="aspect-[4/3] border border-base-300 rounded-xl">
            <Diff.Item1>
                <Text class="grid place-content-center w-full h-full bg-success text-success-content text-3xl font-bold">4:3 Ratio</Text>
            </Diff.Item1>
            <Diff.Item2>
                <Text class="grid place-content-center w-full h-full bg-warning text-warning-content text-3xl font-bold">4:3 Ratio</Text>
            </Diff.Item2>
            <Diff.Resizer />
        </Diff>
    );
});

render(<Demo />, "#sandbox");
```

## Before / After Text

Show a before and after comparison with styled content.

```tsx
import { component, render } from 'sigx';
import { Diff, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Diff class="aspect-[16/9] border border-base-300 rounded-xl">
            <Diff.Item1>
                <Text class="grid place-content-center w-full h-full bg-base-200 text-base-content text-2xl">Before</Text>
            </Diff.Item1>
            <Diff.Item2>
                <Text class="grid place-content-center w-full h-full bg-accent text-accent-content text-2xl">After</Text>
            </Diff.Item2>
            <Diff.Resizer />
        </Diff>
    );
});

render(<Demo />, "#sandbox");
```

## With Card Content

Diff items can contain rich content like cards.

```tsx
import { component, render } from 'sigx';
import { Diff, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Diff class="aspect-[16/9] border border-base-300 rounded-xl">
            <Diff.Item1>
                <Card class="w-full h-full bg-error text-error-content rounded-none">
                    <Card.Body>
                        <Card.Title>Version A</Card.Title>
                        <Text>This is the original content before any changes were made.</Text>
                    </Card.Body>
                </Card>
            </Diff.Item1>
            <Diff.Item2>
                <Card class="w-full h-full bg-info text-info-content rounded-none">
                    <Card.Body>
                        <Card.Title>Version B</Card.Title>
                        <Text>This is the updated content after improvements.</Text>
                    </Card.Body>
                </Card>
            </Diff.Item2>
            <Diff.Resizer />
        </Diff>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Sized

Control the size via width and height utility classes.

```tsx
import { component, render } from 'sigx';
import { Diff, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Diff class="w-80 h-48 border border-base-300 rounded-xl">
            <Diff.Item1>
                <Text class="grid place-content-center w-full h-full bg-neutral text-neutral-content text-xl font-bold">Small</Text>
            </Diff.Item1>
            <Diff.Item2>
                <Text class="grid place-content-center w-full h-full bg-primary text-primary-content text-xl font-bold">Small</Text>
            </Diff.Item2>
            <Diff.Resizer />
        </Diff>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Diff

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes (e.g., aspect ratio, border, size) |

### Diff.Item1

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

### Diff.Item2

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

### Diff.Resizer

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/flex/
title: Flex / Row / Col
description: Flexible layout components using Tailwind CSS flex utilities
---

# Flex / Row / Col

Layout components for building flexible layouts with gap, alignment, and justify controls.

## Import

```tsx
import { Flex, Row, Col } from '@sigx/daisyui';
```

## Basic Usage

### Row (Horizontal)

`Row` arranges children horizontally.

```tsx
import { component, render } from 'sigx';
import { Row, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4">
            <Button>Button 1</Button>
            <Button>Button 2</Button>
            <Button>Button 3</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

### Col (Vertical)

`Col` arranges children vertically.

```tsx
import { component, render } from 'sigx';
import { Col, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Button>Button 1</Button>
            <Button>Button 2</Button>
            <Button>Button 3</Button>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

### Flex (Generic)

`Flex` is the base component with configurable direction.

```tsx
import { component, render } from 'sigx';
import { Flex, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Flex direction="row" gap="4">
            <Button>Button 1</Button>
            <Button>Button 2</Button>
            <Button>Button 3</Button>
        </Flex>
    );
});

render(<Demo />, "#sandbox");
```

## Gap

Control spacing between items with the `gap` prop.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Text size="sm" color="muted">gap="1"</Text>
                <Row gap="1">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">gap="4"</Text>
                <Row gap="4">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">gap="8"</Text>
                <Row gap="8">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Alignment

Use `align` to control cross-axis alignment.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Text size="sm" color="muted">align="start"</Text>
                <Row gap="4" align="start" background="base-200" rounded padding="2" height="20">
                    <Row background="primary" padding="2" rounded="md">Short</Row>
                    <Row background="secondary" padding="4" rounded="md">Tall</Row>
                    <Row background="accent" padding="2" rounded="md">Short</Row>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">align="center"</Text>
                <Row gap="4" align="center" background="base-200" rounded padding="2" height="20">
                    <Row background="primary" padding="2" rounded="md">Short</Row>
                    <Row background="secondary" padding="4" rounded="md">Tall</Row>
                    <Row background="accent" padding="2" rounded="md">Short</Row>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">align="end"</Text>
                <Row gap="4" align="end" background="base-200" rounded padding="2" height="20">
                    <Row background="primary" padding="2" rounded="md">Short</Row>
                    <Row background="secondary" padding="4" rounded="md">Tall</Row>
                    <Row background="accent" padding="2" rounded="md">Short</Row>
                </Row>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Justify

Use `justify` to control main-axis distribution.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Text size="sm" color="muted">justify="start"</Text>
                <Row gap="2" justify="start" background="base-200" rounded padding="2">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">justify="center"</Text>
                <Row gap="2" justify="center" background="base-200" rounded padding="2">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">justify="end"</Text>
                <Row gap="2" justify="end" background="base-200" rounded padding="2">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">justify="between"</Text>
                <Row gap="2" justify="between" background="base-200" rounded padding="2">
                    <Button size="sm">A</Button>
                    <Button size="sm">B</Button>
                    <Button size="sm">C</Button>
                </Row>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Wrap

Enable wrapping when items overflow.

```tsx
import { component, render } from 'sigx';
import { Row, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" wrap background="base-200" rounded padding="2" maxWidth="20rem">
            <Button size="sm">Button 1</Button>
            <Button size="sm">Button 2</Button>
            <Button size="sm">Button 3</Button>
            <Button size="sm">Button 4</Button>
            <Button size="sm">Button 5</Button>
            <Button size="sm">Button 6</Button>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Reverse Direction

Use the `reverse` prop to reverse the order of items.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="6">
            <Col gap="2">
                <Text size="sm" color="muted">Row reverse</Text>
                <Row gap="2" reverse>
                    <Button size="sm">1</Button>
                    <Button size="sm">2</Button>
                    <Button size="sm">3</Button>
                </Row>
            </Col>
            <Col gap="2">
                <Text size="sm" color="muted">Col reverse</Text>
                <Col gap="2" reverse>
                    <Button size="sm">1</Button>
                    <Button size="sm">2</Button>
                    <Button size="sm">3</Button>
                </Col>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Inline

Use `inline` prop for inline-flex behavior.

```tsx
import { component, render } from 'sigx';
import { Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Text as="p">
            This is text with an 
            <Row inline gap="1" background="base-200" rounded="md" padding={{ x: "1" }} margin={{ x: "1" }}>
                <Text color="primary">inline</Text>
                <Text color="secondary">flex</Text>
            </Row>
            row in the middle.
        </Text>
    );
});

render(<Demo />, "#sandbox");
```

## Styling Props

Row and Col components include built-in styling props for common patterns.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Row gap="4" padding="4" background="base-200" rounded>
                <Text>Padding, background and rounded</Text>
            </Row>
            <Row gap="4" padding="4" background="primary" rounded="lg">
                <Text>Primary background with lg rounded</Text>
            </Row>
            <Row gap="4" padding={{ x: "6", y: "3" }} background="secondary" rounded="full">
                <Text>Different x/y padding with full rounded</Text>
            </Row>
            <Col gap="2" padding="4" background="accent" rounded="xl">
                <Text>Accent column</Text>
                <Text>with multiple items</Text>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Width & Height

Control dimensions with `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight` props.

Supports both Tailwind presets and arbitrary CSS values.

```tsx
import { component, render } from 'sigx';
import { Row, Col, Button, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Row gap="4" width="full" padding="4" background="base-200" rounded>
                <Text>Full width row (width="full")</Text>
            </Row>
            <Row gap="4" width="1/2" padding="4" background="primary" rounded>
                <Text>Half width row (width="1/2")</Text>
            </Row>
            <Row gap="4" width="400px" padding="4" background="secondary" rounded>
                <Text>Arbitrary width (width="400px")</Text>
            </Row>
            <Col gap="2" width="200px" height="100px" padding="4" background="accent" rounded align="center" justify="center">
                <Text>Fixed size box</Text>
                <Text>200px × 100px</Text>
            </Col>
            <Row gap="4" maxWidth="50%" padding="4" background="neutral" rounded>
                <Text>Max 50% width (maxWidth="50%")</Text>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Common Patterns

### Header with Actions

```tsx
import { component, render } from 'sigx';
import { Row, Button, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row justify="between" align="center" padding="4" background="base-200" rounded>
            <Heading level={2} size="lg">Page Title</Heading>
            <Row gap="2">
                <Button size="sm" variant="ghost">Cancel</Button>
                <Button size="sm" variant="primary">Save</Button>
            </Row>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

### Form Layout

```tsx
import { component, render } from 'sigx';
import { Col, Row, FormField, Input, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4" maxWidth="24rem">
            <Row gap="4">
                <FormField label="First Name" class="flex-1">
                    <Input placeholder="John" />
                </FormField>
                <FormField label="Last Name" class="flex-1">
                    <Input placeholder="Doe" />
                </FormField>
            </Row>
            <FormField label="Email">
                <Input type="email" placeholder="john@example.com" />
            </FormField>
            <Row justify="end" gap="2">
                <Button variant="ghost">Cancel</Button>
                <Button variant="primary">Submit</Button>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

### Centered Content

```tsx
import { component, render } from 'sigx';
import { Col, Button, Heading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4" align="center" justify="center" background="base-200" rounded padding="6" height="48">
            <Heading level={2} size="xl">Welcome!</Heading>
            <Text color="muted">Get started with your project</Text>
            <Button variant="primary">Get Started</Button>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Flex Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `direction` | `'row' \| 'col' \| 'row-reverse' \| 'col-reverse'` | `'row'` | Flex direction |
| `gap` | `SpacingValue \| SpacingObject` | - | Gap between items. Can be a single value `"4"` or object `{{ x: "4", y: "2" }}` |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | - | Cross-axis alignment |
| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | - | Main-axis distribution |
| `wrap` | `boolean` | `false` | Enable flex wrap |
| `inline` | `boolean` | `false` | Use inline-flex instead of flex |
| `padding` | `SpacingValue \| SpacingObject` | - | Padding. Can be `"4"` or `{{ x: "2", y: "4" }}` or `{{ top: "2", left: "4" }}` |
| `margin` | `SpacingValue \| SpacingObject` | - | Margin. Same format as padding |
| `width` | `SizeValue` | - | Width (e.g., `"full"`, `"screen"`, `"48"`, `"1/2"`) |
| `height` | `SizeValue` | - | Height (e.g., `"full"`, `"screen"`, `"48"`, `"1/2"`) |
| `minWidth` | `SizeValue` | - | Minimum width |
| `minHeight` | `SizeValue` | - | Minimum height |
| `maxWidth` | `SizeValue` | - | Maximum width |
| `maxHeight` | `SizeValue` | - | Maximum height |
| `rounded` | `boolean \| 'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| 'full' \| 'box'` | - | Border radius (`true` = `rounded-box`) |
| `background` | `'base-100' \| 'base-200' \| 'base-300' \| 'primary' \| 'secondary' \| 'accent' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'error'` | - | Background color (auto sets text color for semantic colors) |
| `grow` | `boolean` | `false` | Enable flex-grow |
| `shrink` | `boolean` | `false` | Enable flex-shrink |
| `class` | `string` | - | Additional CSS classes |

### SpacingValue

`'0' | '1' | '2' | '3' | '4' | '5' | '6' | '8' | '10' | '12'`

### SpacingObject

```tsx
{
    all?: SpacingValue;
    x?: SpacingValue;
    y?: SpacingValue;
    top?: SpacingValue;
    right?: SpacingValue;
    bottom?: SpacingValue;
    left?: SpacingValue;
}
```

### SizeValue

Accepts Tailwind presets or arbitrary CSS values:

```tsx
// Tailwind presets
width="48"       // → w-48 (12rem)
width="full"     // → w-full (100%)
width="1/2"      // → w-1/2 (50%)
width="screen"   // → w-screen (100vw)

// Arbitrary CSS values (auto-wrapped in [])
width="400px"    // → w-[400px]
width="70%"      // → w-[70%]
width="calc(100% - 2rem)"  // → w-[calc(100%-2rem)]
```

**Tailwind presets:**
- Numeric: `'0'` through `'96'`
- Special: `'auto' | 'full' | 'screen' | 'min' | 'max' | 'fit'`
- Fractions: `'1/2' | '1/3' | '2/3' | '1/4' | '2/4' | '3/4' | '1/5' | '2/5' | '3/5' | '4/5' | '1/6' | '5/6'`

### Row Props

Same as Flex props, but without `direction`. Adds:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `reverse` | `boolean` | `false` | Reverse row direction |

### Col Props

Same as Flex props, but without `direction`. Adds:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `reverse` | `boolean` | `false` | Reverse column direction |

---
url: https://sigx.dev/daisyui/docs/components/join/
title: Join
description: Container for grouping multiple items with connected styles
---

# Join

Join is a container for grouping multiple items together. It applies border radius to the first and last item, creating a visually connected group of buttons, inputs, or other elements.

## Import

```tsx
import { Join, Button, Input, Select } from '@sigx/daisyui';
```

## Basic Usage

Group buttons together horizontally.

```tsx
import { component, render } from 'sigx';
import { Join, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join>
            <Join.Item><Button>Left</Button></Join.Item>
            <Join.Item><Button>Center</Button></Join.Item>
            <Join.Item><Button>Right</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## Vertical

Stack items vertically.

```tsx
import { component, render } from 'sigx';
import { Join, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join vertical>
            <Join.Item><Button>Top</Button></Join.Item>
            <Join.Item><Button>Middle</Button></Join.Item>
            <Join.Item><Button>Bottom</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## Horizontal (explicit)

Explicitly set horizontal direction. Useful for responsive overrides.

```tsx
import { component, render } from 'sigx';
import { Join, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join horizontal>
            <Join.Item><Button variant="primary">Left</Button></Join.Item>
            <Join.Item><Button variant="primary">Center</Button></Join.Item>
            <Join.Item><Button variant="primary">Right</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## Responsive

Use Tailwind responsive classes to switch direction at different breakpoints.

```tsx
import { component, render } from 'sigx';
import { Join, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join class="join-vertical lg:join-horizontal">
            <Join.Item><Button>First</Button></Join.Item>
            <Join.Item><Button>Second</Button></Join.Item>
            <Join.Item><Button>Third</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## With Inputs and Buttons

Mix different form elements inside a join.

```tsx
import { component, render } from 'sigx';
import { Join, Button, Input } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join>
            <Join.Item><Input placeholder="Search..." class="join-item" /></Join.Item>
            <Join.Item><Button variant="primary">Search</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## With Select and Button

Combine selects with buttons in a group.

```tsx
import { component, render } from 'sigx';
import { Join, Button, Select } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Join>
            <Join.Item>
                <Select options={[
                    { label: 'Sci-fi', value: 'scifi' },
                    { label: 'Drama', value: 'drama' },
                    { label: 'Action', value: 'action' },
                ]} class="join-item" />
            </Join.Item>
            <Join.Item>
                <Select options={[
                    { label: '2024', value: '2024' },
                    { label: '2023', value: '2023' },
                    { label: '2022', value: '2022' },
                ]} class="join-item" />
            </Join.Item>
            <Join.Item><Button variant="primary">Search</Button></Join.Item>
        </Join>
    );
});

render(<Demo />, "#sandbox");
```

## ButtonGroup

`ButtonGroup` is a convenience wrapper specifically for grouping buttons. It uses the same underlying join classes.

```tsx
import { component, render } from 'sigx';
import { ButtonGroup, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <ButtonGroup>
            <Button variant="primary">Left</Button>
            <Button variant="primary">Center</Button>
            <Button variant="primary">Right</Button>
        </ButtonGroup>
    );
});

render(<Demo />, "#sandbox");
```

## ButtonGroup Vertical

```tsx
import { component, render } from 'sigx';
import { ButtonGroup, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <ButtonGroup vertical>
            <Button>Top</Button>
            <Button>Middle</Button>
            <Button>Bottom</Button>
        </ButtonGroup>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Join Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `vertical` | `boolean` | `false` | Stack items vertically |
| `horizontal` | `boolean` | `false` | Explicitly set horizontal direction |
| `background` | `BackgroundColor` | - | Theme-aware background |
| `rounded` | `RadiusValue \| boolean` | - | Corner rounding (theme `box`/`field`/`selector`, or fixed scale) |
| `width` | `SizeValue` | - | Width — Tailwind step or unitful value |
| `height` | `SizeValue` | - | Height — same value format as `width` |
| `padding` | `Spacing` | - | Inner padding |
| `class` | `string` | `undefined` | Additional CSS classes |

### Join.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes |

### ButtonGroup Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `vertical` | `boolean` | `false` | Stack buttons vertically |
| `horizontal` | `boolean` | `false` | Explicitly set horizontal direction |
| `class` | `string` | `undefined` | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/hero/
title: Hero
description: Hero section component for landing pages and headers
---

# Hero

Hero sections for landing pages and headers with flexible layouts.

## Import

```tsx
import { Hero, HeroContent, Text } from '@sigx/daisyui';
```

## Basic Hero

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Col, Heading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Hero minHeight="400px" background="base-200">
                <HeroContent>
                    <Col gap="6" align="center">
                        <Heading level={1} size="5xl">Hello there</Heading>
                        <Text as="p" align="center">
                            Provident cupiditate voluptatem et in. Quaerat fugiat ut assumenda excepturi exercitationem quasi.
                        </Text>
                        <Button variant="primary">Get Started</Button>
                    </Col>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hero with Image

### Image on Side

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Col, Row, Heading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Hero minHeight="400px" background="base-200">
                <HeroContent>
                    <Row gap="8" wrap align="center" justify="center">
                        <Card.Image
                            src="https://picsum.photos/400/300"
                            alt="Hero image"
                            class="max-w-sm rounded-lg shadow-2xl"
                        />
                        <Col gap="6" maxWidth="24rem">
                            <Heading level={1} size="5xl">Box Office News!</Heading>
                            <Text as="p">
                                Provident cupiditate voluptatem et in. Quaerat fugiat ut assumenda excepturi exercitationem quasi.
                            </Text>
                            <Button variant="primary">Get Started</Button>
                        </Col>
                    </Row>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hero with Overlay

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Col, Heading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card class="overflow-hidden">
            <Hero 
                minHeight="400px"
                bgImage="https://picsum.photos/800/400"
                overlay
            >
                <HeroContent class="text-neutral-content">
                    <Col gap="5" align="center">
                        <Heading level={1} size="5xl">Welcome</Heading>
                        <Text as="p" align="center">
                            Explore our amazing platform and discover new possibilities for your projects.
                        </Text>
                        <Button variant="primary">Explore Now</Button>
                    </Col>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hero with Form

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Input, FormField, Col, Row, Heading, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const form = signal({ email: '' });
    
    return () => (
        <Card>
            <Hero minHeight="400px" background="base-200">
                <HeroContent>
                    <Row gap="8" wrap align="center" justify="center">
                        <Col gap="6" maxWidth="24rem" align="center">
                            <Heading level={1} size="5xl" align="center">Join Us Today!</Heading>
                            <Text as="p" align="center">
                                Sign up to get exclusive access to our newsletter and early product announcements.
                            </Text>
                        </Col>
                        <Card width="full" shadow="xl" background="base-100" class="max-w-sm">
                            <Card.Body>
                                <Col gap="6">
                                    <FormField label="Email">
                                        <Input 
                                            model={() => form.email}
                                            type="email"
                                            placeholder="email@example.com"
                                        />
                                    </FormField>
                                    <Button variant="primary" class="w-full">Subscribe</Button>
                                </Col>
                            </Card.Body>
                        </Card>
                    </Row>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hero with Stats

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Badge, Col, Row, Heading, Stats, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Hero minHeight="500px" class="bg-gradient-to-br from-primary to-secondary text-primary-content">
                <HeroContent class="text-center">
                    <Col gap="8" align="center" maxWidth="32rem">
                        <Badge>New Release</Badge>
                        <Heading level={1} size="5xl" align="center">Build Amazing Apps</Heading>
                        <Text as="p" size="xl" align="center" class="opacity-90">
                            Create stunning user interfaces with SignalX and DaisyUI components.
                        </Text>
                        
                        <Row gap="4" justify="center">
                            <Button size="lg">Get Started</Button>
                            <Button size="lg" variant="ghost" class="text-primary-content border-primary-content">
                                Documentation
                            </Button>
                        </Row>
                        
                        <Stats class="bg-primary-content text-primary md:stats-horizontal">
                            <Stats.Item title="Downloads" value="31K" />
                            <Stats.Item title="Users" value="4,200" />
                            <Stats.Item title="Components" value="50+" />
                        </Stats>
                    </Col>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Hero with Features

```tsx
import { component, render } from 'sigx';
import { Hero, HeroContent, Button, Card, Col, Heading, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const features = [
        { icon: '⚡', title: 'Fast', desc: 'Optimized for speed' },
        { icon: '🔒', title: 'Secure', desc: 'Built-in security' },
        { icon: '📱', title: 'Responsive', desc: 'Works on all devices' }
    ];
    
    return () => (
        <Card>
            <Hero minHeight="500px" background="base-200">
                <HeroContent>
                    <Col gap="8" align="center" maxWidth="56rem">
                        <Col gap="4" align="center">
                            <Heading level={1} size="5xl" align="center">Why Choose Us?</Heading>
                            <Text as="p" size="lg" align="center" class="opacity-70">
                                We provide the best tools for building modern web applications.
                            </Text>
                        </Col>
                    
                        <Row gap="6" wrap justify="center">
                            {features.map(feature => (
                                <Card background="base-100" width="72">
                                    <Card.Body center>
                                        <Text as="span" size="4xl">{feature.icon}</Text>
                                        <Heading level={3} size="xl">{feature.title}</Heading>
                                        <Text as="p" color="muted" align="center">{feature.desc}</Text>
                                    </Card.Body>
                                </Card>
                            ))}
                        </Row>
                    
                        <Button variant="primary">Learn More</Button>
                    </Col>
                </HeroContent>
            </Hero>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Notes on current API constraints

This page now favors component composition, but a few styling classes remain intentional due to current component API limitations:

- `HeroContent` always applies an internal `max-w-md` wrapper, which can constrain wide layouts.
- `Stats.Item` currently has no props for title/value-specific styling.
- Some responsive behaviors (like `md:stats-horizontal`) still require class utilities.

These are tracked as migration gap candidates for Milestone 5.

## Props

### Hero Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `overlay` | `boolean` | `false` | Show hero overlay |
| `bgImage` | `string` | - | Background image URL |
| `minHeight` | `string` | - | Minimum height (e.g., `'400px'`) |
| `background` | `BackgroundColor` | - | Theme-aware background, e.g. `"base-200"` |
| `rounded` | `RadiusValue \| boolean` | - | Corner rounding (`true` → theme `rounded-box`) |
| `width` | `SizeValue` | - | Width — Tailwind step or unitful value |
| `height` | `SizeValue` | - | Height — same value format as `width` |
| `padding` | `Spacing` | - | Inner padding |
| `class` | `string` | - | Additional CSS classes |

### Hero Slots

| Slot | Description |
|------|-------------|
| `default` | Hero content (overlay + HeroContent) |
| `overlay` | Content for the overlay layer |

### HeroContent Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | - | Additional CSS classes for layout |

### HeroContent Slots

| Slot | Description |
|------|-------------|
| `default` | Content elements |

---
url: https://sigx.dev/daisyui/docs/components/menu/
title: Menu
description: Vertical menu component for navigation
---

# Menu

Vertical menu component for navigation with support for nested items, icons, and active states.

## Import

```tsx
import { Menu, Row, Text } from '@sigx/daisyui';
```

## Basic Menu

```tsx
import { component, render } from 'sigx';
import { Menu } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Menu background="base-200" rounded width="56">
            <Menu.Item>Home</Menu.Item>
            <Menu.Item>About</Menu.Item>
            <Menu.Item>Services</Menu.Item>
            <Menu.Item>Contact</Menu.Item>
        </Menu>
    );
});

render(<Demo />, "#sandbox");
```

## Links

By default a `Menu.Item` wraps its content in an `<a>` for styling. To make it a
real navigable link, pass `href`. To use your own interactive element (a router
`<Link>`, a `<button>`, …) without nesting interactive elements, pass `asChild`
and provide the element yourself.

```tsx
import { component, render } from 'sigx';
import { Menu } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Menu background="base-200" rounded width="56">
            <Menu.Item href="/daisyui/docs/getting-started">Getting started</Menu.Item>
            <Menu.Item href="/daisyui/docs/components/button">Button</Menu.Item>
            <Menu.Item asChild>
                <button type="button" onClick={() => alert('clicked')}>Run action</button>
            </Menu.Item>
        </Menu>
    );
});

render(<Demo />, "#sandbox");
```

## Menu with Active Item

Use model binding to track the active menu item:

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Badge, Col, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const nav = signal({ active: 'home' });
    
    const items = [
        { id: 'home', label: 'Home' },
        { id: 'about', label: 'About' },
        { id: 'services', label: 'Services' },
        { id: 'contact', label: 'Contact' }
    ];
    
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Menu model={() => nav.active} background="base-200" rounded width="56">
                        {items.map(item => (
                            <Menu.Item value={item.id}>{item.label}</Menu.Item>
                        ))}
                    </Menu>
                    
                    <Col gap="1">
                        <Text size="sm" color="muted">Current page:</Text>
                        <Badge variant="primary" size="lg">{nav.active}</Badge>
                    </Col>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Menu with Icons

```tsx
import { component, render } from 'sigx';
import { Menu, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [
        { icon: '🏠', label: 'Home' },
        { icon: 'ℹ️', label: 'About' },
        { icon: '📊', label: 'Stats' }
    ];

    return () => (
        <Menu background="base-200" rounded width="56">
            {items.map(item => (
                <Menu.Item>
                    <Row align="center" gap="2">
                        <Text as="span">{item.icon}</Text>
                        <Text as="span">{item.label}</Text>
                    </Row>
                </Menu.Item>
            ))}
        </Menu>
    );
});

render(<Demo />, "#sandbox");
```

## Menu with Title

```tsx
import { component, render } from 'sigx';
import { Menu } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Menu background="base-200" rounded width="56">
            <Menu.Title>Category 1</Menu.Title>
            <Menu.Item>Item 1</Menu.Item>
            <Menu.Item>Item 2</Menu.Item>

            <Menu.Title>Category 2</Menu.Title>
            <Menu.Item>Item 3</Menu.Item>
            <Menu.Item>Item 4</Menu.Item>
        </Menu>
    );
});

render(<Demo />, "#sandbox");
```

## Nested Menu (Submenu)

```tsx
import { component, render } from 'sigx';
import { Menu } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Menu background="base-200" rounded width="56">
            <Menu.Item>Item 1</Menu.Item>
            <Menu.Item submenu>
                <details open>
                    <summary>Parent Item</summary>
                    <ul>
                        <li><a>Submenu 1</a></li>
                        <li><a>Submenu 2</a></li>
                        <li>
                            <details open>
                                <summary>Nested Parent</summary>
                                <ul>
                                    <li><a>Deep Item 1</a></li>
                                    <li><a>Deep Item 2</a></li>
                                </ul>
                            </details>
                        </li>
                    </ul>
                </details>
            </Menu.Item>
            <Menu.Item>Item 3</Menu.Item>
        </Menu>
    );
});

render(<Demo />, "#sandbox");
```

## Menu Sizes

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Col gap="4">
                    <Menu size="xs" background="base-200" rounded width="56">
                        <Menu.Item>xs size</Menu.Item>
                        <Menu.Item>Item 2</Menu.Item>
                        <Menu.Item>Item 3</Menu.Item>
                    </Menu>
                    
                    <Menu size="sm" background="base-200" rounded width="56">
                        <Menu.Item>sm size</Menu.Item>
                        <Menu.Item>Item 2</Menu.Item>
                        <Menu.Item>Item 3</Menu.Item>
                    </Menu>
                    
                    <Menu size="md" background="base-200" rounded width="56">
                        <Menu.Item>md size</Menu.Item>
                        <Menu.Item>Item 2</Menu.Item>
                        <Menu.Item>Item 3</Menu.Item>
                    </Menu>
                    
                    <Menu size="lg" background="base-200" rounded width="56">
                        <Menu.Item>lg size</Menu.Item>
                        <Menu.Item>Item 2</Menu.Item>
                        <Menu.Item>Item 3</Menu.Item>
                    </Menu>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Horizontal Menu

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Menu horizontal background="base-200" rounded>
                    <Menu.Item>Item 1</Menu.Item>
                    <Menu.Item>Item 2</Menu.Item>
                    <Menu.Item>Item 3</Menu.Item>
                </Menu>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Menu with Badges

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Badge, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const items = [
        { label: 'Inbox', badge: '99+', variant: 'primary' as const },
        { label: 'Notifications', badge: '8', variant: 'secondary' as const },
        { label: 'Updates', badge: 'New', variant: 'accent' as const }
    ];

    // Place the label and badge as direct children of Menu.Item — daisyUI's
    // menu-item grid pushes the trailing badge to the right automatically.
    return () => (
        <Card>
            <Card.Body>
                <Menu background="base-200" rounded width="64">
                    {items.map(item => (
                        <Menu.Item>
                            <Text as="span">{item.label}</Text>
                            <Badge variant={item.variant}>{item.badge}</Badge>
                        </Menu.Item>
                    ))}
                </Menu>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled Items

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card>
            <Card.Body>
                <Menu background="base-200" rounded width="56">
                    <Menu.Item>Normal item</Menu.Item>
                    <Menu.Item disabled>Disabled item</Menu.Item>
                    <Menu.Item>Normal item</Menu.Item>
                    <Menu.Item disabled>Another disabled</Menu.Item>
                </Menu>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Sidebar Navigation Example

```tsx
import { component, render } from 'sigx';
import { Menu, Card, Badge, Row, Col, Heading, Text } from '@sigx/daisyui';

const Demo = component(({ signal }) => {
    const nav = signal({ active: 'dashboard' });
    
    const menuItems = [
        { id: 'dashboard', icon: '📊', label: 'Dashboard' },
        { id: 'users', icon: '👥', label: 'Users', badge: 12 },
        { id: 'products', icon: '📦', label: 'Products' },
        { id: 'orders', icon: '🛒', label: 'Orders', badge: 5 },
        { id: 'analytics', icon: '📈', label: 'Analytics' },
        { id: 'settings', icon: '⚙️', label: 'Settings' }
    ];
    
    return () => (
        <Card>
            <Card.Body>
                <Row gap="4" align="start">
                    <Col class="w-64">
                        <Menu model={() => nav.active} background="base-200" rounded width="full">
                            {menuItems.map(item => (
                                <Menu.Item value={item.id}>
                                    <Text as="span">{item.icon}</Text>
                                    <Text as="span">{item.label}</Text>
                                    {item.badge && (
                                        <Badge variant="primary" size="sm">{item.badge}</Badge>
                                    )}
                                </Menu.Item>
                            ))}
                        </Menu>
                    </Col>
                    
                    <Col gap="2" grow class="p-4 bg-base-200 rounded-lg">
                        <Heading level={3} size="xl" class="capitalize">{nav.active}</Heading>
                        <Text color="muted">Content for {nav.active} page goes here.</Text>
                    </Col>
                </Row>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Menu Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `model` | `() => string` | - | Two-way binding for active item |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Menu item size |
| `horizontal` | `boolean` | `false` | Horizontal layout |
| `background` | `BackgroundColor` | - | Panel background (e.g. `"base-200"`) — theme-aware |
| `rounded` | `RadiusValue \| boolean` | - | Corner rounding. Theme radii `"box"` / `"field"` / `"selector"` (or fixed `sm`…`3xl`/`full`); `true` → box |
| `width` | `SizeValue` | - | Menu width — Tailwind step (`"56"`=14rem) or unitful value (`"560px"`). daisyUI menus are `fit-content` by default |
| `padding` | `Spacing` | - | Inner padding |
| `class` | `string` | - | Additional CSS classes |

> Menu *items* are already rounded by the theme's **field** radius. The `background`/`rounded` props above style the whole menu panel (`rounded` uses the theme **box** radius); you can also wrap the menu in a box container (`Col`/`Row`) if you prefer.

### Menu.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Value for model binding |
| `active` | `boolean` | `false` | Force active state |
| `href` | `string` | - | Render the item as a real link (`<a href>`); `menu-active` is applied automatically |
| `asChild` | `boolean` | `false` | Render the slot directly (no `<a>` wrap) so you can supply your own `<a>`/`<button>`/router `<Link>` without nesting interactive elements. You own the active styling |
| `submenu` | `boolean` | `false` | Render slot directly (no `<a>` wrap) for a nested `<details>` submenu |
| `disabled` | `boolean` | `false` | Disable the item |
| `class` | `string` | - | Additional CSS classes |

### Menu.Title Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | - | Additional CSS classes |

## Events

| Event | Type | Description |
|-------|------|-------------|
| `update:modelValue` | `(value: string) => void` | Emitted when active item changes |

---
url: https://sigx.dev/daisyui/docs/components/swap/
title: Swap
description: Swap component toggles between two states with rotate or flip animation
---

# Swap

Swap toggles the visibility of two elements using a checkbox, with optional rotate or flip animation. Built with `Swap.On`, `Swap.Off`, and optional `Swap.Indeterminate` sub-components.

## Import

```tsx
import { Swap } from '@sigx/daisyui';
```

## Basic Text Swap

Toggle between two text labels.

```tsx
import { component, render } from 'sigx';
import { Swap } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap class="text-4xl">
            <Swap.On>ON</Swap.On>
            <Swap.Off>OFF</Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Rotate Effect

Apply a rotation animation during the swap transition.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap rotate class="text-6xl">
            <Swap.On>
                <Text class="text-6xl">🌙</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-6xl">☀️</Text>
            </Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Flip Effect

Apply a 3D flip animation during the swap transition.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap flip class="text-6xl">
            <Swap.On>
                <Text class="text-6xl">😈</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-6xl">😇</Text>
            </Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Hamburger Button

Combine Swap with button classes for a hamburger menu toggle.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap rotate class="btn btn-circle">
            <Swap.On>
                <Text class="text-xl">✕</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-xl">☰</Text>
            </Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Active (Class-based)

Use the `active` prop to control the swap state without a checkbox interaction.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap active class="text-4xl">
            <Swap.On>
                <Text class="text-4xl">Active content</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-4xl">Inactive content</Text>
            </Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Volume Icons

Swap between volume on and off icons with rotation.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap rotate class="text-4xl">
            <Swap.On>
                <Text class="text-4xl">🔊</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-4xl">🔇</Text>
            </Swap.Off>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## With Indeterminate State

The `Swap.Indeterminate` sub-component renders content visible when the checkbox is in an indeterminate state.

```tsx
import { component, render } from 'sigx';
import { Swap, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Swap class="text-4xl">
            <Swap.On>
                <Text class="text-4xl">✅</Text>
            </Swap.On>
            <Swap.Off>
                <Text class="text-4xl">❌</Text>
            </Swap.Off>
            <Swap.Indeterminate>
                <Text class="text-4xl">➖</Text>
            </Swap.Indeterminate>
        </Swap>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Swap

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `rotate` | `boolean` | `false` | Apply rotation animation effect |
| `flip` | `boolean` | `false` | Apply 3D flip animation effect |
| `active` | `boolean` | `false` | Activate swap display via class (no checkbox needed) |
| `model` | `Signal<boolean>` | `undefined` | Two-way binding for controlled state |
| `class` | `string` | `undefined` | Additional CSS classes |
| `onChange` | `(checked: boolean) => void` | `undefined` | Callback when swap state changes |

### Swap.On

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes for the on-state element |

### Swap.Off

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes for the off-state element |

### Swap.Indeterminate

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `class` | `string` | `undefined` | Additional CSS classes for the indeterminate-state element |

---
url: https://sigx.dev/daisyui/docs/components/stat/
title: Stats
description: Display statistics with title, value, description, figure, and actions
---

# Stats

Stats display numeric data or key metrics in a structured layout.

## Import

```tsx
import { Stats } from '@sigx/daisyui';
```

## Basic Usage

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item>
                <Stats.Title>Total Page Views</Stats.Title>
                <Stats.Value>89,400</Stats.Value>
                <Stats.Desc>21% more than last month</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## Multiple Stats

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item>
                <Stats.Title>Downloads</Stats.Title>
                <Stats.Value>31K</Stats.Value>
                <Stats.Desc>Jan 1st - Feb 1st</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Users</Stats.Title>
                <Stats.Value>4,200</Stats.Value>
                <Stats.Desc>↗︎ 400 (22%)</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Registers</Stats.Title>
                <Stats.Value>1,200</Stats.Value>
                <Stats.Desc>↘︎ 90 (14%)</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## Vertical Layout

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats vertical shadow>
            <Stats.Item>
                <Stats.Title>Downloads</Stats.Title>
                <Stats.Value>31K</Stats.Value>
                <Stats.Desc>Jan 1st - Feb 1st</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Users</Stats.Title>
                <Stats.Value>4,200</Stats.Value>
                <Stats.Desc>↗︎ 400 (22%)</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Registers</Stats.Title>
                <Stats.Value>1,200</Stats.Value>
                <Stats.Desc>↘︎ 90 (14%)</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## With Figure / Icons

Use `Stats.Figure` to add icons or images alongside stats.

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item>
                <Stats.Figure class="text-primary">
                    <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" class="inline-block h-8 w-8 stroke-current">
                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z" />
                    </svg>
                </Stats.Figure>
                <Stats.Title>Total Likes</Stats.Title>
                <Stats.Value class="text-primary">25.6K</Stats.Value>
                <Stats.Desc>21% more than last month</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Figure class="text-secondary">
                    <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" class="inline-block h-8 w-8 stroke-current">
                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z" />
                    </svg>
                </Stats.Figure>
                <Stats.Title>Page Views</Stats.Title>
                <Stats.Value class="text-secondary">2.6M</Stats.Value>
                <Stats.Desc>21% more than last month</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## With Actions

Use `Stats.Actions` to add buttons or links below the stat.

```tsx
import { component, render } from 'sigx';
import { Stats, Button } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item>
                <Stats.Title>Account balance</Stats.Title>
                <Stats.Value>$89,400</Stats.Value>
                <Stats.Actions>
                    <Button variant="primary" size="sm">Withdraw</Button>
                    <Button size="sm">Deposit</Button>
                </Stats.Actions>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## Centered Items

Apply `place-items-center` class to center stat content.

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item class="place-items-center">
                <Stats.Title>Downloads</Stats.Title>
                <Stats.Value>31K</Stats.Value>
                <Stats.Desc>From January 1st to February 1st</Stats.Desc>
            </Stats.Item>
            <Stats.Item class="place-items-center">
                <Stats.Title>Users</Stats.Title>
                <Stats.Value>4,200</Stats.Value>
                <Stats.Desc>↗︎ 40 (2%)</Stats.Desc>
            </Stats.Item>
            <Stats.Item class="place-items-center">
                <Stats.Title>Registers</Stats.Title>
                <Stats.Value>1,200</Stats.Value>
                <Stats.Desc>↘︎ 90 (14%)</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## Responsive

Use `vertical` with responsive class overrides for mobile-vertical, desktop-horizontal layouts.

```tsx
import { component, render } from 'sigx';
import { Stats } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats vertical shadow class="lg:stats-horizontal">
            <Stats.Item>
                <Stats.Title>Downloads</Stats.Title>
                <Stats.Value>31K</Stats.Value>
                <Stats.Desc>Jan 1st - Feb 1st</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Users</Stats.Title>
                <Stats.Value>4,200</Stats.Value>
                <Stats.Desc>↗︎ 400 (22%)</Stats.Desc>
            </Stats.Item>
            <Stats.Item>
                <Stats.Title>New Registers</Stats.Title>
                <Stats.Value>1,200</Stats.Value>
                <Stats.Desc>↘︎ 90 (14%)</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## With Figure and Avatar

```tsx
import { component, render } from 'sigx';
import { Stats, Avatar } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Stats shadow>
            <Stats.Item>
                <Stats.Figure>
                    <Avatar size="md" shape="circle" src="https://i.pravatar.cc/150?u=stat1" />
                </Stats.Figure>
                <Stats.Value>86%</Stats.Value>
                <Stats.Title>Tasks done</Stats.Title>
                <Stats.Desc class="text-secondary">31 tasks remaining</Stats.Desc>
            </Stats.Item>
        </Stats>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Stats (container)

| Prop       | Type      | Default | Description                        |
|------------|-----------|---------|------------------------------------|
| vertical   | boolean   | false   | Stack stats vertically             |
| horizontal | boolean   | false   | Force horizontal layout            |
| shadow     | boolean   | false   | Add shadow to container            |
| background | BackgroundColor | — | Theme-aware background             |
| rounded    | RadiusValue \| boolean | — | Corner rounding (theme box/field/selector, or fixed scale) |
| width      | SizeValue | —       | Width — Tailwind step or unitful value |
| height     | SizeValue | —       | Height — same format as width      |
| padding    | Spacing   | —       | Inner padding                      |
| class      | string    | —       | Additional CSS classes             |

### Stats.Item

| Prop  | Type   | Default | Description            |
|-------|--------|---------|------------------------|
| class | string | —       | Additional CSS classes |

### Stats.Title / Stats.Value / Stats.Desc / Stats.Figure / Stats.Actions

| Prop  | Type   | Default | Description            |
|-------|--------|---------|------------------------|
| class | string | —       | Additional CSS classes |

---
url: https://sigx.dev/daisyui/docs/components/tabs/
title: Tabs
description: Tabbed navigation for organizing content
---

# Tabs

Tabs organize content into separate views where only one view can be visible at a time.

## Import

```tsx
import { Tabs, Row, Col } from '@sigx/daisyui';
```

## Basic Usage

Simple tabs without content panels - just tab buttons:

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('tab1');
    
    const tabs = [
        { id: 'tab1', label: 'Tab 1' },
        { id: 'tab2', label: 'Tab 2' },
        { id: 'tab3', label: 'Tab 3' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
        />
    );
});

render(<Demo />, "#sandbox");
```

## Tabs with Content

When tabs include a `content` property, the component uses DaisyUI's native radio input pattern for seamless content switching:

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('tab1');
    
    const tabs = [
        { id: 'tab1', label: 'Tab 1', content: 'This is the content for Tab 1. Click other tabs to switch!' },
        { id: 'tab2', label: 'Tab 2', content: 'Welcome to Tab 2. Each tab has its own content panel.' },
        { id: 'tab3', label: 'Tab 3', content: 'Tab 3 content goes here. The switching is handled by CSS!' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="lift"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Variants

### Box

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('home');
    
    const tabs = [
        { id: 'home', label: 'Home', content: 'Welcome home! This is the home tab content.' },
        { id: 'profile', label: 'Profile', content: 'Your profile settings and information.' },
        { id: 'settings', label: 'Settings', content: 'Application settings and preferences.' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="box"
        />
    );
});

render(<Demo />, "#sandbox");
```

### Border

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('overview');
    
    const tabs = [
        { id: 'overview', label: 'Overview', content: 'Project overview and summary information.' },
        { id: 'tasks', label: 'Tasks', content: 'Your assigned tasks and to-do items.' },
        { id: 'timeline', label: 'Timeline', content: 'Project timeline and milestones.' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="border"
        />
    );
});

render(<Demo />, "#sandbox");
```

### Lift

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('info');
    
    const tabs = [
        { id: 'info', label: 'Info', content: 'General information about the topic.' },
        { id: 'docs', label: 'Documentation', content: 'Read the documentation here.' },
        { id: 'faq', label: 'FAQ', content: 'Frequently asked questions and answers.' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="lift"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Rich Content

Tab content can include JSX elements and SignalX components:

```tsx
import { component, signal, render } from 'sigx';
import { Tabs, Button, Badge, Row, Col, Heading, Text, Card } from '@sigx/daisyui';
const Demo = component(() => {
    const activeTab = signal('dashboard');
    
    // Define tabs with JSX content in setup - runs once
    const tabs = [
        { 
            id: 'dashboard', 
            label: 'Dashboard', 
            content: (
                <Col gap="4">
                    <Heading level={3} size="lg">Dashboard Overview</Heading>
                    <Text>Welcome to your dashboard. Here's a quick summary of your activity.</Text>
                    <Row gap="2">
                        <Badge variant="primary">Active</Badge>
                        <Badge variant="success">Online</Badge>
                    </Row>
                </Col>
            )
        },
        { 
            id: 'analytics', 
            label: 'Analytics', 
            content: (
                <Col gap="4">
                    <Heading level={3} size="lg">Analytics</Heading>
                    <Text>View your performance metrics and statistics.</Text>
                    <Button size="sm" variant="primary">View Full Report</Button>
                </Col>
            )
        },
        { 
            id: 'reports', 
            label: 'Reports', 
            content: (
                <Col gap="4">
                    <Heading level={3} size="lg">Reports</Heading>
                    <Text>Download and manage your reports here.</Text>
                    <Button size="sm" variant="outline">Download PDF</Button>
                </Col>
            )
        },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="lift"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

```tsx
import { component, signal, render } from 'sigx';
import { Tabs, Text, Col, Card } from '@sigx/daisyui';
const Demo = component(() => {
    const activeTab = signal('a');
    const tabs = [
        { id: 'a', label: 'Tab A' },
        { id: 'b', label: 'Tab B' },
        { id: 'c', label: 'Tab C' },
    ];
    
    return () => (
        <Col gap="8">
            <Card>
                <Card.Body>
                <Text size="sm" class="mb-2">Extra Small</Text>
                <Tabs tabs={tabs} activeTab={activeTab.value} onChange={(id) => activeTab.value = id} size="xs" variant="lift" />
                </Card.Body>
            </Card>
            <Card>
                <Card.Body>
                <Text size="sm" class="mb-2">Small</Text>
                <Tabs tabs={tabs} activeTab={activeTab.value} onChange={(id) => activeTab.value = id} size="sm" variant="lift" />
                </Card.Body>
            </Card>
            <Card>
                <Card.Body>
                <Text size="sm" class="mb-2">Medium (default)</Text>
                <Tabs tabs={tabs} activeTab={activeTab.value} onChange={(id) => activeTab.value = id} size="md" variant="lift" />
                </Card.Body>
            </Card>
            <Card>
                <Card.Body>
                <Text size="sm" class="mb-2">Large</Text>
                <Tabs tabs={tabs} activeTab={activeTab.value} onChange={(id) => activeTab.value = id} size="lg" variant="lift" />
                </Card.Body>
            </Card>
            <Card>
                <Card.Body>
                <Text size="sm" class="mb-2">Extra Large</Text>
                <Tabs tabs={tabs} activeTab={activeTab.value} onChange={(id) => activeTab.value = id} size="xl" variant="lift" />
                </Card.Body>
            </Card>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Disabled Tabs

```tsx
import { component, signal, render } from 'sigx';
import { Tabs } from '@sigx/daisyui';

const Demo = component(() => {
    const activeTab = signal('enabled1');
    
    const tabs = [
        { id: 'enabled1', label: 'Enabled', content: 'This tab is enabled and clickable.' },
        { id: 'disabled', label: 'Disabled', content: 'You should not see this.', disabled: true },
        { id: 'enabled2', label: 'Also Enabled', content: 'This tab is also enabled.' },
    ];
    
    return () => (
        <Tabs 
            tabs={tabs}
            activeTab={activeTab.value}
            onChange={(id) => activeTab.value = id}
            variant="box"
        />
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tabs` | `Tab[]` | required | Array of tab objects with `id`, `label`, and optional `content` |
| `activeTab` | `string` | required | ID of the currently active tab |
| `onChange` | `(id: string) => void` | required | Called when a tab is clicked |
| `variant` | `'box' \| 'border' \| 'lift'` | `undefined` | Tab style variant |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Tab size |
| `position` | `'top' \| 'bottom'` | `'top'` | Position of tabs relative to content |
| `contentClass` | `string` | `undefined` | Additional CSS classes for tab content panels |
| `background` | `BackgroundColor` | - | Content panel background (overrides default `bg-base-100`) |
| `rounded` | `RadiusValue \| boolean` | - | Content panel rounding |
| `width` | `SizeValue` | - | Content panel width — Tailwind step or unitful value |
| `padding` | `Spacing` | - | Content panel padding (overrides default `p-6`) |
| `class` | `string` | `undefined` | Additional CSS classes for the tabs container (root) |

### Tab Object

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Unique tab identifier |
| `label` | `string \| JSX.Element` | Tab label (text or JSX) |
| `content` | `string \| JSX.Element` | Optional tab content panel |
| `disabled` | `boolean` | Whether the tab is disabled |

---
url: https://sigx.dev/daisyui/docs/components/text/
title: Text
description: Typography components for consistent text styling
---

# Text

Typography components for consistent text styling without manual CSS classes.

## Import

```tsx
import { Text, Heading } from '@sigx/daisyui';
```

## Basic Usage

The `Text` component provides consistent text styling with props instead of classes.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Text>Default text (renders as span)</Text>
            <Text size="lg">Large text</Text>
            <Text size="sm" color="muted">Small muted text</Text>
            <Text weight="bold" color="primary">Bold primary text</Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Heading Component

Use `Heading` for semantic heading elements with consistent styling.

```tsx
import { component, render } from 'sigx';
import { Col, Heading } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Heading level={1}>Heading 1</Heading>
            <Heading level={2}>Heading 2</Heading>
            <Heading level={3}>Heading 3</Heading>
            <Heading level={4}>Heading 4</Heading>
            <Heading level={5}>Heading 5</Heading>
            <Heading level={6}>Heading 6</Heading>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Block Text (Paragraphs)

Use `as="p"` to render block-level text content.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Text as="p">
                This is a paragraph of text. It renders as a {'<p>'} element and 
                supports all the same styling props.
            </Text>
            <Text as="p" size="sm" color="muted">
                A smaller, muted paragraph for secondary content.
            </Text>
            <Text as="p">
                You can use <Text color="primary" weight="bold">inline Text</Text> components 
                within paragraphs for <Text color="accent">colorful</Text> emphasis.
            </Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Text Sizes

Available size options from extra small to 5xl.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const sizes = ['xs', 'sm', 'base', 'lg', 'xl', '2xl', '3xl', '4xl', '5xl'] as const;
    
    return () => (
        <Col gap="2">
            {sizes.map(size => (
                <Text size={size} key={size}>
                    size="{size}"
                </Text>
            ))}
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Colors

Use semantic colors for consistent theming.

```tsx
import { component, render } from 'sigx';
import { Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Col gap="2">
                <Text size="sm" color="muted">Base colors</Text>
                <Row gap="4" wrap>
                    <Text color="base">base (default)</Text>
                    <Text color="muted">muted</Text>
                    <Text color="faint">faint</Text>
                </Row>
            </Col>
            
            <Col gap="2">
                <Text size="sm" color="muted">Semantic colors</Text>
                <Row gap="4" wrap>
                    <Text color="primary">primary</Text>
                    <Text color="secondary">secondary</Text>
                    <Text color="accent">accent</Text>
                    <Text color="neutral">neutral</Text>
                </Row>
            </Col>
            
            <Col gap="2">
                <Text size="sm" color="muted">Status colors</Text>
                <Row gap="4" wrap>
                    <Text color="info">info</Text>
                    <Text color="success">success</Text>
                    <Text color="warning">warning</Text>
                    <Text color="error">error</Text>
                </Row>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Font Weight

Control text weight with the `weight` prop.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    const weights = ['light', 'normal', 'medium', 'semibold', 'bold'] as const;
    
    return () => (
        <Col gap="2">
            {weights.map(weight => (
                <Text weight={weight} key={weight}>
                    weight="{weight}"
                </Text>
            ))}
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Text Alignment

Control text alignment with the `align` prop.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2" background="base-200" padding="4" rounded>
            <Text align="left">Left aligned (default)</Text>
            <Text align="center">Center aligned</Text>
            <Text align="right">Right aligned</Text>
            <Text align="justify">Justify aligned - This text will be justified to fill the available width when long enough.</Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Text Decoration

Add italic, underline, strikethrough, or uppercase styling.

```tsx
import { component, render } from 'sigx';
import { Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Row gap="4" wrap>
                <Text italic>Italic text</Text>
                <Text underline>Underlined text</Text>
                <Text strikethrough>Strikethrough text</Text>
                <Text uppercase>Uppercase text</Text>
            </Row>
            <Text italic underline color="primary">Combined styles</Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Truncation

Truncate overflowing text with an ellipsis.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4" maxWidth="20rem">
            <Text truncate>
                This is a very long text that will be truncated with an ellipsis when it exceeds the container width.
            </Text>
            <Text truncate={2}>
                This text will truncate after 2 lines. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
                Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, 
                quis nostrud exercitation ullamco laboris.
            </Text>
            <Text truncate={3}>
                This text will truncate after 3 lines. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
                Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, 
                quis nostrud exercitation ullamco laboris. Duis aute irure dolor in reprehenderit in voluptate 
                velit esse cillum dolore eu fugiat nulla pariatur.
            </Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Custom Element (as prop)

Render as a different element using the `as` prop.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Text as="span">Span element (default)</Text>
            <Text as="p">Paragraph element</Text>
            <Text as="label" weight="medium">Label element</Text>
            <Text as="strong" weight="bold">Strong element</Text>
            <Text as="em" italic>Em element</Text>
            <Text as="small" size="sm">Small element</Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## With Margin

Add spacing with the `margin` prop.

```tsx
import { component, render } from 'sigx';
import { Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col background="base-200" padding="4" rounded>
            <Text margin={{ bottom: "4" }} size="lg" weight="bold">
                Title with bottom margin
            </Text>
            <Text margin={{ bottom: "2" }} color="muted">
                Subtitle with smaller margin
            </Text>
            <Text>Regular content below</Text>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Heading Sizes

Headings have default sizes based on level, but can be customized.

```tsx
import { component, render } from 'sigx';
import { Col, Heading, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Col gap="2">
                <Text size="sm" color="muted">Default heading sizes</Text>
                <Heading level={1}>H1 (default 4xl)</Heading>
                <Heading level={2}>H2 (default 3xl)</Heading>
                <Heading level={3}>H3 (default 2xl)</Heading>
            </Col>
            
            <Col gap="2">
                <Text size="sm" color="muted">Custom heading sizes</Text>
                <Heading level={1} size="2xl">H1 with size="2xl"</Heading>
                <Heading level={2} size="lg">H2 with size="lg"</Heading>
                <Heading level={3} size="base">H3 with size="base"</Heading>
            </Col>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Practical Examples

### Card with Typography

```tsx
import { component, render } from 'sigx';
import { Col, Heading, Text, Button, Card } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Card class="border border-base-200" shadow="lg">
            <Card.Body>
                <Col gap="4" maxWidth="24rem">
                    <Heading level={2} size="xl">Getting Started</Heading>
                    <Text as="p" color="muted">
                        Welcome to our platform! Follow these steps to get started 
                        with your first project.
                    </Text>
                    <Col gap="2">
                        <Text weight="medium">Features include:</Text>
                        <Text color="muted" size="sm">• Easy setup and configuration</Text>
                        <Text color="muted" size="sm">• Comprehensive documentation</Text>
                        <Text color="muted" size="sm">• Active community support</Text>
                    </Col>
                    <Card.Actions>
                        <Button variant="ghost" size="sm">Learn More</Button>
                        <Button variant="primary" size="sm">Get Started</Button>
                    </Card.Actions>
                </Col>
            </Card.Body>
        </Card>
    );
});

render(<Demo />, "#sandbox");
```

### Status Message

```tsx
import { component, render } from 'sigx';
import { Col, Row, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="4">
            <Row gap="2" align="center" background="success" padding="3" rounded>
                <Text color="success-content" weight="medium">✓ Success!</Text>
                <Text color="success-content" size="sm">Your changes have been saved.</Text>
            </Row>
            
            <Row gap="2" align="center" background="error" padding="3" rounded>
                <Text color="error-content" weight="medium">✕ Error!</Text>
                <Text color="error-content" size="sm">Something went wrong.</Text>
            </Row>
            
            <Row gap="2" align="center" background="warning" padding="3" rounded>
                <Text color="warning-content" weight="medium">⚠ Warning!</Text>
                <Text color="warning-content" size="sm">Please review before continuing.</Text>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

### Text Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `as` | `'span' \| 'p' \| 'label' \| 'strong' \| 'em' \| 'small' \| 'div'` | `'span'` | HTML element to render |
| `size` | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl'` | - | Font size |
| `weight` | `'light' \| 'normal' \| 'medium' \| 'semibold' \| 'bold'` | - | Font weight |
| `color` | `TextColor` | - | Text color (see colors above) |
| `align` | `'left' \| 'center' \| 'right' \| 'justify'` | - | Text alignment |
| `italic` | `boolean` | `false` | Italic style |
| `underline` | `boolean` | `false` | Underline decoration |
| `strikethrough` | `boolean` | `false` | Strikethrough decoration |
| `uppercase` | `boolean` | `false` | Uppercase transform |
| `truncate` | `boolean \| number` | - | Truncate with ellipsis. `true` = single line, number = max lines |
| `margin` | `SpacingValue \| SpacingObject` | - | Margin around text |
| `class` | `string` | - | Additional CSS classes |

### Heading Props

Same as Text props, plus:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading level (renders h1-h6) |

Default sizes by level: h1=4xl, h2=3xl, h3=2xl, h4=xl, h5=lg, h6=base

### TextColor

```tsx
'base' | 'muted' | 'faint' |
'primary' | 'primary-content' |
'secondary' | 'secondary-content' |
'accent' | 'accent-content' |
'neutral' | 'neutral-content' |
'info' | 'info-content' |
'success' | 'success-content' |
'warning' | 'warning-content' |
'error' | 'error-content'
```

---
url: https://sigx.dev/server/packages/resume/usage/
title: Usage
description: Write resumable components, install the plugin, and wire single-flight boundary refresh
---

# Using Resume

<p class="lede">Ordinary components in resume modules, one plugin install, and an optional boundary-refresh endpoint.</p>

## Resumable components

Write ordinary SignalX components in a `*.resume.tsx` file (or under a configured `resume/` directory) — no QRL API, no registration. The transform derives everything: **named** signals (`const x = ctx.signal(…)`, keyed by declaration name) are serialized and rebuilt in the resumed scope; anything else stays local.

```tsx
export const Counter = component<{ label: string }>((ctx) => {
    const count = ctx.signal(0);
    return () => (
        <button onClick={() => count.value++}>
            {ctx.props.label}: {count.value}
        </button>
    );
});
```

A handler is resumable when its captures resolve through the resumed scope — named signals, `ctx.props` reads, imports, globals. Anything else (loop variables, setup helpers, `ctx.emit`) makes the whole component fall back to wake-on-interaction, with a build-time warning naming the capture.

## Install the plugin

`resumePlugin` is an SSR pack — install it on the app in your per-request entry, passing the build's manifest (which is `undefined` under dev, where resume runs manifest-less):

```tsx
// src/entry-server.tsx
import { defineApp } from 'sigx';
import { resumePlugin } from '@sigx/resume';
import { resumeManifest } from 'virtual:sigx-manifests';

export function createApp(url: string) {
    return defineApp(<App />).use(resumePlugin({ manifest: resumeManifest }));
}
```

The `sigxResume()` transform from `@sigx/vite/resume` produces the manifest and the delegation loader entry; the browser loads only that loader until an interaction upgrades a boundary.

## The client half

There are two postures, and picking the wrong one fails silently — so pick
deliberately.

### Coexisting with a hydrated app

The common case: an app that has a root — a shell, a router, ordinary
interactive components — and *also* wants some resumable components on the page.
Install the plugin on the **server** app as above, and on the client import only
the generated loader entry:

```tsx
// src/entry-client.tsx
import { defineApp } from 'sigx';
import 'virtual:sigx-resume/entry';   // the delegation loader — that's it
import { App } from './App';

const app = defineApp(<App />);
app.hydrate(document.getElementById('app')!);
```

Nothing else is needed, and that's the point. `hydrate()` walks the root as
usual and **skips** resume boundaries on the way past — the server plugin
records them `hydrate: 'never'` — while everything around them hydrates
normally. The loader wakes a boundary on first interaction.

Adding `app.use(resumePlugin())` before `hydrate()` is harmless but unnecessary:
on the client the plugin only registers the pack's DI provides, and none of the
wake-on-interaction behaviour depends on it.

### App-less resumable pages

A page whose entire bootstrap is the loader entry: no root app and no hydration
walk, so the browser downloads little more than the loader itself. There's
nothing to configure — just don't create an app.

If you *do* have an app and deliberately want no root walk (the islands
posture), ask for it:

```ts
app.use(resumePlugin({ boundaries: 'explicit' }));
```

That mode takes `hydrate()` down the no-root-walk path, so it schedules the
boundary table and returns. Since every resume record is `hydrate: 'never'`,
combining it with a root app you expected to hydrate leaves a dead shell — which
is why it's opt-in rather than the default.

## Progressive enhancement and `form: true`

A [server function](/server/packages/server/usage) marked `form: true` gets its
native `action` stamped by the resume extractor, so the stamping reaches only
files matching `sigxResume()`'s `include` **and** components that extract in
resume mode. A `<form>` anywhere else still submits through the server function
as RPC, once its component is running — hydrated, or resumed on interaction — it
just has no native no-JS fallback to fall back to before then.

The build warns when a `form: true` `<form>` will never be stamped, either
because its file is outside `include` or because the component fell back to
hydrate mode.

## What makes a boundary unrefreshable

A boundary is stamped `refreshable: false` when its props snapshot can't
reproduce the render. Dropped event handlers are forgiven — they never shape
server HTML — and the rule is **an `on*` prop whose value is a function**,
whatever its spelling: `onclick` counts exactly as `onClick` does.

An `on`-prefixed *data* prop that the snapshot can't carry is a different thing,
and correctly still counts as dropped state.

## Single-flight boundary refresh

To let a mutation update the server-rendered boundaries it invalidated, build a refresher with `createBoundaryRefresh` and hand it to your server-function request handler as its `renderBoundaries` option:

```ts
import { createBoundaryRefresh } from '@sigx/resume/server';

const renderBoundaries = createBoundaryRefresh({
    plugins: [resumePlugin({ manifest })],  // or omit and let `app` carry them
    components: { Tracker, Cart },          // registry key (__resumeId) → server component
});
// handleServerFnRequest(request, { fns, renderBoundaries })
```

`components` is **required** and explicit (never ambient) — the same posture as the server-function registry, since the key comes from the client. When a mutation server function declares `invalidates`, the endpoint admits a boundary whose recorded `useData` deps intersect it, re-renders each in an id-seeded isolated context, and returns fresh HTML + state in one response. The client half is automatic (`@sigx/resume/client` applies the fresh entries) — a never-hydrated boundary updates without loading its chunk.

Nothing throws outward: a boundary it can't honor (unknown key, unserializable props, a render throw) is silently omitted, and those reads converge through `@sigx/cache` invalidation instead.

---
url: https://sigx.dev/daisyui/docs/components/kbd/
title: Kbd
description: Kbd is used to display keyboard keys and shortcuts
---

# Kbd

Kbd is used to display keyboard keys and shortcuts.

## Import

```tsx
import { Kbd } from '@sigx/daisyui';
```

## Basic Usage

Display individual keyboard keys.

```tsx
import { component, render } from 'sigx';
import { Kbd, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" align="center">
            <Kbd>A</Kbd>
            <Kbd>B</Kbd>
            <Kbd>C</Kbd>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Sizes

Kbd supports five sizes: `xs`, `sm`, `md`, `lg`, and `xl`.

```tsx
import { component, render } from 'sigx';
import { Kbd, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="4" align="center">
            <Kbd size="xs">Xsmall</Kbd>
            <Kbd size="sm">Small</Kbd>
            <Kbd size="md">Medium</Kbd>
            <Kbd size="lg">Large</Kbd>
            <Kbd size="xl">Xlarge</Kbd>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Inline Context

Use Kbd inline with text.

```tsx
import { component, render } from 'sigx';
import { Kbd, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Text>Press <Kbd size="sm">F</Kbd> to pay respects.</Text>
    );
});

render(<Demo />, "#sandbox");
```

## Key Combinations

Display keyboard shortcuts with multiple keys.

```tsx
import { component, render } from 'sigx';
import { Kbd, Row, Col, Text } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="2">
            <Row align="center" gap="2">
                <Text class="w-24">Copy:</Text>
                <Kbd>Ctrl</Kbd>
                <Text>+</Text>
                <Kbd>C</Kbd>
            </Row>
            <Row align="center" gap="2">
                <Text class="w-24">Paste:</Text>
                <Kbd>Ctrl</Kbd>
                <Text>+</Text>
                <Kbd>V</Kbd>
            </Row>
            <Row align="center" gap="2">
                <Text class="w-24">Save:</Text>
                <Kbd>Ctrl</Kbd>
                <Text>+</Text>
                <Kbd>S</Kbd>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Function Keys

Display macOS-style modifier keys.

```tsx
import { component, render } from 'sigx';
import { Kbd, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Row gap="2" align="center">
            <Kbd>⌘</Kbd>
            <Kbd>⌥</Kbd>
            <Kbd>⇧</Kbd>
            <Kbd>⌃</Kbd>
        </Row>
    );
});

render(<Demo />, "#sandbox");
```

## Arrow Keys

Display arrow key layout.

```tsx
import { component, render } from 'sigx';
import { Kbd, Row, Col } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col align="center" gap="1">
            <Kbd>▲</Kbd>
            <Row gap="1">
                <Kbd>◀</Kbd>
                <Kbd>▼</Kbd>
                <Kbd>▶</Kbd>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Full Keyboard Layout

Display a full QWERTY keyboard row.

```tsx
import { component, render } from 'sigx';
import { Kbd, Col, Row } from '@sigx/daisyui';

const Demo = component(() => {
    return () => (
        <Col gap="1" align="center">
            <Row gap="1">
                <Kbd>q</Kbd>
                <Kbd>w</Kbd>
                <Kbd>e</Kbd>
                <Kbd>r</Kbd>
                <Kbd>t</Kbd>
                <Kbd>y</Kbd>
                <Kbd>u</Kbd>
                <Kbd>i</Kbd>
                <Kbd>o</Kbd>
                <Kbd>p</Kbd>
            </Row>
            <Row gap="1">
                <Kbd>a</Kbd>
                <Kbd>s</Kbd>
                <Kbd>d</Kbd>
                <Kbd>f</Kbd>
                <Kbd>g</Kbd>
                <Kbd>h</Kbd>
                <Kbd>j</Kbd>
                <Kbd>k</Kbd>
                <Kbd>l</Kbd>
            </Row>
            <Row gap="1">
                <Kbd>z</Kbd>
                <Kbd>x</Kbd>
                <Kbd>c</Kbd>
                <Kbd>v</Kbd>
                <Kbd>b</Kbd>
                <Kbd>n</Kbd>
                <Kbd>m</Kbd>
                <Kbd>/</Kbd>
            </Row>
        </Col>
    );
});

render(<Demo />, "#sandbox");
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | - | Key size |
| `class` | `string` | - | Additional CSS classes |

---
url: https://sigx.dev/deploy/packages/netlify/api/
title: API reference
description: API reference for @sigx/netlify — every export of the SignalX Netlify adapter.
---

# API reference

<p class="lede">Exports of `@sigx/netlify` .</p>

## netlify

Create the Netlify adapter for `sigx({ ssr: { adapter } })` — a fully bundled
function emitted through the Frameworks API
(`.netlify/v1/functions/sigx-ssr/`), with `preferStatic` catch-all routing.

```ts
function netlify(options?: NetlifyAdapterOptions): SigxAdapter

interface NetlifyAdapterOptions {
  /** Platform entry (project-relative), scaffolded iff absent. Default 'src/entry.netlify.ts'. */
  entry?: string;
}
```

See [Deploying to Netlify](/deploy/packages/netlify/deploying) for the
generated layout and routing policy.

---
url: https://sigx.dev/server/packages/server/usage/
title: Authoring
description: "serverFn's two forms, input validation, the request context, errors and streaming"
---

# Authoring server functions

A server function is created with `serverFn`. Its first parameter is always the
**request context** (`rq` by convention) — the framework passes it, callers
never do. Everything after it is your own typed arguments.

```ts
import { serverFn } from '@sigx/server';

export const greet = serverFn(async (rq, name: string) => {
  return `Hello, ${name}!`;
});

// client stub: greet(name: string): Promise<string>
```

## Where server functions live

There are two placement conventions. Both produce the identical runtime API —
the difference is only where the code sits and how the transform treats it.

### `*.server.ts` modules

Put a server function in a file whose name ends in `.server.ts` (or
`.server.tsx`) and the **whole module is server-only**. It may import database
clients, secrets and `node:` builtins freely. The client build swaps the module
for typed fetch stubs, so none of that reaches the browser; the server import is
the real module. You import from the same path on both sides:

```ts
// src/todos.server.ts
import { serverFn } from '@sigx/server';
import { db } from './db';

export const listTodos = serverFn(async (rq) => db.todos.all());
```

### Inline, co-located with a component

A **module-scope** `const x = serverFn(...)` may also sit directly in a
component file; the build lifts it out to the server. Co-location keeps a small
read next to the component that uses it.

```tsx
import { component, useData } from 'sigx';
import { serverFn } from '@sigx/server';

// lifted to the server; may reference its args, imports and server globals
const serverTime = serverFn((rq) => new Date().toISOString());

export const Clock = component(() => {
  const now = useData(() => ['server-time'], serverTime);
  return () => now.match({ ready: (t) => <p>Server time: {t}</p> });
});
```

Because an inline function is lifted away from its surroundings, its body may
reference only **its own parameters and locals, imports, and globals**.
Capturing component scope, signals, props, module-scope locals, JSX, or
type-only imports is a **build error**, not a silent bug — the transform tells
you at compile time. When a lifted function needs shared server code, import it
(from a `*.server.ts` module); don't close over it.

> There is no closure serialization anywhere. Data crosses the boundary only as
> the typed arguments you pass.

## Two authoring forms

`serverFn` accepts either an implementation directly, or an options object.

### Direct form

Pass the implementation. It takes the context plus any number of typed
arguments — zero ceremony, ideal for internal calls.

```ts
export const rename = serverFn(async (rq, id: string, title: string) => {
  return db.todos.rename(id, title);
});
```

The parameter types are **compile-time only**: the wire arguments are not
schema-validated and the argument count is not enforced at runtime. In
development, a direct-form function that receives wire input logs a one-time
warning — reported as the function receiving input it does not declare — a nudge to
move validation into the options form's `input` schema once a function is a real
client boundary. Use the direct form for trusted, app-internal
calls; reach for the options form (below) when a function is a validated boundary.

### Options form

Pass `{ input, authorize, handler, … }` for a validated, authorized boundary.
It takes exactly **one** input, described by a
[Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType, …) that
runs on every transport.

```ts
import { serverFn, principal, requireAuthenticated } from '@sigx/server';
import * as z from 'zod';

const QuoteInput = z.object({ symbol: z.string(), qty: z.number().int() });

export const quote = serverFn({
  input: QuoteInput,        // validated server-side on every call → 400 on failure
  authorize: requireAuthenticated,   // runs AFTER input validation, on every transport
  async handler(rq, input) {
    return priceQuote(principal(rq), input); // input is typed from the schema
  },
});
```

The input type `S` is inferred from `input`; if you omit `input`, it is inferred
from the `handler`'s parameter annotation. With neither, `S` is `void` and the
callable takes **no** arguments — you call it as `fn()`, not `fn(undefined)`.

`ServerFnOptions` fields:

| Field | Purpose |
|---|---|
| `input?` | A Standard Schema. Always validated server-side; a rejection becomes `ServerFnError(400, 'Invalid input', { issues })`. Also the source of the input type. |
| `authorize?` | A `ServerPolicy` or array of them — `(principal, rq, op) => boolean` — run **after** `input` validation on every transport (in-process SSR calls included). **Strict-`true` to allow**; anything else is a 403, or a 401 when the principal is null. |
| `handler` | The implementation: `(rq, input) => R \| Promise<R>`. |
| `invalidates?` | `(input, result) => InvalidatePattern[]` — keys to invalidate after the handler runs. **Declare it after `handler`** so TypeScript infers `result`. Patterns are key strings, tuple prefixes, or server-function references, and reach every matching read whether or not it carries a `cache` option. |
| `cache?` | Marks a side-effect-free GET read (`{ maxAge, staleWhileRevalidate?, public?, sMaxAge? }`) and emits `Cache-Control`. Mutually exclusive with `invalidates`. |
| `form?` | `true` marks a progressive-enhancement form target (accepts form-encoded bodies, does a 303 redirect). Must be the literal `true`, and **requires `input`** — a form target without an input schema is a definition-time error. Mutually exclusive with `cache`. The native `action` is stamped by the [resume](/server/packages/resume/usage) extractor, so the no-JS half needs a resume component; elsewhere the form still posts as RPC. |
| `id?` | An explicit, stable string id that pins the route across file moves/renames. |
| `allowAnonymous?` | The literal `true`, waiving the **identity gate** for a deliberately public endpoint. Middleware and authentication still run; declared policies still run, with a nullable principal. |

## The three stages

Every server function is a public endpoint reachable on every transport, and the
work of protecting one splits into three concerns with three different natural
scopes. Each has its own vocabulary:

| Stage | Where it lives | What it is for |
|---|---|---|
| **Middleware** | app-wide, `createServerApp({ middleware })` | cross-cutting work that always runs — logging, tracing, rate limiting, response headers. Never per-function disableable. |
| **Authentication** | app-wide, `createServerApp({ authenticate })` | deciding *who* the caller is, once. Produces the `Principal`. |
| **Authorization** | per function, `authorize:` (with an app-wide default) | deciding whether *this* caller may run *this* operation. |

They run in that order, and the identity gate closes **before** the wire payload
is revived:

```
middleware → authenticate → identity gate → reviveWire → input validation → authorize → handler
```

That ordering is load-bearing: an anonymous attacker's payload never reaches the
codec or the validator, and by the time a policy runs, `op.input` is the parsed,
trusted resource rather than raw wire data.

## The app

`createServerApp` is the one value that holds everything app-wide — the pipeline,
the endpoint posture, and the principal codec:

```ts
// src/server-app.ts
import { createServerApp, requireAuthenticated } from '@sigx/server';

export const app = createServerApp({
  middleware: [rateLimit, requestLog],
  authenticate: (rq) => sessionFrom(rq.request),
  authorize: requireAuthenticated,   // the default every fn inherits
  origin: 'verify-when-present',     // posture, stated once
  maxBodyBytes: 1_000_000,
  onError: (err, info) => report(err, info.name),
});
```

Point the Vite plugin at it and dev reloads it on edit:

```js
sigxServer({ serverApp: '/src/server-app.ts' })
```

The posture fields are inherited by every mount and by bare
`handleServerFnRequest` calls; an explicit per-call value wins. Mounts claim
their `base` namespace, and overlapping prefixes throw at **mount** time —
everything after the base *is* the symbol, so a partly-wrong base is worse than a
missing one.

**The config is frozen once stamped**, so the pipeline cannot be weakened in place
at runtime — reconfiguring means stamping a new app, and in tests it means
re-stamping through `stubServerApp`. See
[the frozen config](/server/packages/server/api#the-config-is-frozen-once-stamped).

## The runtime is fail-closed

A function that declares nothing, with no app configured, **denies with 401**.
There is no "ran open" state to forget your way into.

```ts
// Denies. There is no declaration and no app default.
export const health = serverFn(async () => 'ok');

// Deliberately public.
export const health = serverFn({
  allowAnonymous: true,
  handler: async () => 'ok',
});
```

`allowAnonymous` is a word rather than an omission on purpose: "I meant this to
be public" and "I forgot" must not look identical. It keeps the app's open
surface greppable — `grep -rn allowAnonymous --include='*.server.ts' src/` prints
every endpoint that deliberately waives identity.

It waives **only** the identity gate. Middleware and authentication still run for
these functions, which is the point — a rate limiter applies to your sign-in
endpoint, and a throwing authenticator surfaces there too. Declared policies
still run, with a nullable principal.

```ts
export const submitPat = serverFn({
  allowAnonymous: true,     // deliberate: this IS the sign-in
  form: true,
  input: PatSchema,
  handler: async (rq, pat) => exchangeToken(pat),
});
```

Because the runtime denies rather than trusting a static analysis, a `*.server.ts`
the build never analyzes is no longer a hole: an unanalyzed module denies instead
of running open.

## Writing a policy

A `ServerPolicy` is `(principal, rq, op) => boolean`, **strict-`true` to allow**:

```ts
// src/policies.ts
import type { ServerPolicy } from '@sigx/server';

export const requireStaff: ServerPolicy = (p) => p?.roles.includes('staff') === true;

// Because policies run after validation, op.input is trusted and typed.
export const ownsCart: ServerPolicy = (p, rq, op) =>
  p != null && (op.input as { cartId: string }).cartId.startsWith(`${p.id}:`);
```

Share **policies**, one imported identifier per function — there is no preset
factory to derive from, and the app default covers the common case:

```ts
// src/board.server.ts
import { requireStaff } from './policies';

export const boardIssues = serverFn({ input: BoardKey, authorize: requireStaff, handler });
export const feed = serverStream({ authorize: requireStaff, handler: async function* (rq) { … } });
```

Reading the identity anywhere on the request:

```ts
import { principal, requirePrincipal } from '@sigx/server';

principal(rq)         // Principal | null — memoized once per request store
requirePrincipal(rq)  // Principal — throws 401 when absent
```

`principal(rq)` is memoized per request, so one SSR render with five cells
decodes the session once.

### Rate limiting is middleware

Rate limiting is the clearest case for the middleware stage rather than a policy:
it is not about *who* the caller is or *what* they may do, it must run before the
body is read, and no function should be able to opt out of it.

```ts
// src/server-app.ts
import { createServerApp, ServerFnError, type ServerMiddleware } from '@sigx/server';

const rateLimit: ServerMiddleware = async (rq, fn) => {
  if (fn.transport !== 'wire') return;      // in-process SSR calls are not traffic
  const ip = rq.request.headers.get('cf-connecting-ip') ?? 'unknown';
  if (!(await bucket.take(ip, fn.name))) {
    throw new ServerFnError(429, 'Slow down');
  }
};

createServerApp({ middleware: [rateLimit], /* … */ });
```

`fn.transport` is the gate — an SSR render calling the same function in-process
is your own code, not inbound traffic. Do **not** infer this from `fn.symbol`;
`symbol` is pure identity, and `''` only ever means "no build stamp".

Because middleware runs for `allowAnonymous` functions too, this covers the
sign-in endpoint — the one that most needs it.

Pair it with `maxResponseBytes` for the other direction: a limiter bounds how
often a caller can ask, and `maxResponseBytes` bounds how much any one answer can
return.

## Migrating from 0.14

| 0.14 | 0.15 |
|---|---|
| `use: [guard]` | Authorization → `authorize: ServerPolicy \| ServerPolicy[]`. Cross-cutting work → app `middleware`. |
| `unguarded: true` | `allowAnonymous: true` — but middleware and authentication now run for it. |
| `serverFnPreset({ use })` / `preset.stream` | The app default (`createServerApp({ authorize })`), or one imported policy identifier per function. |
| endpoint `guard` option | App `middleware` — same pre-decode slot, and it reaches in-process calls too. Wire-only behaviour is `if (fn.transport !== 'wire') return`. |
| `info.symbol === ''` to detect in-process | `ServerFnInfo.transport`. `symbol` is pure identity; `''` only ever means "no build stamp". |
| a bare `serverFn({ handler })` ran open | It denies 401. Configure an app, or declare. |

The order change is the one to read twice: policies now run **after** `input`
validation, where the old guards ran before it. That is what makes authorizing on
the payload safe.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>`cache.public` without `allowAnonymous: true` now dev-warns</strong> —
    a shared-cache header over an authenticated response serves one caller's copy
    to the next.
  </div>
</div>

> **Note:** a spread inside a `serverFn({ ... })` options literal hides `id`,
> `cache`, `invalidates` and `form` from the static readers — which silently
> disables single-flight boundary refresh. The build warns about it.

## Per-request values

A value derived from the request — a decoded session, an authenticated API
client, a request id — usually needs to be shared by a guard, a handler, and
every other server function the same render calls. `perRequest(setup)` computes
it at most once per request and hands back the accessor:

```ts
// src/session.server.ts
import { perRequest, ServerFnError } from '@sigx/server';

export const session = perRequest(async (rq) =>
  decodeSession(rq.request.headers.get('cookie')));

export const github = perRequest(async (rq) => {
  const s = await session(rq);          // the SAME memoized promise
  if (!s) throw new ServerFnError(401, 'Sign in');
  return createGitHubClient(s.token);
});

// src/server-app.ts — authentication reads the same memoized promise
createServerApp({ authenticate: (rq) => session(rq), authorize: requireAuthenticated });

// src/board.server.ts
export const boardIssues = serverFn({
  input: BoardKey,
  handler: async (rq, key) => (await github(rq)).issues(key),  // no decode, no cast
});
```

Without this, a page with five SSR-enabled `useData` cells decodes the same
session five times — cookie parse, signature verify, database read, decrypt, per
call.

- **The accessor takes `rq`.** There is no ambient no-argument form; the context
  stays a parameter, which is the rule `rq` itself follows.
- **Values compose by calling each other.** There is no composition API.
- **The memoized promise is shared**, so a guard and a handler racing on first
  touch get one in-flight decode.
- **A failed setup stays failed for that request** — retrying a failed decode
  once per cell would be a footgun. A setup that resolves itself throws
  "circular request value".

`perRequest` and `rq.locals` are two faces of the same store, not two equals.
`rq.locals` is the untyped escape hatch, for a value too small or transient to
name. A per-request value is the recommended hand-off: it types itself from its
own setup, and the accessor is the only way to reach it, so there is nothing to
cast.

### Disposal

A setup's **second parameter registers teardown**:

```ts
const dbConn = perRequest(async (rq, onDispose) => {
  const conn = await pool.connect();
  onDispose(() => conn.release());
  return conn;
});
```

Disposers run **LIFO**, each awaited, and a throw is logged and swallowed so one
bad disposer cannot strand the rest. They run when the request is *really* over,
which is a different moment per path:

| Path | Disposes at |
|---|---|
| Endpoint call | the work promise's settle — **never** the `timeoutMs` race, so a 504 does not yank resources out from under a still-settling handler |
| `serverStream` | after the generator's `return()` settles, so a `finally` reading a per-request value never races its own teardown |
| Streamed edge response | **end of body**, via the `keepAlive(until)` seam the fetch handler calls with a body-settle promise |

That last row is why disposal could not exist before: on WinterCG runtimes the
render's scope settles at the shell, so "released once the response has flushed"
would have fired mid-stream. `keepAlive` is optional — an older package beside a
newer renderer degrades to the pre-disposal behaviour rather than breaking.

Ownership is claim-based per store: the endpoint first, then the outermost scope
entry. A `fn.with({ context })` or otherwise detached store has **no owner** and
dev-warns; call **`disposeRequestValues(rq)`** yourself to trigger teardown there.

Where `AsyncLocalStorage` is unavailable — workerd without `nodejs_compat` —
there is no scope to share, so a value is computed per invocation. The guards
and handler of one call still share it; nothing throws and nothing splits.

With `.with({ context })`, passing the **same** `{ request, locals }` object
shares one store across explicit calls. A fresh `Request` per call is its own
store, which is how a test isolates calls.

## The request context

The first parameter carries everything about the current request:

```ts
interface ServerFnContext {
  request: Request;         // the WinterCG request — headers, cookies, method
  url: URL;                 // the parsed request URL
  abortSignal: AbortSignal; // fires when the client disconnects
  responseHeaders: Headers; // mutable — set cookies/headers on the response
  status(code: number): void; // override the success status code
  locals: Record<string, unknown>; // guard → handler hand-off (e.g. the auth result)
}
```

Pass `rq.abortSignal` straight to any `fetch` you make so upstream work is
cancelled when the caller goes away:

```ts
export const search = serverFn(async (rq, q: string) => {
  const res = await fetch(`https://api.example.com/search?q=${q}`, {
    signal: rq.abortSignal,
  });
  return res.json();
});
```

### Calling a server function during SSR

When a server function runs **in-process** during server rendering (rather than
over HTTP), there is no incoming HTTP request to expose, so the default context
is *detached*: reading `rq.request` or `rq.url` throws a descriptive error.
Supply a request when you need one:

- **Per call** — `await getCart.with({ context: request })(cartId)`. Works on
  every runtime; `.with({ context })` takes a `Request` or a partial
  `ServerFnContext`.
- **Ambient** — wrap a region in `runWithServerFnContext(request, () => …)` from
  `@sigx/server/node` (backed by `AsyncLocalStorage`). The Node and edge request
  handlers already open this scope, so most apps get an ambient context for free
  and never call either API.

The ambient form also takes a source object, which is how you pre-seed a render:

```ts
runWithServerFnContext({ request, locals: { user } }, () => renderHandler(…));
```

Nested scopes for the **same request** merge rather than replace, so the seed
survives the inner scope a document handler opens with the raw request: the
inner source's fields win where it supplies them, and the enclosing `locals`
stays the request's store. "Same request" means same URL and method — protocol
is excluded, so a TLS-terminating proxy doesn't split one request in two.

A source naming no request always merges, which makes
`runWithServerFnContext({ locals }, …)` the simplest pre-seed. A genuinely
different request gets its own store, plus a once-per-process development notice
naming both. To isolate a nested render deliberately, hand it its own `locals`.

## Cacheable reads

By default every call is a `POST`. Declaring `cache` marks a function a
**side-effect-free idempotent read**: the stub issues `GET` with the arguments in
the query string, and the endpoint emits `Cache-Control`, so browser and edge
caches can absorb the traffic before it reaches your server.

```ts
export const listProducts = serverFn({
  id: 'catalog',
  input: z.object({ category: z.string() }),
  allowAnonymous: true,
  cache: { maxAge: 60, staleWhileRevalidate: 300, public: true },
  handler: async (rq, { category }) => db.products.byCategory(category),
});
```

```ts
interface ServerFnReadCache {
  maxAge: number;                  // seconds fresh in HTTP caches. No default — you choose.
  staleWhileRevalidate?: number;   // seconds a stale answer may still be served
  public?: boolean;                // opt into SHARED caches
  sMaxAge?: number;                // shared-cache TTL; defaults to maxAge
}
```

The emitted header follows directly from the declaration:

| Declaration | `Cache-Control` |
|---|---|
| `{ maxAge: 60 }` | `private, max-age=60` — plus `Vary: Cookie` |
| `{ maxAge: 60, staleWhileRevalidate: 300 }` | `private, max-age=60, stale-while-revalidate=300` |
| `{ maxAge: 60, public: true }` | `public, max-age=60, s-maxage=60` |
| `{ maxAge: 60, public: true, sMaxAge: 600 }` | `public, max-age=60, s-maxage=600` |

`POST` stays valid for a cache-marked function — the GET is what makes it
*cacheable*, not the only way to call it.

### The two promises you are making

**`cache` asserts the function does not mutate.** A GET read drops the JSON
content-type CSRF gate, so marking a mutating function `cache` re-opens CSRF
completely. Nothing checks this for you; it is the author's promise.

**`public: true` asserts the output depends only on the arguments** — never
cookies, never auth, never a request header. A shared cache will serve one user's
response to another. Without it, the endpoint emits `private` and appends
`Vary: Cookie`.

`cache` with [`invalidates`](#options-form) is a **definition-time error** — a
read that invalidates is not a read. So is `cache` with `form: true`; a form
target is a mutation. Both throw where the function is defined rather than
silently preferring one, so the contradiction cannot reach a deploy.

Bypass the HTTP cache for a single call with
[`.with({ fresh: true })`](#per-call-options).

> **`cache` is the HTTP layer.** `@sigx/cache`'s `staleTime` is the in-app layer,
> and the two compose: `cache` decides what a browser or CDN may reuse without
> asking, `staleTime` decides when a mounted read refetches.

### What the GET looks like

When every argument is a simple scalar, a cache-marked read rides as **named
params** rather than an encoded blob:

```
GET /_sigx/fn/catalog/listProducts?a0=shoes
```

Types survive because a param reads back as a number, `true`, `false` or `null`
only when its raw text says so. A *string* that would otherwise be misread is
JSON-quoted — `?a0="42"` — which is the only escape a scalar read can still
produce.

Anything richer (objects, `Date`, `Map`, `Set`, `BigInt`) falls back to the
`?args=` blob for the **whole** call, never a mix, so the cache key stays a pure
function of the arguments. Mixing the two explicitly, or leaving a gap in the
`a0, a1, …` sequence, is a `400` rather than a call with silently shifted
arguments.

Long argument lists are the one operational limit — the query string is capped at
`maxUrlBytes` (default 8 KiB) and answered with a `414` past it.

## Zero-JS form actions

`form: true` marks a function a **form target**. A `<form>` whose submit handler
calls it gets a real `action` and `method="post"` stamped in at build time, so the
form works before — and without — JavaScript. With JS, the same function runs as
ordinary RPC. One function, one validator, two transports.

```ts
export const submitFeedback = serverFn({
  form: true,                 // must be the literal `true`
  input: z.object({
    email: z.string().email(),
    rating: z.coerce.number().int().min(1).max(5),
    message: z.string().min(1),
  }),
  allowAnonymous: true,
  handler: async (rq, feedback) => db.feedback.add(feedback),
});
```

`input` is **required** — a form target without one is a definition-time error.
Form fields are attacker-typable strings, and the validator is the only thing
between them and your handler.

### FormData becomes your input

The body is normalized into the function's single input as a **flat object**:

| In the form | In your input |
|---|---|
| One field named `email` | `email: string` |
| Repeated fields named `tag` | `tag: string[]` |
| `<input type="file">` | the `File`, passed through |
| Anything else | still a **string** |

Values stay strings because that is what the platform gives you — Standard Schema
coercion is the mapping tool, which is why `z.coerce.number()` appears above and a
bare `z.number()` would reject every submission. Prototype-polluting field names
are dropped, the same posture the JSON reviver takes.

### The round trip

A successful no-JS submit answers **303 See Other**, so a reload doesn't resubmit.
The redirect target is, in order:

1. a `Location` your handler set on `rq.responseHeaders`;
2. the request's `Referer` — **only if same-origin**, and only its path and query;
3. `/`.

An attacker-controlled `Referer` must never become an open redirect, which is why
step 2 is same-origin-only. A handler that sets its own status via `rq.status()`
is honoured verbatim, with no default `Location` added.

A validation failure without JS renders a minimal HTML page — in production a
plain "please go back and correct it", in development the actual issues. It is a
backstop, not a UX: native HTML validation (`required`, `type="email"`,
`pattern=`) is the first line, because it never round-trips at all.

### Security: what you are giving up

A declared form target **deliberately drops the JSON content-type CSRF layer** —
it has to, because a native form cannot send `application/json`. Everything else
stays at full strength:

- The **Origin check stays on**. An Origin-less form POST is `403` under every
  policy short of `origin: false` — including `'verify-when-present'`, which
  relaxes the check for JSON callers but not for forms.
- `input` is mandatory, so the validator always runs.
- Only `origin: false` — the explicit public-endpoint escape hatch — **reopens
  classic CSRF** on a form target. Don't, unless it is genuinely public.

`'verify-when-present'` used to admit Origin-less form posts, and that quietly
reopened CSRF: the relaxation's safety rests on the JSON content-type gate, which
a form target deliberately gives up. It no longer does. Form posts carrying a
matching `Origin`, and the whole JSON path, are unaffected.

`form` with `cache` is a definition-time error — a form target is a mutation.

### When stamping happens

The `action` is stamped by the [resume](/server/packages/resume/usage) extractor,
so it reaches only files matching `sigxResume()`'s `include` and only components
that extract in **resume** mode. The rules and their edges:

- Exactly **one** form-marked capture per `<form>`.
- An `action`/`method` you wrote by hand **wins** — stamping never overwrites it.
- `role: 'client'` builds and hydrate-mode components never stamp.
- A form-target import via a bare specifier does not stamp.

A `<form>` outside those rules still submits through the server function as RPC
once its component is running. It just has no native fallback before then — and
the build warns when a `form: true` form will never be stamped, so this is
visible rather than silent.

## Per-call options

Every wrapped function carries a `.with(options)` channel that returns the same
callable with those options bound. It is a **separate** channel on purpose: your
arguments stay exactly your arguments, with no trailing-options parameter for the
transport to sniff.

```ts
const cart = await getCart.with({ signal: controller.signal })(cartId);
```

```ts
interface ServerFnCallOptions {
  signal?: AbortSignal;
  headers?: Record<string, string>;
  fresh?: boolean;
  context?: Request | Partial<ServerFnContext>;
}
```

| Option | Where it applies | Effect |
|---|---|---|
| `signal` | Everywhere | Aborts the in-flight call. On the client the `fetch` is aborted; on an in-process (SSR) call it becomes `rq.abortSignal`. |
| `headers` | **Client transport only** | One-off request headers for this call, merged over `configureServerFn`'s transport headers — the per-call value wins. `content-type` is never overridable (stripped case-insensitively; the endpoint 415s anything else). |
| `fresh` | **Client transport only**, cache-marked GET reads | Sets `cache: 'no-cache'` on the fetch, so the browser revalidates with the origin instead of answering from `max-age`. |
| `context` | **In-process (SSR) only** | The request this call should see — see [Calling a server function during SSR](#calling-a-server-function-during-ssr) above. Wins over the ambient `runWithServerFnContext` scope. |

The two "client only" options are no-ops in-process, and `context` is a no-op on
the client — each warns in development rather than failing, because the same code
legitimately runs on both sides. The mirror is deliberate: an in-process call
makes no HTTP request, so there are no headers to send and no cache to bypass; a
client stub's context *is* the request it makes, and silently accepting one there
would imply it travelled.

`fresh` is meaningless on a POST, which is never HTTP-cached, so it is a
dev-warned no-op there too.

**Streams take the same channel minus `fresh`.** A `serverStream` is always POST
and therefore never answered from an HTTP cache, so `ServerStreamCallOptions`
omits the option entirely — using it is a compile error rather than a silent
no-op:

```ts
for await (const line of tailLog.with({ signal, headers: { 'x-trace': id } })(jobId)) {
  console.log(line);
}
```

## Errors

Throw `ServerFnError` to send a typed, client-visible failure. It crosses the
wire verbatim as `{ status, message, data? }`:

```ts
import { serverFn, ServerFnError, isServerFnError } from '@sigx/server';

export const publish = serverFn(async (rq, id: string) => {
  const post = await db.posts.find(id);
  if (!post) throw new ServerFnError(404, 'No such post');
  if (post.locked) throw new ServerFnError(409, 'Post is locked', { id });
  return db.posts.publish(id);
});
```

```tsx
try {
  await publish(id);
} catch (err) {
  if (isServerFnError(err) && err.status === 409) {
    // err.message and err.data are the values thrown on the server
  }
}
```

Every **other** thrown error is masked: in production the client sees a generic
500, and the original never fires the app's `onError`. `ServerFnError` is the
deliberate channel for failures the caller is meant to handle.

## Streaming

`serverStream` returns values over time. The implementation is an async
generator; the client stub is an `AsyncIterable` you can `for await` over, and a
string stream drops straight into [`useStream`](/core/docs/data-loading):

```ts
// src/chat.server.ts
import { serverStream } from '@sigx/server';

export const streamReply = serverStream(async function* (rq, prompt: string) {
  const completion = await llm.stream(prompt, { signal: rq.abortSignal });
  for await (const token of completion) yield token; // sent as NDJSON
});
```

```tsx
const reply = useStream(() => ['reply', prompt], streamReply);
return () => <p>{reply.text}</p>;
```

Streams are lazy — the request starts on the first iteration, and a consumer
that `break`s or returns early aborts the fetch and runs the generator's
`finally`. Response status and headers freeze at the first `yield`.

`serverStream` has the same two authoring forms as `serverFn`. The options form
carries `authorize`, `allowAnonymous` and `handler`:

```ts
export const feed = serverStream({
  authorize: requireAuthenticated,
  async *handler(rq, room: string) {
    for await (const msg of subscribe(room, rq.abortSignal)) yield msg;
  },
});
```

### Declaring an input

Adding `input` selects a single-input form, shaped exactly like `serverFn`'s:

```ts
export const feed = serverStream({
  input: z.object({ room: z.string(), since: z.coerce.number().optional() }),
  authorize: requireAuthenticated,
  async *handler(rq, { room, since }) {
    for await (const msg of subscribe(room, since, rq.abortSignal)) yield msg;
  },
});
```

The schema runs after the policies and **before the first chunk**, on every
transport. Over the wire a rejection is a buffered JSON `400 { issues }` — headers
are still writable and no stream byte has been sent; in-process it rejects on the
first pull. With `input` declared the stream takes exactly **one** argument, extra
wire args are a 400, and the handler receives the validated value rather than the
raw wire arg.

Omitting `input` never falls back to the handler's annotation — no `input` means
the multi-argument form above.

An authorization denial surfaces on the **first pull** rather than at the call,
which is where the wire path's pre-first-yield errors surface too. Streams run the
same pipeline in-process during SSR as they do over the wire.

## Next steps

- [Deployment & security](/server/packages/server/deployment) — serve the endpoint in dev,
  Node and edge runtimes, and the security defaults you're getting.
- [Native clients](/server/packages/server/native-clients) — pointing a lynx or
  terminal app's stubs at a remote backend.
- [Data Loading](/core/docs/data-loading) — `useData` / `useAction` / `useStream`,
  the value-first primitives server functions feed.

---
url: https://sigx.dev/core/docs/advanced/globals/
title: Globals on the page
description: The __SIGX_* names a sigx page defines — which are visible and why, what lands in the data cache, and the rule for a pack stamping its own seam
---

# Globals on the page

<p class="lede">Open devtools on a sigx page and a handful of `__SIGX_*` names are there. This
is what each one is, which of them you are meant to see, and the one thing worth knowing
before you put a secret behind a `useData` key.</p>

Every SSR framework puts state on a global, because the server has to hand the browser
something and `window` is the channel — Next.js ships `__NEXT_DATA__` and `self.__next_f`,
Nuxt has `__NUXT__`, SvelteKit one hashed name, Solid `_$HY`. So the question is not whether
to have them. It is which ones a person opening a console should ever see.

## Two classes

**Wire seams are enumerable.** They are the page's data cache and streaming bootstrap — the
things you might legitimately want to inspect — and the server writes them with a plain
assignment from an emitted `<script>`, so their descriptor is not ours to choose without
changing what goes over the wire.

| Global | What it is |
|---|---|
| `__SIGX_ASYNC__` | the page's data cache: `key → value` for everything [`useData`](/core/docs/data-loading) and `useAsync` resolved, encoded by [`@sigx/serialize`](/server/packages/serialize/overview). Every mount of the same key restores from it, including after client-side navigation. |
| `__SIGX_BOUNDARIES__` | `id → SSRBoundaryRecord` — per-boundary props and signal snapshots, for selective hydration and [resume](/server/packages/resume/overview). |
| `__SIGX_STREAMING_COMPLETE__` | `true` once the document has finished streaming. It is set alongside a `sigx:ready` event on `window`, and **the event is the half most apps should use** — the flag is for code that starts running after it already fired. |
| `$SIGX_REPLACE` | `(id, html) => void` — swaps a resolved async boundary's placeholder for its HTML, then dispatches a bubbling `sigx:async-ready` event. |
| `$SIGX_APPEND` | `(id, text) => void` — appends a streamed `useStream` text token into its placeholder. |

**Control seams are non-enumerable.** Everything else. These are pack-to-pack wiring stamped
by JavaScript at runtime — the server-app config, the serverFn codec and scope, the type
handlers, the devtools hook. Nobody reads them off `globalThis` by hand, so they are kept out
of `Object.keys(globalThis)` and console completion.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Non-enumerable is not a security boundary.</strong> Anything running on the page
    can still read a hidden property by name. The point is surface area and legibility, not
    access control.
  </div>
</div>

## What the page exposes is yours, and unfiltered

This is the part worth reading twice.

Whatever your fetcher returns lands **verbatim** in `__SIGX_ASYNC__` under its key, and a
claimed component's props and signals land in `__SIGX_BOUNDARIES__[id]`. Boundary records
additionally carry canonical cache-key strings in `deps`, which can identify a user
(`user:42`) even when the value itself does not.

The renderer applies **key-safety and serializability checks, and no sensitivity filter**. So:

```ts
// Everything this returns is readable from the console.
const account = useData('billing', () => getAccount(userId));
```

A secret fetched under a `useData` key is one `window.__SIGX_ASYNC__` away. Fetch it in a
[server function](/server/packages/server/overview) the client calls when it needs it, or
return only the fields the page actually renders.

Nothing the framework itself owns goes there. The principal lives on `rq.locals` under a
non-enumerable `Symbol.for` slot that no serializer walks, and `@sigx/server-renderer`
performs no `globalThis` writes at all.

## Stamping a seam from your own pack

Plain assignment works and stays hidden:

```ts
globalThis.__SIGX_MY_PACK__ = value;
```

An assignment to an existing writable data property **inherits its descriptor**, so a seam
another pack already defined non-enumerably stays that way. To define a fresh one, match the
convention:

```ts
Object.defineProperty(globalThis, '__SIGX_MY_PACK__', {
    value,
    writable: true,      // last-wins re-stamping
    configurable: true,  // so a dispose() path can delete it
});
```

A *new* property defined this way is non-enumerable by default, which is the behaviour you
want — spell `enumerable: false` only when you may be overwriting a property that an older
module copy created by assignment during HMR.

Reach for one global accessor module per seam rather than touching `globalThis` from several
places; that is the rule the framework holds itself to, and it is why each of these has
exactly one writer.

## Next steps

- [Data loading](/core/docs/data-loading) — what fills `__SIGX_ASYNC__`.
- [`@sigx/server`](/server/packages/server/api#the-config-is-frozen-once-stamped) — the
  server-app control seam and why its config is frozen.
- [Hydration](/server/packages/server-renderer/hydration) — how the boundary table is read.

---
url: https://sigx.dev/deploy/packages/vercel/api/
title: API reference
description: API reference for @sigx/vercel — every export of the SignalX Vercel adapter.
---

# API reference

<p class="lede">Exports of `@sigx/vercel` .</p>

## vercel

Create the Vercel adapter for `sigx({ ssr: { adapter } })` — a fully bundled
function plus complete `.vercel/output` (Build Output API v3) generation on
every build.

```ts
function vercel(options?: VercelAdapterOptions): SigxAdapter

interface VercelAdapterOptions {
  /**
   * 'node' (default — Vercel's current guidance; Fluid compute) | 'edge'.
   * Edge resolves the edge-light/worker conditions and wraps your entry in
   * the bare-default-function edge contract.
   */
  runtime?: 'node' | 'edge';

  /** Platform entry (project-relative), scaffolded iff absent. Default 'src/entry.vercel.ts'. */
  entry?: string;

  /** .vc-config.json runtime string for the node runtime. Default 'nodejs22.x'. */
  nodeVersion?: string;
}
```

See [Deploying to Vercel](/deploy/packages/vercel/deploying) for the generated
layout and the load-bearing `{ fetch }` entry shape.

---
url: https://sigx.dev/server/packages/resume/api/
title: API reference
description: Resume — resumePlugin, the resume manifest, and createBoundaryRefresh
---

# API reference

<p class="lede">Exports of `@sigx/resume` , by entry point.</p>

## Entry points

| Subpath | Purpose |
|---|---|
| `@sigx/resume` | `resumePlugin` + the resume types. |
| `@sigx/resume/server` | WinterCG-clean server surface — `createBoundaryRefresh`, signal-state capture. |
| `@sigx/resume/client` | The scope-resume / upgrade-on-write runtime (lazy-loaded on first interaction). |
| `@sigx/resume/loader` | The delegation loader — the page's only script. |

Apps usually import only `@sigx/resume` (and `@sigx/resume/server` for boundary refresh); the client and loader entries are wired up by the generated `virtual:sigx-resume/entry`.

## resumePlugin

```ts
function resumePlugin(options?: ResumePluginOptions): SSRPack;

interface ResumePluginOptions {
  manifest?: ResumeManifest;
}
```

Install on the app: `app.use(resumePlugin({ manifest }))`. On the server it records resume-stamped components as boundaries with `hydrate: 'never'` (the pack's delegation owns all waking) and declines any usage site carrying a `client:*` directive (that belongs to [islands](/server/packages/ssr-islands/overview)). Pass `resumeManifest` from `virtual:sigx-manifests` as the manifest (`undefined` under dev).

```ts
interface ResumeManifest {
  components: Record<string, ResumeChunkRef>;  // __resumeId → upgrade chunk
  handlers: Record<string, ResumeChunkRef>;    // QRL symbol → handler chunk
}
interface ResumeChunkRef { chunkUrl: string; exportName: string; }
```

## createBoundaryRefresh

From `@sigx/resume/server`. Builds the function that re-renders admitted boundaries for a mutation — hand its result to your server-function request handler as `renderBoundaries`.

```ts
function createBoundaryRefresh(options: BoundaryRefreshOptions): (
  requests: ReadonlyArray<BoundaryRefreshRequest>,
  base: number,
  rq?: unknown,
) => Promise<BoundaryRefreshEntry[]>;

interface BoundaryRefreshOptions {
  plugins?: SSRPlugin[];                     // SSR plugins the re-render runs with (resumePlugin at least)
  components: Record<string, unknown>;       // REQUIRED — __resumeId → server component (factory or lazy loader)
  app?: (rq?: unknown) => App | Promise<App>; // per-call app for DI (type handlers, provides)
}
```

- `components` is **required** and explicit — own-property lookup only (the key is attacker-controlled).
- `plugins` may be omitted when `app` carries them.
- The returned function floors the component-id counter at the client-chosen `base` to avoid marker collisions.

```ts
interface BoundaryRefreshRequest { id: number; component: string; deps?: string[]; props?: Record<string, unknown>; }
interface BoundaryRefreshEntry { for: number; id: number; html: string; state?: Record<string, unknown>; records: Record<number, unknown>; }
```

`state` / `records` and the request `props` are encoded with [`@sigx/serialize`](/server/packages/serialize/overview). Failure is silent by design: a descriptor it can't honor (unknown key, unserializable props, a render throw) is omitted — the mutation already succeeded, and those reads converge through `@sigx/cache` invalidation.

## Vite

The `sigxResume()` plugin from `@sigx/vite/resume` runs the transform and emits `.vite/sigx-resume-manifest.json`, surfaced as `resumeManifest` from `virtual:sigx-manifests`.

---
url: https://sigx.dev/terminal/packages/args/api/
title: API reference
description: API reference for @sigx/args — every export of the SignalX Terminal Args package.
---

# API reference

<p class="lede">Exports of `@sigx/args` .</p>

## Exports

| Export | What it is |
| --- | --- |
| `command(name)` | Start a fluent command chain — `.describe()` / `.version()` / `.aliases()` / `.hidden()` / `.allowUnknownFlags()` / `.args()` / `.subcommands()` / `.run()`. See [the command chain](/terminal/packages/args/overview/#the-command-chain). |
| `a` | The arg-builder namespace: `a.string()`, `a.number()`, `a.boolean()`, `a.enum([...])`, `a.positional()`, `a.rest()`, refined with `.required()` / `.default()` / `.multiple()` / `.alias()` / `.negatable()` / `.describe()` / `.valueHint()` / `.hidden()`. See [arg builders](/terminal/packages/args/overview/#arg-builders) and [refiners](/terminal/packages/args/overview/#refiners). |
| `runMain(cmd, opts?)` | Parse `process.argv`, run the matched handler, print errors/help and set `process.exitCode`. See [embedding](/terminal/packages/args/overview/#embedding). |
| `runCommand(cmd, opts)` | Like `runMain` but **throws** instead of printing — for hosts that render errors themselves. |
| `parseArgs(argv, shape)` | Headless parsing against a record of builders, no command needed. See [headless parsing](/terminal/packages/args/overview/#headless-parsing). |
| `buildHelpCatalog(cmd)` / `renderHelp(catalog)` | The structured `HelpCatalog` model plus the plain-text renderer. See [headless help catalog](/terminal/packages/args/overview/#headless-help-catalog). |
| `ParseError` / `DefinitionError` | Typed errors with machine-readable `code` + structured `detail`. See [errors](/terminal/packages/args/overview/#errors). |

The companion types `AnyArg`, `ArgsShape` and `InferArgs` are exported alongside the
builders. See the package source for the complete typed surface.

---
url: https://sigx.dev/server/packages/server/api/
title: API reference
description: Server Functions — serverFn, serverStream, ServerFnContext and errors
---

# API reference

<p class="lede">Exports of `@sigx/server` . See [Authoring](/server/packages/server/usage) for the guide and [Deployment & security](/server/packages/server/deployment) for the runtime wiring.</p>

## Authoring (main entry)

```ts
import { serverFn, serverStream, ServerFnError, isServerFnError } from '@sigx/server';
```

### serverFn

```ts
// direct form — context + typed args
function serverFn<A extends unknown[], R>(
  impl: (rq: ServerFnContext, ...args: A) => R | Promise<R>
): ServerFnCallable<A, Awaited<R>>;

// options form — one validated input
function serverFn<S = void, R = unknown>(
  options: ServerFnOptions<S, R>
): ServerFnCallable<[S] extends [void] ? [] : [S], Awaited<R>>;
```

The client stub is `(...args) => Promise<R>` — the context is server-only and never passed by callers. `ServerFnOptions` carries `input` (a Standard Schema), `authorize` (policies), `allowAnonymous`, `handler`, `invalidates`, `cache`, `form` and `id` — see [Authoring](/server/packages/server/usage#options-form).

### createServerApp

```ts
function createServerApp(config: ServerAppConfig): ServerApp;

interface ServerAppConfig {
  middleware?: ServerMiddleware[];       // always runs, every transport, pre-decode
  authenticate?: (rq: ServerFnContext) => Principal | null | Promise<Principal | null>;
  authorize?: ServerPolicy | ServerPolicy[];   // the app-wide default
  codec?: PrincipalCodec;                // cross-hop propagation (@sigx/actors)
  origin?: OriginPolicy;                 // ─┐
  maxBodyBytes?: number;                 //  │ endpoint posture, stated once and
  maxUrlBytes?: number;                  //  │ inherited by every mount and by
  maxResponseBytes?: number;             //  │ bare handleServerFnRequest calls;
  timeoutMs?: number;                    //  │ an explicit per-call value wins
  onError?: (err: unknown, info: ServerFnInfo) => void;  // ─┘
  authorizeBoundary?: (d: BoundaryDescriptor, rq: ServerFnContext) => boolean;
}

interface ServerApp {
  serverFns(mount?: ServerFnRequestOptions): (request: Request) => Promise<Response>;
  dispose(): void;
}
```

The one user-owned value holding everything app-wide. `app.serverFns(mount)` returns a plain handler bound to the app — routing stays in the platform entry, and `matchesServerFn` is still the predicate. The app decides what every operation passes *through*, never which handler answers a URL.

Mounts claim their `base` namespace: overlapping prefixes **throw at mount time**, because everything after the base *is* the symbol. Stamping the `__SIGX_SERVER_APP__` seam is last-wins, and `dispose()` releases it only if it still holds this app's stamp.

#### The config is frozen once stamped

`__SIGX_SERVER_APP__` is the fail-closed control seam — `middleware`, `authenticate`, `authorize`, posture and `codec`. Stamping freezes the config object, so swapping a member in place throws:

```ts
globalThis.__SIGX_SERVER_APP__.authorize = () => true;   // TypeError
```

This applies to the object you pass `createServerApp` and to the one you pass [`stubServerApp`](#testing) alike; `resolveServerAppConfig()` likewise returns a frozen object.

The freeze is **shallow**, so `claimedBases` still accepts `push` and mounting is unaffected.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Upgrading from 0.15.2 or earlier?</strong> Mutating a member used to warn nothing
    and silently fail <em>open</em> — an authorization bypass — which is why the throw shipped
    in a patch. The pattern that breaks is a test suite that stamps once and then swaps
    <code>authorize</code> or <code>authenticate</code> between cases. Re-stamp through
    <code>stubServerApp</code> instead; see <a href="#testing">Testing</a>.
  </div>
</div>

### ServerPolicy

```ts
type ServerPolicy = (principal: Principal | null, rq: ServerFnContext, op: ServerOp) => boolean;

function principal(rq: ServerFnContext): Principal | null;    // memoized per request
function requirePrincipal(rq: ServerFnContext): Principal;    // throws 401 when absent
function setPrincipal(rq: ServerFnContext, p: Principal | null): void;

const requireAuthenticated: ServerPolicy;                     // the built-in default
```

**Strict-`true` to allow** — any other return is a 403, or a 401 when the principal is null. Policies run **after** `input` validation, so `op.input` is the trusted, parsed resource. (The old `use:` guards ran *before* validation, which is why they could never safely authorize on the payload.)

`principal(rq)` is memoized once per request store, so one SSR render with five cells decodes the session once.

### perRequest

```ts
function perRequest<T>(
  setup: (rq: ServerFnContext, onDispose: (fn: () => void | Promise<void>) => void) => T
): (rq: ServerFnContext) => T;

function disposeRequestValues(rq: ServerFnContext): Promise<void>;
```

Declares a value derived from the request and computed at most once per request, shared by every middleware, policy, handler and nested in-process call in that flow. Returns the accessor, which is the only way to reach the value; values compose by calling each other. A rejected setup stays rejected for the request.

The setup's second parameter registers teardown. Disposers run LIFO, each awaited, throws logged and swallowed. Ownership is claim-based per store — the endpoint first, then the outermost scope entry; a detached store (`fn.with({ context })`) has no owner, dev-warns, and is the app's job to tear down via `disposeRequestValues(rq)`. See [Per-request values](/server/packages/server/usage#per-request-values).

### serverStream

```ts
function serverStream<A extends unknown[], T>(
  impl: (rq: ServerFnContext, ...args: A) => AsyncGenerator<T>
): ((...args: A) => AsyncIterable<T>) & WrappedServerFn;

function serverStream<A extends unknown[], T>(
  options: ServerStreamOptions<A, T>
): ((...args: A) => AsyncIterable<T>) & WrappedServerFn;

// multi-argument options form
interface ServerStreamOptions<A extends unknown[], T> {
  authorize?: ServerPolicy | ServerPolicy[];
  allowAnonymous?: true;
  handler(rq: ServerFnContext, ...args: A): AsyncGenerator<T>;
}

// single-input options form — selected by declaring `input`
interface ServerStreamInputOptions<S, T> {
  input: StandardSchemaV1<S>;
  authorize?: ServerPolicy | ServerPolicy[];
  allowAnonymous?: true;
  handler(rq: ServerFnContext, input: S): AsyncGenerator<T>;
}
```

Streams yield as NDJSON; a string stream plugs into [`useStream`](/core/docs/data-loading). An authorization denial surfaces on the first pull.

**Declaring `input` selects the single-input form.** Any Standard Schema works (Zod, Valibot, ArkType). The schema runs after the policies and **before the first chunk**, on every transport:

- Over the wire a rejection is a buffered JSON `400 { issues }` — headers are still writable and no stream byte has been sent.
- In-process it rejects on the first pull, exactly where an authorization denial surfaces.
- The stream then takes **one** argument; extra wire args are a 400, and the *validated* value (not the raw wire arg) reaches the handler.

Omitting `input` never falls back to the handler's annotation — no `input` means the multi-argument form.

### Per-call options

Every wrapped callable carries `.with(options)`, returning the same signature with
those options bound.

```ts
type ServerFnCallable<A extends unknown[], R> = ((...args: A) => Promise<R>) & {
  with(options?: ServerFnCallOptions): (...args: A) => Promise<R>;
  /** The build-stamped stable data key, `<stableId>#<name>`. */
  __sigxKey: string;
} & WrappedServerFn;

interface ServerFnCallOptions {
  /** Aborts the call — the client fetch, or `rq.abortSignal` in-process. */
  signal?: AbortSignal;
  /** Client transport only. Merged over the transport headers; `content-type` is not overridable. */
  headers?: Record<string, string>;
  /** Client transport only, cache-marked GET reads. Sets `cache: 'no-cache'` on the fetch. */
  fresh?: boolean;
  /** In-process (SSR) only. The request this call should see; beats the ambient scope. */
  context?: Request | Partial<ServerFnContext>;
}

/** A stream's channel — the same, minus `fresh` (a stream is never HTTP-cached). */
type ServerStreamCallOptions = Omit<ServerFnCallOptions, 'fresh'>;
```

Options that do not apply to the current transport are dev-warned no-ops, not
errors — see [Per-call options](/server/packages/server/usage#per-call-options).

### configureServerFn

```ts
function configureServerFn(config: ServerFnTransport | null): void;

interface ServerFnTransport {
  /** Absolute URL or path prefix; wins over the build-time endpoint. */
  endpoint?: string;
  /** Static map, or a (possibly async) factory called per request. */
  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
  /** Fetch implementation; defaults to the global fetch. */
  fetch?: typeof globalThis.fetch;
}
```

From `@sigx/server/client`. Sets the transport every stub resolves at **call**
time, so one build serves dev, staging and production. Pass `null` to clear it.
See [Native clients](/server/packages/server/native-clients).

### ServerFnContext

```ts
interface ServerFnContext {
  request: Request;
  url: URL;
  abortSignal: AbortSignal;
  responseHeaders: Headers;
  status(code: number): void;
  locals: Record<string, unknown>;
}
```

### ServerFnInfo

```ts
interface ServerFnInfo {
  /** Pure identity. `''` means "no build stamp" — never a transport signal. */
  symbol: string;
  name: string;
  transport: 'wire' | 'in-process';
}
```

`transport` is the discriminator for middleware that should only apply to real HTTP traffic — a rate limiter's gate line is `if (fn.transport !== 'wire') return`. Do not infer it from `symbol`.

### Errors

```ts
class ServerFnError extends Error {
  readonly status: number;
  constructor(status: number, message: string, data?: unknown);
}
function isServerFnError(error: unknown): error is ServerFnError;
```

`ServerFnError` crosses the wire verbatim (`{ status, message, data }`) and never fires `onError`; every other throw is masked to a generic 500 in production.

## Runtime entries

- **`@sigx/server/node`** — `createServerFnHandler(options)` (a connect-style middleware) and `runWithServerFnContext(source, fn)`, where `source` is a `Request` or a partial `{ request?, locals? }`. Nested scopes for the same request (same URL and method) merge, so `runWithServerFnContext({ locals }, …)` pre-seeds a render that opens its own inner scope.
- **`@sigx/server/server`** — WinterCG/edge: `handleServerFnRequest(request, options)`, `matchesServerFn(request, base?)`. Both are also re-exported from the package root, so a platform entry that already imports `createServerApp` needs no second import path.
- **`@sigx/server/plugin`** — the app-plugin face: `serverPlugin({ transport?, types? })`, `registerWireTypeHandlers(handlers)`. The `types` option registers [`@sigx/serialize`](/server/packages/serialize/overview) handlers for the RPC wire **and** the SSR state registry in one call.
- **`@sigx/server/testing`** — `createTestServerFnContext(init?, { principal })` and `stubServerApp(config)`. See [Testing](#testing) below.

See [Deployment & security](/server/packages/server/deployment) for how these are mounted.

## Testing

```ts
import { createTestServerFnContext, stubServerApp } from '@sigx/server/testing';

const restore = stubServerApp({ authenticate: () => ({ id: 'u_1', roles: ['staff'] }) });

try {
    const rq = createTestServerFnContext({ url: 'http://localhost/checkout' });
    await placeOrder.with({ context: rq })(cart);
} finally {
    restore();
}
```

`createTestServerFnContext(init?)` builds a real, `Request`-backed `ServerFnContext` (default `http://localhost/`) with none of the ceremony: `rq.request` and `rq.url` never throw the detached-context error, `rq.status(code)` records to a readable `.statusCode` instead of dev-warning, and caller `locals` keep their identity — one factory context reused across several `fn.with({ context: ctx })` calls is **one** request store, while two contexts are two.

`stubServerApp(config)` stamps the app seam for a test **and returns the restore**. Call it in teardown: the seam is process-global and last-wins, so an un-restored stamp leaks into every test that follows. Because the runtime is fail-closed, a `serverFn` under no app **denies with 401**, so a unit test that exercises a handler needs either a stubbed app or an `allowAnonymous: true` declaration.

**Varying the config between cases means re-stamping, not mutating** — [the stamped config is frozen](#the-config-is-frozen-once-stamped):

```ts
let restore: (() => void) | undefined;

afterEach(() => {
    restore?.();
    restore = undefined;   // so a test that stamps nothing restores nothing
});

it('denies a non-owner', async () => {
    restore = stubServerApp({ authorize: ownsIt });
    // …
});
```

For a plain unit test of a single handler, prefer `createTestServerFnContext(init, { principal })` — injecting the identity tests the handler rather than the cookie parser.

## Extending the pipeline

`ServerFeatureContext` is the seam for an endpoint family *other* than `serverFns` — `@sigx/actors` is the first — so two families cannot drift apart on the auth path. It exposes `prelude` (middleware → authenticate → identity gate), `enter` (the same, from a raw `Request`), `authorize` (carrying `op.resource`, for per-instance policies), plus the app's `posture`, its `principalCodec`, and `claimBase`.

```ts
import { serverFeature } from '@sigx/server';

const feature = serverFeature();          // or app.feature() from a ServerApp
```

Both resolve `__SIGX_SERVER_APP__` per call, so a feature can hold one at module scope and a call site with no platform value in scope still runs the whole pipeline. These are the same functions the serverFn path runs, not a second implementation — fail-closed throughout.

---
url: https://sigx.dev/core/packages/cache/usage/
title: Usage
description: Working through @sigx/cache — staleTime, revalidation, keepPreviousData, invalidate and optimistic mutate
---

# Using Cache

<p class="lede">Every policy is opt-in per call site through the <code>cache</code> option; <code>cachePlugin()</code> only sets the defaults. A read or action with no <code>cache</code> option behaves exactly as it does without the pack.</p>

This guide assumes the plugin is registered — see [Installation](/core/packages/cache/installation). Examples build on the [data-loading](/core/docs/data-loading) primitives (`useData`, `useAction`, `.match()`).

## Freshness: `staleTime`

`staleTime` is how long a cached value is considered fresh. Within the window the value is served with no fetch. Past it, the stale value is served **immediately** and revalidated in the background — the read moves to state `refreshing`, so the `ready` arm keeps rendering while the new value loads:

```tsx
import { component, useData } from 'sigx';

const Profile = component(() => {
    const user = useData('user', fetchUser, {
        cache: { staleTime: 60_000 },   // fresh for a minute
    });

    return () =>
        user.match({
            pending: () => <Spinner />,
            error: (e) => <p>{e.message}</p>,
            ready: (u) => <h1>{u.name}</h1>,   // stays on screen during background revalidation
        });
});
```

The default is `0` — every mount revalidates. Raise it for data that doesn't change often; a value that never goes stale within a session can use a very large `staleTime`.

## Retention: `gcTime`

When the last component reading a key unmounts, the entry isn't dropped straight away — it's retained for `gcTime` (default 5 minutes). Navigate away and back within that window and the value is there instantly, no refetch:

```tsx
const list = useData('inbox', fetchInbox, {
    cache: { staleTime: 30_000, gcTime: 600_000 },   // keep for 10 minutes
});
```

Set `gcTime: 0` to drop an entry the moment nothing is reading it.

## Revalidation: on focus, on an interval

Mounted reads can refetch on their own. `revalidateOnFocus` refetches when the window regains focus or becomes visible again; `revalidateOnInterval` refetches on a timer:

```tsx
const feed = useData('feed', fetchFeed, {
    cache: {
        staleTime: 15_000,
        revalidateOnFocus: true,
        revalidateOnInterval: 30_000,   // ms
    },
});
```

Both respect `staleTime` — a value still fresh isn't refetched. On the web, focus revalidation is wired to window focus and `visibilitychange` out of the box; on other platforms you supply the event source (see [Renderer portability](#renderer-portability)).

## No skeleton flash: `keepPreviousData`

When a read's key changes and nothing is cached for the new key, core resets to `pending`. For pagination or a filter, that flashes a skeleton on every page. `keepPreviousData` keeps the previous key's value on screen (state `refreshing`) until the new one arrives:

```tsx
const Results = component((ctx) => {
    const page = ctx.signal(1);

    const results = useData(
        () => ['results', page.value],
        ([, p]) => fetchPage(p),
        { cache: { keepPreviousData: true } },
    );

    return () => (
        <div>
            {results.match({
                pending: () => <Skeleton />,   // only the very first load
                error: (e) => <p>{e.message}</p>,
                ready: (rows) => <Rows data={rows} dim={results.state === 'refreshing'} />,
            })}
            <button onClick={() => page.value++}>Next</button>
        </div>
    );
});
```

## Invalidating after a write

`invalidate()` drops an entry's freshness and refetches it for every mounted consumer. Call it directly on a read, or — more usefully — declare it on the action that made the write. Action `invalidates` accepts exact keys **or tuple prefixes**: `['users']` matches every `['users', …]` read.

```tsx
const save = useAction(saveUser, {
    cache: {
        invalidates: [['users']],   // prefix: refetch every ['users', …] read
    },
});

// somewhere in a handler:
const r = await save.run(draft);
```

A declared pattern reaches **every mounted read whose canonical key matches**,
not only the ones that carry a `cache` option — key-addressable refresh is core's
mechanism, and the pack layers freshness on top of it. So a read written without
any cache policy is still refetched:

```tsx
const users = useData(() => ['users', page], loadUsers);   // no cache option
```

Don't add `cache: { staleTime: … }` to a read just to make invalidation fire —
adding `cache: {}` forces a freshness decision the read may not want.

Calling `invalidate()` by hand works too, when the trigger isn't an action:

```ts
const user = useData('user', fetchUser, { cache: {} });
user.invalidate();   // refetch this read everywhere it's mounted
```

A cached `null` revalidates as `'refreshing'`, keeping the null on screen rather
than falling back to a skeleton — presence is tracked separately from the value,
so see [Presence is not the value](/core/docs/data-loading#presence-is-not-the-value).

## Optimistic updates: `mutate()` and `optimistic`

`mutate()` writes through the cache immediately — every mounted consumer re-renders with the new value before any request settles:

```ts
user.mutate((current) => ({ ...current, name: 'Ada' }));
```

For an action, declare the optimistic write inline. `apply` produces the provisional value from the current entry and the action input; if the run fails it rolls back — unless something newer wrote to the entry in the meantime. Its parameters infer as `unknown` (the cached state isn't knowable from the action's input), so annotate them — `current` is nullish (`null`/`undefined`) when the read has nothing cached yet:

```tsx
const rename = useAction(renameUser, {
    cache: {
        optimistic: {
            key: 'user',
            apply: (current: { name: string } | null | undefined, next: { name: string }) =>
                ({ ...(current ?? {}), name: next.name }),
        },
        invalidates: [['users']],
    },
});
```

## Renderer portability

The pack works on any renderer because it never imports the `sigx` umbrella. Two things are platform-specific.

**Focus revalidation's event source.** On the web the default subscribes to window focus and `visibilitychange`, installed only when a DOM is present. On another platform, hand the plugin your own attention event through `revalidateTrigger` — return an unsubscribe and it runs on app teardown:

```ts
app.use(cachePlugin({
    revalidateTrigger: (revalidate) => {
        const off = platform.onResume(revalidate);   // lynx app-resume, terminal focus, …
        return off;
    },
}));
```

Reads still opt in per call site with `revalidateOnFocus`.

**Live-client detection.** A windowless client runtime must declare itself a live client once, from its platform module — `declareLiveClient()` from `@sigx/runtime-core/internals`. This is a renderer concern, not an app one; on the web nothing is required.

## Precise typing

`useData(...)` still returns `AsyncState<T>`; the augmentation adds an optional `invalidate?()` and `mutate?()`. For a read you know is cached, assert the exported view to type them as present:

```ts
import type { CachedAsyncState } from '@sigx/cache';

const user = useData('user', fetchUser, { cache: {} }) as CachedAsyncState<User>;
user.invalidate();   // now typed non-optional
```

## Next steps

- [API reference](/core/packages/cache/api) — every export, option and default
- [Data loading](/core/docs/data-loading) — the `useData` / `useAction` primitives this builds on

---
url: https://sigx.dev/core/packages/cache/api/
title: API reference
description: The @sigx/cache public surface — cachePlugin, CacheOptions, CacheActionOptions, CacheDefaults, CachedAsyncState
---

# API reference

<p class="lede">The public surface of <code>@sigx/cache</code> . One value export — <code>cachePlugin</code> — plus the option and view types. Everything else is delivered by augmenting core's <code>useData</code> / <code>useAction</code> option interfaces.</p>

## `cachePlugin(defaults?)`

```ts
function cachePlugin(defaults?: CacheDefaults): Plugin;
```

Registers the caching async engine on the app (plugin name `'sigx:cache'`) and provides its store. Install it once, before mount:

```ts
app.use(cachePlugin({ staleTime: 30_000 }));
```

### `CacheDefaults`

App-wide defaults. Every field is optional, and each is the fallback for the matching per-read option.

```ts
interface CacheDefaults {
    staleTime?: number;
    gcTime?: number;
    revalidateTrigger?: (revalidate: () => void) => (() => void) | void;
}
```

| Field | Default | Meaning |
|---|---|---|
| `staleTime` | `0` | Milliseconds a value stays fresh. `0` revalidates on every mount. |
| `gcTime` | `300_000` (5 min) | Milliseconds an entry is retained after its last consumer unmounts. |
| `revalidateTrigger` | window focus + `visibilitychange` (DOM only) | The event source for focus revalidation. Return an unsubscribe; it runs on app teardown. See [Renderer portability](/core/packages/cache/usage#renderer-portability). |

## `CacheOptions` (per read)

The shape of `cache` on `useData(key, fetcher, { cache })`:

```ts
interface CacheOptions {
    staleTime?: number;
    gcTime?: number;
    revalidateOnFocus?: boolean;
    revalidateOnInterval?: number;
    keepPreviousData?: boolean;
}
```

| Field | Default | Meaning |
|---|---|---|
| `staleTime` | plugin default (`0`) | Freshness window for this read. |
| `gcTime` | plugin default (5 min) | Retention after the last consumer leaves; `0` drops immediately. |
| `revalidateOnFocus` | `false` | Refetch when the window regains focus / visibility. |
| `revalidateOnInterval` | — | Refetch on a timer, in milliseconds. |
| `keepPreviousData` | `false` | On a key change with nothing cached, keep rendering the previous value (state `refreshing`) instead of resetting to `pending`. |

## `CacheActionOptions` (per action)

The shape of `cache` on `useAction(fn, { cache })`:

```ts
interface CacheActionOptions {
    invalidates?: readonly (string | readonly unknown[])[];
    optimistic?: {
        key: string | readonly unknown[];
        apply: (current: unknown, input: unknown) => unknown;
    };
}
```

| Field | Meaning |
|---|---|
| `invalidates` | Keys to invalidate after the action settles. An entry is an **exact key** or a **tuple prefix** — `['users']` matches every `['users', …]` read. |
| `optimistic.key` | The read entry to write through before the action settles. |
| `optimistic.apply` | Produces the provisional value from `(current, input)`. Rolled back on failure — unless a newer write landed on the entry meanwhile. Both params infer as `unknown` (the cached state can't be inferred from the action), so **annotate them** — e.g. `apply: (current: User \| null \| undefined, next: Rename) => …`. `current` is nullish (`null`/`undefined`) when the target read has nothing cached yet. |

## `CachedAsyncState<T>`

The precisely-typed view of a cached read. `useData` still returns `AsyncState<T>`; the augmentation adds `invalidate?()` and `mutate?()` as optional. Assert this view when you know a read is cached:

```ts
interface CachedAsyncState<T> extends AsyncState<T> {
    invalidate(): void;
    mutate(update: T | ((current: T | null) => T)): void;
}
```

- **`invalidate()`** — drop this entry's freshness and refetch for every mounted consumer. Present on every read once the plugin is installed.
- **`mutate(update)`** — write through the cache immediately; every mounted consumer re-renders. Present on reads served **with** a `cache` option.

```ts
import type { CachedAsyncState } from '@sigx/cache';

const user = useData('user', fetchUser, { cache: {} }) as CachedAsyncState<User>;
user.mutate((u) => ({ ...u, seen: true }));
```

## Augmented core interfaces

Importing `@sigx/cache` augments `@sigx/runtime-core` (which the `sigx` umbrella re-exports), adding:

- `AsyncOptions.cache?: CacheOptions` — the `cache` option on `useData`.
- `ActionOptions.cache?: CacheActionOptions` — the `cache` option on `useAction`.
- `invalidate?(): void` and `mutate?(update): void` on `AsyncState<T>`.

These appear automatically once the package is a dependency — no import beyond the package itself.

## Pack-author seam

For authors building a *different* async pack, core exposes the engine contract at `@sigx/runtime-core/internals` — `ASYNC_ENGINE_TOKEN`, `provideAsyncEngine()`, `defaultAsyncEngine`, and the `AsyncEngine` interface. This is internal, not application API: `@sigx/cache` is one implementation of it, and reads without a `cache` option delegate to `defaultAsyncEngine` unchanged. The contract is specified in core's `rfc-async` (§7).

## See also

- [Overview](/core/packages/cache/overview) — what the pack is and why
- [Usage](/core/packages/cache/usage) — the policies worked through
- [Data loading](/core/docs/data-loading) — `useData`, `useAction`, `.match()`

---
url: https://sigx.dev/actors/docs/shipping-actors-in-packages/
title: Shipping actors in a package
description: "The dual-package client swap an npm package must do itself, and the four things that become the author's responsibility"
---

# Shipping actors in a package

<p class="lede">An app registers actors from anywhere — `withActors([Greeter, Presence])`. The
build is the part that needs care: `sigxActors()` only transforms first-party source, so a
package must do its own client swap.</p>

## Why it is required, not optional

The [Vite plugin](/actors/docs/vite-plugin) excludes `node_modules`. A packaged actor is
therefore **never transformed** by the consuming app's build — so without the package's own
swap, its implementation reaches the browser: your database client, your secrets, your server
code.

## The exports map

```json
{
    "exports": {
        ".": {
            "types": "./dist/server.d.ts",
            "browser": "./dist/client.js",
            "import": "./dist/server.js"
        }
    }
}
```

```ts
// client.ts — the browser half
import { __actorRef } from '@sigx/actors/client';
import type { Greeter as GreeterDef } from './server';

// Types come from the real definition; the value is a ref. The `import type`
// is erased, so no implementation reaches the browser.
export const Greeter = __actorRef(
    'acme/greeter',
    '/_sigx/actor',
    ['watch'],        // stream names
    ['summary'],      // cacheable read names
) as typeof GreeterDef;
```

That is the same swap the Vite plugin performs for `*.actor.ts`, done by **static resolution**
instead — so it works with any bundler, not just Vite.

## Four things become yours

The consuming app's build never sees your source, so it cannot check any of this.

**Authorization.** `requireAuthorization` cannot inspect a package, so declare `authorize` or `allowAnonymous`
yourself. The host dev-warns for a registered actor that declares neither. See
[Authorization](/actors/docs/guards).

**Stream names** in the ref must match the definition — they drive wire routing.

**Cacheable read names** likewise, as the ref's fourth argument. They are what make the client
issue `GET`, and a name present in one place but not the other means either a `405` or a read
that quietly never caches. See [Cacheable reads](/actors/docs/cacheable-reads).

**`type` is public API.** It is the wire, directory *and* storage key, so renaming it breaks
deployed state. Two different actors claiming one type is refused at startup.

> Namespace the type after your package — `acme/greeter` — but **not** with the npm scope
> form. A `type` starting with `@` or `$` is refused: those heads belong to the runtime's own
> data keys (`@actor`) and mounts (`$live`).

## Consuming one

```ts
import { Greeter } from '@acme/greeter';

const host = await app.withActors([Greeter, Presence]).start();
```

Nothing else changes — a packaged actor is called exactly like a local one, and
`withActors` throws if the app already declared `actors`, so a host can never silently replace
what the author configured.

## Next steps

- [The Vite plugin](/actors/docs/vite-plugin) — the swap it does for first-party code.
- [Authorization](/actors/docs/guards) — the gate that cannot see your package.
- [The client](/actors/docs/client) — what `__actorRef` produces.

---
url: https://sigx.dev/actors/docs/actors-or-server-functions/
title: Actors or server functions?
description: When to reach for @sigx/actors and when a plain serverFn is the better answer — and why actors are built on top of server functions, not instead of them
---

# Actors or server functions?

<p class="lede">SignalX gives you two ways to run code on the server from a component, and they
are not rivals. A server function is the default. An actor is what you reach for when calls
about the same thing need identity, ordering or memory.</p>

## The rule of thumb

> Use a [server function](/server/packages/server/overview) until you need **identity**,
> **ordering** or **memory between calls**. Then use an actor.

Most endpoints never need any of the three. Fetching a product, submitting a form, running a
search — these have no "which one" to be serial about, and a `serverFn` handles them with less
machinery and no activation to keep warm.

## Side by side

The same feature, both ways. A counter that must never lose an increment:

```ts
// As a server function — correctness lives in the database
export const increment = serverFn(async (rq, id: string) => {
    const row = await db.query(
        'UPDATE counters SET n = n + 1 WHERE id = $1 RETURNING n', [id]);
    return row.n;
});
```

```ts
// As an actor — correctness lives in the model
export const Counter = defineActor({
    type: 'Counter',
    state: () => ({ n: 0 }),
    methods: (ctx) => ({
        async increment() {
            ctx.state.n += 1;   // the only writer, one turn at a time
            await ctx.save();
            return ctx.state.n;
        },
    }),
});
```

The server function is correct because the database serialized the update. The actor is
correct because only one turn runs at a time and the actor is the only writer. The first is
simpler; the second stops needing the database to arbitrate every read, and keeps working when
the operation is not expressible as one statement.

Flip the example to *"increment, then call a payment API, then decide"* and the server-function
version needs a lock, a transaction boundary or an idempotency key. The actor version is the
same six lines.

## What pushes you toward an actor

- **Identity.** The work is about one cart, one room, one device, one game — and two calls
  about the same one must not interleave.
- **Ordering.** Later calls must observe earlier ones. [Serial turns](/actors/docs/turns)
  give you that for free.
- **Memory between calls.** Keeping state hot avoids re-reading it on every request, and lets
  you hold things that do not belong in a row — an in-flight batch, a connection, a timer.
- **Timers and reminders.** [`ctx.timer`](/actors/docs/timers-and-reminders) and durable
  reminders let an object wake itself up. A stateless function has nowhere to put that.
- **Long-running work.** [Tasks](/actors/docs/tasks) and [jobs](/actors/docs/jobs) survive
  the request that started them.

## What pushes you toward a server function

- **No identity.** A list, a search, a report.
- **Read-heavy and cacheable.** A `serverFn` can be cached at the edge without turn ordering in
  the way. Actors have [cacheable reads](/actors/docs/cacheable-reads) too, but the trade is
  sharper.
- **Fan-out over many rows.** An actor is one object; a query is better at touching thousands.
- **Nothing to keep warm.** An activation has a lifetime and a memory cost. If there is no
  state worth keeping, that cost buys nothing.

## They are the same wire

This matters more than it looks: **an actor call is a synthesized server function.** The actor
endpoint speaks the serverFn protocol verbatim, so everything you already configured applies
unchanged — the origin policy, the [serialize codec](/server/packages/serialize/overview),
`ServerFnError` masking, body size caps, `onError`, and the per-request scope.

`@sigx/actors` peer-depends on [`@sigx/server`](/server/packages/server/overview) for exactly
this reason. Actors are a layer **on** server functions, not an alternative stack.

Three practical consequences:

1. **Policies are the same policies.** An actor's `authorize` takes core's `ServerPolicy`, so
   one you wrote for your server functions works on an actor unchanged — and your app's default
   policy covers both. What an actor adds is `op.resource`, which carries the actor's type and
   key, so a policy can decide per **instance**. See [Authorization](/actors/docs/guards).
2. **Your types cross both boundaries identically.** `Date`, `Map`, `Set`, `bigint` and your
   own registered types round-trip through the same codec.
3. **The fail-closed rule applies to both.** A server function and an actor that each declare
   nothing, with no server app configured, both deny — so configuring the app once is what
   makes either of them callable.

## Using both together

The common shape in a real app is not a choice at all:

```ts
// A server function does the query — no identity involved.
export const listRooms = serverFn(async (rq) => db.rooms.findMany());

// An actor owns the thing that has identity and ordering.
export const RoomActor = defineActor({ type: 'Room', /* … */ });
```

A server function may call an actor, and an actor may call another actor. What an actor must
not do is call back into itself through a server function — that is a cycle, and the
[deadlock detector](/actors/docs/errors) will say so.

One wrinkle worth knowing when you mix them: a write performed by a *server function* does not
invalidate an actor read on the page, because nothing told the page it went stale. Declare it
by hand with `cells.invalidate([actorKey(RoomActor, room)])` — see
[Reads and writes in components](/actors/docs/in-components).

## Next steps

- [Installation](/actors/docs/installation) — set up the plugin and the app module.
- [Your first actor](/actors/docs/your-first-actor) — build the counter above for real.
- [Server functions](/server/packages/server/overview) — the layer underneath.

---
url: https://sigx.dev/devtools/docs/connecting-an-inspector/
title: Connecting an inspector
description: Choose a transport and connect a browser extension or external inspector to @sigx/devtools
---

# Connecting an inspector

The plugin is transport-agnostic. It speaks a small JSON protocol through a `Transport`
and lets you swap how those messages travel: `postMessage` for browser panels and
extensions, WebSocket for non-browser hosts, or your own implementation.

## How the wire works

Every message is wrapped in a namespaced envelope so a content script or relay can
filter SignalX traffic out of everything else on the channel:

```ts
{ __sigx: 'SIGX_DEVTOOLS', dir: 'to-panel' | 'to-page', msg }
```

Page-to-panel traffic uses `dir: 'to-panel'`; panel-to-page requests use
`dir: 'to-page'`. The page side sends `PageEvent` broadcasts and `PanelResponse`
replies; the panel side sends `PanelRequest` messages, each carrying a numeric `id`
for response correlation.

On connect the plugin emits a `hello` event:

```ts
{ t: 'hello', payload: { protocol: 1, agentVersion: '0.0.3' } }
```

A panel bootstraps by calling `get:apps`, then `get:tree` for each app id it cares
about. After a reconnect it re-runs the same sequence — intermediate dropped events
are acceptable.

## Default: postMessage (browser)

`devtools()` defaults to `createPostMessageTransport()` whenever `window` is available,
so you usually do not configure a transport at all:

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { App } from './App';

defineApp(<App />)
    .use(devtools())
    .mount('#app');
```

The transport posts `to-panel` envelopes to the target window (`targetOrigin: '*'`) and
listens for `to-page` envelopes. You can pass an explicit target window if you need to:

```tsx
import { devtools, createPostMessageTransport } from '@sigx/devtools';

app.use(devtools({
    transport: createPostMessageTransport(window),
}));
```

### An in-page overlay

If your panel lives in the same page (an overlay or a debug iframe sharing the window),
it can listen on the same `window` for the same `__sigx: 'SIGX_DEVTOOLS'` tag and post
`to-page` envelopes back. No relay is needed because both sides share JavaScript objects.

### A Chrome extension

A Chrome MV3 extension cannot share JS objects between the page world and the extension,
so a content script must relay envelopes both directions:

- Listen on `window` for `message` events whose data has `__sigx === 'SIGX_DEVTOOLS'`
  and `dir === 'to-panel'`, and forward `msg` to `chrome.runtime`.
- Receive panel requests from `chrome.runtime` and `window.postMessage` them back as
  `{ __sigx: 'SIGX_DEVTOOLS', dir: 'to-page', msg }`.

The page-side plugin needs no extra configuration for this — the default `postMessage`
transport already produces the envelopes the content script filters on. The content
script, the extension panel, and any standalone inspector are separate packages outside
`@sigx/devtools`.

## Non-browser hosts: WebSocket

For native hosts (for example Lynx) or terminal renderers there is no `window`, so use
the WebSocket transport and pair it with a relay that the inspector connects to:

```tsx
import { defineApp } from 'sigx';
import { devtools, createWebSocketTransport } from '@sigx/devtools';
import { App } from './App';

defineApp(<App />)
    .use(devtools({
        transport: createWebSocketTransport({
            url: 'ws://localhost:8098/page',
        }),
    }))
    .mount('#app');
```

`createWebSocketTransport` defaults to `ws://localhost:8098/page` — the path the bundled
`sigx-devtools-inspector` relay listens on for page-side clients. While disconnected it
queues outgoing messages (up to `maxQueue`, default 1000, dropping the oldest on
overflow) and flushes them on connect. It auto-reconnects with exponential backoff
capped by `maxBackoffMs` (default 30000ms). If no `WebSocket` constructor is available
it returns a no-op stub.

For tests you can inject a custom WebSocket implementation:

```tsx
import { createWebSocketTransport } from '@sigx/devtools';

const transport = createWebSocketTransport({
    url: 'ws://localhost:8098/page',
    maxQueue: 500,
    WebSocketImpl: MyFakeWebSocket,
});
```

## Custom transports

Implement the `Transport` interface to ferry messages over any channel — for instance a
`BroadcastChannel`:

```ts
import type { Transport } from '@sigx/devtools';

function createBroadcastTransport(name = 'sigx-devtools'): Transport {
    const channel = new BroadcastChannel(name);
    const listeners = new Set<(msg: unknown) => void>();

    channel.onmessage = (event) => {
        const data = event.data;
        if (data && data.__sigx === 'SIGX_DEVTOOLS' && data.dir === 'to-page') {
            for (const fn of listeners) fn(data.msg);
        }
    };

    return {
        send(msg) {
            channel.postMessage({ __sigx: 'SIGX_DEVTOOLS', dir: 'to-panel', msg });
        },
        onMessage(listener) {
            listeners.add(listener);
            return () => listeners.delete(listener);
        },
        close() {
            listeners.clear();
            channel.close();
        },
    };
}
```

Pass it like any other transport:

```tsx
app.use(devtools({ transport: createBroadcastTransport() }));
```

## What the panel can ask for

Once connected, the panel drives inspection through `PanelRequest` messages:

- `get:apps` — list the apps the plugin knows about.
- `get:tree` — component nodes for an app id.
- `get:value` — resolve a `ValueRef` (props records and other large values).
- `get:reactive-value` — serialize a reactive's current raw value.
- `get:reactives` — the primitives owned by a component.
- `highlight` / `unhighlight` — currently acknowledged with `{ ok: true }`; this
  package does not implement DOM highlighting itself.

See the [API Reference](/devtools/docs/api) for the exact message shapes.

---
url: https://sigx.dev/devtools/docs/tuning-what-gets-traced/
title: Tuning what gets traced
description: Control reactivity volume, observe stores and the router, and understand how @sigx/devtools serializes values
---

# Tuning what gets traced

A busy app can update signals hundreds of times per frame. `@sigx/devtools` gives you a
few knobs to keep the panel responsive and to choose exactly which event families flow
over the wire.

## Throttling reactive updates

The plugin coalesces `reactive:updated` events per primitive id within a millisecond
window. The default is `16` (~one frame), which collapses bursts of same-id updates into
a single event. Raise it to cap traffic harder, or set `0` to disable coalescing and see
every update:

```tsx
import { devtools } from '@sigx/devtools';

// ~10 updates/sec per primitive at most
app.use(devtools({ throttleMs: 100 }));

// every update, no coalescing
app.use(devtools({ throttleMs: 0 }));
```

Throttling only affects `reactive:updated` — create and dispose events are always sent.

## Dropping reactivity entirely

If you only care about the component tree, props, stores, and router, turn reactivity
off. This keeps those timelines but drops all signal/computed/effect events:

```tsx
app.use(devtools({ includeReactivity: false }));
```

## Observing stores

Stores are observed automatically: the plugin subscribes to wildcard patterns on the
core inspection registry (`@sigx/runtime-core/inspect`), where every `@sigx/store`
instance registers its state, action, and custom-event topics. Stores that already
exist and stores created later are both picked up — no per-store wiring. The
`includeStores` option (default `true`) turns this off:

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { App } from './App';

defineApp(<App />)
    .use(devtools({
        includeStores: false, // drop store:action / store:mutation / store:event
    }))
    .mount('#app');
```

Each action dispatch is reported in three phases that share one `actionId`:
`dispatching` then either `dispatched` (with the serialized `result` and `durationMs`)
or `failed` (with a serialized `error`). Mutations carry the changed `key` and the new
`value` serialized inline. Store custom events (`defineEvents`) arrive as `store:event`
with the event key and serialized payload.

Note that observing a store activates its refCount state watchers — state observation
is pay-when-observed by design, so the watchers run only while devtools (or another
subscriber) is attached.

## Observing the router

Pass your router instance to stream navigations as `router:nav` events:

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { createRouter } from '@sigx/router';
import { App } from './App';

const router = createRouter({ routes: [/* ... */] });

defineApp(<App />)
    .use(router)
    .use(devtools({ router }))
    .mount('#app');
```

The observer wraps the router's reactive `currentRoute` in an effect. The route present
at mount is skipped — only subsequent navigations fire. Each event carries `fromPath`,
`toPath`, and serialized `params` and `query`.

## How values are serialized

The plugin never puts live reactive proxies or DOM nodes on the wire. Two mechanisms
keep traffic safe and small:

- **Value references.** Component props and other large values are sent as a numeric
  `ValueRef`. The panel resolves the actual value on demand with a `get:value` request.
  Object values are held via `WeakRef` so unmounted components can be garbage-collected;
  primitives and functions are held strongly.
- **Bounded serialization.** When a value is serialized it is unwrapped from any reactive
  proxy first, cycles become `{ kind: 'circular' }`, functions become
  `{ kind: 'function', name }`, and recursion is bounded to a depth of 4 — past which a
  value becomes `{ kind: 'truncated', reason: 'depth' }`. Objects/arrays are capped at 100
  entries, but extra entries past the cap are silently dropped with no `truncated` marker.
  Only own enumerable string keys are included; symbol keys (framework internals) are skipped.

Reactive current values are resolved with `get:reactive-value`, which serializes through
`toRaw` so reading the value does not re-engage the proxy or create accidental
subscriptions.

You don't call the serializer yourself — it runs inside the plugin and observers — but
knowing its bounds explains why a deeply nested object shows up `truncated` in the panel.

## A combined configuration

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { createRouter } from '@sigx/router';
import { App } from './App';

const router = createRouter({ routes: [/* ... */] });

defineApp(<App />)
    .use(router)
    .use(devtools({
        appName: 'shop',
        includeStores: true,   // the default — stores auto-discovered
        router,
        includeReactivity: true,
        throttleMs: 32,
    }))
    .mount('#app');
```

See the [API Reference](/devtools/docs/api) for every option and event shape.

---
url: https://sigx.dev/store/docs/events-and-observability/
title: Events & Observability
description: State events, action events, custom events, and the inspection registry
---

# Events & Observability

A store emits three kinds of events, and they answer different questions:

- **State events** (`$events.count`) tell you **what** changed — a key's value went from `prev` to `value`, regardless of who changed it.
- **Action events** (`save.onDispatched`) tell you **why** — an action ran, with which arguments and what result. See [Actions & Async](/store/docs/actions-and-async#the-lifecycle-events).
- **Custom events** (`defineEvents`) are **domain events** you publish yourself — "checked out", "logged in" — decoupled from both state shape and action names.

All three are built on the same core primitive, the [Topic](/core/docs/advanced/messaging), which is what makes the observability story below uniform: subscriptions clean up the same way everywhere, and every event a store emits is discoverable by tooling.

## State events: `$events` vs. `watch`

`store.$events.count.subscribe((value, prev) => ...)` is the store-native way to react to a single key. Compared to a raw `watch` from the reactivity package:

- The callback receives `(value, prev)` for exactly that key — no expression to write, deep changes included (mutating an object or array stored under the key fires it too).
- It is **lazy** (see below) — an unobserved key costs nothing.
- It is **typed from the store's public surface** — `$events` only has the keys you returned from the setup.

Use `watch`/`effect` instead when you need to react to an arbitrary *expression* over several keys or across stores. For rendering, you need neither — reads in render functions are tracked automatically.

Inside the setup, `defineState`'s own `events` object covers **every** key of the slice, including ones you keep private. On the instance, `$events` (like `$patch`) covers only the **returned** key signals — private state is invisible outside the setup. See [TypeScript](/store/docs/typescript#patch-and-events-follow-the-returned-keys) for how that's enforced at the type level.

## Laziness: refCounted watchers

State events are engineered so that *declaring* them is free and only *observing* them costs anything:

- The topic behind each key is created **eagerly** when `defineState` runs — that's what makes it discoverable in the registry (below).
- The **deep watcher** that feeds it is created on the **first subscribe** and stopped on the **last unsubscribe** (a refCount pattern). A key nobody listens to has no watcher running.
- Nothing fires at subscribe time — you only see changes that happen *after* you subscribed.

So returning twenty state keys from a setup does not create twenty deep watchers; it creates twenty cheap topics, and watchers only spin up for the keys someone actually observes.

## Subscriptions clean up with the component

Every `subscribe()` — on `$events.*`, on action lifecycle events, on custom events — returns a `Subscription` with `unsubscribe()`. But when you subscribe **inside a component setup**, you rarely need to keep it: the topic's `subscribe` registers an `onUnmounted` cleanup with the current component, so the subscription is removed automatically when the component unmounts. Outside a component (scripts, tests, module scope), keep the `Subscription` and unsubscribe yourself.

The demo below leans on that: all four subscriptions are made in the component setup with no manual teardown.

```tsx
import { component, render, signal } from 'sigx';
import { defineStore } from '@sigx/store';

const useCounterStore = defineStore('counter', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ count: 0 });

    const actions = defineActions({
        increment() { state.count++; },
        async incrementLater() {
            await new Promise(resolve => setTimeout(resolve, 700));
            state.count++;
        },
    });

    return { ...signals, ...actions };
});

const EventLog = component(() => {
    const store = useCounterStore();
    const log = signal([] as string[]);

    // WHAT changed — the state event:
    store.$events.count.subscribe((value, prev) => {
        log.push(`count: ${prev} → ${value}`);
    });
    // WHY it changed — the action events:
    store.increment.onDispatched.subscribe(() => log.push('increment ran'));
    store.incrementLater.onDispatching.subscribe(() => log.push('incrementLater started…'));
    store.incrementLater.onDispatched.subscribe(() => log.push('incrementLater resolved'));

    return () => (
        <div class="space-y-2">
            <div class="flex items-center gap-2">
                <button class="btn btn-sm" onClick={() => store.increment()}>+1 now</button>
                <button class="btn btn-sm" disabled={store.incrementLater.pending}
                        onClick={() => store.incrementLater()}>
                    +1 in 0.7s
                </button>
                <span class="font-bold">{store.count}</span>
            </div>
            <ul class="text-sm font-mono max-h-32 overflow-y-auto">
                {log.map(line => <li>{line}</li>)}
            </ul>
        </div>
    );
});

render(<EventLog />, "#sandbox");
```

Notice the ordering in the log for the async action: `started…` (onDispatching), then on resolution the state event fires from the mutation, then `resolved` (onDispatched).

## Custom events with `defineEvents`

When neither "key x changed" nor "action y ran" is the right vocabulary, define domain events. `defineEvents<EventMap>()` on the setup context creates a typed group of topics; return the ones subscribers should reach:

```ts
import { defineStore } from '@sigx/store';

type CartEvents = {
    checkedOut: { orderId: string };
    cleared: void;
};

const useCartStore = defineStore('cart', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ items: [] as Item[] });
    const events = ctx.defineEvents<CartEvents>();

    const actions = ctx.defineActions({
        async checkout() {
            const orderId = await api.checkout(state.items);
            patch({ items: [] });
            events.checkedOut.publish({ orderId });
        },
    });

    return { ...signals, ...actions, onCheckedOut: events.checkedOut };
});

useCartStore().onCheckedOut.subscribe(({ orderId }) => { /* typed payload */ });
```

Custom-event topics are created lazily, on first access of each key — the event-map type is erased at runtime, so a topic exists (and registers for inspection) once your code first touches `events.checkedOut`.

## The inspection registry

Every store event is a **namespaced topic**, and namespaced topics register in a realm-global, inspection-only registry that tooling reads via `@sigx/runtime-core/inspect`. A store with `$id` `'todos#1'` registers under three namespaces:

| Namespace | Topics |
|---|---|
| `todos#1.state` | one per state key — `count`, `items`, … |
| `todos#1.actions` | three per action — `save.onDispatching`, `save.onDispatched`, `save.onFailure` |
| `todos#1.events` | one per custom event key (as each is first touched) |

```ts
import { listTopics, subscribeTopics } from '@sigx/runtime-core/inspect';

listTopics('todos#1.*');          // every topic of this instance
listTopics('*.actions.*');        // every action event of every store

// Tap everything one store emits — existing topics AND ones created later:
const sub = subscribeTopics('todos#1.*', (data, { namespace, name }) => {
    console.log(`[${namespace}] ${name}`, data);
});
sub.unsubscribe();                // one call tears the whole tap down
```

This is how devtools auto-discover stores without any store-side registration code: the topics carry `namespace` and `name` metadata, `onTopicCreated` notifies about new ones, and wildcard patterns like `'*.state.*'` slice across all stores. The registry is deliberately `Topic<unknown>`-typed and **inspection-only** — application code should share typed topic references (like `onCheckedOut` above) instead of looking topics up by string.

When a store is disposed, all of its topics are destroyed — they unregister from the registry, their refCount watchers stop, and `$events` / action events stop firing. See [Using Stores in Components](/store/docs/using-in-components#cleanup-on-unmount).

For store-creation-time observability (wiring a logger to every store automatically), see [`onStoreCreated`](/store/docs/composables-and-plugins#global-plugins-with-onstorecreated).

## Next steps

- [Actions & Async](/store/docs/actions-and-async) — the action lifecycle events in depth.
- [Composables & Plugins](/store/docs/composables-and-plugins) — cross-cutting observability with `onStoreCreated`.
- [Messaging in core](/core/docs/advanced/messaging) — the Topic primitive itself.
- [API Reference](/store/docs/api#statekeyevent) — `StateKeyEvent`, `Topic`, and `Subscription` signatures.

---
url: https://sigx.dev/store/docs/composables-and-plugins/
title: Composables & Plugins
description: Reusable setup composables and global onStoreCreated plugins
---

# Composables & Plugins

There are two ways to package store behavior for reuse, and they sit at different altitudes:

- **Setup composables** — plain functions you call *inside* a store's setup, with the setup context. Per-store, opt-in, fully typed against that store's state. [`persist`](/store/docs/persistence) is one.
- **Global plugins** — functions registered once with `onStoreCreated`, running for **every** store instance. Untyped by design, ideal for infrastructure: logging, devtools, metrics.

## Setup composables

A composable is just a function whose first parameter is the `SetupStoreContext`. That context is what makes composables possible — it carries everything a reusable behavior needs:

- `storeName` / `instanceId` — stable identity for storage keys, log labels, registry lookups.
- `onDeactivated(fn)` — tie any resource to the store's disposal.
- `subscriptions` — a handler that batch-unsubscribes on disposal (`ctx.subscriptions.add(fn)`).
- `defineState` / `defineActions` / `defineEvents` — composables can even contribute state or events of their own.

### Case study: `persist`

The persistence composable shows the full shape — context first, then the data it operates on, then options; resources registered for cleanup; a handle returned for the setup to use or expose:

```ts
import { defineStore } from '@sigx/store';
import { persist } from '@sigx/store/persist';

const useSettings = defineStore('settings', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ theme: 'dark' });

    const { hydrated } = persist(ctx, { state, patch });   // ← the composable

    return { ...signals, hydrated };
}, 'singleton');
```

Internally, `persist` uses the context for everything it can't do alone: `ctx.storeName` provides the default storage key (`sigx:settings`), and `ctx.onDeactivated` stops its save watcher and cancels its debounce timer when the store is disposed. The setup decides what (if anything) to expose — here, the `hydrated` flag.

That's the contract to copy: **a composable takes `ctx`, registers its cleanup through `ctx`, and returns a handle.**

### Writing your own

A polling composable that re-runs an action on an interval, pauses on demand, and dies with the store:

```ts
import type { SetupStoreContext } from '@sigx/store';

export function autoRefresh(ctx: SetupStoreContext, action: () => unknown, ms: number) {
    let timer: ReturnType<typeof setInterval> | null = null;

    const start = () => {
        if (timer) return;
        timer = setInterval(() => action(), ms);
    };
    const stop = () => {
        if (timer) clearInterval(timer);
        timer = null;
    };

    ctx.onDeactivated(stop);   // never outlive the store
    start();
    return { start, stop };
}
```

And in a store:

```ts
const useFeedStore = defineStore('feed', (ctx) => {
    const { state, signals } = ctx.defineState({ posts: [] as Post[] });
    const actions = ctx.defineActions({
        async load() { state.posts = await api.posts(); },
    });

    const refresh = autoRefresh(ctx, actions.load, 30_000);

    return { ...signals, ...actions, pauseRefresh: refresh.stop, resumeRefresh: refresh.start };
});
```

Because composables run inside the setup, they get the **typed** slice (`state`, `patch`, the actions) — generic over the store's actual state shape, like `persist<TState>` is. A composable that needs to react to changes can subscribe to the slice's `events` (which cover *all* keys, including private ones — see [Events & Observability](/store/docs/events-and-observability#state-events-events-vs-watch)).

## Global plugins with `onStoreCreated`

`onStoreCreated(plugin)` registers a function that runs for **every store instance**, synchronously after its setup returns. Register plugins once, at app bootstrap, before stores are created:

```ts
import { onStoreCreated } from '@sigx/store';

const sub = onStoreCreated(({ name, instanceId, instance, onDeactivated }) => {
    // runs for every instance of every store
});

sub.unsubscribe();   // stops future invocations (existing wiring stays)
```

The plugin context per instance:

- `name` — the logical store name (`'todos'`).
- `instanceId` — the friendly id (`'todos#1'`).
- `instance` — the **raw setup return**, not the unwrap proxy. Key signals appear as `{ value }` objects here; duck-type for what you need.
- `onDeactivated(fn)` — tie plugin resources to that instance's lifetime.

Three guarantees worth knowing:

- **Registration order** — plugins run in the order they were registered.
- **Error isolation** — a throwing plugin is logged (`console.error`) and skipped; it cannot break store creation or the other plugins.
- **Synchronous timing** — the store factory hasn't returned yet, so the plugin observes the instance before any caller does.

### Example: a universal change logger

Because every store event is a registered topic namespaced under the instance id ([the inspection registry](/store/docs/events-and-observability#the-inspection-registry)), one wildcard subscription per store logs everything — state changes, action dispatches, custom events:

```ts
import { onStoreCreated } from '@sigx/store';
import { subscribeTopics } from '@sigx/runtime-core/inspect';

onStoreCreated(({ instanceId, onDeactivated }) => {
    const sub = subscribeTopics(`${instanceId}.*`, (data, { namespace, name }) => {
        console.debug(`[${namespace}] ${name}`, data);
    });
    onDeactivated(() => sub.unsubscribe());
});
```

No store opted in, none had to change — and the `onDeactivated` hook keeps the tap from outliving any instance. This is essentially how devtools integrations attach.

> One caveat: subscribing to a store's *state* topics activates their refCount watchers — observed keys are no longer free. Fine for development tooling; think twice before shipping an always-on subscriber to production.

## Which one do I want?

| | Setup composable | `onStoreCreated` plugin |
|---|---|---|
| Scope | one store, explicitly opted in | every store instance, globally |
| Typing | full — generic over the slice | untyped `instance` (duck-typing) |
| Can add state/actions/events | yes (it has the setup context) | no — observe and attach only |
| Cleanup hook | `ctx.onDeactivated` | `onDeactivated` in the plugin context |
| Examples | persistence, polling, form bindings | logging, devtools, metrics, error reporting |

Rule of thumb: if the behavior is part of *what the store is*, it's a composable; if it's part of *how your app observes stores*, it's a plugin.

## Next steps

- [Persistence](/store/docs/persistence) — the `persist` composable in full.
- [Events & Observability](/store/docs/events-and-observability) — the registry plugins build on.
- [API Reference](/store/docs/api#onstorecreated) — `onStoreCreated` and `StorePluginContext` signatures.

---
url: https://sigx.dev/terminal/docs/input-and-components/
title: Input & Interactive Components
description: Focus, keyboard input and the built-in terminal widgets
---

# Input & Interactive Components

This guide covers how keyboard input is dispatched, how focus traversal works, and how to use the built-in interactive components.

## Keyboard input

When you mount a terminal app, the runtime puts stdin into raw mode and dispatches every keypress. You can subscribe to raw input with `onKey`:

```tsx
import { component, defineApp, onMounted, onUnmounted } from '@sigx/terminal';
import { onKey, exitTerminal } from '@sigx/terminal';

const App = component(() => {
    let off: (() => void) | undefined;

    onMounted(() => {
        off = onKey((key) => {
            // key is a raw string, e.g. '\r' (Enter), arrow keys as escape sequences
            if (key === 'q') {
                exitTerminal();
            }
        });
    });

    onUnmounted(() => off?.());

    return () => (
        <box border="rounded" label="Keys">
            <text>Press 'q' to quit.</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

`onKey` returns an unsubscribe function. Each keypress arrives as a string — printable characters as themselves, special keys as escape sequences (for example `'\x1B[A'` for the up arrow). By default **Ctrl+C** tears down and exits (code 130); set `exitOnCtrlC: false` at mount to receive it as a key instead (see [Render modes](/terminal/docs/render-modes)).

## Layered key dispatch

Handlers run in **layers**, so an overlay can intercept a key before the control underneath sees it. Pass a `layer` to `onKey`:

```tsx
onKey(handler, { layer: 'overlay' });   // 'overlay' | 'control' | 'view' | 'global'
```

Dispatch order is **overlay → control → view → global**, and within a layer in registration order. A handler that returns strictly `true` **consumes** the key and stops dispatch; returning anything else lets it fall through.

- `overlay` — modal UI on top of everything (a suggestion popup, a confirm dialog).
- `control` — the default; focused widgets register here.
- `view` — page/screen-level shortcuts.
- `global` — app-wide fallbacks. The built-in Tab / Shift+Tab focus cycling is the first `global` handler, so an overlay or control can consume Tab first (e.g. accept-completion).

```tsx
import { onKey } from '@sigx/terminal';

// A view-level shortcut that doesn't fight focused inputs.
onKey((key) => {
    if (key === '?') { openHelp(); return true; }   // consume
}, { layer: 'view' });
```

## Focus traversal

Focus is a global singleton. Interactive components register a focusable id when they mount; the first one registered becomes active. Tab and Shift+Tab cycle through them (wrapping around).

You can read and drive focus directly:

```tsx
import {
    focusState,
    registerFocusable,
    unregisterFocusable,
    focus,
    focusNext,
    focusPrev,
} from '@sigx/terminal';

// Is some id currently active?
const active = focusState.activeId;

// Programmatically move focus
focusNext();
focusPrev();
focus('my-id');
```

`focusState` is created with the object overload of `signal`, so it is a deeply reactive proxy read via property access. Reading `focusState.activeId` inside a render makes the component repaint when focus changes. Custom interactive components typically call `registerFocusable(id)` in `onMounted` and `unregisterFocusable(id)` in `onUnmounted`.

## Built-in components

The examples below cover the core focusable widgets. The full themed library — forms, feedback, navigation, layout, data, fx and task components — is documented page-by-page under [Components](/terminal/docs/components).

### Input

A focusable single-line text field with two-way model binding. It renders as a bordered box (green border when focused). Backspace deletes, Enter emits `submit`, and printable characters emit `input`.

```tsx
import { component, defineApp, signal } from '@sigx/terminal';
import { Input } from '@sigx/terminal';

const App = component(() => {
    const text = signal('');

    return () => (
        <box border="single" label="Form">
            <Input
                model={() => text}
                label="Name"
                placeholder="Type here"
                autofocus
                onInput={(v) => console.log('changed:', v)}
                onSubmit={(v) => console.log('submitted:', v)}
            />
            <br />
            <text>You typed: {text.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

### Button

A focusable button. Enter or Space triggers a brief press visual and emits `click`. It shows a green border with a blue background when focused.

```tsx
import { component, defineApp, signal } from '@sigx/terminal';
import { Button } from '@sigx/terminal';

const App = component(() => {
    const clicks = signal(0);

    return () => (
        <box border="rounded" label="Buttons">
            <Button label="Click me" onClick={() => clicks.value++} />
            <br />
            <Button label="With shadow" dropShadow onClick={() => { clicks.value = 0; }} />
            <br />
            <text>Clicks: {clicks.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

### Checkbox

A focusable toggle with two-way model binding. Enter or Space toggles it. It renders as `> [x] Label` when focused and checked.

```tsx
import { component, defineApp, signal } from '@sigx/terminal';
import { Checkbox } from '@sigx/terminal';

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

    return () => (
        <box border="single" label="Terms">
            <Checkbox
                model={() => agreed}
                label="I agree"
                autofocus
                onChange={(v) => console.log('agreed:', v)}
            />
            <br />
            <text>{agreed.value ? 'Thank you!' : 'Please accept to continue.'}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

### Select

A focusable option list with keyboard navigation. Up/`k` and Down/`j` move the selection (wrapping), updating the model and emitting `change`; Enter emits `submit`. The selected option is marked with `❯`. The `options` prop is required and takes `SelectOption[]`.

```tsx
import { component, defineApp, signal } from '@sigx/terminal';
import { Select } from '@sigx/terminal';
import type { SelectOption } from '@sigx/terminal';

const options: SelectOption[] = [
    { label: 'Development', value: 'dev', description: 'Local dev build' },
    { label: 'Staging', value: 'staging', description: 'Pre-production' },
    { label: 'Production', value: 'prod', description: 'Live environment' },
];

const App = component(() => {
    const env = signal('dev');

    return () => (
        <box border="rounded" label="Deploy target">
            <Select
                options={options}
                model={() => env}
                label="Environment"
                showDescription
                autofocus
                onChange={(v) => console.log('selected:', v)}
                onSubmit={(v) => console.log('confirmed:', v)}
            />
            <br />
            <text>Target: {env.value}</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

### ProgressBar

A read-only progress indicator. It renders filled and empty characters plus a percentage label. It is not focusable and emits no events.

```tsx
import { component, defineApp, signal, onMounted } from '@sigx/terminal';
import { ProgressBar } from '@sigx/terminal';

const App = component(() => {
    const value = signal(0);

    onMounted(() => {
        const t = setInterval(() => {
            value.value = Math.min(100, value.value + 5);
        }, 200);
        return () => clearInterval(t);
    });

    return () => (
        <box border="single" label="Download">
            <ProgressBar value={value.value} max={100} width={30} color="green" />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Quitting gracefully

For a clean programmatic exit, pair `mountTerminal()` with `exitTerminal()`:

```tsx
import { component, defineApp } from '@sigx/terminal';
import { mountTerminal, exitTerminal, onKey, onMounted, onUnmounted } from '@sigx/terminal';

const App = component(() => {
    let off: (() => void) | undefined;
    onMounted(() => {
        off = onKey((key) => {
            if (key === 'q') exitTerminal();
        });
    });
    onUnmounted(() => off?.());

    return () => (
        <box border="rounded" label="App">
            <text>Press 'q' to quit cleanly.</text>
        </box>
    );
});

defineApp(<App />).mount(mountTerminal());
```

`mountTerminal()` returns a mount target you pass to `.mount()`, and captures the unmount callback so `exitTerminal()` can tear it down, restore the cursor and clear the screen.

## Next steps

- [Components](/terminal/docs/components) — every component in the library, page by page.
- [Prompts](/terminal/docs/prompts) — the same widgets as imperative CLI prompts.
- [Layout & Styling](/terminal/docs/layout-and-styling) — boxes, borders and colors.
- [API Reference](/terminal/docs/api) — the full export list.

---
url: https://sigx.dev/use/docs/use-intersection-observer/
title: useIntersectionObserver
description: Observe viewport intersection with an IntersectionObserver that follows reactive targets, pauses without losing config, and disconnects with the owning scope
---

# useIntersectionObserver

Observe viewport intersection with an `IntersectionObserver`. Browser composable — import from `@sigx/use-web`.

The observer **follows reactive targets**, supports [`pause()`/`resume()`](/use/docs/conventions#control-handles-pausable-and-stop) without losing its config, and disconnects with the owning scope. Point it at a single [element target](/use/docs/conventions#element-targets-web) or an array.

```ts
import { signal } from 'sigx';
import { useIntersectionObserver } from '@sigx/use-web';

const sentinel = signal<HTMLElement | null>(null);
// <div ref={sentinel}> …

useIntersectionObserver(sentinel, ([entry]) => {
    if (entry.isIntersecting) loadMore();
});
```

The callback is the native `IntersectionObserverCallback` — you get `IntersectionObserverEntry[]`. Configure `root` (an [element target](/use/docs/conventions#element-targets-web) or `Document`), `rootMargin`, and `threshold` as with the native observer.

> Just need a reactive "is it on screen?" boolean? Use [`useElementVisibility`](/use/docs/use-element-visibility), which wraps this.

## Signature

```ts
function useIntersectionObserver(
    target: MaybeSignalElement | MaybeSignalElement[],
    callback: IntersectionObserverCallback,
    options?: UseIntersectionObserverOptions,
): UseIntersectionObserverReturn;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `root` | `MaybeSignalElement \| Document` | viewport | Intersection root to observe within. |
| `rootMargin` | `string` | `'0px'` | Margin around the root (native `rootMargin`). |
| `threshold` | `number \| number[]` | `0` | Visibility ratio(s) that trigger the callback. |
| `immediate` | `boolean` | `true` | Start observing on creation. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). |

## Returns

```ts
interface UseIntersectionObserverReturn extends Pausable {
    isSupported: ReadSignal<boolean>;
    stop: Stop;
}
```

Extends [`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop) (`isActive`, `pause`, `resume`) with `isSupported` and a `stop` that disconnects the observer.

## SSR

Inert: on the server or where `IntersectionObserver` is unavailable, `isSupported` is `false` and the observer never runs.

## See also

- [`useElementVisibility`](/use/docs/use-element-visibility) — reactive boolean built on this.
- [`useResizeObserver`](/use/docs/use-resize-observer) — the size counterpart.
- [Conventions → Control handles](/use/docs/conventions#control-handles-pausable-and-stop) — `Pausable` and `Stop`.

---
url: https://sigx.dev/actors/docs/state-and-persistence/
title: State & persistence
description: ctx.save(), write-behind, rich types across storage, and migrateState for records whose shape predates this deploy
---

# State & persistence

<p class="lede">Persistence is explicit by default: only `ctx.save()` writes. A method that
returns success has persisted what it acknowledged.</p>

## Explicit saves

```ts
methods: (ctx) => ({
    async addItem(item: Item) {
        ctx.state.items.push(item);
        await ctx.save();            // durable before we ack
        return ctx.state.items.length;
    },
})
```

`ctx.state` is a deep reactive proxy — mutate it directly, no setter and no immutable update
needed. `ctx.save()` writes the whole state through the [`ActorStorage`](/actors/docs/storage)
seam with an **etag**, so a conflicting writer is detected rather than overwritten.

Forget the `await` and you have told the caller a thing is durable when it is not. That is the
one mistake this API can't stop you making, which is why the default is explicit.

## Write-behind

```ts
persistence: { mode: 'write-behind', debounceMs: 200 }
```

Saves automatically after mutating turns, debounced. Pending writes flush on deactivation and
on shutdown.

> **Acked ≠ persisted under write-behind.** A method can return success for state that is
> still only in memory. Use it for state you can afford to lose — a presence marker, a
> scroll position, a hit counter — and not for anything a user believes they have saved.

## Rich types survive

`Date`, `Map`, `Set`, `bigint`, `URL`, `RegExp` and your own registered handlers round-trip
through storage *and* the wire, because both use the same
[`@sigx/serialize`](/server/packages/serialize/overview) vocabulary.

```ts
state: () => ({ lastVisit: null as Date | null, tags: new Set<string>() }),
```

`lastVisit` is a real `Date` when it comes back out of storage, and a real `Date` in the
browser. Register your own types with `defineTypeHandler` and add them via the app's `types:`
option or a plugin's `addTypeHandlers`.

## Conflicts

Every save is compare-and-set on the etag. If another activation wrote first, yours raises
`ActorStateConflictError` and the stale activation is faulted — the next call activates fresh
against the winning state.

You do not normally handle this. It means the single-activation invariant was briefly violated
— a network partition, a directory hiccup, a migration — and the recovery is automatic. What
it *is* good for is alerting: a steady trickle of conflicts says something in your cluster is
wrong. See [Metrics](/actors/docs/metrics).

## Migrating state

`migrateState` evolves a record whose shape predates this deploy — the answer to "the `state:`
shape changed and the stored records didn't."

```ts
defineActor({
    type: 'Cart',
    state: () => ({ v: 2, items: [], coupons: [] }),
    migrateState: (stored) => {
        const s = stored as CartV1 | CartV2;
        if ('v' in s) return s;                              // fast path
        return { v: 2, items: s.items ?? [], coupons: [] };  // v1 → v2
    },
});
```

**When it runs.** Between the storage read and activation, and only on a load that *found* a
record — never on the fresh `state(key)` path, never after `ctx.clearState()`. Always before
`onActivate`, which therefore always sees migrated state.

**What it receives.** The codec-revived state, so `Date` and `Map` are already real objects.
`unknown` here means unknown *shape*, not raw JSON. A second argument carries `{ raw, key }`
when the revived view cannot tell two stored versions apart — `raw` is the encoded record as
storage holds it.

**Returning the input unchanged is the fast path**, and identity is how that is detected. To
migrate, return a *new* object.

**Write-back is lazy, and that is the contract.** The migrated shape rides the next save the
actor would have made anyway, so a read-only activation still issues zero writes and a rolling
deploy costs no extra ones. This holds in both persistence modes — `migrateState` never causes
a write by itself, so a write-behind actor that is only ever *read* after a migration does not
persist it.

For a record that would otherwise never be saved at all — and so would be re-migrated on every
activation forever — opt into one CAS write-back at activation:

```ts
migrateState: { persist: 'eager', migrate: (stored) => /* … */ },
```

**Concurrent migration is safe by design.** A fleet mid-deploy can migrate the same record on
several hosts. The hook is a pure function of the stored value and every write is etag-CAS'd,
so first save wins and the loser either adopts the winner (eager) or takes
`ActorStateConflictError` and re-activates against it (lazy).

**Failure is loud.** The hook is synchronous; a throw fails activation with
`ActorActivationError` and leaves the stored record untouched. Corrupt state is never silently
reset. Malformed declarations throw at definition time, and an `async` hook is a type error.

**Non-goals.** Version-field bookkeeping is your convention — the runtime neither reads nor
writes one. And this is not a scheme for versioning an actor's *interface* across a
mixed-version fleet.

> **`defineJob` does not accept `migrateState`.** A job's stored record is the job envelope —
> `status`, `progress`, `checkpoint` and so on, with your own state under `extra` — so a hook
> over it would hand you a runtime shape you do not own. Migrating the `extra` half wants its
> own option, and is not part of this. See [Jobs](/actors/docs/jobs).

## Providers

| Provider | Use |
|---|---|
| `memoryStorage()` | tests and dev |
| `fileStorage({ dir })` | dev — one cat-able JSON file per actor |
| [`redisStorage`](/actors/packages/actors-redis/overview) | production, with the cluster providers |
| [`pgStorage`](/actors/packages/actors-pg/overview) | production, `text` rows with etag CAS |

Implement `ActorStorage` — `load` / `save` / `clear` with etags — for anything else. See
[Storage](/actors/docs/storage).

## Next steps

- [Storage](/actors/docs/storage) — the seam and how to implement it.
- [Lifecycle](/actors/docs/lifecycle) — when state is loaded and flushed.
- [Reentrancy](/actors/docs/reentrancy) — how interleaving changes save semantics.

---
url: https://sigx.dev/use/docs/create-shared-composable/
title: createSharedComposable
description: Reference-counted sharing of an effect-ful composable — N callers share one instance, torn down when the last subscriber leaves
---

# createSharedComposable

Reference-counted sharing of an effect-ful composable: the first subscriber runs it in a fresh detached `effectScope`; later subscribers get the same result. Cross-platform — import from `@sigx/use`.

```ts
import { createSharedComposable } from '@sigx/use';
import { useMouse } from '@sigx/use-web';

export const useSharedMouse = createSharedComposable(useMouse);

// in any number of components — ONE mousemove listener total:
const mouse = useSharedMouse();
```

This is the standard way to turn a per-caller sensor into an app singleton — N components share ONE `mousemove` listener (see [`useMouse`](/use/docs/use-mouse)). When the **last** subscriber's scope disposes, the shared scope stops (listeners detach, timers clear) and the next call re-creates everything.

## Refcount semantics

Subscribers are counted **per in-scope call** — each call registers a matching dispose with its owning scope. Calling twice in one scope counts twice, and both disposers fire together when that scope stops.

> Calls made **outside** any component or `effectScope` don't participate in refcounting: they receive (and, when first, create) the shared state without incrementing the count. So a shared instance created by an out-of-scope call lives until a later scoped subscriber's dispose brings the count back to zero. **Prefer calling from a scope** (a component setup, or wrap standalone use in `effectScope()`).

## Signature

```ts
function createSharedComposable<Fn extends (...args: never[]) => unknown>(composable: Fn): Fn;
```

The returned function has the same signature as the composable you pass.

**Platform:** everywhere.

## See also

- [`createGlobalState`](/use/docs/create-global-state) — a never-disposed singleton for plain state factories (no refcounting).
- [`useMouse`](/use/docs/use-mouse) — the canonical sensor to share this way.
- [`@sigx/store`](/store) — `defineStore` for structured, per-user application state.

---
url: https://sigx.dev/actors/docs/health-and-readiness/
title: Health & readiness
description: health() — why liveness and readiness are allowed to disagree, the fenced state, and the fatal flag that forces a restart
---

# Health & readiness

<p class="lede">Two probes, and the important thing about them is that they are **allowed to
disagree**.</p>

```ts
import { health } from '@sigx/actors/host';

export const app = defineActorApp({ actors, storage })
    .use(cluster({ providers, advertise, secret }))
    .use(health());
```

| Route | Answers |
|---|---|
| `GET /_sigx/health` | liveness — is this process alive? |
| `GET /_sigx/health/ready` | readiness — should it receive traffic? |

## The three states

| State | Liveness | Readiness | What to do |
|---|---|---|---|
| **active** | 200 | 200 | normal |
| **leaving / draining** | 200 | 503 | drain it; **do not restart** |
| **fenced** | 503 `{status:'fatal'}` | 503 | restart the pod |

A graceful `host.stop()` announces `leaving` before handoff — it is alive and finishing work,
so restarting it is exactly wrong.

**The fenced state is the one nothing else catches.** A host that loses its membership
heartbeat refuses every activation while its *published* status still says `active`. Only
readiness sees it.

## `fatal` forces a restart

A readiness check can declare the process unrecoverable:

```ts
registry.reportHealth('membership', () => ({ ready: false, fatal: true, detail: 'fenced' }));
```

`fatal` implies not-ready, and the **liveness** route then answers `503 {status:'fatal'}` so
the orchestrator restarts the pod. `cluster()` marks `fenced` fatal for you.

Why fenced must restart rather than recover: host identities are minted per start, and a
cluster host id is gone once its membership entry is. The fence is permanent for the process.

## The readiness seam

```ts
registry.reportHealth('db', () => ({ ready: await pingOk(), detail: 'primary' }));
registry.health();   // the aggregate
```

Every check must pass. All of them are evaluated, so a failing probe names **every** reason
rather than the first. A throwing check reads as not-ready rather than a 500 —
a health endpoint that 500s is a second incident on top of the first.

`cluster()` registers its own, which is why `health()` needs no wiring.

## Before `start()`

The whole mount answers 503, **including liveness**. Kubernetes therefore needs a
`startupProbe`, or the liveness probe will kill the pod during a slow boot:

```yaml
startupProbe:
  httpGet: { path: /_sigx/health, port: 7311 }
  failureThreshold: 30
  periodSeconds: 2
livenessProbe:
  httpGet: { path: /_sigx/health, port: 7311 }
readinessProbe:
  httpGet: { path: /_sigx/health/ready, port: 7311 }
```

## Probes cannot be authenticated

A kubelet cannot sign the cluster HMAC, so these routes are unauthenticated by necessity —
which is why they must be **internal-only**, and why they deliberately withhold `perType`
detail.

```ts
health({ detail: false });   // reduce the body to the status code
```

The asymmetry is the design: `health()` answers *may I take traffic?* in a **status code** and
cannot be authenticated. [`ops()`](/actors/docs/ops-endpoint) answers *what is going on in
here?* in a **body**, is authenticated, and may therefore carry actor type names and cluster
topology.

## Next steps

- [The ops endpoint](/actors/docs/ops-endpoint) — the authenticated half.
- [Kubernetes](/actors/docs/kubernetes) — the full manifest.
- [Clustering](/actors/docs/clustering) — draining and handoff.

---
url: https://sigx.dev/actors/docs/timers-and-reminders/
title: Timers & reminders
description: ctx.timer for volatile ticks and ctx.reminders for durable wake-ups that re-activate an idle or restarted actor
---

# Timers & reminders

<p class="lede">Two mechanisms, and the difference is the whole point: a timer dies with the
activation, a reminder survives a restart and brings the actor back.</p>

## Timers — volatile

```ts
ctx.timer('poll', async () => {
    ctx.state.checkedAt = new Date();
    await ctx.save();
}, { due: 1_000, period: 5_000 });
```

Ticks run as ordinary [turns](/actors/docs/turns), so they serialize with your methods and cannot race your
state. Under load they **coalesce** rather than pile up.

A timer **does not keep the actor alive**. If the actor goes idle it deactivates, and the
timer goes with it. That is deliberate: a volatile timer is a convenience, not a reason to pin
an object in memory. Pass `keepAlive: true` when you really do want the actor held open.

Use a timer for something that only matters while the actor is already active — refreshing a
cached value, expiring an in-memory lease, driving an animation of state you are streaming.

## Reminders — durable

```ts
await ctx.reminders.set('daily-digest', { due: 60_000, period: 86_400_000 });
```

```ts
defineActor({
    type: 'Digest',
    async onReminder(ctx, name) {
        if (name === 'daily-digest') await sendDigest(ctx.state);
    },
    // …
});
```

Reminders are stored through [`ActorStorage`](/actors/docs/storage), fired by the host's
scheduler, and they **re-activate an idle or restarted actor**. That is the capability a
stateless function has nowhere to put.

The contract, stated precisely:

- **Minimum period 60 seconds.** Reminders are not a scheduler for sub-minute work; use a
  timer or a [task](/actors/docs/tasks).
- **Coarse resolution** — "at or after `nextDue`", checked every `reminderTickMs` (default
  30s). Not a cron guarantee.
- **At-most-once per tick.** A reminder is a wake-up, not a queue. If the work must not be
  lost, make it idempotent or record progress in state.

## Choosing

| Want | Use |
|---|---|
| A tick while the actor is busy anyway | `ctx.timer` |
| To wake up in an hour, even after a deploy | `ctx.reminders` |
| Sub-second precision | neither — drive it from the caller |
| Something that must run exactly once | a [job](/actors/docs/jobs) |

## Pluggable backends

`ActorReminders` is a seam. The default rides your storage through `shardedReminders()`, and
providers replace it:

- [`pgReminders()`](/actors/packages/actors-pg/overview) — a due-time-indexed table claimed
  with `SKIP LOCKED`, at-most-once, no catch-up bursts.
- [`durableObjectReminders()`](/actors/packages/actors-cloudflare/overview) — the Durable
  Object alarm. Semantics differ visibly here: an alarm fires **at** the due time, where
  `shardedReminders()` promises only "at or after".

## The clock is a seam

Background work — the idle sweeper, the reminder tick, `ctx.timer`, write-behind flushes — all
runs on an `ActorScheduler` rather than on bare `setTimeout`. Set it on the app:

```ts
import { manualScheduler } from '@sigx/actors/host';

const scheduler = manualScheduler();
const app = defineActorApp({ actors, scheduler, defaults: { idleAfterMs: 0 } });
```

`timerScheduler()` is the default and uses host timers. `manualScheduler()` is driven by hand,
which is how you test idle deactivation, reminders and write-behind without sleeping:

```ts
scheduler.advance(60_000);   // an hour of sweeps, instantly
```

`advance(ms)` fires due jobs in order and cannot go backwards.

**Why it is a seam rather than a test shim.** Background work is exactly the set of jobs that
must keep running *between* requests — and a Cloudflare Worker only runs while it is handling
one, so an interval registered at startup never fires there. A platform that schedules
differently supplies its own scheduler instead of losing the capability.

Two things deliberately do **not** go through it: call deadlines and the shutdown drain. Both
are scoped to an in-flight request or to `stop()`, so they stay on host timers.

## Cron-shaped work

There is no cron API, deliberately. The pattern is an actor per schedule that re-arms a
one-shot reminder from inside `onReminder` — written up in `docs/job-recipes.md` in the actors
repo, along with a singleton queue-worker and the Cloudflare caveats.

## Next steps

- [Lifecycle](/actors/docs/lifecycle) — what keeps an actor alive.
- [Tasks](/actors/docs/tasks) — long-running work inside an activation.
- [Jobs](/actors/docs/jobs) — durable, resumable, observable work.

---
url: https://sigx.dev/lynx/docs/platform-specific-code/
title: Platform-specific code
description: Branch between iOS, Android and web — at runtime, at build time, or per file
---

# Platform-specific code

<p class="lede">One component tree runs on iOS, Android and the web. Where they need to diverge, SignalX gives you three tools — pick by <em>when</em> the split happens.</p>

There are two axes to keep straight:

- **web ↔ native** is a **build-time** split. The web and native bundles are produced separately, so you can fully drop code from the bundle that doesn't need it. Branch on the `__WEB__` / `__NATIVE__` defines, or split by file extension (`.web.tsx` / `.lynx.tsx`).
- **iOS ↔ Android** is a **runtime** split. iOS and Android share one native bundle, so there is nothing to drop at build time — discriminate at runtime with `Platform.OS` / `Platform.select`.

> **Key constraint:** file/define splitting is **web↔native only**. iOS and Android share one native bundle; there is no `__IOS__` define and no `.ios.tsx` resolution. Split those two at runtime.

## Runtime: `Platform`

`Platform` is re-exported from `@sigx/lynx` (it lives in `@sigx/lynx-core`) and is read once from the Lynx `SystemInfo` global. Use it for iOS-vs-Android differences and for reading display metrics.

```tsx
import { Platform } from '@sigx/lynx';

Platform.OS;       // 'ios' | 'android' | 'web'
Platform.Version;  // '17.4' / '14'
Platform.isPad;    // best-effort iPad detection
Platform.pixelRatio;
Platform.pixelWidth;
Platform.pixelHeight;
```

`Platform.select` picks a value for the current platform. Precedence is exact OS key → `native` (matches `ios`/`android`) → `default`. It is presence-based, not truthiness, so an explicit `undefined` for the matching key is honored.

```tsx
import { Platform } from '@sigx/lynx';

// Providing `default` makes the return non-optional.
const spacing = Platform.select({ ios: 12, android: 8, default: 10 }); // number

// `native` matches both iOS and Android; `web` takes the other branch.
const transport = Platform.select({ web: webTransport, native: nativeTransport });
```

`Platform.OS === 'web'` is a *runtime* check — it does **not** tree-shake, because a property read can't fold across modules. For dropping code from a bundle, use the build-time tools below.

## Build-time: `__WEB__` / `__NATIVE__` defines

`@sigx/lynx-plugin` injects the `__WEB__` and `__NATIVE__` defines per environment, folding each to a literal `true` / `false`. Branch on the raw globals and the minifier eliminates the dead branch from the other bundle:

```tsx
if (__WEB__) {
  // only the web bundle keeps this; dropped from native
} else {
  // only the native bundle keeps this
}
```

`__NATIVE__` is always `!__WEB__`. Use this when a branch imports something that only exists on one platform — the dead branch (and its imports) never reach the other bundle.

### `__MAIN_THREAD__` / `__BACKGROUND__`

A second pair splits by **thread layer** rather than platform. A Lynx bundle is emitted per layer, so these fold to literals independently in each and dead-code-eliminate the same way:

```tsx
if (__BACKGROUND__) {
  // only the background-thread layer keeps this
}
```

Use them to keep layer-specific setup out of the layer that will never run it. They apply to **app code** — a packaged dist does not get the per-layer fold.

To type the defines, reference the client types once at your source root (`env.d.ts`):

```ts
/// <reference types="@sigx/lynx/client" />
```

That declares `__WEB__` and `__NATIVE__` as `boolean` so they typecheck everywhere.

## Build-time: file-extension resolution

For a whole-module split, give a module platform-specific files. The plugin resolves `.web.tsx` / `.lynx.tsx` / `.native.tsx` ahead of the generic file, so the importer never names a platform:

```
Map.web.tsx     // resolved for the web bundle
Map.lynx.tsx    // resolved for the native bundle
Map.tsx         // fallback
```

```tsx
import { Map } from './Map'; // picks Map.web.tsx or Map.lynx.tsx per bundle
```

Each file exports the same shape; the importer is platform-agnostic. As with the defines, this is **web↔native only** — there is no `.ios.tsx` / `.android.tsx` resolution.

## Choosing

| Difference | Tool |
|---|---|
| iOS vs Android | `Platform.OS` / `Platform.select` (runtime) |
| A few lines differ between web and native | `__WEB__` / `__NATIVE__` (build-time, tree-shaken) |
| A whole module differs between web and native | `.web.tsx` / `.lynx.tsx` files |
| A per-platform constant or display metric | `Platform.select` / `Platform.pixelRatio` etc. |

## See also

- [`@sigx/lynx-core` API](/lynx/modules/core/api#platform) — every `Platform` and `DeviceInfo` export.
- [Reactivity bridge](/lynx/docs/reactivity) — the background ↔ main-thread model.

---
url: https://sigx.dev/monaco/docs/imperative-and-shiki/
title: Imperative editors and Shiki highlighting
description: Create editors imperatively with createEditor and add TextMate-grade highlighting with the Shiki subpath
---

# Imperative editors and Shiki highlighting

The `<MonacoEditor />` component covers most cases, but you can also drop down to the imperative API when you need full control over the editor lifecycle, or add Shiki for TextMate-grade syntax highlighting.

## Creating an editor imperatively

`createEditor()` is the low-level building block the component is built on. It awaits `loadMonaco()`, creates a uniquely-named model, applies the editor defaults, wires `onChange`, and returns a live Monaco editor instance.

```tsx
import { createEditor } from '@sigx/monaco-editor';

const container = document.getElementById('editor')!;

const editor = await createEditor({
    container,
    value: 'const x: number = 1;\n',
    language: 'typescript',
    theme: 'vs-dark',
    onChange: (value) => {
        console.log('content changed:', value);
    },
});

// editor is a Monaco IStandaloneCodeEditor — use the full Monaco API.
editor.focus();

// Dispose when you are done.
editor.dispose();
```

`createEditor()` applies sensible defaults: `theme: 'vs-dark'`, `readOnly: false`, minimap off, `lineNumbers: 'on'`, `fontSize: 14`, `automaticLayout: true`, `tabSize: 2`, `wordWrap: 'on'`, and `fixedOverflowWidgets: true`. The `language` defaults to `'typescript'`. Pass raw Monaco construction options via `monacoOptions` to override anything:

```tsx
const editor = await createEditor({
    container,
    value: '',
    language: 'json',
    monacoOptions: { minimap: { enabled: true }, scrollBeyondLastLine: false },
});
```

### The TSX/JSX trick

When you ask for `tsx` or `jsx`, `createEditor()` first creates the model with the base `typescript`/`javascript` language id (so the TS worker assigns the correct script kind), then swaps the model language to `tsx`/`jsx` for highlighting. The TypeScript pack registers tsx/jsx completion and hover providers off the TS worker so IntelliSense survives the swap. This happens automatically — just pass `language: 'tsx'`.

## Loader control

If you need to load Monaco yourself or inspect loader state, use the loader exports directly. Register languages/themes with `configureMonaco()` and override the strategy with `configureMonacoLoader()` before the first `loadMonaco()`:

```tsx
import {
    configureMonacoLoader,
    loadMonaco,
    isMonacoLoaded,
    getMonaco,
} from '@sigx/monaco-editor';

// Must run before loadMonaco() — warns if Monaco is already loaded.
configureMonacoLoader({ strategy: 'cdn', version: '0.55.1' });

const monaco = await loadMonaco(); // idempotent; caches after first call

if (isMonacoLoaded()) {
    // Synchronous accessor — throws if not yet loaded.
    const m = getMonaco();
    m.editor.setTheme('vs-dark');
}
```

## Shiki highlighting

For TextMate-grade highlighting (and theme parity with static code blocks), use the optional Shiki integration from the `@sigx/monaco-editor/shiki` subpath. It dynamically imports `shiki/core`, the JS regex engine, and `@shikijs/monaco`, creates a highlighter, optionally registers Monaco languages first, then wires the grammars and themes into the live Monaco instance.

Install the optional peers first:

```bash
pnpm add @shikijs/monaco shiki
```

Then apply themes after Monaco loads. Pass `import()` promises (or already-resolved objects) for the themes and langs:

```tsx
import { loadMonaco } from '@sigx/monaco-editor';
import { applyShikiThemes } from '@sigx/monaco-editor/shiki';

const monaco = await loadMonaco();

const { highlighter } = await applyShikiThemes(monaco, {
    themes: [import('@shikijs/themes/github-dark')],
    langs: [import('@shikijs/langs/tsx')],
    // Register Monaco languages before wiring grammars (omit if already registered).
    monacoLanguages: [{ id: 'tsx', extensions: ['.tsx'] }],
});

// Reuse the returned highlighter to render static code outside Monaco.
const html = await (highlighter as any).codeToHtml('const x = 1', {
    lang: 'tsx',
    theme: 'github-dark',
});
```

`applyShikiThemes()` returns `{ highlighter }` (a Shiki `HighlighterCore`) so you can reuse it for non-Monaco code.

## Next steps

- [Language packs and IntelliSense](/monaco/docs/language-packs)
- [API Reference](/monaco/docs/api)

---
url: https://sigx.dev/use/docs/use-document-visibility/
title: useDocumentVisibility
description: Reactive document.visibilityState via the visibilitychange event
---

# useDocumentVisibility

Reactive `document.visibilityState` via the `visibilitychange` event. Browser composable — import from `@sigx/use-web`.

```ts
import { watch } from 'sigx';
import { useDocumentVisibility } from '@sigx/use-web';

const visibility = useDocumentVisibility();
watch(visibility, v => v === 'visible' && refetch()); // refetch when the tab returns
```

The return is a [`ReadSignal<DocumentVisibilityState>`](/use/docs/conventions#outputs-single-value--readsignalt) — `'visible'` or `'hidden'`.

## Signature

```ts
function useDocumentVisibility(options?: ConfigurableDocument): ReadSignal<DocumentVisibilityState>;
```

Pass `{ document }` to drive it from another document or a mock — see [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides).

## SSR

On the server the signal reads `'visible'`, then reflects the real `document.visibilityState` on mount.

## See also

- [`useOnline`](/use/docs/use-online) — pair with connectivity to gate background work.
- [`useNetwork`](/use/docs/use-network) — full reactive network state.
- [`useIntervalFn`](/use/docs/use-interval-fn) — pause polling while the tab is hidden.

---
url: https://sigx.dev/terminal/docs/layout-and-styling/
title: Layout & Styling
description: Boxes, borders, colors and the terminal line layout model
---

# Layout & Styling

The terminal renderer walks your component tree into an array of ANSI-styled lines and paints them every frame. This guide covers the three intrinsic elements, the line layout model, and how colors and borders work.

## The intrinsic elements

`@sigx/terminal` provides three host elements you can use in TSX:

- **`box`** — a block container that can draw a border, a centered label, a background and a drop shadow.
- **`text`** — an inline run of text, optionally colored.
- **`br`** — a hard line break that starts a new line.

```tsx
import { component, defineApp } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box border="single" label="Demo">
            <text>First line of </text>
            <text color="cyan">inline text.</text>
            <br />
            <text>Second line after a break.</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## How layout works

The layout is a simple inline/block line flow — not a full flexbox engine. There are no row/column, justify or align props. The rules are:

- A `box` (and any element whose immediate child is a `box`) is treated as a **block** — it gets its own lines.
- `text` and other single-line children are appended **inline** to the current line.
- A `br` forces a new line.
- Multi-line non-box children are promoted to block so they don't break a surrounding border.

So to stack content vertically, wrap each row in its own `box`, or separate runs with `br`:

```tsx
<box border="rounded" label="Stacked">
    <box><text>Row one</text></box>
    <box><text>Row two</text></box>
    <box><text>Row three</text></box>
</box>
```

## Layout primitives

For real horizontal and vertical layout, the foundation ships components that compose `box` for you:

- **`Box`** — the themed container: `border` (`single` / `double` / `rounded` / `thick` / `none`), `borderColor`, `backgroundColor`, `label`, `labelColor`, `padX`, `dropShadow`.
- **`Row`** — lays children out **horizontally** with a `gap` and `align` (`start` / `center` / `end`, plus `top` / `bottom`).
- **`Col`** — stacks children **vertically** with a `gap`.
- **`Spacer`** — inserts blank `size` lines (vertical spacing).
- **`Divider`** — a horizontal rule with an optional centered `label` and `color`.

```tsx
import { component, defineApp, Box, Row, Col, Divider } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <Box border="rounded" label="Dashboard">
            <Row gap={2} align="center">
                <Box border="single" label="Left"><text>A</text></Box>
                <Box border="single" label="Right"><text>B</text></Box>
            </Row>
            <Divider label="logs" />
            <Col gap={1}>
                <text>line one</text>
                <text>line two</text>
            </Col>
        </Box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

The `box`/`text`/`br` intrinsics below are the lower-level host elements these primitives render to. Use the intrinsics for fine control or the primitives for ordinary layout.

## Borders

The `border` prop accepts `single`, `double`, `rounded` or `thick`. To draw **no** border, use `none` (the `Box` component) or omit the prop entirely (the `box` intrinsic):

```tsx
<box border="single">...</box>    {/* ┌─┐ │ └─┘ */}
<box border="double">...</box>    {/* ╔═╗ ║ ╚═╝ */}
<box border="rounded">...</box>   {/* ╭─╮ │ ╰─╯ */}
<box border="thick">...</box>     {/* ┏━┓ ┃ ┗━┛ */}
<box>...</box>                     {/* no border */}
```

> The renderer draws a border only when `border` is truthy, and `"none"` counts as falsy — so `border="none"` and leaving the prop off are the same thing. Any *other* unrecognized value falls back to the single-line style.
>
> A borderless box also costs nothing: `padX` and `dropShadow` are drawn by the border pass, so on a bare `<box>` they are silently inert. [`boxChrome`](/terminal/docs/api#boxchrome) takes the `border` prop directly for exactly this reason.

Set `borderColor` to color the border with a named color, and `label` to render a centered caption in the top border, like a fieldset legend:

```tsx
<box border="rounded" borderColor="cyan" label="Settings">
    <text>Configuration goes here.</text>
</box>
```

## Colors

Colors use a fixed named palette mapped to ANSI codes:

`red`, `green`, `blue`, `yellow`, `cyan`, `white`, `black`.

```tsx
<box backgroundColor="blue" borderColor="white">
    <text color="yellow">Warning</text>
    <br />
    <text color="green">OK</text>
</box>
```

- `color` styles text foreground.
- `backgroundColor` fills the box padding and border area.
- `borderColor` colors the border characters.

> Only the named palette resolves to an ANSI code. Arbitrary strings or hex values such as `#666666` produce no color, so stick to the named set.

## Drop shadow

`dropShadow` adds a gray shadow on the right and bottom edges of a box:

```tsx
<box border="single" label="Card" dropShadow={true}>
    <text>This box casts a shadow.</text>
</box>
```

## Putting it together

```tsx
import { component, defineApp, signal } from '@sigx/terminal';

const App = component(() => {
    const status = signal<'ok' | 'warn'>('ok');

    return () => (
        <box border="rounded" label="Dashboard" borderColor="cyan" dropShadow={true}>
            <box>
                <text>Status: </text>
                <text color={status.value === 'ok' ? 'green' : 'yellow'}>
                    {status.value === 'ok' ? 'Healthy' : 'Degraded'}
                </text>
            </box>
            <box backgroundColor="blue">
                <text color="white">Background-filled row</text>
            </box>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Tokens vs named colors

The named palette above maps to fixed ANSI codes. The themed components and the `Box`/`Text` primitives instead accept **theme tokens** (`accent`, `fg`, `line`, …) that resolve against the active theme and adapt to the terminal's color depth — see [Theming](/terminal/docs/theming). Use named colors for quick scripts; use tokens for themed apps.

## Next steps

- [Typography](/terminal/docs/typography) — `Text` and `Heading` for styled, token-aware text.
- [Theming](/terminal/docs/theming) — semantic tokens and the built-in themes.
- [Input & Interactive Components](/terminal/docs/input-and-components) — focus and the built-in widgets.
- [Components](/terminal/docs/components) — the full component library.
- [API Reference](/terminal/docs/api) — the full export list.

---
url: https://sigx.dev/use/docs/use-element-visibility/
title: useElementVisibility
description: Whether an element intersects the viewport (or a scroll container), as a reactive boolean over an IntersectionObserver
---

# useElementVisibility

Whether an element intersects the viewport (or a scroll container), as a reactive boolean. Browser composable — import from `@sigx/use-web`.

It builds on [`useIntersectionObserver`](/use/docs/use-intersection-observer) and returns a [`ReadSignal<boolean>`](/use/docs/conventions#outputs-single-value--readsignalt).

```ts
import { signal, effect } from 'sigx';
import { useElementVisibility } from '@sigx/use-web';

const heroRef = signal<HTMLElement | null>(null);
// <section ref={heroRef}> …

const visible = useElementVisibility(heroRef);
effect(() => {
    if (visible.value) startAnimation();
});
```

Pass any [element target](/use/docs/conventions#element-targets-web). Set `scrollTarget` to observe within a scroll container instead of the viewport, and `threshold` to require more of the element on screen before it counts as visible.

## Signature

```ts
function useElementVisibility(
    target: MaybeSignalElement,
    options?: UseElementVisibilityOptions,
): ReadSignal<boolean>;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `threshold` | `number` | — | Visibility ratio required before `visible` flips true. |
| `scrollTarget` | `MaybeSignalElement` | viewport | Observe within this scroll container instead of the viewport. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). |

## SSR

`false` — the element is reported not visible until the observer runs on mount.

## See also

- [`useIntersectionObserver`](/use/docs/use-intersection-observer) — the observer this wraps; use it for entry-level detail or `pause`/`resume`.
- [`useElementSize`](/use/docs/use-element-size) — the size counterpart, over `useResizeObserver`.

---
url: https://sigx.dev/actors/docs/cloudflare-workers/
title: Cloudflare Workers
description: Running actors on Durable Objects — the one-bundle setup, the app factory, and three gotchas each worth its own callout
---

# Cloudflare Workers

<p class="lede">Cloudflare already guarantees one instance of a Durable Object globally and
serializes its requests — which *is* the virtual-actor contract. So there is no membership, no
directory and no authenticated host mount: the platform is the cluster.</p>

```bash
pnpm add @sigx/actors-cloudflare
```

## The entry

The Durable Object and the Worker are the **same bundle**, which is why the actor registry is
a plain import and needs no build-time indirection.

```ts
import { createHostDurableObject, createWorkerHandler } from '@sigx/actors-cloudflare';
import { createApp } from './actors.app';
import { Counter } from './counter.actor';
import { servePage } from './page';

export interface Env { ACTORS: DurableObjectNamespace }

const actors = [Counter, Ticker];

// The object: hosts exactly the actor its id names.
export class ActorHost extends createHostDurableObject<Env>({
    actors,
    namespace: (env) => env.ACTORS,
    app: createApp,
}) {}

// The edge: hosts nothing, routes everything.
export default createWorkerHandler<Env>({
    actors,
    namespace: (env) => env.ACTORS,
    app: createApp,
    fetch: { origin: false, fallback: servePage },
});
```

Both need the registry: the Worker to run guards, tell a stream method from a unary one and be
the 404 authority; the object to actually activate.

## Pass an app *factory*, not an app

```ts
export const createApp = (base: ActorAppOptions) => defineActorApp(base).use(metrics());
export const { defineActor } = createApp({});   // type-only binding, never started
```

Building the app at module scope — which is fine on Node — binds whichever Durable Object
constructed it first, and every other object is then served from **those** seams. The factory
receives the object's own storage, reminders and defaults and must pass them on.

It never receives `env`, so it cannot reach a namespace binding and build a placement of its
own.

## One placement runs on both sides

> **This is the single most important thing to understand here, because the wrong version
> looks more natural.**

Using the plain local host *inside* a Durable Object silently corrupts state: a cross-actor
call would activate the callee **inside the caller's object**, writing its record into the
wrong storage and violating single activation.

`durableObjectPlacement()` runs on both sides. Inside an object it needs `isSelf`:

```ts
durableObjectPlacement({ isSelf: (ref) => actorId(ref) === state.id.name });
```

In the Worker there is no `isSelf` — everything is remote.

There is no HMAC and no 421 retry here, deliberately. A stub is not network-reachable, so
holding the binding **is** the capability grant, and guards run once at the public edge. And
ref → object id is a pure function, so a mismatch is a config bug rather than a race.

## Identity versus routing

`locationHint` is a hint and safe to change. **`jurisdiction` and `objectName` are part of
identity**, so changing either is a state migration.

## Three gotchas

> **`new_sqlite_classes`, not `new_classes` — a one-way door.** `new_classes` creates the
> legacy key-value backed storage, which cannot be migrated to SQLite in place; the class is
> stuck with it forever, with a far smaller per-value limit. This is the single most
> consequential irreversible line in `wrangler.jsonc`.

> **`__DEV__` must be defined by the bundler.** The published package ships both a dev and a
> production dist and expects its bundler to define the flag. Without
> `"define": { "__DEV__": "false" }` the host throws `__DEV__ is not defined` on the first
> request.

> **The public mount needs an explicit `origin` policy.** Workers callers are not browsers
> posting a form, and the mount defaults to refusing a request with no `Origin` — so ordinary
> calls are rejected as cross-origin. `origin: false` is right for a service; a browser
> front-end should pass its own origin list.

## Client sockets

Browsers can speak [`@sigx/actors/socket-wire`](/actors/docs/wire-protocol#the-socket-wire)
over a WebSocket here, with `socketTransport()` from
[`@sigx/actors-ws`](/actors/packages/actors-ws/overview) on the client side unchanged. There
are two places the socket can terminate, and the choice is about **who the connection belongs
to**.

| | Worker-terminated | Object-terminated |
|---|---|---|
| Upgrade path | `{path}` | `{path}/{type}/{key}` |
| Sockets | one per **client** | one per **actor** |
| Reach | every actor, multiplexed | that one actor |
| Releases a departed consumer's `keptAlive` | no | **yes** |
| Survives hibernation | n/a — the Worker holds nothing | yes |
| Good for | a dashboard watching many actors | a room many clients watch |

### Worker-terminated

```ts
export default createWorkerHandler<Env>({
    actors,
    namespace: (env) => env.ACTORS,
    app: createApp,
    socket: { path: '/_sigx/socket' },        // terminate: 'worker' is the default
});
```

Sugar for `app.use(workerSocket(...))`. The upgrade happens in the Worker — on Workers a 101
**is** a `Response`, so this is an ordinary route contribution around
[`createActorSocketSession`](/actors/docs/socket-sessions), not a special case.

Every call and every subscription re-dispatches through placement to its actor's Durable
Object, with the stub derived fresh per dispatch. A refused construction — origin, or
authentication — answers with an honest HTTP status rather than an accepted-then-closed
socket. No pre-session buffer is needed either: the client end of a `WebSocketPair` only
exists inside the returned `Response`, so no frame can race the session's construction.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>This mode does not release <code>keptAlive</code> for a departed live
    consumer.</strong> The cancellation dies at the <code>stub.fetch</code> boundary, so an
    actor whose last watcher closed its tab stays alive until it idles out. When empty-room
    economics matter, terminate in the object.
  </div>
</div>

### Object-terminated — the room pattern

```ts
export class ActorHost extends createHostDurableObject<Env>({
    actors,
    namespace: (env) => env.ACTORS,
    app: createApp,
    socket: { maxConnectionMs: 3_600_000 },   // session options live HERE in this mode
}) {}

export default createWorkerHandler<Env>({
    actors,
    namespace: (env) => env.ACTORS,
    app: createApp,
    socket: { terminate: 'object' },          // only `path` is meaningful on this side
});
```

The Worker parses the actor out of `{path}/{type}/{key}` and **forwards the upgrade verbatim**
— cookies, `Origin` and all — to that actor's Durable Object, which accepts it with
`state.acceptWebSocket` under the tag `sigx:socket`. The 101 carrying the client end passes
straight back out.

Because the session lives where the actor lives, **a disconnect tears down locally**:
`iterator.return()` reaches the watch, `keptAlive` clears, and the empty room is released.
That is the whole reason this mode exists.

The option split is enforced by the types: in `'object'` mode the Worker side accepts only
`path`, so session options cannot be configured on the side that never runs the session.

Note the arity difference means the two modes **compose** — mount this one and
`app.use(workerSocket(...))` for the other if you want both.

### The hibernation contract

Deliberately minimal, because the point of hibernation is that an idle page costs nothing:

- **Keepalive is `setWebSocketAutoResponse`**, answered by the runtime without waking the
  object. `pingMs` is therefore **not accepted** — a session-owned ping timer would hold the
  object resident, which is exactly the cost hibernation removes.
- **`maxConnectionMs` survives eviction** as a deadline stored in the socket attachment,
  checked per message. So an idle hibernated socket can nominally outlive its cap until its
  next frame; the alternative would be an alarm, and the object's one alarm belongs to
  reminders.
- **An evicted isolate loses the session** — pinned principal, in-flight calls, watches. The
  first message after a cold wake closes **`1012 'session evicted — reconnect'`**, and the
  client transport redials: a fresh upgrade with the browser's current cookies, subscriptions
  re-seeded exactly as on any other drop.

A subclass may accept its own sockets under a different tag and compose fine; one that
overrides the hibernation handlers must delegate `sigx:socket` sockets back through `super`.

### Also exported

`objectSocketRoute` and `parseSocketActorPath` for the forwarding half, and
**`durableObjectStubResolver`** — the ref → stub derivation, extracted so placement and the
forwarding route cannot drift apart about where an actor lives. `CloudflareWebSocketLike`,
`DurableWebSocketLike` and the optional hibernation members on `DurableObjectStateLike`
describe the runtime surface structurally.

## Eviction is not deactivation

> The platform destroys the isolate, the host and the activation **together**. `onDeactivate`
> never runs, and there is no idle sweeper.
>
> An actor that flushes in `onDeactivate` must `ctx.save()` in the turn instead.

The same applies to [tasks](/actors/docs/tasks): a fiber does not survive eviction, so a task
here is checkpoint-and-resume with short gaps rather than one continuous run. Same
at-least-once contract — checkpoint aggressively.

## `wrangler.jsonc`

```jsonc
{
    "main": "src/worker.ts",
    // Pinned, never floating: a compatibility date is how Workers versions
    // runtime behaviour, so bumping it is a deliberate change to test.
    "compatibility_date": "2026-07-01",
    "compatibility_flags": ["nodejs_compat"],
    "durable_objects": { "bindings": [{ "name": "ACTORS", "class_name": "ActorHost" }] },
    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ActorHost"] }],
    "define": { "__DEV__": "false" },
    "observability": { "enabled": true }
}
```

`nodejs_compat` is required — [interleaving](/actors/docs/reentrancy) needs
`AsyncLocalStorage`.

## Reminders differ visibly

`durableObjectReminders()` maps onto the DO alarm, so a reminder fires **at** the due time —
where `shardedReminders()` promises only "at or after `nextDue`, checked every
`reminderTickMs`".

`onAlarm()` runs in three phases and does **not** hold `blockConcurrencyWhile` across
delivery: claim and persist (gated), deliver (ungated), re-read and re-arm (gated). Holding
the gate across delivery deadlocked the object, because rescheduling from inside `onReminder`
takes the gate itself and `blockConcurrencyWhile` does not nest.

Relatedly, an expected failure is raised **after** the gate closes, not through it — an
exception escaping `blockConcurrencyWhile` *resets* the DO.

## Next steps

- [`@sigx/actors-cloudflare`](/actors/packages/actors-cloudflare/overview) — the API.
- [Socket sessions](/actors/docs/socket-sessions) — the session both modes drive.
- [Tasks](/actors/docs/tasks) — the checkpoint posture here.
- [The app](/actors/docs/the-app) — the factory pattern.

---
url: https://sigx.dev/actors/docs/placement-policies/
title: Placement policies
description: Where a new activation goes — the measured comparison, why the default is random, and when preferLocal or activationCount wins
---

# Placement policies

<p class="lede">A policy decides which host a **new** activation lands on. It never moves an
existing one — that is [rebalancing](/actors/docs/rebalancing).</p>

## The measured comparison

`pnpm bench:run locality-warm`, N=100 hosts, 240 actors, in the **warm** steady state — actors
already placed, which is where a running cluster spends its life.

| Edge × policy | Local fraction | Ownership spread |
|---|---:|---:|
| round-robin × `randomPlacementPolicy()` *(default)* | 0.02 | 2.92 |
| round-robin × `preferLocalPolicy()` | 0.00 | 1.25 |
| **hash the routing token × `preferLocalPolicy()`** | **1.00** | 2.50 |
| skewed LB × `randomPlacementPolicy()` | 0.00 | 2.92 |
| skewed LB × `preferLocalPolicy()` | 0.80 | **80.4** |

*Ownership spread is the most-loaded host's actor count over the mean: 1.0 is perfectly even,
and N means one host owns everything.*

## Use `preferLocalPolicy()` only with a hashing edge

> **Use `preferLocalPolicy()` if — and only if — your edge hashes the
> [routing token](/actors/docs/locality-routing).**

That is the one row that wins, and it wins completely: 100% local. Set it per type with
`defineActor({ placement })` or cluster-wide with `cluster({ policy })`.

## Why the default is random

Two rows explain it.

**Under a plain round-robin balancer, `preferLocalPolicy()` buys nothing** — 0.00 against
random's 0.02, both noise around 1/N. It pins each actor wherever its first call landed, and
the balancer then sends the next call somewhere else anyway. A default that only helps once
you have *also* configured your load balancer is not a default; it is a trap with a good
outcome attached.

**Under a balancer that is not even** — a rolling deploy, a bad health check, a scaled-down
pool — it concentrates ownership catastrophically: **80×** at N=100, one host holding 80% of
the actors. And they do not move back, because placement only applies to new activations.

Random holds ~2.9 regardless of what the edge does, which is the property you want precisely
when things are going wrong.

## `consistentHashPolicy()`

Mostly an anti-pattern under edge hashing: the edge's hash and the cluster's rendezvous hash
are different functions over different sets, so they disagree on most keys and guarantee a hop
for nearly every actor.

It earns its place when a *client* routes with the cluster's own rule rather than the load
balancer's.

## `activationCountPolicy()`

Steers new activations toward the least-loaded host — the answer when the workload is uneven
(hot types, lumpy keys) and **ownership spread** is the number you are watching.

```ts
cluster({ providers, advertise, secret, policy: activationCountPolicy({ refreshMs: 5_000 }) });
```

It keeps a load view refreshed out of band over the authenticated host-to-host ops channel
(`refreshMs` default 5s; a peer probe that misses its `timeoutMs` keeps its stale entry).
`choose()` stays synchronous: it samples **two** random active hosts and takes the less loaded
— power-of-two-choices — plus a local pending delta, so a burst inside one refresh window sees
its own effect.

Degradation is graceful by design. Un-attached it keeps no state and behaves exactly as
`randomPlacementPolicy()`; attached but not yet refreshed it spreads random-or-better until
data lands. A host with no known load reads as **cold**, which is what makes a freshly joined
host attract work immediately.

> Staleness is the design, not a defect. Routing is an optimization, so a decision made on old
> numbers costs a little balance — never correctness.

## Stateful policies: the attach seam

A policy may declare `attach(runtime)`, which the placement calls at start — or on first
resolution for a `defineActor({ placement })` declaration — with `PolicyRuntime`:
`{ hostId, view(), selfLoad(), peerLoad(target, timeoutMs) }`. It returns a teardown run at
stop.

A throwing `attach` is contained, and `choose()` must keep working un-attached.

## Precedence

Highest first:

1. `defineActor({ placement })`
2. `cluster({ typePolicies })`
3. `cluster({ policy })`
4. random

## Next steps

- [Locality routing](/actors/docs/locality-routing) — the edge half of `preferLocalPolicy`.
- [Rebalancing](/actors/docs/rebalancing) — moving actors that are already placed.
- [Cluster stats](/actors/docs/cluster-stats) — watching ownership spread.

---
url: https://sigx.dev/store/docs/using-in-components/
title: Using Stores in Components
description: Read store state in render, share instances, and control lifetimes
---

# Using Stores in Components

A store factory returns a live instance with a flat, signal-backed surface. When you read `store.x` inside a component's render function, SignalX tracks the dependency and re-renders that component whenever the value changes. This guide covers the rendering model, the destructuring footgun, component-scoped stores, and cleanup.

## How rendering reactivity works

The store instance is an unwrap proxy: reading `store.count` reads the underlying key signal, and reading `store.total` reads the underlying computed. Reactivity then follows the normal SignalX rules — what matters is **where** the read happens:

- **Inside a render function** (`return () => <... {store.count} ...>`): the read is tracked. That component — and only that component — re-renders when `count` changes. There is no store-level subscription; granularity is per read, per component.
- **Inside an effect or `watch`**: tracked the same way; the effect re-runs on change.
- **In the component setup body** (outside the returned render function): the read is a one-time snapshot. `const n = store.count` in setup gives you the value at mount time and never updates — by design, just like reading a signal's `.value` outside a reactive context.

So the rule of thumb is simple: *keep reads on the store object, inside the render function*. The proxy does the unwrapping; the signal core does the tracking.

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const useCounterStore = defineStore('counter', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ count: 0 });
    const actions = defineActions({
        increment() { state.count++; },
    });
    return { ...signals, ...actions };
});

const Counter = component(() => {
    const store = useCounterStore();
    return () => (
        <button class="btn btn-primary" onClick={() => store.increment()}>
            Clicked {store.count} times
        </button>
    );
});

render(<Counter />, "#sandbox");
```

Returned computeds work the same — read them like plain (read-only) values and they update as the underlying state changes:

```tsx
import { component, render, computed } from 'sigx';
import { defineStore } from '@sigx/store';

const useCartStore = defineStore('cart', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({
        items: [
            { name: 'Keyboard', price: 80, qty: 1 },
            { name: 'Mouse', price: 30, qty: 1 },
        ],
    });

    const total = computed(() =>
        state.items.reduce((sum, item) => sum + item.price * item.qty, 0)
    );

    const actions = defineActions({
        addMouse() {
            const mouse = state.items.find(i => i.name === 'Mouse');
            if (mouse) mouse.qty++;
        },
    });

    return { ...signals, ...actions, total };
});

const Cart = component(() => {
    const store = useCartStore();
    return () => (
        <div class="space-y-2">
            <ul class="text-sm">
                {store.items.map(item => (
                    <li>{item.name} x{item.qty} - ${item.price * item.qty}</li>
                ))}
            </ul>
            <p class="font-bold">Total: ${store.total}</p>
            <button class="btn btn-sm" onClick={() => store.addMouse()}>Add a mouse</button>
        </div>
    );
});

render(<Cart />, "#sandbox");
```

## The destructuring footgun

The one way to lose reactivity is to **destructure state off the store**. `const { count } = store` reads through the unwrap proxy *at that moment* — you get a plain number, not a signal, and it will never update. The same applies to computeds.

When you want destructured locals, use `storeToSignals`: it returns signal views (`{ value }`) for every state key and computed, safe to pull apart. See the difference live — click increment and watch the first row stay frozen:

```tsx
import { component, render } from 'sigx';
import { defineStore, storeToSignals } from '@sigx/store';

const useSharedCounter = defineStore('shared-counter', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ count: 0 });
    const actions = defineActions({
        increment() { state.count++; },
    });
    return { ...signals, ...actions };
}, 'singleton');

const BrokenDestructure = component(() => {
    const store = useSharedCounter();
    const { count } = store; // ✗ snapshot: plain number, taken once at setup
    return () => (
        <div class="flex items-center gap-2">
            <span class="badge badge-error">broken</span>
            <code>const {'{ count }'} = store</code> → {count}
        </div>
    );
});

const SafeDestructure = component(() => {
    const store = useSharedCounter();
    const { count } = storeToSignals(store); // ✔ signal view, still reactive
    return () => (
        <div class="flex items-center gap-2">
            <span class="badge badge-success">works</span>
            <code>storeToSignals(store)</code> → {count.value}
        </div>
    );
});

const App = component(() => {
    const store = useSharedCounter();
    return () => (
        <div class="space-y-2">
            <button class="btn btn-primary btn-sm" onClick={() => store.increment()}>
                increment (store.count = {store.count})
            </button>
            <BrokenDestructure />
            <SafeDestructure />
        </div>
    );
});

render(<App />, "#sandbox");
```

### Destructuring safely with storeToSignals

```tsx
import { storeToSignals } from '@sigx/store';

const store = useTodoStore();
const { todos, remaining } = storeToSignals(store);

todos.value.push({ id: 1, text: 'hi', done: false }); // still reactive
remaining.value;                                       // read-only computed view
```

Actions don't need this — they are plain functions and can be referenced freely (`const { add } = store` is fine for an action, though calling through the store keeps things uniform). `storeToSignals` skips functions and `$`-meta entirely; how its return type is inferred is covered in [TypeScript](/store/docs/typescript).

## Async actions and `pending`

Every action carries a reactive `pending` flag — `true` while any invocation of that action is in flight. Read it in render to drive spinners and disabled states:

```tsx
const Saver = component(() => {
    const store = useSaveStore();
    return () => (
        <button onClick={() => store.save()} disabled={store.save.pending}>
            {store.save.pending ? 'Saving…' : 'Save'}
        </button>
    );
});
```

Async actions return the **original promise**, so `await store.save()` observes rejections; un-awaited (fire-and-forget) calls never surface unhandled-rejection noise — failures still reach `onFailure` subscribers. Overlap counting, optimistic updates, and race patterns are covered in [Actions & Async](/store/docs/actions-and-async).

## Reacting to specific changes

To run side effects when a single key changes, subscribe to its `$events` entry. Callbacks receive `(value, prev)`; each `subscribe` returns a `Subscription` you can `unsubscribe()` later.

```tsx
const store = useCounterStore();

const sub = store.$events.count.subscribe((value, prev) => {
    document.title = `Count: ${value} (was ${prev})`;
});

// later, when you no longer need it:
sub.unsubscribe();
```

These events are lazy — the deep watcher behind a key only runs while it has subscribers, and nothing fires at subscribe time. Action lifecycle events (`store.save.onFailure`, …) work the same way for cross-cutting concerns like logging. The full event model — state events vs. action events vs. custom events, and devtools discovery — is in [Events & Observability](/store/docs/events-and-observability).

## Sharing one instance vs. fresh instances

The third argument to `defineStore` is the instance **lifetime** — a string literal, defaulting to `'scoped'`:

```ts
import { defineStore } from '@sigx/store';

const useAppStore = defineStore('app', setup, 'singleton');
```

- `'singleton'` — one shared instance per app (`AppContext`), created on first use and disposed on `app.unmount()`. Outside any app context, one instance per JS realm. Ideal for global app state.
- `'scoped'` (default) — the nearest instance provided via `defineProvide` in the component tree; falls back to the app-context instance when no provider exists.
- `'transient'` — a new instance every time the factory is called, auto-disposed with the calling component.

Pick `'singleton'` when several components must read and write the same state. Pick `'transient'` when each component should own an isolated copy. For the full decision guide — including parameterized stores (arguments honored at **first creation only** for non-transient lifetimes) and the SSR app-per-request contract — see [Lifetimes & DI](/store/docs/lifetimes-and-di).

## Component-scoped stores with defineProvide

A `'scoped'` store resolves to the nearest provided instance up the component tree. `defineProvide(useXxxStore)` creates a **fresh instance owned by the current component** and provides it to the subtree — every descendant that calls the factory gets *that* instance instead of the app-wide one:

```tsx
import { component, defineProvide } from 'sigx';
import { defineStore } from '@sigx/store';

const usePanelStore = defineStore('panel', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ expanded: false });
    const actions = defineActions({
        toggle() { state.expanded = !state.expanded; },
    });
    return { ...signals, ...actions };
}); // 'scoped' by default

const Panel = component(() => {
    // This Panel owns its instance; children resolve it automatically.
    const store = defineProvide(usePanelStore);
    return () => (
        <section>
            <PanelHeader />
            {store.expanded && <PanelBody />}
        </section>
    );
});

const PanelHeader = component(() => {
    const store = usePanelStore(); // the nearest Panel's instance
    return () => <button onClick={() => store.toggle()}>toggle</button>;
});
```

Mount three `<Panel />`s and you get three independent stores; each disposes when its panel unmounts. This is the middle ground between a shared singleton and a per-call transient: shared *within a subtree*, isolated *between subtrees*. `defineProvide` also accepts a custom factory (`defineProvide(useXxxStore, () => instance)`) when you need to pre-configure the instance — details in [Lifetimes & DI](/store/docs/lifetimes-and-di).

## Cleanup on unmount

When you create a store instance **inside a component**, it is tied to a lifecycle per the lifetime rules:

- `'transient'` instances and `defineProvide`d instances dispose with the component that created them.
- `'singleton'` and app-level `'scoped'` instances are app-owned — they dispose on `app.unmount()`, not when the first component that touched them unmounts.

Disposal stops the state watchers and destroys all the instance's event topics, so `$events` and action events stop firing. If you create an instance **outside** a component (scripts, tests), dispose it yourself:

```ts
const store = useCounterStore();
store.count = 1;   // subscribers fire

store.$dispose();  // stop watchers + destroy topics
store.count = 2;   // subscribers no longer fire
```

Each instance has a friendly id, `store.$id` (e.g. `'counter#1'`) — handy in logs and devtools.

## Next steps

- [Actions & Async](/store/docs/actions-and-async) — `pending`, lifecycle events, optimistic updates, races.
- [Lifetimes & DI](/store/docs/lifetimes-and-di) — lifetimes in practice, `defineProvide`, parameterized stores, SSR.
- [Persistence](/store/docs/persistence) — persist state slices with `@sigx/store/persist`.
- [API Reference](/store/docs/api) — full signatures for every export.

---
url: https://sigx.dev/devtools/docs/getting-started/
title: Getting Started
description: "@sigx/devtools — inspect signals and the reactive graph at runtime"
---

# Getting Started with DevTools

`@sigx/devtools` is the page-side agent that lets an external inspector or browser
extension see inside a running SignalX app. Install it as a plugin and it attaches
to the framework's global devtools hook, then streams two families of events to a
panel: component lifecycle (mount, update, unmount, error) and reactivity primitives
(signal, computed, effect create/update/dispose). It also observes `@sigx/store`
activity — stores are discovered automatically through the core inspection registry —
and `@sigx/router` navigations.

Everything the plugin sends over the wire is JSON-serializable. It never puts a DOM
node or a live reactive proxy on the wire — large or reactive values are inspected on
demand through value references and a bounded, cycle-safe serializer.

The package is SSR-safe: with no transport supplied and no `window`, the plugin
installs as a no-op so server rendering never crashes.

## Install

```bash
pnpm add -D @sigx/devtools
```

## Minimal example

Register the plugin on your app. With no options it uses the default `postMessage`
transport (in the browser), names the app `sigx-app`, and tracks reactivity.

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { App } from './App';

defineApp(<App />)
    .use(devtools())
    .mount('#app');
```

Store activity needs no wiring at all: every `@sigx/store` instance — existing and
future — is discovered automatically through the core inspection registry
(`@sigx/runtime-core/inspect`) and streamed as `store:action`, `store:mutation`, and
`store:event` timeline events. To also see router navigations, pass the router in:

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { createRouter } from '@sigx/router';
import { App } from './App';

const router = createRouter({ routes: [/* ... */] });

defineApp(<App />)
    .use(router)
    .use(devtools({
        appName: 'my-app',
        router,
    }))
    .mount('#app');
```

Once the wire is up the plugin emits a `hello` event carrying `PROTOCOL_VERSION` and
the agent version. A connected panel then calls `get:apps` followed by
`get:tree(appId)` to bootstrap its component tree.

## Production builds

Prefer not to ship devtools in production. Dynamic-import it behind a dev flag so
bundlers tree-shake it out of release builds:

```tsx
import { defineApp } from 'sigx';
import { App } from './App';

const app = defineApp(<App />);

if (import.meta.env.DEV) {
    const { devtools } = await import('@sigx/devtools');
    app.use(devtools());
}

app.mount('#app');
```

## Next steps

- [Installation](/devtools/docs/installation) — peer dependencies, config, and wiring details.
- [Connecting an inspector](/devtools/docs/connecting-an-inspector) — transports, the Chrome extension relay, and non-browser hosts.
- [Tuning what gets traced](/devtools/docs/tuning-what-gets-traced) — throttling, reactivity opt-out, stores and router.
- [API Reference](/devtools/docs/api) — every export with signatures.

---
url: https://sigx.dev/actors/docs/stateless-workers/
title: Stateless workers
description: defineWorker — interchangeable activations for pure compute, always local, with the identity-bound surface structurally removed
---

# Stateless workers

<p class="lede">Everything else here assumes an actor *is* somebody — one identity, one
activation, turns in order. Pure compute has none of that, so serializing it behind one
<a href="/actors/docs/turns">turn sequence</a> is a bottleneck the semantics never asked for.</p>

```ts
import { defineWorker } from '@sigx/actors';

export const Resize = defineWorker({
    type: 'Resize',
    authorize: requireAuthenticated,
    maxLocal: 8,             // pool cap; default: hardwareConcurrency (≤16)
    methods: () => ({
        async run(image: Uint8Array, width: number) {
            return transform(image, width);
        },
    }),
});

await actor(Resize, 'any').run(img, 800);   // callers look exactly the same
```

## The contract

**Two calls to the same key may run concurrently, on different pool members.** The host keeps
up to `maxLocal` activations per `(type, key)`, spun up under load, and each dispatch rides the
member with the fewest queued turns. `ctx.key` is still the key the caller addressed — it just
no longer names a single runner.

**Always local, zero directory traffic.** A worker activates on whichever host — or Cloudflare
isolate — received the call. No directory claim, no lookup, no routing, no `421` redirect, and
nothing for a cluster to fence, migrate or rebalance. Both invariants are gated in CI:
`directory_ops == 0`, pool ≤ cap.

**No identity, so no identity-bound surface.** `state`, `persistence`, `reminders`, `tasks:`,
`subscriptions:`, `placement` and `reentrant` do not exist on `WorkerOptions` — passing one is
a compile error. `ctx.state`, `ctx.save()` and friends are typed away by `WorkerContext` and
throw if reached through a cast.

## What remains

- **Authorization** — `authorize` / `methodAuthorize` / `allowAnonymous`, the same build gate.
- **[`reads:`](/actors/docs/cacheable-reads)** — a pure read is the ideal cacheable `GET`.
- **[`streams:`](/actors/docs/streams)** — pure generators; an open stream pins its member
  against the sweep.
- **`onActivate` / `onDeactivate`** for per-member warm-up and teardown. Load a model once per
  member, close it on the way out.
- **`ctx.timer`, `ctx.actor`, `ctx.publish`.**

Pool members idle-collect individually after `idleAfterMs`, so a quiet worker shrinks back to
zero footprint.

## Two sharp edges

**A same-key self-call is a deadlock, deterministically.** `reentrant` does not exist for
workers, so `ctx.actor(Self, ctx.key)` throws
[`ActorDeadlockError`](/actors/docs/errors) rather than working only when the pool happens to
have a free member. A *different* key is a different pool and is fine.

**Watches are refused.** A watch is a state-change feed and a worker has no state.

## Where they live

Workers live in `*.actor.ts` files like every other definition — **not** `*.worker.ts`, which
belongs to Vite's Web Worker convention. The build swaps them for the same wire client, so a
browser can call one directly.

In an app, `app.defineWorker` is the plugin-typed twin of `app.defineActor`.

## When to reach for one

Validation, image or document transformation, parsing, embedding generation, fan-out helpers —
anything where the answer depends only on the arguments.

If two calls about the same key would ever want to see each other's effects, you want an
[actor](/actors/docs/actor-model), not a worker.

## Next steps

- [The actor model](/actors/docs/actor-model) — the identity a worker gives up.
- [Cacheable reads](/actors/docs/cacheable-reads) — a natural fit for pure compute.
- [Clustering](/actors/docs/clustering) — why workers need none of it.

---
url: https://sigx.dev/terminal/docs/getting-started/
title: Getting Started
description: "@sigx/terminal — build TUIs with TSX"
---

# Getting Started with Terminal

`@sigx/terminal` lets you build terminal user interfaces (TUIs) and interactive CLI apps using the same reactive model and TSX components you use on the web. It is built on `@sigx/reactivity` and `@sigx/runtime-core`, and ships a cell renderer that paints your component tree to the terminal as ANSI-styled lines.

The package is an umbrella: it re-exports the terminal renderer, the headless `@sigx/terminal-zero` foundation and the themed `@sigx/terminal-ui` components, so you can import everything you need from a single `@sigx/terminal` entry. See [Architecture](/terminal/docs/architecture) for how the pieces fit together.

## What you get

- **TSX intrinsics** for the terminal — `box`, `text`, and `br` — with colors, borders, labels and drop shadows.
- **A render entry** (`renderTerminal` / `terminalMount`) with `inline` and `fullscreen` [render modes](/terminal/docs/render-modes), a non-TTY plain-text fallback and a reactive `getTerminalSize()`.
- **Layered keyboard input** — `onKey(handler, { layer })` dispatch with built-in Tab/Shift+Tab focus traversal and a `focusState` signal.
- **A themed component library** — forms (`Input`, `Select`, `MultiSelect`, …), feedback (`Spinner`, `ProgressBar`, `Badge`), navigation, layout, data, fx and task components. See [Components](/terminal/docs/components).
- **A prompt kit** — imperative `text` / `select` / `confirm` / `spinner` wizards. See [Prompts](/terminal/docs/prompts).

## Install

```bash
npm install @sigx/terminal
```

The umbrella brings the reactive engine (`@sigx/reactivity`, `@sigx/runtime-core`) and the whole TUI stack with it — there is nothing else to add. See [Installation](/terminal/docs/installation) for the required TSX/Vite wiring.

## A minimal app

Set `jsxImportSource` **once** in your `tsconfig.json` and every `.tsx` file in the project compiles against the terminal runtime:

```json
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "@sigx/terminal"
    }
}
```

Then write plain TSX, with no per-file pragma:

```tsx
import { component, defineApp, signal } from '@sigx/terminal';

const App = component(() => {
    const count = signal(0);
    const tick = () => count.value++;

    return () => (
        <box border="rounded" label="Counter" color="cyan">
            <text>Count is {count.value}</text>
            <br />
            <text color="green">Press the button to increment.</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

`defineApp(<App />).mount(...)` works without passing a mount function because the terminal runtime registers `terminalMount` as the platform default. Any reactive change in your tree schedules a repaint of the whole screen.

## Adding interactivity

The runtime ships focusable components with two-way model binding. Tab and Shift+Tab move focus between them:

```tsx
import { component, defineApp, signal } from '@sigx/terminal';
import { Input, Button } from '@sigx/terminal';

const App = component(() => {
    const name = signal('');

    return () => (
        <box border="single" label="Greeting">
            <Input model={() => name} placeholder="Your name" autofocus label="Name" />
            <br />
            <text>Hello, {name.value || 'stranger'}!</text>
            <br />
            <Button label="Done" onClick={() => console.log(name.value)} />
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

## Loading data

Terminal apps are full SignalX clients, so the value-first async primitives work here too. `@sigx/terminal` re-exports [`useData`](/core/docs/data-loading) (along with `useStream`, `useAction` and `all`): call it during setup with a key and a fetcher, then render every state through `.match()`. No `window` is required — the terminal runtime declares itself a live client, so keyed reads actually fetch instead of parking at `pending`.

```tsx
import { component, defineApp, useData } from '@sigx/terminal';

const App = component(() => {
    const joke = useData('joke', async (key, { signal }) => {
        const res = await fetch('https://icanhazdadjoke.com/', {
            headers: { Accept: 'application/json' },
            signal,
        });
        return (await res.json()).joke as string;
    });

    return () => (
        <box border="rounded" label="Dad joke" color="cyan">
            {joke.match({
                pending: () => <text color="dim">Loading…</text>,
                error: (e) => <text color="warn">Failed: {e.message}</text>,
                ready: (text) => <text>{text}</text>,
            })}
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

The fetcher receives the resolved key and an `AbortSignal` — pass it straight to `fetch`. `useStream` follows the same shape for progressive, token-at-a-time output, which is handy for piping an LLM response into a `<text>` cell.

## Next steps

- [Architecture](/terminal/docs/architecture) — the renderer, headless foundation, UI library and args parser.
- [Installation](/terminal/docs/installation) — install command, peer deps and TSX/Vite config.
- [Layout & Styling](/terminal/docs/layout-and-styling) — boxes, borders, colors and the line layout model.
- [Render modes](/terminal/docs/render-modes) — inline vs fullscreen, non-TTY and resize.
- [Input & Interactive Components](/terminal/docs/input-and-components) — focus, keyboard input and the built-in widgets.
- [Components](/terminal/docs/components) — the full themed component library.
- [Prompts](/terminal/docs/prompts) — imperative CLI wizards.
- [API Reference](/terminal/docs/api) — every export, grouped by kind.

---
url: https://sigx.dev/use/docs/try-on-scope-dispose/
title: tryOnScopeDispose
description: "Register teardown with the active scope — returns false when there's no scope, so the caller knows it owns disposal"
---

# tryOnScopeDispose

Register teardown with the currently-active scope — the owning component's setup, or the innermost running `effectScope()`. Cross-platform — import from `@sigx/use`.

```ts
import { tryOnScopeDispose } from '@sigx/use';

const id = setInterval(tick, 1000);
tryOnScopeDispose(() => clearInterval(id));
```

It returns `false` (retaining nothing) when called **outside** any scope — the caller keeps responsibility for disposal then. That's exactly why every composable with ongoing work also returns an explicit `stop()`/[`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop) handle: it's the escape hatch for standalone, scope-less use.

```ts
const registered = tryOnScopeDispose(cleanup);
if (!registered) {
    // no active scope — you must call cleanup() yourself
}
```

## Signature

```ts
function tryOnScopeDispose(fn: () => void): boolean;
```

Returns `true` when the teardown was registered with a scope, `false` when there was no active scope.

**Platform:** everywhere.

## See also

- [`tryOnMounted`](/use/docs/try-on-mounted) — the mount-time counterpart.
- [Conventions → Lifecycle helpers](/use/docs/conventions#lifecycle-helpers) — how these two power the cleanup model.
- [Conventions → Control handles](/use/docs/conventions#control-handles-pausable-and-stop) — the `stop()`/`Pausable` handles that back scope-less use.

---
url: https://sigx.dev/router/docs/advanced-patterns/
title: Advanced Patterns
description: Advanced routing patterns for @sigx/router - pattern matching, nested layouts, dynamic routes, and more
---

# Advanced Patterns

This guide covers advanced routing techniques for building complex applications with `@sigx/router`.

## Pattern Matching

Use `router.match()` for declarative, type-safe route rendering. Each key maps a route name to a render function that receives that route's params. Use `_` as a catch-all fallback.

```tsx
import { component } from 'sigx';
import { useRouter } from '@sigx/router';

const App = component(() => {
    const router = useRouter();

    return () => router.match({
        home: () => <HomePage />,
        'blog-post': ({ slug }) => <BlogPost slug={slug} />,
        'user-profile': ({ id }) => <UserProfile userId={id} />,
        _: () => <NotFound />
    });
});
```

Values can also be static (non-function) for simple mappings:

```tsx
router.match({
    home: <HomePage />,
    about: <AboutPage />,
    _: <NotFound />
});
```

## Nested Layouts

Define parent routes with `children` and render nested content with `<RouterView />`. The parent component acts as a layout shell — child routes render inside the parent's `<RouterView />`.

```tsx
import { createRouter, RouterView, RouterLink } from '@sigx/router';
import { component } from 'sigx';

const AdminLayout = component(() => {
    return () => (
        <div class="admin">
            <aside>
                <RouterLink to="/admin/dashboard">Dashboard</RouterLink>
                <RouterLink to="/admin/users">Users</RouterLink>
                <RouterLink to="/admin/settings">Settings</RouterLink>
            </aside>
            <main>
                <RouterView />
            </main>
        </div>
    );
});

const router = createRouter({
    routes: [
        {
            path: '/admin',
            component: AdminLayout,
            children: [
                { path: 'dashboard', name: 'admin-dashboard', component: Dashboard },
                { path: 'users', name: 'admin-users', component: UserList },
                { path: 'users/:id', name: 'admin-user', component: UserDetail },
                { path: 'settings', name: 'admin-settings', component: Settings },
            ],
        },
    ],
});
```

Each `<RouterView />` automatically tracks its depth. The root `RouterView` renders the parent (`AdminLayout`), and the `RouterView` inside `AdminLayout` renders the matched child.

## Route Props

The `props` option on a route record controls how props are passed to the route's component. There are three modes:

### Boolean Mode

Set `props: true` to pass route params directly as component props:

```tsx
const routes = [
    { path: '/users/:id', component: UserProfile, props: true },
];

// UserProfile receives { id: '123' } as props when visiting /users/123
const UserProfile = component<{ id: string }>((ctx) => {
    return () => <h1>User {ctx.props.id}</h1>;
});
```

### Object Mode

Pass a static props object, useful for routes that share a component with different configurations:

```tsx
const routes = [
    { path: '/blog', component: PostList, props: { category: 'all' } },
    { path: '/blog/featured', component: PostList, props: { category: 'featured' } },
];
```

### Function Mode

Derive props from the current route for full flexibility:

```tsx
const routes = [
    {
        path: '/search',
        component: SearchResults,
        props: (route) => ({
            query: route.query.q,
            page: Number(route.query.page) || 1,
        }),
    },
];
```

## Dynamic Routes

Add and remove routes at runtime with `addRoute()` and `removeRoute()`. This is useful for plugin systems, feature flags, or lazy feature modules that register their own routes.

### Adding Routes

`addRoute()` returns a removal function for easy cleanup:

```tsx
// Add a top-level route
const removeRoute = router.addRoute({
    path: '/analytics',
    name: 'analytics',
    component: AnalyticsDashboard,
});

// Add a child route to an existing parent
router.addRoute(
    { path: 'reports', name: 'analytics-reports', component: Reports },
    'analytics' // parent route name
);
```

### Removing Routes

Remove by name or use the removal function returned by `addRoute()`:

```tsx
router.removeRoute('analytics');

// Or use the function returned by addRoute
const remove = router.addRoute({ path: '/temp', name: 'temp', component: Temp });
remove(); // removes the route
```

### Plugin System Example

```tsx
function installAnalyticsPlugin(router) {
    const cleanup = router.addRoute({
        path: '/analytics',
        name: 'analytics',
        component: AnalyticsDashboard,
        meta: { title: 'Analytics' },
        children: [
            { path: 'overview', name: 'analytics-overview', component: Overview },
            { path: 'reports', name: 'analytics-reports', component: Reports },
        ],
    });

    // Return cleanup for uninstall
    return cleanup;
}
```

### Checking Routes

```tsx
if (!router.hasRoute('analytics')) {
    router.addRoute({ path: '/analytics', name: 'analytics', component: Analytics });
}

// List all registered routes
const allRoutes = router.getRoutes();
```

## Lazy Loading

Load route components on demand using dynamic imports wrapped with `lazy()` from `sigx`:

```tsx
import { lazy } from 'sigx';
import { createRouter } from '@sigx/router';

const router = createRouter({
    routes: [
        { path: '/', component: Home },
        { path: '/settings', component: lazy(() => import('./Settings')) },
        { path: '/admin', component: lazy(() => import('./AdminLayout')),
            children: [
                { path: 'dashboard', component: lazy(() => import('./Dashboard')) },
                { path: 'users', component: lazy(() => import('./UserManagement')) },
            ],
        },
    ],
});
```

> **Note:** Async component imports currently require wrapping with `lazy()` from `sigx`. The router does not resolve raw dynamic imports on its own.

## Route Meta

Attach arbitrary metadata to routes via the `meta` field. Access it from route guards, hooks, or anywhere you have the current route.

### Defining Meta

```tsx
const routes = [
    {
        path: '/',
        name: 'home',
        component: Home,
        meta: { title: 'Home', requiresAuth: false },
    },
    {
        path: '/dashboard',
        name: 'dashboard',
        component: Dashboard,
        meta: { title: 'Dashboard', requiresAuth: true, roles: ['admin', 'editor'] },
    },
    {
        path: '/settings',
        name: 'settings',
        component: Settings,
        meta: {
            title: 'Settings',
            requiresAuth: true,
            breadcrumbs: [
                { label: 'Home', to: '/' },
                { label: 'Settings' },
            ],
        },
    },
];
```

### Page Title Updates

```tsx
router.afterEach((to) => {
    document.title = to.meta.title
        ? `${to.meta.title} — My App`
        : 'My App';
});
```

### Auth Guard with Meta

```tsx
router.beforeEach((to) => {
    if (to.meta.requiresAuth && !isAuthenticated()) {
        return '/login';
    }
});
```

### Breadcrumbs from Meta

```tsx
import { component } from 'sigx';
import { useRoute, RouterLink } from '@sigx/router';

const Breadcrumbs = component(() => {
    const route = useRoute();

    return () => {
        const crumbs = route.meta.breadcrumbs;
        if (!crumbs) return null;

        return (
            <nav aria-label="Breadcrumb">
                {crumbs.map((crumb, i) =>
                    crumb.to
                        ? <RouterLink to={crumb.to}>{crumb.label}</RouterLink>
                        : <span>{crumb.label}</span>
                )}
            </nav>
        );
    };
});
```

---
url: https://sigx.dev/use/docs/use-debounced-signal/
title: useDebouncedSignal
description: A read-only signal that trails a source, collapsing bursts of changes into one update
---

# useDebouncedSignal

A read-only signal that trails `source`, collapsing a burst of rapid changes into a single update once things settle. Cross-platform — import from `@sigx/use`.

```ts
import { signal, watch } from 'sigx';
import { useDebouncedSignal } from '@sigx/use';

const query = signal('');
const debounced = useDebouncedSignal(query, 300);

watch(debounced, q => search(q)); // fires 300ms after the last keystroke
```

Both `source` and `ms` are [`MaybeSignal`](/use/docs/conventions#inputs-maybesignalt-and-tovalue) — pass a reactive `ms` to change the window on the fly. The result is a [`ReadSignal<T>`](/use/docs/conventions#outputs-single-value--readsignalt); `ms` defaults to `200`.

Use `maxWait` to guarantee an update even while the source never stops changing — an upper bound on how long the debounced signal will lag behind.

## Signature

```ts
function useDebouncedSignal<T>(
    source: MaybeSignal<T>,
    ms?: MaybeSignal<number>,
    options?: UseDebouncedSignalOptions,
): ReadSignal<T>;

interface UseDebouncedSignalOptions {
    maxWait?: number;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `maxWait` | `number` | — | Upper bound (ms) between updates while the source keeps changing. |

**Platform:** everywhere (setTimeout). Any pending update is cancelled when the owning scope disposes.

## See also

- [`useThrottledSignal`](/use/docs/use-throttled-signal) — cap the update *rate* instead of waiting for quiet.
- [`watchDebounced`](/use/docs/watch-debounced) — debounce a `watch` callback rather than derive a signal.
- [Conventions](/use/docs/conventions) — `MaybeSignal` inputs and `ReadSignal` outputs.

---
url: https://sigx.dev/use/docs/use-throttled-signal/
title: useThrottledSignal
description: A read-only signal that follows a source at most once per window
---

# useThrottledSignal

A read-only signal that follows `source` at most **once per `ms`** — steady updates while the source streams, instead of waiting for it to fall quiet. Cross-platform — import from `@sigx/use`.

```ts
import { signal, watch } from 'sigx';
import { useThrottledSignal } from '@sigx/use';

const scroll = { y: signal(0) };
const throttled = useThrottledSignal(() => scroll.y.value, 100);

watch(throttled, y => updateMinimap(y)); // at most once every 100ms
```

Both `source` and `ms` are [`MaybeSignal`](/use/docs/conventions#inputs-maybesignalt-and-tovalue); the result is a [`ReadSignal<T>`](/use/docs/conventions#outputs-single-value--readsignalt) and `ms` defaults to `200`. `leading` updates on the first change of a window; `trailing` delivers the last change of a window (both default `true`).

## Signature

```ts
function useThrottledSignal<T>(
    source: MaybeSignal<T>,
    ms?: MaybeSignal<number>,
    options?: UseThrottledSignalOptions,
): ReadSignal<T>;

type UseThrottledSignalOptions = ThrottleOptions;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `leading` | `boolean` | `true` | Update on the first change of a window. |
| `trailing` | `boolean` | `true` | Deliver the last change of a window. |

**Platform:** everywhere (setTimeout). Any pending update is cancelled when the owning scope disposes.

## See also

- [`useDebouncedSignal`](/use/docs/use-debounced-signal) — wait for quiet instead of capping the rate.
- [`watchThrottled`](/use/docs/watch-throttled) — throttle a `watch` callback rather than derive a signal.
- [Conventions](/use/docs/conventions) — `MaybeSignal` inputs and `ReadSignal` outputs.

---
url: https://sigx.dev/actors/docs/locality-routing/
title: Locality routing
description: The routing token, load-balancer recipes, and onMiss redirect with client follow — getting the edge to send a call to the host that owns the actor
---

# Locality routing

<p class="lede">The actor **key** rides in the JSON body, and no load balancer will parse a
body to route. The routing token is what lets the edge see which actor a request is for.</p>

Without it, locality decays as 1/N — measured 1.00, 0.50, 0.12, 0.02, 0.01 for N = 1, 2, 10,
50, 100 — and a cross-host hop costs about 20× a local dispatch.

```
POST {base}/r/{token}/{Type}%23{method}
x-sigx-actor-route: {token}
```

The token is a stable per-actor hint, present in **both carriers** with the same value. It is
a **middle** segment deliberately: the symbol is decoded as the last path segment, so the
token slots in ahead of it and the endpoint neither parses nor validates it. A stale, wrong or
absent token costs a network hop — never a wrong answer.

Two carriers because neither alone is enough: a path segment cannot be silently stripped by a
service mesh and a mangled one 404s loudly, but Envoy's `route.hash_policy` has no
path-substring option at all.

## Configuring it

```ts
configureActors({ route: 'hash' });
```

| `route` | Token | For |
|---|---|---|
| `'hash'` *(default)* | opaque hash of the actor id | production |
| `'key'` | the raw key | debugging |
| `'none'` | no token; plain URL | simple cross-origin GETs |
| `(ref) => string \| null` | yours | tenant affinity, existing sharding |

> **The default hash is log hygiene, not privacy.** An unkeyed hash of an email is one
> dictionary lookup from plaintext at any width. What it buys is keys staying out of access
> logs, proxy traces, referrers and screenshots. Real unlinkability needs a keyed HMAC with a
> secret the client holds — which a browser cannot hold.

## Load-balancer recipes

```nginx
map $uri $actor { ~^/_sigx/actor/r/([^/]+)/ $1; }
upstream hosts { hash $actor consistent; }
# or: hash $http_x_sigx_actor_route consistent;
```

```
# HAProxy
balance uri depth 4
```

```yaml
# Envoy
hash_policy: { header: { header_name: x-sigx-actor-route } }
```

## The token alone does nothing

> **It must be paired with [`preferLocalPolicy()`](/actors/docs/placement-policies).**

Steady-state local fraction:

| Edge × placement | N=2 | N=10 | N=50 | N=100 |
|---|---:|---:|---:|---:|
| round-robin × `randomPlacementPolicy()` *(default)* | 0.50 | 0.12 | 0.02 | 0.01 |
| hash token × `consistentHashPolicy()` | 0.48 | 0.09 | 0.02 | 0.01 |
| **hash token × `preferLocalPolicy()`** | **1.00** | **1.00** | **1.00** | **1.00** |

The middle row is an **anti-pattern**, not a middle ground: the edge's hash and the cluster's
rendezvous hash are different functions over different sets, so they disagree on most keys and
guarantee a hop for every actor.

## Two limits not to bury

**`$live` carries no routing token**, nor does any `$`-reserved symbol — one held-open
response fans out to many actors. [Live subscriptions](/actors/docs/live-reads) still dispatch
correctly through placement, but they keep paying the hop. "~100% locality" does not cover
live components.

**A migrated actor does not follow the LB.** `preferLocalPolicy()` applies to *new*
activations, and the directory keeps a live actor where it is. After a scale-out, already-hot
actors stay misrouted until they deactivate.

## Redirect instead of proxy

By default a call that lands on the wrong host is **proxied**: one client round trip, one
internal hop, every time. The alternative is to tell the client where to go:

```ts
handleActorRequest(request, { host, onMiss: 'redirect' });   // or 'auto'
configureActors({ endpoint, follow: true });
cluster({ advertise: 'http://10.0.4.7:7311', publicAddress: 'https://host-3.example.com', secret });
```

`onMiss` goes on the **mount**, not the host, so one cluster can serve a browser origin that
proxies and a service origin that redirects.

**`follow` is not optional in practice.** On its own a redirect is *two* client round trips
against one trip plus an internal hop — strictly worse than proxying. The win exists only
because the client remembers: **2 requests once, then 1 forever.** A learned endpoint is
dropped as soon as it proves wrong, and falls back to the configured endpoint.

```mermaid
sequenceDiagram
    participant Cl as Client
    participant H1 as Host 1
    participant H2 as Host 2
    Note over H2: owns the actor
    Cl->>H1: call
    H1->>H2: forward over the host transport
    H2-->>H1: result
    H1-->>Cl: result
    Note over Cl,H2: every later call repeats the hop
```

```mermaid
sequenceDiagram
    participant Cl as Client
    participant H1 as Host 1
    participant H2 as Host 2
    Note over H2: owns the actor
    Cl->>H1: call
    H1-->>Cl: 421 with owner.endpoint
    Cl->>H2: retry
    H2-->>Cl: result
    Note over Cl: endpoint learned
    Cl->>H2: every later call, one trip
    H2-->>Cl: result
```

**`publicAddress` is required and deliberately never guessed.** `advertise` is the *internal*
peer origin, typically a pod IP. Redirecting a client there hangs, and publishing it hands
internal topology to anyone who can reach the public mount. Without `publicAddress` the mount
**proxies anyway** and dev-warns once. The 421 body carries `owner.endpoint`, never
`address`.

**`'proxy'` is the browser answer.** A cross-origin redirect preflights and is refused by the
default same-origin policy; redirecting a browser needs an explicit `origin` allowlist plus
CORS on the *owner's* mount. For browsers the single-origin shape above is better.

**Why 421 is safe to auto-retry:** the endpoint resolves the owner *before* dispatching, so a
redirect has provably run no application code. That matters because 421 is a status user
agents may retry on their own, and actor calls are not idempotent.

Limits: `$live` is never redirected; a redirected watch is bound to its owner only until the
actor migrates, then silently proxied again; and redirect chains are bounded at both ends,
default 2 hops.

The `locates` / `locateRemote` counters give you the miss rate your edge is producing — see
[Cluster stats](/actors/docs/cluster-stats).

## Next steps

- [Placement policies](/actors/docs/placement-policies) — the other half.
- [The client](/actors/docs/client) — `learningRouter()` and friends.
- [Wire protocol](/actors/docs/wire-protocol) — where the token sits.

---
url: https://sigx.dev/actors/docs/your-first-actor/
title: Your first actor
description: Build a persistent, live-updating counter end to end — the actor, the app module, the browser call and the dev server
---

# Your first actor

<p class="lede">A counter that survives restarts, never loses an increment, and pushes changes
to every open tab. Four files, no database.</p>

This is `examples/counter` from the actors repo, which runs this exact shape in dev and in
production.

## 1. The app module

One source of truth for storage, defaults and plugins — loaded by the dev server, the
production entry and your actor modules alike.

```ts
// src/actors.app.ts
import { defineActorApp } from '@sigx/actors/host';
import { fileStorage } from '@sigx/actors/node';

export const app = defineActorApp({
    // Keeps dev state across actor-file edits and restarts.
    storage: fileStorage({ dir: '.actors' }),
});

/** Bound to this app's plugin set — actor modules import this. */
export const { defineActor } = app;
```

## 2. The actor

```ts
// src/counter.actor.ts
import { defineActor } from './actors.app.ts';

export const Counter = defineActor({
    type: 'Counter',
    // This demo counter is deliberately public. Real actors inherit the
    // server app's policy, or declare their own `authorize:`.
    allowAnonymous: true,
    state: () => ({ count: 0, lastVisit: null as Date | null }),
    methods: (ctx) => ({
        async increment(by: number) {
            ctx.state.count += by;
            ctx.state.lastVisit = new Date();
            await ctx.save(); // persistence is explicit — state saves only when asked
            return ctx.state.count;
        },
        async current() {
            return { count: ctx.state.count, lastVisit: ctx.state.lastVisit };
        },
    }),
});
```

Four things are already true of this object, and none of them are things you wrote:

- Two browsers clicking at once cannot lose an increment — `increment` runs one turn at a
  time, so `ctx.state.count += by` needs no lock.
- Two different `name` props are two different actors with separate state, created on demand.
- `lastVisit` is a real `Date` in the browser, not a string — the
  [serialize codec](/server/packages/serialize/overview) carries it across.
- The actor deactivates when idle and reloads its state on the next call.

## 3. Read and write it from a component

Register the plugin once, so components can reach the actor:

```ts
// src/main.tsx
import { actorsPlugin } from '@sigx/actors/app';

app.use(actorsPlugin());
```

Then the actor is just data and an action:

```tsx
// src/Counter.tsx
import { component } from 'sigx';
import { useActorAction, useActorState } from '@sigx/actors/app';
import { Counter } from './counter.actor';

export const CounterView = component<{ name: string }>(({ props }) => {
    // Re-runs after every turn that changes this actor's state — in any tab.
    const state = useActorState(Counter, props.name, 'current', { live: true });
    const increment = useActorAction(Counter, props.name, 'increment');

    return () => (
        <>
            {state.match({
                pending: () => <p>…</p>,
                ready: (s) => (
                    <p>
                        {s.count} — last visit {s.lastVisit?.toLocaleTimeString() ?? '–'}
                    </p>
                ),
            })}
            <button disabled={increment.loading} onClick={() => increment.run([1])}>
                +1
            </button>
        </>
    );
});
```

Four things happened there without you asking:

- **`counter.actor.ts` was build-swapped**, so `Counter` is a typed client ref and
  `increment.run([1])` is a `POST` to `/_sigx/actor`. Rename the method and this file fails to
  compile — there is no second interface to keep in sync.
- **`current` was read on the server during SSR** and serialized into the page, so first paint
  has the count already and hydration costs no request.
- **`{ live: true }`** means the actor pushes a new result after every turn that changed its
  state, from any tab — see [Live reads](/actors/docs/live-reads).
- **The write refreshed the read.** `increment.run()` invalidates this counter's reads by default,
  so nothing calls `refresh()` by hand.

## 4. Run it

```ts
// vite.config.ts
import { sigxActors } from '@sigx/actors/vite';

export default {
    plugins: [sigxActors({ app: '/src/actors.app.ts' })],
    server: { watch: { ignored: ['**/.actors/**'] } },
};
```

```bash
pnpm dev
```

Open the page twice. Click in one tab and **both** update — the actor re-ran `current` after
the turn that changed its state and pushed the result to every live reader.

Stop the dev server and start it again — the count is still there, in `.actors/`.

## What to try next

- **Remove `await ctx.save()`** and restart. The count resets: persistence is explicit, and
  that is [deliberate](/actors/docs/state-and-persistence).
- **Add `await new Promise(r => setTimeout(r, 3000))`** inside `increment`, then click twice
  quickly. The second click waits — that is guarantee 3, [`await` keeping the turn open](/actors/docs/turns).
- **Replace `allowAnonymous: true`** with a real [policy](/actors/docs/guards) — usually by
  configuring the server app once, so every actor inherits it.
- **Run `pnpm --filter counter-example runtime-demo`** for the parts a counter does not
  reach: [detached work](/actors/docs/tasks) through `ctx.tasks`, and a
  [durable reminder](/actors/docs/timers-and-reminders) that survives a host restart.

## Next steps

- [The app](/actors/docs/the-app) — plugins, context extensions and lifecycle.
- [The actor model](/actors/docs/actor-model) — activation, turns and identity in depth.
- [State & persistence](/actors/docs/state-and-persistence) — `ctx.save()`, write-behind and
  migrations.
- [Running a host on Node](/actors/docs/node) — the production entry and graceful shutdown.

---
url: https://sigx.dev/daisyui/docs/getting-started/
title: Getting Started
description: Get started with @sigx/daisyui - beautiful UI components for SignalX
---

# Getting Started with DaisyUI

SignalX DaisyUI provides pre-built, accessible UI components powered by DaisyUI and Tailwind CSS.

## Installation

```bash
pnpm add @sigx/daisyui daisyui tailwindcss
```

The components run against your app's `sigx`, so there are no extra core packages to install — the only extra peers are the styling libraries `daisyui` (≥ 5) and `tailwindcss` (≥ 4), installed above. `@sigx/daisyui` does require your app to be on **SignalX core 0.14.x** (`sigx`, `@sigx/reactivity`, `@sigx/runtime-core`, `@sigx/runtime-dom`, all `^0.14.0`); an older core can't install it — pnpm's `strict-peer-dependencies` refuses outright and other package managers warn. The components' own API is unchanged across these core bumps, so they need no code changes — but upgrading a core from before 0.9.0 crosses core's async removals (`useAsync` / `<Suspense>` / `<ErrorBoundary>` → [`useData`](/core/docs/data-loading) / [`errorScope`](/core/docs/error-handling) / `<Defer>`), which an app using those must migrate even though daisyui itself is unaffected. Make sure Tailwind CSS and DaisyUI are also configured in your project (see below).

## Setup

### 1. Configure Tailwind

Add DaisyUI to your Tailwind config:

```js
// tailwind.config.js
module.exports = {
    content: ['./src/**/*.{tsx,ts,jsx,js}'],
    plugins: [require('daisyui')],
    daisyui: {
        themes: ['light', 'dark', 'cupcake', 'forest'],
    },
};
```

### 2. Initialize Theme

Initialize the theme system in your app:

```tsx
import { component, onMounted } from 'sigx';
import { initializeTheme } from '@sigx/daisyui';

const App = component(() => {
    onMounted(() => {
        initializeTheme({ defaultTheme: 'dark' });
    });
    
    return () => <div>...</div>;
});
```

## Using Components

Import and use components directly:

```tsx
import { component, signal, render } from 'sigx';
import { Button, Modal, ModalHeader, ModalBody, Card, CardTitle } from '@sigx/daisyui';

const MyComponent = component(() => {
    const showModal = signal(false);
    
    return () => (
        <Card>
            <Card.Body>
                <CardTitle>Welcome!</CardTitle>
                <p>This is a beautiful card component.</p>
                <Card.Actions>
                    <Button 
                        variant="primary"
                        onClick={() => showModal.value = true}
                    >
                        Open Modal
                    </Button>
                </Card.Actions>
            </Card.Body>
            
            <Modal 
                open={showModal.value}
                onClose={() => showModal.value = false}
            >
                <ModalHeader onClose={() => showModal.value = false}>Hello!</ModalHeader>
                <ModalBody>
                    Modal content goes here.
                </ModalBody>
            </Modal>
        </Card>
    );
});

render(<MyComponent />, "#sandbox");
```

## Theme Toggle

Add a theme toggle to your app:

```tsx
import { ThemeToggle } from '@sigx/daisyui';

// Simple toggle between light and dark
<ThemeToggle />

// Or with custom themes
<ThemeToggle themes={['light', 'dark', 'cupcake']} />
```

## Next Steps

- [Components](/daisyui/docs/components) - Browse all available components
- [Theming](/daisyui/docs/theming) - Customize themes and colors
- [API Reference](/daisyui/api) - Complete API documentation

---
url: https://sigx.dev/use/docs/create-global-state/
title: createGlobalState
description: Wrap a state factory so it runs once in a detached scope and every later call returns the same cached result — app-wide shared signals without a store
---

# createGlobalState

Wrap a state factory so its first call runs inside a detached `effectScope()` and every later call returns the **same cached result** — app-wide shared signals without a store. Cross-platform — import from `@sigx/use`.

```ts
import { signal } from 'sigx';
import { createGlobalState } from '@sigx/use';

export const useFilters = createGlobalState(() =>
    signal({ q: '', tags: [] as string[] })
);

// any component gets the SAME signal:
const filters = useFilters();
filters.q = 'sigx';
```

The scope the factory runs in is **never disposed** — the state lives for the process. That's the point: it's a lightweight singleton for device- and UI-level state that every component shares.

> **SSR caveat.** The cache is module-level, shared across every request in the process. Use it for device/UI state only, **never per-user data** — that's [`defineStore`](/store)'s job. A per-user value cached here would leak between requests.

## Signature

```ts
function createGlobalState<Fn extends (...args: never[]) => unknown>(stateFactory: Fn): Fn;
```

The returned function has the same signature as the factory you pass — the wrapping is transparent to callers.

**Platform:** everywhere.

## See also

- [`createSharedComposable`](/use/docs/create-shared-composable) — refcounted sharing that tears down when the last subscriber leaves, for effect-ful composables.
- [`@sigx/store`](/store) — `defineStore` for structured, per-user application state.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/store/docs/actions-and-async/
title: Actions & Async
description: pending, action lifecycle events, error semantics, and async patterns
---

# Actions & Async

`defineActions(obj)` wraps each function you pass it. The wrapped action is callable with its **exact original signature** — same parameters, same return type — and carries three things on the function itself: a reactive `pending` flag, and the `onDispatching` / `onDispatched` / `onFailure` lifecycle subscribers. This page covers what each of those does precisely, the error semantics, and the async patterns they enable.

If you haven't read [Defining a Store](/store/docs/defining-a-store) yet, start there — this page assumes you know what `defineState` and `defineActions` return.

## `pending` is a counter, not a boolean flag

`store.save.pending` is `true` while **any** invocation of `save` is in flight. Internally each call increments a reactive counter on entry and decrements it when the call settles (synchronously for sync actions, on promise settlement for async ones); `pending` reads as `count > 0`. Two consequences:

- **Overlapping invocations are handled correctly.** Fire `save()` twice and `pending` stays `true` until *both* settle — there is no flicker when the first one finishes early.
- **Reading `pending` in a render function is reactive** — the component re-renders when the action goes in or out of flight, like any other signal read.

Try it: fire both uploads quickly. The status stays "Uploading…" until the *slower* one finishes, and the counter only catches up as each completes.

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const useUploadStore = defineStore('uploads', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ completed: 0 });

    const actions = defineActions({
        async upload(ms: number) {
            await new Promise(resolve => setTimeout(resolve, ms));
            state.completed++;
        },
    });

    return { ...signals, ...actions };
});

const Uploader = component(() => {
    const store = useUploadStore();
    return () => (
        <div class="space-y-2">
            <div class="flex gap-2">
                <button class="btn btn-sm" onClick={() => store.upload(800)}>Upload (0.8s)</button>
                <button class="btn btn-sm" onClick={() => store.upload(2500)}>Upload (2.5s)</button>
            </div>
            <p class="text-sm">
                <span class={store.upload.pending ? 'text-warning font-bold' : ''}>
                    {store.upload.pending ? 'Uploading…' : 'Idle'}
                </span>
                {' — '}{store.completed} completed
            </p>
        </div>
    );
});

render(<Uploader />, "#sandbox");
```

`pending` is per-action — `store.save.pending` and `store.load.pending` are independent. For a store-wide "anything in flight" flag, derive one with `computed` in the setup.

## Don't call state-writing actions from inside a render

Reading `store.x` inside a render function subscribes that render to `x` — that's the whole point of the reactive surface. **Calling an action whose body writes state from inside the render closure self-loops by design:** the write changes state the render depends on, which schedules the render again, which calls the action again. That's not a store quirk; it's the same loop you'd get writing a signal you read in the same render.

```tsx
// ✗ self-loop: the render reads `count`, and calling load() writes it
const Bad = component(() => {
    const store = useThingStore();
    return () => {
        store.load();              // writes state the render reads → re-render → load() → …
        return <p>{store.count}</p>;
    };
});
```

Do data work in a lifecycle hook or a `watch`, not in the render body — the render should only *read*:

```tsx
import { component, onMounted, watch } from 'sigx';

const Good = component(() => {
    const store = useThingStore();
    onMounted(() => store.load());                 // once, on mount
    watch(() => route.params.id, (id) => store.load(id)); // again when the input changes
    return () => <p>{store.count}</p>;              // render only reads
});
```

The action wrapper helps you here in one specific way: its own bookkeeping — the inflight counter behind `.pending` and the lifecycle-topic plumbing — runs **untracked**. So merely *calling* an action from a reactive context never subscribes that context to the wrapper's internals; only the reads your action body actually performs get tracked. That's why `.pending` stays reactive (you can read it in render to drive a spinner) without a call itself dragging the render into a loop. The loop above comes purely from your action *writing state the render reads* — keep state writes out of render and you're fine.

## The lifecycle events

Each action carries three subscribable events, in dispatch order:

| Event | Fires | Callback receives |
|---|---|---|
| `onDispatching` | before the action body runs | `(...args)` — the original arguments |
| `onDispatched` | after the action completes | `(result, ...args)` — for async actions, the **resolved value** |
| `onFailure` | on a sync throw or async rejection | `(error, ...args)` |

```ts
const store = useUploadStore();

store.upload.onDispatching.subscribe((ms) => {
    console.log('starting upload, simulated ms:', ms);
});
store.upload.onDispatched.subscribe((result, ms) => {
    console.log('upload done');
});
store.upload.onFailure.subscribe((error, ms) => {
    console.error('upload failed:', error);
});
```

Every `subscribe()` returns a `Subscription` with `unsubscribe()`. When you subscribe **inside a component setup**, the subscription is automatically removed on unmount — see [Events & Observability](/store/docs/events-and-observability#subscriptions-clean-up-with-the-component) for how that works.

Note that `onDispatched` fires with the **resolved value**, not the promise: for `async fetchUser(id)` returning a `User`, subscribers get `(user, id)`. The subscriber types are derived from the action's own signature — see [TypeScript](/store/docs/typescript#what-subscribers-receive).

## Error semantics

Errors are the caller's to handle — the wrapper never swallows them:

- **Sync actions**: a throw publishes `onFailure` (with `(error, ...args)`) and then **re-throws** to the caller. The call site sees the exception exactly as if the action were unwrapped.
- **Async actions**: the call returns the **original promise**. `await store.save()` observes the resolved value or the rejection, normally. On rejection, `onFailure` fires too.
- **No unhandled-rejection noise**: the wrapper attaches an internal, handled side chain to the returned promise (that's where `pending` is settled and the events publish). Because that side chain handles rejection, a fire-and-forget call — `store.save()` without `await` — never triggers an unhandled-rejection warning, while an awaited call still rejects into your `try/catch`.

That combination is what makes the "feed" pattern below safe: components can fire actions without awaiting them and route all failure handling through `onFailure`.

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const useSyncStore = defineStore('sync', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ log: [] as string[] });

    const actions = defineActions({
        async push(shouldFail: boolean) {
            await new Promise(resolve => setTimeout(resolve, 600));
            if (shouldFail) throw new Error('server said no');
            return 'synced';
        },
    });

    // Cross-cutting failure handling, wired once in the setup:
    actions.push.onFailure.subscribe((error, shouldFail) => {
        state.log.push(`✗ ${String(error)}`);
    });
    actions.push.onDispatched.subscribe((result) => {
        state.log.push(`✓ ${result}`);
    });

    return { ...signals, ...actions };
});

const SyncPanel = component(() => {
    const store = useSyncStore();
    return () => (
        <div class="space-y-2">
            <div class="flex gap-2">
                <button class="btn btn-sm btn-primary" disabled={store.push.pending}
                        onClick={() => store.push(false)}>
                    Sync (succeeds)
                </button>
                <button class="btn btn-sm btn-error" disabled={store.push.pending}
                        onClick={() => store.push(true)}>
                    Sync (fails)
                </button>
            </div>
            <ul class="text-sm font-mono">
                {store.log.map(line => <li>{line}</li>)}
            </ul>
        </div>
    );
});

render(<SyncPanel />, "#sandbox");
```

The buttons above call `store.push(...)` without `await` — failures still reach `onFailure`, and the console stays free of unhandled-rejection warnings.

> Subscriber errors are isolated, too: a throwing `onFailure` or `onDispatched` handler is logged and cannot poison the action's own promise chain or break other subscribers.

## Cancellation with AbortSignal

The store doesn't impose a cancellation mechanism — actions are plain functions, so the standard `AbortController` pattern works as-is. Keep the controller in **private state** (don't return it) and expose a `cancel` action:

```ts
import { defineStore } from '@sigx/store';

const useSearchStore = defineStore('search', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ results: [] as string[] });
    let controller: AbortController | null = null;

    const actions = defineActions({
        async search(query: string) {
            controller?.abort();                     // cancel the previous run
            controller = new AbortController();
            const res = await fetch(`/api/search?q=${query}`, { signal: controller.signal });
            state.results = await res.json();
        },
        cancel() {
            controller?.abort();
        },
    });

    return { ...signals, ...actions };
});
```

An aborted `fetch` rejects with an `AbortError`, which fires `onFailure` like any other rejection — filter it out there if cancellations shouldn't be reported as failures.

## Races: latest wins

`pending` tells you *whether* something is in flight, not *which* invocation will finish last. When overlapping calls can resolve out of order (type-ahead search, tab switching), guard the state write with a request id so only the latest invocation applies:

```ts
let requestId = 0;

const actions = defineActions({
    async load(query: string) {
        const id = ++requestId;
        const data = await api.search(query);
        if (id !== requestId) return;   // a newer call superseded this one
        state.results = data;
    },
});
```

This and related recipes — de-duplication, optimistic updates with rollback via `onFailure` — are worked through in [Patterns](/store/docs/patterns#request-de-duplication-and-latest-wins).

## Next steps

- [Events & Observability](/store/docs/events-and-observability) — state events vs. action events, laziness, and the inspection registry.
- [Patterns](/store/docs/patterns) — optimistic updates, request races, undo.
- [TypeScript](/store/docs/typescript) — how the subscriber types are derived, and why actions should be single-signature.
- [API Reference](/store/docs/api#storeaction) — the `StoreAction` type in full.

---
url: https://sigx.dev/use/docs/use-session-storage/
title: useSessionStorage
description: A useStorage preset backed by window.sessionStorage — persists for the current tab session only
---

# useSessionStorage

A [`useStorage`](/use/docs/use-storage) preset backed by `window.sessionStorage` — a signal that persists for the current **tab session** and is cleared when the tab closes. Browser composable — import from `@sigx/use-web`.

```ts
import { useSessionStorage } from '@sigx/use-web';

const draft = useSessionStorage('draft', '');
draft.value = 'hello';   // persisted for this tab session
```

## Signature

```ts
function useSessionStorage<T extends Primitive>(key: string, defaults: T, options?: UseStorageOptions<T>): PrimitiveSignal<T>;
function useSessionStorage<T extends object>(key: string, defaults: T, options?: UseStorageOptions<T>): Signal<T>;
```

Same two overloads as `useStorage`: an **object default** returns a deep-reactive `Signal<T>` that auto-persists on mutation; a **primitive default** returns a `PrimitiveSignal<T>` that persists on `.value` write.

See [`useStorage`](/use/docs/use-storage) for the full semantics — object proxies, serializers, options, and SSR behaviour.

## See also

- [`useStorage`](/use/docs/use-storage) — the flagship, with every option and the deep-reactive model.
- [`useLocalStorage`](/use/docs/use-local-storage) — the same preset persisted across sessions.

---
url: https://sigx.dev/use/docs/use-resize-observer/
title: useResizeObserver
description: Observe element size changes with a ResizeObserver that follows reactive targets and disconnects with the owning scope
---

# useResizeObserver

Observe element size changes with a `ResizeObserver`. Browser composable — import from `@sigx/use-web`.

The observer **follows reactive targets** — re-observing when the element changes — and disconnects with the owning scope. Point it at a single [element target](/use/docs/conventions#element-targets-web) or an array of them.

```ts
import { signal } from 'sigx';
import { useResizeObserver } from '@sigx/use-web';

const box = signal<HTMLElement | null>(null);
// <div ref={box}> …

useResizeObserver(box, ([entry]) => {
    console.log(entry.contentRect.width, entry.contentRect.height);
});
```

The callback is the native `ResizeObserverCallback` — you receive `ResizeObserverEntry[]`, so `contentRect`, `borderBoxSize`, and friends are all available. Options extend the native `ResizeObserverOptions` (e.g. `{ box: 'border-box' }`) alongside the `ConfigurableWindow` override.

> Reaching for `width`/`height` as reactive values? Use [`useElementSize`](/use/docs/use-element-size), which wraps this into a `{ width, height }` reactive view.

## Signature

```ts
function useResizeObserver(
    target: MaybeSignalElement | MaybeSignalElement[],
    callback: ResizeObserverCallback,
    options?: UseResizeObserverOptions,
): UseResizeObserverReturn;

interface UseResizeObserverOptions extends ConfigurableWindow, ResizeObserverOptions {}
```

## Returns

```ts
interface UseResizeObserverReturn {
    isSupported: ReadSignal<boolean>;
    stop: Stop;
}
```

| Field | Type | Description |
|---|---|---|
| `isSupported` | `ReadSignal<boolean>` | Whether `ResizeObserver` exists in this context. |
| `stop` | [`Stop`](/use/docs/conventions#control-handles-pausable-and-stop) | Disconnect the observer manually (for standalone, no-scope use). |

## SSR

Inert: `isSupported` is `false` and the callback **never fires**.

## See also

- [`useElementSize`](/use/docs/use-element-size) — reactive `{ width, height }` built on this.
- [`useIntersectionObserver`](/use/docs/use-intersection-observer) — the visibility counterpart.
- [Conventions → Element targets (web)](/use/docs/conventions#element-targets-web) — the accepted target shapes.

---
url: https://sigx.dev/actors/docs/cacheable-reads/
title: Cacheable reads
description: "The reads: declaration, GET on the actor endpoint, and the ordering guarantee you give up in exchange for cache hits"
---

# Cacheable reads

<p class="lede">Declare a method a cacheable read and the endpoint accepts `GET` for it and
emits the `Cache-Control` you asked for — so browsers, CDNs and reverse proxies absorb read
traffic that would otherwise reach an actor.</p>

```ts
defineActor({
    type: 'Product',
    allowAnonymous: true,
    reads: {
        summary: { maxAge: 5 },
        price: { maxAge: 60, public: true, staleWhileRevalidate: 30 },
    },
    state: () => ({ cents: 999 }),
    methods: (ctx) => ({
        async summary(currency: string) { /* … */ },
        async price() { return ctx.state.cents; },
    }),
});
```

`GET {base}/r/{token}/Product%23price?args=["p1"]` returns the same envelope a POST returns,
plus `Cache-Control: public, max-age=60, s-maxage=60, stale-while-revalidate=30`.

The declaration is core's `ServerFnReadCache` vocabulary unchanged, and the build stamps the
names onto the client ref so the proxy issues `GET` on its own — **nothing at the call site
changes.**

## What you are trading

> **A cached read bypasses the [turn ordering guarantee](/actors/docs/turns).** For `maxAge`
> seconds the response an intermediary serves may be older than the actor's state, and nothing
> on the server can
> pull it back — not `ctx.save()`, not `useActorAction`, not `cells.invalidate()`, which
> refresh this page's cells and never a CDN's copy.

Declare a read where staleness is a **product decision**, not where it would be a bug. A price
that may be five seconds old is usually fine. A cart total on the checkout screen is not.

The declaration is also a promise the runtime cannot verify: a listed method must be
side-effect-free and idempotent, exactly as with `cache` on a server function. A mutating
method declared cacheable re-opens CSRF.

## The rules that follow

**`public` is gated.** It puts the response in *shared* caches, where one caller's copy is
served to the next, so core's contract for it is args-only — never cookies, auth or headers. A
guard is the one thing here that provably reads the request, and nothing can inspect *what* it
reads, so `public` on an authorized read is a **definition-time throw**. Without `public` the read
is still cached, per client, and the endpoint adds `Vary: Cookie`.

**Policies still run**, on `GET` exactly as on `POST`. A denial answers its own status with
`Cache-Control: no-store` — a failed read is never cacheable.

**Streams cannot be declared.** Saying so is a definition-time throw rather than a silently
ignored declaration.

**POST keeps working** for every declared read. The declaration lives on the definition, not
on the wire, so a hand-built host with no build transform, an older client, or a service
calling by hand all still work.

**Routing is unchanged** — the [token](/actors/docs/locality-routing) travels in both
carriers, and an actor another host owns is proxied as usual, with the answering host making
the caching promise.

**No `content-type` on the GET.** It would describe a body that does not exist, and it is a
non-safelisted header, so leaving it off is one fewer reason to preflight. That is not a
promise of no preflight — the routing token header ships by default and triggers one on its
own. A cross-origin caller who needs a genuinely simple `GET` wants `route: 'none'` and no
custom headers either. Same-origin, the usual case, never preflights.

**A GET puts the actor key and every argument in the URL**, where a POST body kept them out of
access logs, proxy traces and referrer headers. That is the same log-hygiene concern the
[hashed routing token](/actors/docs/locality-routing) exists for, and it now applies to the
arguments too, in plaintext.

`maxAge` values are the whole non-negative seconds `Cache-Control` actually defines — a
fractional one is a malformed directive, so it is refused rather than emitted.

## Opting out per call

```ts
await actor(Product, 'p1').with({ get: false }).summary('EUR');
```

Sends a declared read as a `POST`: no caching, but no arguments in the URL either, and no
query-length cap — a long enough query is a `414`. The endpoint accepts both carriers for a
declared read, so this is purely a client-side choice.

A [one-way call](/actors/docs/one-way-calls) forces `POST` even on a declared read, because an
acknowledgement must never be served from a cache.

## Reads that should not queue

If the problem is that a read is stuck behind slow writes rather than that it is expensive,
the answer is not caching — it is
[`methodReentrancy: { price: 'always' }`](/actors/docs/reentrancy), which lets that one method
interleave. The two compose well.

## Next steps

- [Live reads](/actors/docs/live-reads) — the opposite trade: always current, pushed.
- [Locality routing](/actors/docs/locality-routing) — the token in the URL.
- [Authorization](/actors/docs/guards) — why `public` is refused on an authorized read.

---
url: https://sigx.dev/router/docs/getting-started/
title: Getting Started
description: Get started with @sigx/router - the declarative router for SignalX
---

# Getting Started with Router

The SignalX Router provides declarative, type-safe routing for your SignalX applications with full SSR support.

## Installation

```bash
pnpm add @sigx/router
```

The router runs against your app's copy of SignalX, so it expects `sigx` to already be installed — the reactive engine comes from there. No core packages to list: with `sigx` present, `pnpm add @sigx/router` is all you need.

## Basic Setup

Create a router instance and define your routes:

```tsx
import { createRouter, RouterView, RouterLink } from '@sigx/router';
import { createApp } from 'sigx';

// Define your routes
const router = createRouter({
    routes: [
        { path: '/', component: Home },
        { path: '/about', component: About },
        { path: '/users/:id', component: UserProfile },
    ],
});

// Create your app with the router plugin
const app = createApp(App);
app.use(router);
app.mount('#app');
```

## Using RouterView

The `RouterView` component renders the matched route component:

```tsx
import { component } from 'sigx';
import { RouterView, RouterLink } from '@sigx/router';

const App = component(() => {
    return () => (
        <div>
            <nav>
                <RouterLink to="/">Home</RouterLink>
                <RouterLink to="/about">About</RouterLink>
            </nav>
            
            <main>
                <RouterView />
            </main>
        </div>
    );
});
```

## RouterLink Component

Use `RouterLink` for navigation instead of regular anchor tags:

```tsx
<RouterLink to="/users/123">View User</RouterLink>

{/* With active class */}
<RouterLink 
    to="/about" 
    activeClass="text-primary font-bold"
>
    About
</RouterLink>
```

## Next Steps

- [Defining Routes](/router/docs/routes) - Learn about route configuration
- [Navigation](/router/docs/navigation) - Programmatic navigation
- [Route Guards](/router/docs/guards) - Protect routes with guards
- [SSR Routing](/router/docs/ssr) - Server-side rendering and hash-based routing for static hosts

---
url: https://sigx.dev/actors/docs/socket-sessions/
title: Socket sessions
description: createActorSocketSession — one session per connection, the upgrade-time posture it pins, the caps HTTP used to give implicitly, and session lifetime
---

# Socket sessions

<p class="lede">A `Request` in, a send and a close callback out. That is the whole seam, which
is why `ws`, socket.io, uWS, Bun, Deno and a Durable Object all drive the same core.</p>

```ts
import { createActorSocketSession } from '@sigx/actors/server';

const session = await createActorSocketSession({
    host,
    request,                                   // the UPGRADE request
    send: (message) => socket.send(message),
    close: (code, reason) => socket.close(code, reason),
});

socket.on('message', (data) => session.handle(String(data)));
socket.on('close', () => session.close());
```

`session.handle(message)` never throws — a protocol breach closes the socket through your
`close` callback instead. `session.close()` aborts every in-flight call and is idempotent.

Most people never call this directly:
[`attachActorSocket`](/actors/packages/actors-ws/installation#the-node-adapter) wraps it for
Node, and [`workerSocket()`](/actors/packages/actors-cloudflare/overview) for Workers.

## What pins at the upgrade, and what does not

**Origin is checked once, at the upgrade.** This is the one check that cannot move to
per-message, because the cookies ride the upgrade: a browser will open a cross-origin
WebSocket with credentials attached and **no preflight** to stop it. The policy is
`posture.origin ?? 'same-origin'` — the same contract as `ServerFnRequestOptions.origin`.

**Identity is pinned once**, from the upgrade request's cookies.

**The full prelude re-runs on every message.** Middleware may be a rate limiter, so it has to
see each call; authentication itself stays memoized on the connection.

A refused upgrade — origin, or authentication — answers before serving a byte.

## Calls

Unary calls, streams and cancellation all ride the one connection, with a per-call deadline
from `posture.timeoutMs`. Middleware sees per-call `locals`, but `responseHeaders` and
`status()` are **inert**: there is no response to put a header on.

Guards reach the pipeline through the same single door every transport uses —
`enterActorRequest()`, `actorPosture()` and `actorPrincipal()`.

## The caps HTTP gave you for free

An HTTP mount gets body limits, connection limits and timeouts from the server around it. A
socket has none of that, so the session states them:

| Option | Default | What it does |
|---|---|---|
| `maxMessageBytes` | `posture.maxBodyBytes ?? 1 MiB` | oversized message closes **1009**. `0` disables |
| `maxConcurrent` | `256` | most calls in flight at once; excess **fails the call with 429**, never the connection. `0` disables |
| `maxSubscriptions` | `256` | most live subscriptions this connection may hold |
| `pingMs` | `30_000` | outbound keepalive after this much send-silence. `0` disables |

An unparseable message closes **1003**.

`maxSubscriptions` is validated at construction, not at first use — a security bound must not
be disabled by a typo. The connection is the right unit for it, because the connection is what
actually costs activations: over one socket a page can hold thousands of in-flight calls, each
able to force an activation.

## Session lifetime

Both default to `0` (off), and both are validated at construction.

**`revalidateMs`** re-runs authentication against the **pinned upgrade request** on a fresh
context every interval, and closes **1008** when it no longer stands: the authenticate hook
throws, a previously-authenticated connection comes back anonymous, or the identity *changes*
— a swap mid-connection is a reconnect, not a mutation.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Its honest contract is narrow.</strong> It answers "are the credentials presented
    at upgrade still valid" — never "what would the browser send now". A rotated cookie is
    invisible until the next connection.
  </div>
</div>

**`maxConnectionMs`** caps one connection's lifetime and closes 1008 at the cap. It is also
the credential-refresh mechanism, precisely because the reconnect is a fresh upgrade carrying
the browser's **current** cookies. Subscriptions re-establish over it; in-flight calls fail
un-retried, as on any drop.

**Set one of them in any app with sign-out or short-lived sessions.** With both off, a
connection authenticated an hour ago is still trusted.

## Next steps

- [`@sigx/actors-ws`](/actors/packages/actors-ws/overview) — the client transport and the Node adapter.
- [Observability](/actors/docs/observability#socket-sessions) — `socketStats()`.
- [Wire protocol](/actors/docs/wire-protocol#the-socket-wire) — the messages themselves.

---
url: https://sigx.dev/monaco/docs/getting-started/
title: Getting Started
description: "@sigx/monaco-editor — pluggable Monaco editor wrapper with prebundled assets and a Vite plugin"
---

# Getting Started with Monaco

`@sigx/monaco-editor` is a pluggable wrapper around the [Monaco](https://microsoft.github.io/monaco-editor/) editor (the engine behind VS Code) built for SignalX apps. It gives you:

- A reactive `<MonacoEditor />` SignalX component plus a low-level imperative `createEditor()` API.
- A loader that lazy-loads Monaco on demand using one of two strategies — `prebundled` (assets committed to the package) or `cdn`.
- Composable language packs for TypeScript/JSX, HTML, CSS, and JSON, each wiring the correct Monaco worker and IntelliSense.
- Optional Shiki highlighting via a dedicated subpath.
- A Vite plugin that keeps Monaco out of your application bundle and serves the prebundled assets.

## Install

```bash
pnpm add @sigx/monaco-editor monaco-editor
```

`monaco-editor` is a peer dependency. See [Installation](/monaco/docs/installation) for peer deps, Vite wiring, and the required configuration.

## Minimal example

Wiring up Monaco is three steps: add the Vite plugin, register the language packs you need once at module load, then render the component.

```tsx
// vite.config.ts
import { defineConfig } from 'vite';
import { sigxPlugin } from '@sigx/vite';
import { monacoPrebundledPlugin } from '@sigx/monaco-editor/vite';

export default defineConfig({
    plugins: [
        sigxPlugin(),
        monacoPrebundledPlugin({ strategy: 'prebundled', publicPath: '/monaco-bundle' }),
    ],
    oxc: { jsx: { runtime: 'automatic', importSource: 'sigx' } },
});
```

```tsx
// App.tsx
import { component, render } from 'sigx';
import {
    MonacoEditor,
    configureMonaco,
    typescriptLanguagePack,
    cssLanguagePack,
    jsonLanguagePack,
    htmlLanguagePack,
} from '@sigx/monaco-editor';

// Register language packs once, before the editor first mounts.
configureMonaco({
    languages: [
        typescriptLanguagePack({ jsxImportSource: 'sigx' }),
        cssLanguagePack(),
        jsonLanguagePack(),
        htmlLanguagePack(),
    ],
});

const App = component(({ signal }) => {
    const state = signal({
        language: 'typescript',
        theme: 'vs-dark',
        code: 'const greeting: string = "Hello, Monaco";\n',
    });

    return () => (
        <MonacoEditor
            value={state.code}
            language={state.language}
            theme={state.theme}
            onChange={(v) => (state.code = v)}
        />
    );
});

render(<App />, document.getElementById('app')!);
```

The component lazy-loads Monaco on mount, applies the registered language packs, and disposes the editor automatically on unmount. The container fills its parent by default (`width: 100%; height: 100%;`), so give it a sized parent element.

## Two-way model binding

The example above uses one-way binding: `value` flows into the editor and `onChange` writes edits back by hand. For a single source of truth, bind `model` instead — typing in the editor updates your state, and updating your state updates the editor, with no `onChange` wiring. `MonacoEditorProps` is defined as `Define.Model<string>`, so the prop accepts the same [model binding](/core/docs/two-way-binding) syntax as any other SignalX component. When `model` is supplied it takes precedence over `value`.

```tsx
const App = component(({ signal }) => {
    const state = signal({ code: 'const greeting: string = "Hello, Monaco";\n' });

    return () => (
        <div style="display: flex; flex-direction: column; gap: 8px;">
            <MonacoEditor model={() => state.code} language="typescript" theme="vs-dark" />
            {/* Edits in the editor flow into state.code; this stays in sync. */}
            <p>{state.code.length} characters</p>
        </div>
    );
});
```

`model={() => state.code}` is the accessor form. You can also pass an explicit binding tuple — `model={[state, 'code']}` — when the state object and key are more convenient to forward. Inside the component the editor reads and writes through `props.model.value`.

## How loading works

You never import `monaco-editor` directly in client code. The Vite plugin replaces every `monaco-editor` import with a throwing stub and keeps it out of `optimizeDeps`. Instead, Monaco is fetched at runtime by `loadMonaco()` — which the `<MonacoEditor />` component and `createEditor()` call for you. The plugin and the runtime loader agree on a strategy through a `window.__MONACO_LOADER_CONFIG__` snippet the plugin injects into your HTML.

## Next steps

- [Installation](/monaco/docs/installation) — peer deps, Vite wiring, and the prebundled vs CDN asset strategies.
- [Language packs and IntelliSense](/monaco/docs/language-packs) — registering TS/JSX, HTML, CSS, and JSON, plus themes and extra type definitions.
- [Imperative editors and Shiki highlighting](/monaco/docs/imperative-and-shiki) — `createEditor()` and the optional Shiki integration.
- [API Reference](/monaco/docs/api) — every export with signatures.

---
url: https://sigx.dev/store/docs/defining-a-store/
title: Defining a Store
description: State, derived values, actions, and events with defineStore
---

# Defining a Store

Everything in `@sigx/store` starts with `defineStore`. It takes a `name` (the logical store name, used for instance ids like `todos#1` and as the default persistence key), a `setup` function, and an optional lifetime. The setup receives a context with `defineState`, `defineActions`, and `defineEvents`, and **whatever it returns becomes the store**.

```ts
import { defineStore } from '@sigx/store';

const useMyStore = defineStore('my-store', (ctx) => {
    // ctx.defineState(...), ctx.defineActions(...), ctx.defineEvents(...)
    return { /* spread signals, actions, computeds, anything else */ };
}, 'scoped');
```

`defineStore` returns a **factory function**. Calling that factory creates (or resolves, depending on the lifetime) an instance. By convention it is named `useXxxStore`, but it is just a function — there is no separate `useStore` export.

This page is the conceptual map: each building block in brief, with a deep guide behind it. If you want the full picture of one topic, follow the link at the end of its section.

## State

`defineState(obj)` turns a plain object into deep reactive, signal-backed state. It returns four things:

```ts
const { state, signals, events, patch } = ctx.defineState({ count: 0, name: 'Ada' });
```

- `state` — the deep reactive object. Read and write properties freely inside the setup and actions; nested objects and arrays are reactive too.
- `signals` — spreadable per-key signal views. **The keys you return become the store's public state**; keys you don't return stay private to the setup.
- `events` — one change event per key (`events.count`, `events.name`) with `(value, prev)` callbacks. Lazy: the deep watcher behind a key only runs while someone is subscribed — see [Events & Observability](/store/docs/events-and-observability).
- `patch` — atomic multi-key update; the whole update flushes reactivity once. Accepts a partial object or a mutator function. Errors inside the mutator propagate to the caller.

```ts
state.count = 5;                       // direct assignment
patch({ count: 42, name: 'Grace' });   // atomic multi-key (object form)
patch(s => { s.count++; });            // atomic (mutator form)
```

### Public vs. private state

Only the key signals you spread into the return are part of the store's surface — and of `$patch` / `$events` typing on the instance:

```ts
const useCounter = defineStore('counter', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ count: 0, internalTicks: 0 });

    const actions = defineActions({
        increment() { state.count++; state.internalTicks++; },
    });

    // expose count, keep internalTicks private:
    const { count } = signals;
    return { count, ...actions };
});

const store = useCounter();
store.count;          // ✔ public
// store.internalTicks — not on the store, and not in $patch/$events
```

How that selection drives the instance types is covered in [TypeScript](/store/docs/typescript).

## Derived / computed values

`@sigx/store` does not ship its own getter helper. Build derived values with `computed` and return them directly — on the instance they unwrap to plain **read-only** values.

```tsx
import { computed } from 'sigx';
import { defineStore } from '@sigx/store';

const useCartStore = defineStore('cart', ({ defineState }) => {
    const { state, signals } = defineState({
        items: [
            { name: 'Keyboard', price: 80, qty: 1 },
            { name: 'Mouse', price: 30, qty: 2 },
        ],
    });

    const total = computed(() =>
        state.items.reduce((sum, item) => sum + item.price * item.qty, 0)
    );

    return { ...signals, total };
});

const store = useCartStore();
store.total;       // plain number — no .value
store.total = 0;   // ✗ throws: computed values are read-only
```

## Actions

`defineActions(obj)` wraps a set of functions. Each returned action is callable with its exact original signature, plus a reactive in-flight flag and three lifecycle event subscribers riding on the function itself:

```ts
const actions = ctx.defineActions({
    add(a: number, b: number) { return a + b; },
    async fetchData() { return await api.load(); },
});

actions.add(3, 7);          // => 10
actions.fetchData.pending;  // reactive: true while any invocation is in flight

actions.fetchData.onFailure.subscribe((error) => console.error('fetch failed', error));
```

- `action.onDispatching.subscribe(fn)` — before the action body, with the original args.
- `action.onDispatched.subscribe(fn)` — after the action, with `(result, ...args)`; for async actions, after the promise resolves, with the **resolved value**.
- `action.onFailure.subscribe(fn)` — on a sync throw or async rejection, with `(error, ...args)`.

Errors are the caller's to handle — never swallowed: sync actions re-throw, async actions return the **original promise**. The full story — overlapping invocations, optimistic updates, aborts, race patterns — lives in [Actions & Async](/store/docs/actions-and-async).

> Declare each action as a single function signature (union parameter types instead of overloads); the event subscriber types are inferred from that one signature. Rationale in [TypeScript](/store/docs/typescript).

## Custom events

`defineEvents<EventMap>()` creates a typed group of topics, auto-namespaced to the store instance (`${id}.events`) and destroyed with it. Return the ones you want subscribers to reach:

```ts
import { defineStore } from '@sigx/store';

type CartEvents = {
    checkedOut: { orderId: string };
    cleared: void;
};

const useCartStore = defineStore('cart', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ items: [] as Item[] });
    const events = ctx.defineEvents<CartEvents>();

    const actions = ctx.defineActions({
        async checkout() {
            const orderId = await api.checkout(state.items);
            patch({ items: [] });
            events.checkedOut.publish({ orderId });
        },
    });

    return { ...signals, ...actions, onCheckedOut: events.checkedOut };
});

useCartStore().onCheckedOut.subscribe(({ orderId }) => { /* typed */ });
```

Every `subscribe()` returns a `Subscription` with `unsubscribe()`. When to reach for custom events versus per-key state events versus action events — and how devtools discovers all of them — is the subject of [Events & Observability](/store/docs/events-and-observability).

## Lifetime

The third argument to `defineStore` is the instance lifetime — `'singleton' | 'scoped' | 'transient'`, defaulting to `'scoped'`. It is honored by the core DI layer (core `0.5.0`): singletons are shared per app, scoped instances respect `defineProvide` subtree overrides, transients are created per call. [Lifetimes & DI](/store/docs/lifetimes-and-di) covers each in practice, plus parameterized stores and the SSR contract.

## Composables

Because a store is "just" a setup function, reusable behavior is a plain function that takes the context — the built-in [`persist`](/store/docs/persistence) composable is the canonical example:

```ts
import { persist } from '@sigx/store/persist';

const useSettings = defineStore('settings', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ theme: 'dark' });
    const { hydrated } = persist(ctx, { state, patch });
    return { ...signals, hydrated };
}, 'singleton');
```

Writing your own composables — and when to use the global `onStoreCreated` plugin hook instead — is covered in [Composables & Plugins](/store/docs/composables-and-plugins).

## A complete store

Putting state, derived values, and actions together:

```tsx
import { computed } from 'sigx';
import { defineStore } from '@sigx/store';

const useTodoStore = defineStore('todos', ({ defineState, defineActions }) => {
    const { state, signals, patch } = defineState({
        todos: [] as { id: number; text: string; done: boolean }[],
        nextId: 1,
    });

    const remaining = computed(() => state.todos.filter(t => !t.done).length);

    const actions = defineActions({
        add(text: string) {
            patch(s => {
                s.todos.push({ id: s.nextId, text, done: false });
                s.nextId++;
            });
        },
        toggle(id: number) {
            const todo = state.todos.find(t => t.id === id);
            if (todo) todo.done = !todo.done;
        },
        clearCompleted() {
            state.todos = state.todos.filter(t => !t.done);
        },
    });

    return { ...signals, ...actions, remaining };
}, 'scoped');
```

For larger stores — multiple slices, stores composed of stores, undo/redo — see [Patterns](/store/docs/patterns).

## Next steps

- [Actions & Async](/store/docs/actions-and-async) — `pending`, lifecycle events, and error semantics in depth.
- [Events & Observability](/store/docs/events-and-observability) — the event mental model and devtools discovery.
- [Lifetimes & DI](/store/docs/lifetimes-and-di) — lifetimes in practice, `defineProvide`, SSR.
- [Using Stores in Components](/store/docs/using-in-components) — reading state in render, sharing instances, cleanup.
- [API Reference](/store/docs/api) — full signatures for every export.

---
url: https://sigx.dev/store/docs/lifetimes-and-di/
title: Lifetimes & DI
description: scoped, singleton, and transient stores; defineProvide overrides; disposal ownership; SSR
---

# Lifetimes & DI

A store factory doesn't just *create* instances — it **resolves** them through SignalX's dependency-injection layer. The third argument to `defineStore` picks the resolution strategy:

```ts
const useAppStore = defineStore('app', setup, 'singleton');   // default: 'scoped'
```

This page explains exactly where each lifetime looks for an instance, who owns disposal, and what that means for component subtrees, parameterized stores, and SSR. The mechanism is core's [factory system](/core/docs/advanced/factories) — stores are factories.

## The three lifetimes

### `'scoped'` (the default)

Resolution order when you call the factory:

1. **Nearest provider** — walking up the component tree from the calling component, the first instance provided via `defineProvide` wins.
2. **App context** — otherwise, the per-app shared instance (one per `AppContext`), created on first use and cached. It is **app-owned**: disposed on `app.unmount()`, never by the component that happened to resolve it first.
3. **Realm fallback** — outside any app/component context (tests, scripts), one instance per JS realm.

`'scoped'` therefore *behaves* like a singleton until somebody overrides it for a subtree — which is exactly what makes it the right default: global by convention, locally replaceable on demand.

### `'singleton'`

Steps 2 and 3 only — one shared instance per `AppContext`, disposed on `app.unmount()`, with the same per-realm fallback outside an app. `defineProvide` overrides are **not** consulted: a singleton is the same instance everywhere in the app, by definition.

### `'transient'`

A fresh instance on **every** factory call. When the call happens inside a component setup, the instance is tied to that component and auto-disposed on unmount; outside a component, you own it — call `store.$dispose()` yourself.

```ts
const useWizardStore = defineStore('wizard', setup, 'transient');

const Wizard = component(() => {
    const store = useWizardStore();   // this component's own copy,
    return () => /* ... */;           // disposed when it unmounts
});
```

## Subtree overrides with `defineProvide`

`defineProvide(useStore)` — in a component setup — creates a **fresh instance** and provides it to that component's subtree. Every `'scoped'` resolution below it gets that instance instead of the app-wide one:

```tsx
import { component, defineProvide } from 'sigx';

const useFilterStore = defineStore('filters', setup);   // 'scoped'

const ProductSection = component(() => {
    // This subtree gets its own filter state:
    const filters = defineProvide(useFilterStore);
    return () => <ProductList />;                        // useFilterStore() in any
});                                                      // descendant → this instance
```

Two rules to know:

- **The provider component owns the instance** — it is disposed when the provider unmounts, not on `app.unmount()`.
- **`defineProvide` creates the instance without arguments by default.** Its default factory calls the setup args-less (and beware: a custom `defineProvide(useFn, factory)` callback that calls the use-function would *resolve a shared instance*, not create a fresh one). The reliable pattern for per-subtree configuration is to design provided stores arg-less and seed the fresh instance through an action right after providing it:

```ts
const filters = defineProvide(useFilterStore);
filters.init(props.initialFilters);   // seed via an action, not setup args
```

Sibling sections each calling `defineProvide(useFilterStore)` get fully independent instances — same store definition, isolated state per subtree.

## Parameterized stores: first creation wins

Setup parameters after the context are forwarded through the factory call, with full tuple-typed inference at any arity (see [TypeScript](/store/docs/typescript)). With a `'transient'` lifetime every call uses its own arguments — that's the natural pairing. For `'scoped'` and `'singleton'`, arguments are honored **at first creation only**:

```ts
const useListStore = defineStore('list', ({ defineState }, initial: string[]) => {
    const { signals } = defineState({ items: initial });
    return { ...signals };
}, 'scoped');

useListStore(['a']);   // creates the shared instance, seeded with ['a']
useListStore(['z']);   // resolves the SAME instance — ['z'] is ignored
```

If different callers need different seeds, the store wants to be `'transient'` (or provided per subtree with explicit construction, as above).

## Disposal ownership

Who calls dispose depends on how the instance came to exist:

| How it was created | Disposed by |
|---|---|
| `'scoped'`/`'singleton'`, resolved under an app | `app.unmount()` |
| `defineProvide` in a component | that component's unmount |
| `'transient'`, called in a component setup | that component's unmount |
| `'transient'` outside a component | you — `store.$dispose()` |
| realm fallback (no app context) | you — `store.$dispose()` |

Disposal stops the store's state watchers and destroys all its topics — `$events` and action events go silent ([Events & Observability](/store/docs/events-and-observability#the-inspection-registry)), and anything registered via the setup's `onDeactivated` (like a [persist](/store/docs/persistence) composable's watcher) is cleaned up.

Manually disposing a shared instance does not poison the factory: the next resolution detects the disposed instance and **creates a fresh one** rather than serving a corpse. That makes `$dispose()` a legitimate "reset this store completely" lever in tests.

## SSR: one app per request

The DI layer gives SSR a simple contract: **shared instances live on the `AppContext`**. Create one app per request and every `'scoped'`/`'singleton'` store is automatically per-request — no cross-request state leakage, and everything is disposed together when the request's app is torn down.

The corollary is the thing to avoid: resolving a shared store at **module scope** on the server. There is no app context there, so resolution falls back to the **per-realm** instance — which *is* shared across requests. Keep factory calls inside component setups (or other code that runs within an app), and module-level store usage stays a client-only convenience.

```ts
// ✗ server-dangerous: realm-fallback instance, shared by all requests
const store = useCartStore();
export function totalBadge() { return store.total; }

// ✔ resolved per app / per request
const Badge = component(() => {
    const store = useCartStore();
    return () => <span>{store.total}</span>;
});
```

(`persist` is already SSR-safe on its own — with no storage available it is a no-op; see [Persistence](/store/docs/persistence#how-it-behaves).)

## Choosing a lifetime

- **App-wide state** (session, settings, cart): `'singleton'` — or leave the default `'scoped'`, which behaves identically until you need an override.
- **Feature state that some subtree may want its own copy of** (filters, selection): `'scoped'` + `defineProvide` at the feature root.
- **Per-component state machines** (wizards, editors, anything seeded by props): `'transient'` with setup parameters.

Composing stores from other stores' setups adds one more wrinkle — when the *inner* store resolves and who disposes it — covered in [Patterns](/store/docs/patterns#store-composition-stores-using-stores).

## Testing note

Unit tests usually run outside any app, so shared lifetimes resolve to the **realm fallback** — which persists across tests in the same file. Reset between tests by disposing; the next resolution creates a fresh instance:

```ts
afterEach(() => {
    useCartStore().$dispose();   // next test's useCartStore() starts clean
});
```

For isolation without disposal bookkeeping, prefer `'transient'` in tests of the setup logic itself, or mount each test inside its own app.

## Next steps

- [Factories in core](/core/docs/advanced/factories) — the underlying `defineFactory` machinery.
- [Using Stores in Components](/store/docs/using-in-components) — the component-side view of sharing and cleanup.
- [Patterns](/store/docs/patterns) — store composition and its lifetime implications.
- [API Reference](/store/docs/api#lifetime) — the `Lifetime` type.

---
url: https://sigx.dev/use/docs/use-event-listener/
title: useEventListener
description: Attach a DOM event listener scoped to the owning component — re-attached when the target changes, removed on scope disposal
---

# useEventListener

Attach an event listener that lives exactly as long as the owning scope. Browser composable — import from `@sigx/use-web`.

The listener is added now (or whenever a reactive target produces an element), removed on scope disposal, and **re-attached when the target changes**. It returns an explicit [`stop()`](/use/docs/conventions#control-handles-pausable-and-stop) for standalone use.

```ts
import { useEventListener } from '@sigx/use-web';

// Omit the target to listen on `window`:
useEventListener('keydown', (ev) => {
    if (ev.key === 'Escape') closeModal();
});
```

Pass an [element target](/use/docs/conventions#element-targets-web) as the first argument to bind to a specific element — a template ref works directly, and the listener follows the element if it changes:

```tsx
import { signal } from 'sigx';
import { useEventListener } from '@sigx/use-web';

const el = signal<HTMLElement | null>(null);
// <div ref={el}> …
useEventListener(el, 'click', (ev) => console.log(ev.clientX));
```

You can pass an **array of event names** to attach the same listener to several events, and the usual `boolean | AddEventListenerOptions` third argument (`{ capture, passive, once }`).

## Signature

The overloads specialize the event map and the `ev` type to the target. Omit the target for `window`; pass `document`, a `Window`, or an [element target](/use/docs/conventions#element-targets-web):

```ts
// window (target omitted)
function useEventListener<K extends keyof WindowEventMap>(
    event: K | K[],
    listener: (ev: WindowEventMap[K]) => void,
    options?: boolean | AddEventListenerOptions,
): Stop;

// explicit element target
function useEventListener<K extends keyof HTMLElementEventMap>(
    target: MaybeSignalElement,
    event: K | K[],
    listener: (ev: HTMLElementEventMap[K]) => void,
    options?: boolean | AddEventListenerOptions,
): Stop;
```

There are matching overloads for `Window` and `Document` targets (typed against `WindowEventMap` / `DocumentEventMap`), plus a string-event fallback for arbitrary `EventTarget`s.

## Returns

A [`Stop`](/use/docs/conventions#control-handles-pausable-and-stop) — call it to remove the listener immediately. Inside a component or `effectScope` you rarely need it; the scope removes the listener for you.

## SSR

No-op: on the server nothing is attached and it returns a **noop stop**.

## See also

- [`unrefElement`](/use/docs/unref-element) — how the target is resolved to a raw element for `add`/`removeEventListener` pairing.
- [`useMouse`](/use/docs/use-mouse) / [`useScroll`](/use/docs/use-scroll) — sensors built on scoped listeners.
- [Conventions → Element targets (web)](/use/docs/conventions#element-targets-web) — the accepted target shapes.

---
url: https://sigx.dev/devtools/docs/installation/
title: Installation
description: Install @sigx/devtools and wire the plugin into your app
---

# Installation

## Package

`@sigx/devtools` is ESM-only and ships a single entry point (`@sigx/devtools`). Add it
as a dev dependency — you should not ship it in production builds.

```bash
pnpm add -D @sigx/devtools
```

The package version is `0.0.1`. The wire `PROTOCOL_VERSION` is `1`, and the agent
version reported in the `hello` event is `0.0.3`.

## Engines

Node `^20.19.0 || >=22.12.0`.

## Reactive core

The plugin attaches to the global devtools hook on `@sigx/reactivity` and reads the
component/inspection events from `@sigx/runtime-core` — but you don't install those
separately. They come bundled in the SignalX umbrella your app already runs on
(`sigx` on the web, `@sigx/lynx` on native, `@sigx/terminal` in the terminal), so
adding `@sigx/devtools` is enough.

`@sigx/reactivity` supplies the shared reactivity hook (the plugin calls
`ensureDevtoolsHook()` to attach), and `@sigx/runtime-core` emits the component
lifecycle events and hosts the inspection registry (`@sigx/runtime-core/inspect`)
that store discovery is built on.

## No build configuration required

There is no Vite plugin and no special build step needed to *use* the package. You
install it the same way as any other SignalX plugin:

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { App } from './App';

defineApp(<App />)
    .use(devtools())
    .mount('#app');
```

The plugin's `install()` resolves a transport, attaches to the hook, bridges component
and reactivity events to the panel, and sends a `hello` event once the wire is up. In
SSR or Node, with no `window` and no custom transport, it returns early and does
nothing — so it is safe to leave in shared entry code.

## Keeping it out of production

Because the package has `sideEffects: false`, a dynamic import behind a dev flag lets
your bundler drop it from release builds entirely:

```tsx
import { defineApp } from 'sigx';
import { App } from './App';

const app = defineApp(<App />);

if (import.meta.env.DEV) {
    const { devtools } = await import('@sigx/devtools');
    app.use(devtools());
}

app.mount('#app');
```

## Stores and the router

Stores need **no wiring**: every `@sigx/store` instance is discovered automatically
through the core inspection registry (`@sigx/runtime-core/inspect`) — including stores
created after the plugin installs. Set `includeStores: false` to opt out. The router is
still passed explicitly and must expose a reactive `currentRoute`; any `@sigx/router`
instance satisfies that shape.

```tsx
import { defineApp } from 'sigx';
import { devtools } from '@sigx/devtools';
import { createRouter } from '@sigx/router';
import { App } from './App';

const router = createRouter({ routes: [/* ... */] });

defineApp(<App />)
    .use(router)
    .use(devtools({
        appName: 'shop',
        router,
    }))
    .mount('#app');
```

See [Connecting an inspector](/devtools/docs/connecting-an-inspector) for how to choose
a transport and attach a panel.

---
url: https://sigx.dev/i18n/docs/runtime-catalogs/
title: Runtime catalogs
description: Messages that come from a CMS or database — runtimeNamespaces, useDynamicTranslation and invalidation
---

# Runtime catalogs

<p class="lede">Some messages are not in your repository. A CMS block, a product description, a tenant's custom label — the keys are not knowable at build time, so the typed path cannot cover them.</p>

## The problem with typing them

`useTranslation` checks both the namespace and the key against the schema the [Vite plugin](/i18n/docs/installation#the-vite-plugin) generates from your catalog tree. That is what you want for the app's own chrome: a typo in `t('cart.titel')` should not compile.

It is exactly wrong for content that arrives at runtime. Those keys do not exist in any scanned catalog, so every one of them would be an error.

## `runtimeNamespaces`

Declare which namespaces are sourced at runtime:

```ts
i18n({
    localesDir: 'src/locales',
    masterLocale: 'en',
    runtimeNamespaces: ['content'],
});
```

The generator then knows those namespaces are real but their keys are open, and the consistency check stops reporting them as missing from the master locale.

## `useDynamicTranslation`

The reader for those namespaces. The **namespace is still checked**; only the keys are open:

```tsx
import { useDynamicTranslation } from '@sigx/i18n';

const Block = component<{ block: ContentBlock }>((ctx) => {
    const content = useDynamicTranslation('content');

    return () => (
        <section>
            <h2>{content(ctx.props.block.labelKey, { count }, { default: ctx.props.block.label })}</h2>
            {content.exists(ctx.props.block.helpKey) && <p>{content(ctx.props.block.helpKey)}</p>}
        </section>
    );
});
```

Two things it adds over the typed translator:

- **`default`** — the author's original text, used when the key resolves to nothing. A CMS block always has *something* to show; falling back to the raw key would put `content.block_1841.label` on the page.
- **`exists(key)`** — branch on presence rather than rendering an empty element. Optional content is normal here in a way it is not for app chrome.

Keep [`useTranslation`](/i18n/docs/usage#usetranslation) for everything else. Reaching for the dynamic translator to dodge a type error in your own catalog is throwing away the check that makes the typed path worth having.

## Supplying the messages

Runtime catalogs arrive the same way any other catalog does — through `load`, or seeded with `addMessages`:

```ts
createI18n({
    fallbackLocale: 'en',
    load: async (target, locale, ns) =>
        ns === 'content'
            ? await fetchCmsCatalog(locale)
            : import(`./locales/${target}/${locale}/${ns}.json`),
});
```

For overrides that layer over a base catalog rather than replacing it, see [layers](/i18n/docs/usage#layers).

## Invalidating

Content changes without a deploy, which is the whole point of putting it in a CMS. Re-seed the namespace and every component that read one of its messages re-renders, because the catalogs are signals:

```ts
const i18n = useI18n();

await i18n.invalidate(locale, 'content');   // drop and reload one namespace
await i18n.invalidate();                    // everything
```

`invalidate(locale?, ns?, layer?)` narrows from the left — omit an argument to cover every value of it. `addMessages(locale, ns, catalog)` is the direct form when you already hold the new catalog and would rather not round-trip through `load`.

## Handling failures

A `fetch`-backed catalog fails in ways a bundled `import()` does not, so wire the [load-error surface](/i18n/docs/locales#when-a-catalog-fails-to-load): `useLocale().error` with `retry()`, or `onLoadError` to route it to telemetry. With `default` values on your dynamic calls, a failed content load degrades to the authored text rather than to raw keys.

## Next steps

- [Server & SSR](/i18n/docs/server) — resolving the locale per request.

---
url: https://sigx.dev/monaco/docs/language-packs/
title: Language packs and IntelliSense
description: Register TS/JSX, HTML, CSS, and JSON language packs, themes, and extra type defs with configureMonaco
---

# Language packs and IntelliSense

A `LanguagePack` is a pluggable language registration: it declares a language id, optional file extensions, an optional worker mapping (`workerLabel` + `workerUrl`), and an optional `setup()` that runs once after Monaco loads. `@sigx/monaco-editor` ships four packs out of the box.

## Registering packs

Register the packs you need once at module load with `configureMonaco()`, before the first editor mounts. The registration accumulates across calls; if Monaco is already loaded, the new setup is applied to the live instance immediately.

```tsx
import {
    configureMonaco,
    typescriptLanguagePack,
    htmlLanguagePack,
    cssLanguagePack,
    jsonLanguagePack,
} from '@sigx/monaco-editor';

configureMonaco({
    languages: [
        typescriptLanguagePack({ jsxImportSource: 'sigx' }),
        htmlLanguagePack(),
        cssLanguagePack(),
        jsonLanguagePack(),
    ],
});
```

You can also import individual packs from their subpaths if you prefer narrower imports:

```tsx
import { typescriptLanguagePack } from '@sigx/monaco-editor/languages/typescript';
import { htmlLanguagePack } from '@sigx/monaco-editor/languages/html';
import { cssLanguagePack } from '@sigx/monaco-editor/languages/css';
import { jsonLanguagePack } from '@sigx/monaco-editor/languages/json';
```

## TypeScript and JSX

`typescriptLanguagePack()` registers four language ids — `typescript`, `javascript`, `tsx`, and `jsx` — and configures Monaco's TS/JS compiler and diagnostics defaults (ESNext target/module, ReactJSX, `allowJs`, `noEmit`, NodeJs resolution, and more). It also registers completion and hover providers for the `tsx`/`jsx` ids so IntelliSense keeps working even when Shiki provides highlighting.

For SignalX apps, set `jsxImportSource` to `'sigx'` (it defaults to `'react'`):

```tsx
import { configureMonaco, typescriptLanguagePack } from '@sigx/monaco-editor';

configureMonaco({
    languages: [
        typescriptLanguagePack({
            jsxImportSource: 'sigx',
            compilerOptions: { strict: true },
            diagnosticsOptions: { noSemanticValidation: false },
        }),
    ],
});
```

Pass `skipJsxProviders: true` if you do not want the tsx/jsx completion and hover providers (for example when another integration owns them).

## HTML, CSS, and JSON

`htmlLanguagePack()` and `cssLanguagePack()` take no options — Monaco ships the HTML language (handlebars/razor reuse the HTML worker) and a single CSS worker handles CSS/SCSS/LESS.

`jsonLanguagePack()` accepts schema and validation options that are passed to Monaco's JSON service:

```tsx
import { configureMonaco, jsonLanguagePack } from '@sigx/monaco-editor';

configureMonaco({
    languages: [
        jsonLanguagePack({
            validate: true,
            enableSchemaRequest: true,
            schemas: [
                {
                    uri: 'https://example.com/config.schema.json',
                    fileMatch: ['*'],
                    schema: { type: 'object', properties: { name: { type: 'string' } } },
                },
            ],
        }),
    ],
});
```

## Themes and extra type definitions

`configureMonaco()` also accepts `themes` (defined via `monaco.editor.defineTheme`) and `extraLibs` (`.d.ts` content injected into the TS service). Like languages, they accumulate and apply to the live instance if Monaco is already loaded.

```tsx
import { configureMonaco } from '@sigx/monaco-editor';

configureMonaco({
    themes: [
        {
            name: 'my-theme',
            data: {
                base: 'vs-dark',
                inherit: true,
                rules: [],
                colors: { 'editor.background': '#0b0f17' },
            },
        },
    ],
    extraLibs: [
        {
            content: 'declare const APP_VERSION: string;',
            filePath: 'file:///globals.d.ts',
        },
    ],
});
```

Reference the theme by name through the `theme` prop on `<MonacoEditor />` (or the `theme` option on `createEditor()`). Note that the component applies the theme globally via `monaco.editor.setTheme`, so the theme affects every editor on the page.

## Custom workers

The prebundled loader installs a default worker map (typescript/javascript -> `ts.worker.min.js`, css/scss/less -> `css.worker.min.js`, html/handlebars/razor -> `html.worker.min.js`, json -> `json.worker.min.js`, fallback -> `editor.worker.min.js`). The plugin's `languages` option is informational only. To add a worker beyond the fixed prebundled set, register a `LanguagePack` with both `workerLabel` and `workerUrl`, which override entries in that map:

```tsx
import { configureMonaco } from '@sigx/monaco-editor';
import type { LanguagePack } from '@sigx/monaco-editor';

const myPack: LanguagePack = {
    id: 'my-lang',
    extensions: ['.mylang'],
    workerLabel: 'my-lang',
    workerUrl: '/workers/my-lang.worker.js',
    setup(monaco) {
        monaco.languages.register({ id: 'my-lang' });
    },
};

configureMonaco({ languages: [myPack] });
```

## Next steps

- [Imperative editors and Shiki highlighting](/monaco/docs/imperative-and-shiki)
- [API Reference](/monaco/docs/api)

---
url: https://sigx.dev/store/docs/getting-started/
title: Getting Started
description: "@sigx/store — centralized state on signals"
---

# Getting Started with Store

`@sigx/store` is centralized, reactive state built on the same signal core that powers your components — with a surface that is **flat and signal-first**. You describe state, actions, and derived values in one setup function; whatever you return *becomes* the store. State reads and writes as plain values (`store.count`), computeds read as plain read-only values (`store.total`), actions are called directly (`store.increment()`) — and any of them read inside a render function re-renders that component automatically. No selector layer, no manual subscriptions, no `.value` at the call site.

Here is the whole thing, live — edit it:

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const useCounterStore = defineStore('counter', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ count: 0 });

    const actions = defineActions({
        increment() { state.count++; },
        decrement() { state.count--; },
        reset() { state.count = 0; },
    });

    return { ...signals, ...actions };
});

const Counter = component(() => {
    const store = useCounterStore();

    return () => (
        <div class="flex items-center gap-3">
            <button class="btn" onClick={() => store.decrement()}>-</button>
            <span class="text-xl font-bold w-12 text-center">{store.count}</span>
            <button class="btn" onClick={() => store.increment()}>+</button>
            <button class="btn btn-ghost" onClick={() => store.reset()}>reset</button>
        </div>
    );
});

render(<Counter />, "#sandbox");
```

That's `defineStore(name, setup)`: the setup receives a context with `defineState` and `defineActions`, and the spread `signals` you return become the store's public state. Calling the returned factory anywhere yields a live instance.

## Async without the boilerplate

Real stores talk to servers. Every action carries a reactive **`pending`** flag — `true` while any invocation is in flight — so a save button or spinner is one property read, with no `isLoading` flags to maintain by hand. Try adding a todo (the action fakes a 700 ms API call):

```tsx
import { component, render, computed } from 'sigx';
import { defineStore } from '@sigx/store';

const useTodoStore = defineStore('todos', ({ defineState, defineActions }) => {
    const { state, signals, patch } = defineState({
        todos: [
            { id: 1, text: 'Read the store docs', done: true },
            { id: 2, text: 'Build something', done: false },
        ],
        nextId: 3,
        draft: '',
    });

    const remaining = computed(() => state.todos.filter(t => !t.done).length);

    const actions = defineActions({
        async add(text: string) {
            await new Promise(resolve => setTimeout(resolve, 700)); // pretend API call
            patch(s => {
                s.todos.push({ id: s.nextId, text, done: false });
                s.nextId++;
            });
        },
        toggle(id: number) {
            const todo = state.todos.find(t => t.id === id);
            if (todo) todo.done = !todo.done;
        },
    });

    return { ...signals, ...actions, remaining };
});

const Todos = component(() => {
    const store = useTodoStore();

    const submit = () => {
        const text = store.draft.trim();
        if (!text) return;
        store.draft = '';
        store.add(text);
    };

    return () => (
        <div class="space-y-3">
            <div class="flex gap-2">
                <input
                    class="input input-bordered input-sm flex-1"
                    placeholder="What needs doing?"
                    value={store.draft}
                    onInput={(e) => { store.draft = (e.target as HTMLInputElement).value; }}
                    onKeyDown={(e) => { if (e.key === 'Enter') submit(); }}
                />
                <button class="btn btn-primary btn-sm" onClick={submit} disabled={store.add.pending}>
                    {store.add.pending ? 'Adding…' : 'Add'}
                </button>
            </div>
            <ul class="space-y-1">
                {store.todos.map(todo => (
                    <li class="flex items-center gap-2">
                        <input
                            type="checkbox"
                            class="checkbox checkbox-sm"
                            checked={todo.done}
                            onChange={() => store.toggle(todo.id)}
                        />
                        <span class={todo.done ? 'line-through opacity-60' : ''}>{todo.text}</span>
                    </li>
                ))}
            </ul>
            <p class="text-sm opacity-70">{store.remaining} remaining</p>
        </div>
    );
});

render(<Todos />, "#sandbox");
```

Notice what you *didn't* write: no loading flag, no try/finally to reset it, no selector to subscribe the list. `store.add.pending` is count-based across overlapping calls, the `computed` unwraps as a plain `store.remaining`, and `patch` applies the multi-key update in a single reactivity flush.

## The mental model in five lines

- `defineStore(name, setup, lifetime?)` returns a **factory function**. By convention it's named `useXxxStore`, but it's an ordinary function — calling it creates (or resolves, per the lifetime) an instance. There is no `useStore` export.
- Inside `setup`, `defineState(obj)` returns `{ state, signals, events, patch }`. Mutate `state` freely (it's deeply reactive); **the `signals` keys you return become the store's public state** — unreturned keys stay private.
- `defineActions(obj)` wraps your functions; each keeps its exact signature and carries `pending` plus `onDispatching` / `onDispatched` / `onFailure` events.
- The instance is an **unwrap proxy**: signals and computeds read as plain values; meta lives behind `$` (`$id`, `$patch`, `$events`, `$dispose`).
- Created inside a component, an instance is tied to the component lifecycle and disposes on unmount.

> One convention to internalize early: **don't destructure the store**. `const { count } = store` snapshots the value and loses reactivity. Keep reads on the store (`store.count`) or use [`storeToSignals`](/store/docs/using-in-components#destructuring-safely-with-storetosignals).

## What makes this store different

- **A flat, fully-typed surface.** Public state is exactly the signals you return — `$patch` and `$events` are typed from them, action signatures flow through unchanged. See [TypeScript](/store/docs/typescript).
- **`pending` built in.** Every action knows when it's in flight, with sound error semantics (sync errors re-throw; async calls return the original promise). See [Actions & Async](/store/docs/actions-and-async).
- **Lazy events.** Per-key change events (`store.$events.count`) cost nothing until someone subscribes — the deep watcher behind a key only runs while it has subscribers. See [Events & Observability](/store/docs/events-and-observability).
- **Real lifetimes.** `'singleton' | 'scoped' | 'transient'` are honored by the core DI layer, with `defineProvide` subtree overrides and automatic disposal. See [Lifetimes & DI](/store/docs/lifetimes-and-di).
- **Persistence in the box.** `@sigx/store/persist` handles sync and async storage, versioned migrations, and hydration races. See [Persistence](/store/docs/persistence).
- **Devtools auto-discovery.** Every store's state, action, and custom events are registered topics in the core inspection registry — tooling can find and tap them by wildcard, no wiring. See [Events & Observability](/store/docs/events-and-observability).
- **Composable and pluggable.** Setup composables (like `persist`) and the global `onStoreCreated` hook cover cross-cutting concerns. See [Composables & Plugins](/store/docs/composables-and-plugins).

## Next steps

- [Installation](/store/docs/installation) — install command, dependencies, and project setup.
- [Defining a Store](/store/docs/defining-a-store) — the conceptual hub: state, actions, derived values, events.
- [Using Stores in Components](/store/docs/using-in-components) — rendering reactivity, sharing, cleanup.
- [Patterns](/store/docs/patterns) — multi-slice stores, composition, optimistic updates, undo/redo.
- [API Reference](/store/docs/api) — every export with signatures.

---
url: https://sigx.dev/terminal/docs/installation/
title: Installation
description: Install @sigx/terminal and wire up the TSX runtime
---

# Installation

## Install the package

```bash
npm install @sigx/terminal
```

`@sigx/terminal` is the terminal umbrella — the sibling of `sigx` (web) and `@sigx/lynx` (native). Installing it brings the whole TUI stack: the reactive engine (`@sigx/reactivity`, `@sigx/runtime-core`), the renderer (`@sigx/runtime-terminal`), the headless foundation (`@sigx/terminal-zero`) and the themed components (`@sigx/terminal-ui`). You import `signal`, `component`, `defineApp`, the terminal intrinsics and every built-in component all from `@sigx/terminal` — there is nothing else to add.

The package is ESM-only (`"type": "module"`) and runs under Node. It is a library, not a CLI — there is no `bin` entry; you build your own TUI/CLI app on top of it.

## Runtime requirements

- **Node 18 or newer** — for ESM support and the built-in `fetch` the [data-loading](/terminal/docs/getting-started/#loading-data) examples rely on. The Vite build target below is `node18` for the same reason.
- **A TTY** for full keyboard input. The runtime puts stdin into raw mode; if `setRawMode` is unavailable (for example in some terminals) it degrades gracefully rather than crashing.
- **SignalX core `^0.14.0`.** The bundled reactive engine (`@sigx/reactivity`, `@sigx/runtime-core`) tracks the core `0.14` line. Terminal's own version is **independent of core's** — `@sigx/terminal` and core don't share a minor, so read this requirement rather than the package number. If you also depend on SignalX core directly — or on other **core** packages such as `@sigx/reactivity` or `@sigx/runtime-core` — keep those on the same `0.14.x` line. (Other `@sigx/*` families like `@sigx/lynx` run their own version lines and are unaffected.)

> **Upgrading an older terminal app?** Terminal moved onto the modern core line in 0.7.0, so a `0.6.x` core no longer satisfies these ranges — bump your SignalX core to `0.14.x` alongside the terminal upgrade. Core's own breaking changes since then apply if your app relied on them (the 0.9.0 async removals — `useAsync` / `<Suspense>` → [`useData`](/core/docs/data-loading) / `<Defer>`).

## TSX setup

Terminal intrinsics (`box`, `text`, `br`) compile against the terminal JSX runtime. Point TypeScript at it **once**, in `tsconfig.json`:

```json
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "@sigx/terminal"
    }
}
```

Every `.tsx` file in the project then compiles against it, with no per-file pragma.

If a single file needs a *different* runtime — a shared module that also builds for the DOM — a `/** @jsxImportSource … */` comment at its top still overrides the config for that file. Library authors targeting a non-web runtime should reach for [`defineLibConfig({ importSource })`](/vite/docs/library-builds#targeting-a-non-web-runtime) instead of pragmas.

The package exposes both `./jsx-runtime` and `./jsx-dev-runtime` conditions, so both production and dev JSX transforms resolve correctly.

## Vite wiring

When building with Vite, target Node and keep the framework and Node built-ins external so they are not bundled into your output:

```ts
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
    build: {
        target: 'node18',
        rollupOptions: {
            external: [
                /^@sigx\//,
                'node:process',
                'node:readline',
                'node:tty',
            ],
        },
    },
    esbuild: {
        jsx: 'automatic',
        jsxImportSource: '@sigx/terminal',
    },
});
```

This mirrors how `@sigx/terminal` itself is built: a Node-platform library that marks all `@sigx/*` packages plus `node:process`, `node:readline` and `node:tty` as external.

## Verify the install

Create a file (for example `app.tsx`) and run it through your TSX-capable runner:

```tsx
import { component, defineApp } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box border="rounded" label="Hello">
            <text color="green">It works!</text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

If you see a rounded box with green text, your TSX and runtime wiring are correct. Press Ctrl+C to exit.

## Next steps

- [Architecture](/terminal/docs/architecture) — the packages behind the umbrella and the peer-dependency model.
- [Getting Started](/terminal/docs/getting-started) — the package overview and a minimal app.
- [Layout & Styling](/terminal/docs/layout-and-styling) — boxes, borders and colors.
- [Render modes](/terminal/docs/render-modes) — inline vs fullscreen, non-TTY and resize.
- [Dev mode](/terminal/packages/terminal-dev/overview/) — HMR for terminal apps with `sigx-terminal-dev`.

---
url: https://sigx.dev/terminal/docs/architecture/
title: Architecture
description: How @sigx/terminal is split into a renderer, a headless foundation, a themed UI library and an args parser
---

# Architecture

`@sigx/terminal` is an umbrella. Installing it gives you a complete TUI stack, but that stack is built from a few focused packages, each usable on its own. Knowing the split helps you import from the right place and understand how theming and rendering fit together.

## The packages

| Package | Role |
| --- | --- |
| `@sigx/terminal` | **Umbrella entry.** Re-exports the renderer, the headless foundation and the themed components so you can import everything from one place. Set `jsxImportSource: "@sigx/terminal"` to write TSX. |
| [`@sigx/runtime-terminal`](/terminal/packages/runtime-terminal/overview/) | **The renderer.** Walks your component tree into ANSI lines and paints them: render modes, layered key dispatch, color-depth detection, output targets, reactive terminal size. The host platform for `@sigx/runtime-core`. |
| [`@sigx/terminal-zero`](/terminal/packages/terminal-zero/overview/) | **Headless foundation.** The design-system-neutral half: the token contract, the theme engine (`resolveColor`, `setTheme`), shared glyphs, layout primitives (`Box`, `Row`, `Col`, `Text`, …) and the prompts engine. No fixed look — skins build on it. |
| [`@sigx/terminal-ui`](/terminal/packages/terminal-ui/overview/) | **Themed component library.** The SigX-tui skin: forms, feedback, navigation, layout, data, fx and tasks components, plus five built-in themes (default `obsidian`). Built entirely on `terminal-zero` tokens. |
| [`@sigx/terminal-dev`](/terminal/packages/terminal-dev/overview/) | **HMR dev runner.** `sigx-terminal-dev <entry>` runs your app under Vite — edit a component, the running TUI patches in place. See [Dev mode](/terminal/packages/terminal-dev/overview/). |
| [`@sigx/args`](/terminal/packages/args/overview/) | **Command & argument parser.** A fluent, type-aware CLI parser. Independent of the renderer — it's the engine behind `@sigx/cli`. See [Command-line args](/terminal/packages/args/overview/). |

Every package ships from the [terminal monorepo](https://github.com/signalxjs/terminal) in lockstep — browse them all in the [package catalog](/terminal/packages/).

## How they layer

```
@sigx/terminal  (umbrella: re-exports the three below)
├── @sigx/terminal-ui      themed components (obsidian + 4 themes)
│     └── @sigx/terminal-zero    tokens · theme engine · layout · prompts engine
│             └── @sigx/runtime-terminal   the cell renderer + key dispatch
└── @sigx/runtime-core / @sigx/reactivity  (the reactive engine, bundled in)
```

The renderer sits at the bottom; `terminal-zero` adds a semantic token layer over it; `terminal-ui` paints concrete components against those tokens. Because the colours your components ask for are **tokens** (`accent`, `fg`, `line`, …) resolved at render time, switching the active theme repaints the whole app — see [Theming](/terminal/docs/theming).

## What you import

For application code, import from `@sigx/terminal` — it carries the reactive primitives (re-exported from core), the `box`/`text`/`br` intrinsics, every component, and the render entry:

```tsx
import { component, signal, defineApp, Input, Button } from '@sigx/terminal';
```

The split only matters when you want a piece in isolation — for example building a custom design system on `@sigx/terminal-zero`, or using `@sigx/args` in a CLI with no terminal UI.

## The reactive engine

The SignalX core packages — `@sigx/reactivity` and `@sigx/runtime-core` — are **bundled into the umbrella**, just as `sigx` does on the web and `@sigx/lynx` does on native. Installing `@sigx/terminal` brings exactly one copy of core, so signals and effects across every `@sigx/*` package run on one shared reactivity engine. There is nothing extra to install:

```bash
npm install @sigx/terminal
```

See [Installation](/terminal/docs/installation) for the full setup.

## Next steps

- [Getting Started](/terminal/docs/getting-started) — a minimal app.
- [Render modes](/terminal/docs/render-modes) — inline vs fullscreen, non-TTY, resize.
- [Theming](/terminal/docs/theming) — tokens, themes and `resolveColor`.
- [Components](/terminal/docs/components) — the full component library.

---
url: https://sigx.dev/terminal/docs/render-modes/
title: Render modes
description: Inline vs fullscreen rendering, the non-TTY fallback, resize handling and clean exits
---

# Render modes

The renderer paints your app one of two ways. You choose with the `mode` option on `renderTerminal` / `terminalMount` (and the `.mount()` options object). The default is `inline`.

```tsx
defineApp(<App />).mount({ mode: 'inline' });      // default
defineApp(<App />).mount({ mode: 'fullscreen' });
```

## Inline

`mode: 'inline'` (the default) paints a **live region** at the cursor's current position in the normal screen buffer. Each frame repaints only its own lines (cursor-up, then erase), so the scrollback above the app is never touched. Frames taller than the viewport are clamped to their bottom rows, and lines are truncated to the terminal width so soft-wrapping can't corrupt the cursor arithmetic.

The defining trait of inline mode: **the final frame persists in scrollback** after the app exits. A wizard or build view leaves a tidy record behind instead of vanishing. To opt out — for a transient spinner or one-shot prompt that should leave no trace — set `persistOnExit: false`, and the live region is erased on unmount with the cursor returned to where it began.

```tsx
defineApp(<App />).mount({ mode: 'inline', persistOnExit: false });
```

`clearConsole: true` in inline mode **scrolls** the user's existing content up into scrollback (it never erases it) and homes the cursor, so the app starts at the top of an empty viewport — the shell-app look.

### Static output above the live region

While an inline app is mounted, `console.log` and friends are routed through the renderer by default (`patchConsole`), so stray logs become permanent lines **above** the live region instead of tearing through it. To emit transcript lines yourself, use `writeStatic(text)` (alias `printStatic`): the text scrolls into permanent scrollback, cleanly separated from the repainting frame.

```tsx
import { writeStatic } from '@sigx/terminal';

writeStatic('✔ Built in 1.2s');   // permanent line, above the live frame
```

## Fullscreen

`mode: 'fullscreen'` gives the app the **whole screen**. Mount enters the terminal's alternate screen buffer; unmount restores the user's prior terminal contents exactly as they were — nothing is left in scrollback. The themed canvas fills the empty viewport below your content (see [Theming](/terminal/docs/theming)).

Use fullscreen for dashboards, editors and long-running TUIs that own the screen; use inline for wizards, build runners and anything that should read as part of the command's output.

A fullscreen frame taller than the terminal is **clamped to the viewport** — but it keeps the opposite end from inline. Inline keeps the **bottom** rows, the live end of a transcript. Fullscreen keeps the **top**, because a dashboard's title bar and tab strip are up there, and dropping them to preserve a footer saves the wrong half.

So an over-tall body degrades to a missing footer rather than a missing header. Short frames are still padded out to the full height, so an app that owns the screen still fills it.

Without the clamp the alt buffer scrolls, the next frame's cursor-home no longer lands on the frame's first row, and every row after it is off by the overflow — the dashboard shears and stays sheared. That failure reads as a renderer bug rather than "the body emitted three rows too many", which is why it is clamped rather than reported.

Size content to the space you have — see [`fitLines`](/terminal/docs/api#fitlines) and [`Shell`](/terminal/docs/components/shell).

> `fullscreen: true` is accepted as an alias for `mode: 'fullscreen'`.

## Non-TTY fallback

When stdout is **not** a TTY — piped to a file, captured in CI — there is no live region and no escape codes. The app renders, and the final frame is emitted once as plain text at teardown. Animated components freeze on a single frame, and a `LogStore` switches to streaming complete, ordered lines (see [LogView](/terminal/docs/components/logview)). You write the same app; the renderer degrades it automatically.

## Color depth

The renderer detects terminal color support and honours `FORCE_COLOR` / `NO_COLOR`. Theme tokens resolve to truecolor or 256-color hex where supported, and degrade to the nearest 16-color ANSI name on limited terminals — handled entirely by `resolveColor` (see [Theming](/terminal/docs/theming)).

## Resize

The renderer listens for `SIGWINCH` and exposes the current dimensions as a **reactive** read:

```tsx
import { component, defineApp, getTerminalSize } from '@sigx/terminal';

const App = component(() => {
    return () => {
        const { columns, rows } = getTerminalSize();
        return (
            <box border="single" label="Size">
                <text>{columns} × {rows}</text>
            </box>
        );
    };
});

defineApp(<App />).mount({ mode: 'fullscreen' });
```

Reading `getTerminalSize()` **inside a render function** tracks it, so the component re-renders whenever the terminal is resized. Prefer it over `getOutputTarget().columns/rows`, which are live but not reactive.

## Exiting

The renderer intercepts **Ctrl+C** (raw mode delivers it as the key ``): it tears down cleanly — persisting the inline frame or leaving the alt screen, restoring raw mode and the cursor — then exits with the conventional code 130. For a programmatic exit, call `exitTerminal()`, which performs the same teardown.

To handle Ctrl+C yourself (prompts turn it into a graceful cancel), set `exitOnCtrlC: false` and it is delivered to your `onKey` handlers like any other key.

```tsx
import { exitTerminal, onKey } from '@sigx/terminal';

onKey((key) => {
    if (key === 'q') { exitTerminal(); return true; }
});
```

See [Input & Interactive Components](/terminal/docs/input-and-components) for the layered key-dispatch model.

## Next steps

- [Theming](/terminal/docs/theming) — tokens, themes and the screen canvas.
- [Input & Interactive Components](/terminal/docs/input-and-components) — layered key dispatch and focus.
- [Components](/terminal/docs/components) — the full component library.
- [API Reference](/terminal/docs/api) — `RenderTerminalOptions`, `getTerminalSize`, `writeStatic` and more.

---
url: https://sigx.dev/use/docs/use-local-storage/
title: useLocalStorage
description: A useStorage preset backed by window.localStorage — persists across sessions, with cross-tab sync
---

# useLocalStorage

A [`useStorage`](/use/docs/use-storage) preset backed by `window.localStorage` — a signal that persists across sessions. Browser composable — import from `@sigx/use-web`.

```ts
import { useLocalStorage } from '@sigx/use-web';

const prefs = useLocalStorage('prefs', { theme: 'light' });
prefs.theme = 'dark';   // persisted, reactive — no .value

const token = useLocalStorage('token', '');  // primitive mode
token.value = 'abc';                          // persisted
```

## Signature

```ts
function useLocalStorage<T extends Primitive>(key: string, defaults: T, options?: UseStorageOptions<T>): PrimitiveSignal<T>;
function useLocalStorage<T extends object>(key: string, defaults: T, options?: UseStorageOptions<T>): Signal<T>;
```

Same two overloads as `useStorage`: an **object default** returns a deep-reactive `Signal<T>` that auto-persists on mutation; a **primitive default** returns a `PrimitiveSignal<T>` that persists on `.value` write.

See [`useStorage`](/use/docs/use-storage) for the full semantics — object proxies, cross-tab sync, serializers, options, and SSR behaviour.

## See also

- [`useStorage`](/use/docs/use-storage) — the flagship, with every option and the deep-reactive model.
- [`useSessionStorage`](/use/docs/use-session-storage) — the same preset scoped to one tab session.

---
url: https://sigx.dev/actors/docs/cluster-stats/
title: Cluster stats
description: clusterStats() — a partial-tolerant fan-out across the view, why latency merges rather than averages, and the counters worth watching
---

# Cluster stats

<p class="lede">One call, every host: activations, queue depths, per-type counts, reminder
shard ownership, merged metrics and a health tally — plus an honest account of who did not
answer.</p>

```ts
import { clusterStats } from '@sigx/actors/cluster';

const report = await clusterStats(placement, { detail: true, activations: 20 });
```

It rides the internal mount as a reserved symbol, so it needs the cluster `secret` and
inherits the HMAC.

## Partial results, never an exception

> **It never throws for a sick peer.** Unreachable hosts come back in `unreachable[]` with a
> classified reason, and `partial: true` is set.

That is the correct behaviour for a diagnostic: the moment you most need cluster stats is the
moment some host is not answering.

**`totals.metrics.hosts` is the denominator.** A partial-fleet total is a lower bound, and
reading it as a whole-fleet number during an incident is how you talk yourself into the wrong
diagnosis. It is `null` when nothing is instrumented.

## Latency merges, it does not average

Percentiles are re-derived from **summed histogram buckets**, not averaged across hosts.

Averaging per-host p99s is simply wrong — it is a mean of order statistics, which is not an
order statistic of anything. Ten hosts at p99 = 10ms and one at p99 = 900ms do not make
p99 = 91ms; they make a fleet whose p99 depends entirely on how the traffic was distributed.
Summing the buckets first and then taking the percentile gives the number you meant.

`HISTOGRAM_LAYOUT`, `mergeHistogramDigests()`, `digestSnapshot()` and
`createMetricsAccumulator()` are exported from `@sigx/actors/host` if you want to do the same
folding yourself.

## Reminder shard ownership

The reminder table is split into 16 hash shards, each ticked by exactly one host via
rendezvous hashing over the membership view. The report tells you who owns what, and two
readings matter:

- **Two claimants for one shard** — views have diverged. Safe, because the per-shard etag CAS
  keeps delivery at-most-once, but it means membership is unsettled.
- **An empty shard** — nothing is ticking those reminders.

## Counters worth watching

`placement.counters()` gives routing, route cache, directory, membership and `authFailures`.

The one to put on a dashboard is **`locateRemote / locates`** — the miss rate your edge is
producing. If you have configured [locality routing](/actors/docs/locality-routing) and this
is not near zero, the edge is not hashing the token, or placement is not `preferLocalPolicy()`.

`transportFallbacks` tells you a [transport chain](/actors/docs/transports) is doing real work
— useful mid-deploy, worrying afterwards. `rebalanceRounds` and `rebalanceMigrations` cover
[rebalancing](/actors/docs/rebalancing).

## Detail is opt-in and clamped

```
GET /_sigx/ops/cluster?detail=1&activations=20&host=<id>
```

Requested limits are **clamped by the responder**, not trusted. The activation list is off by
default because actor keys can be personal data — see
[The ops endpoint](/actors/docs/ops-endpoint).

## Reading it

The [CLI dashboard](/actors/packages/actors-cli/overview) renders all of this, and every panel
states its scope — cluster-wide or one host — because that distinction is easy to lose and
expensive to get wrong.

## Next steps

- [The ops endpoint](/actors/docs/ops-endpoint) — how this is served.
- [Metrics](/actors/docs/metrics) — what is being merged.
- [Rebalancing](/actors/docs/rebalancing) — acting on ownership spread.

---
url: https://sigx.dev/actors/docs/in-components/
title: Reads & writes in components
description: useActorState and useActorAction — reading an actor method as component data, writes that refresh what they staled, and free SSR seeding
---

# Reads & writes in components

<p class="lede">`useActorState` reads an actor method as component data; `useActorAction` runs a
mutation and refreshes the reads it staled. Both come from `@sigx/actors/app`.</p>

```ts
import { useActorAction, useActorState } from '@sigx/actors/app';

const Cart = component(({ props }) => {
    const total = useActorState(CartActor, props.id, 'total');
    const add = useActorAction(CartActor, props.id, 'add');
    return () => (
        <button disabled={add.loading} onClick={() => add.run(['apple'])}>
            {total.match({ ready: (n) => `${n} items`, pending: () => '…' })}
        </button>
    );
});
```

Method names, argument types and results all come from the definition, so a rename surfaces at
every call site.

Pass a getter for a reactive key — `useActorState(CartActor, () => [selectedId(), 'total'])` —
and a falsy return parks the read in `'idle'`.

## Writes refresh what they staled

```ts
await add.run(['apple']);   // every read of this cart re-runs
```

No manual `refresh()`. The default invalidation is the whole-actor prefix
`actorKey(def, key)`, because a write changing what a *different* method returns is the normal
case, and under-invalidating leaves stale data on screen.

Narrow or widen it with `invalidates` — a pattern list, a function of `(result, key)`, or
`false`:

```ts
useActorAction(CartActor, id, 'add', {
    invalidates: [actorKey(CartActor, id, 'total'), ['@actor', 'Order']],
});
```

`actorKey(def, key, method?, ...args)` is that key. It is a **tuple** rather than a string
because the prefix relation is what invalidation needs: `['@actor','Cart','c1']` addresses
every read of that cart, `['@actor','Cart']` every cart on the page. It is isomorphic too — a
definition and a build-swapped client ref produce identical tuples.

## Built on `useData` / `useAction`

These are core's primitives, which is where the behaviour comes from: an `AsyncState` with
`match()` and `refresh()` that `errorScope` and `all()` already understand, and **in-flight
dedupe by canonical key** — ten components reading one actor make one dispatch.

The raw recipe still works — `useData(['cart', id], () => actor(CartActor, id).getSummary())`
— but it does not share keys with `useActorState`, so writes will not invalidate it.

## SSR seeding is free

`actor()` is isomorphic, so during a server render the read dispatches **in-process** through
the host — guards and all — resolves into the markup, and serializes into the page under its
canonical actor key. The browser restores it on mount **without refetching**.

There is nothing to configure and no loading flash on first paint.

## A server function's write does not invalidate

This is the one seam worth knowing. Invalidation is local bookkeeping in the page's cell
registry, and a [server function](/actors/docs/actors-or-server-functions) that writes to an
actor never went through `useActorAction` — so nothing told the page anything changed.

Declare it by hand:

```ts
const post = useAction(async (text: string) => {
    const count = await postMessage({ room, text });   // a serverFn
    cells.invalidate([actorKey(RoomActor, room)]);     // say what went stale
    return count;
});
```

## Other tabs need live reads

Everything above refreshes only the tab that wrote. No request/response call tells a *second*
browser that anything happened — that is what [live reads](/actors/docs/live-reads) are for:

```ts
const messages = useActorState(RoomActor, room, 'recent', 20, { live: true });
```

## Next steps

- [Live reads](/actors/docs/live-reads) — pushing changes to every open tab.
- [The client](/actors/docs/client) — calling actors outside a component.
- [Cacheable reads](/actors/docs/cacheable-reads) — absorbing read traffic at the edge.

---
url: https://sigx.dev/actors/docs/observability/
title: Observability
description: Prometheus exposition and OpenTelemetry traces via @sigx/actors-otel — the cardinality rule and the reset caveat
---

# Observability

<p class="lede">[`@sigx/actors-otel`](/actors/packages/actors-otel/overview) turns the host's
own metrics into something your monitoring stack already speaks — without making OpenTelemetry
a dependency of anything that does not want it.</p>

```bash
pnpm add @sigx/actors-otel
```

## Prometheus

The `/prometheus` entry imports **no OpenTelemetry at all**:

```ts
import { prometheusOps } from '@sigx/actors-otel/prometheus';

app.use(metrics()).use(prometheusOps({ secret: process.env.SIGX_OPS_SECRET }));
```

Mounts `GET /_sigx/metrics` beside [`ops()`](/actors/docs/ops-endpoint), with the same bearer
posture — **the secret is mandatory outside dev**.

```yaml
scrape_configs:
  - job_name: sigx-actors
    metrics_path: /_sigx/metrics
    authorization: { credentials_file: /etc/prometheus/sigx-ops-secret }
    static_configs: [{ targets: ['actors-host:7311'] }]
```

Options: `path` (default `/_sigx/metrics`), `secret`, `prefix` (default `sigx_actors_`), and
`bucketsSeconds` — a per-octave grid from 1µs to ~134s, about 28 bounds.

`renderPrometheus(digest, stats, options)` is the pure function underneath, if you would
rather serve it yourself. Among what it emits is `{prefix}one_way_failures_total` — a
[one-way call](/actors/docs/one-way-calls) that failed *after* acceptance has nowhere else to
be reported, so this counter is the only place it surfaces in Prometheus.

> **The cardinality rule: labels are `type` and `method` — never actor keys.** An actor key is
> unbounded by construction, and a key-labelled metric will take your Prometheus down. This is
> enforced, not advisory.

> **`metrics().reset()` breaks monotonicity.** Prometheus counters are expected only ever to
> increase; a `reset()` looks like a counter restart. That is survivable — `rate()` handles
> restarts — but do not wire `reset()` to anything periodic.

## OpenTelemetry traces

```ts
import { otelTraces } from '@sigx/actors-otel';

app.use(otelTraces({ turnSpans: true }));
```

One **CLIENT** span per dispatch and one **SERVER** span per turn, joined across hosts by the
W3C `traceparent` the runtime propagates: captured from the public endpoint header and carried
on the cluster envelope.

Span attributes use a **key hash**, not the key, for the same reason the
[routing token](/actors/docs/locality-routing) does — and with the same caveat that a hash is
log hygiene, not privacy.

`@opentelemetry/api` is an **optional** peer dependency. With no tracer provider registered
the plugin is inert and costs nothing.

## The metrics bridge

```ts
import { otelMetricsBridge } from '@sigx/actors-otel';

app.use(otelMetricsBridge({ percentileGauges: true }));
```

Feeds the host's counters and histograms into whatever OTel meter provider you have
configured, for stacks that collect metrics over OTLP rather than by scraping — including
`sigx.actors.calls.one_way_failures`, the OTLP spelling of the counter above.

## Socket sessions

[Socket connections](/actors/docs/socket-sessions) are counted separately, because none of the
things worth watching about them — how many are open, how long they live, how many were
refused — are visible to the turn metrics.

`socketStats()` is one recorder per host or listener, handed to every session:

```ts
import { socketStats } from '@sigx/actors/server';

const stats = socketStats();
attachActorSocket(server, { host, stats });
```

Publish it as an ops section, and it appears under `ops.sockets` behind the existing
[bearer posture](/actors/docs/ops-endpoint) — no endpoint changes:

```ts
registry.reportOps('sockets', () => stats.snapshot());
```

`snapshot()` carries the totals — connections opened, closed and **refused** (origin or auth,
turned away before serving a byte); calls started and failed; subscriptions opened and closed;
`protocolBreaches` (1003/1009) and `lifetimeCloses` (1008 from `revalidateMs` or
`maxConnectionMs`) — plus three live gauges summed across open sessions (`open`, `inFlight`,
`subscriptions`) and a connection-lifetime histogram, `null` until there is data.

`stats.digest()` is the mergeable form, in the same log-linear layout as every other
histogram, so a fleet-wide view merges the way [cluster stats](/actors/docs/cluster-stats)
does.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Prometheus, OTel and CLI rendering are not wired to this yet.</strong> The ops
    section is the way to read socket stats today.
  </div>
</div>

## Choosing

| You have | Use |
|---|---|
| Prometheus / VictoriaMetrics / Grafana Agent | `prometheusOps()` — no OTel dependency |
| An OTLP collector | `otelMetricsBridge()` + `otelTraces()` |
| Neither, and a terminal | the [CLI dashboard](/actors/packages/actors-cli/overview) |
| A custom stack | read [`ops()`](/actors/docs/ops-endpoint) directly |

Core plumbing this rides on: `ActorCallContext.traceparent`, the trailing `call` parameter on
`ActorTurnObserver`, and `bucketUpperBoundsUs()` / `timingSafeEquals` from
`@sigx/actors/host`.

## Next steps

- [`@sigx/actors-otel`](/actors/packages/actors-otel/overview) — the package reference.
- [Metrics](/actors/docs/metrics) — what is being exported.
- [Cluster stats](/actors/docs/cluster-stats) — the fleet-wide view.

---
url: https://sigx.dev/actors/docs/one-way-calls/
title: One-way calls
description: "with({ oneWay: true }) — resolve when the target accepts the call instead of when the turn completes, and where the failure line falls"
---

# One-way calls

<p class="lede">A one-way call resolves as `Promise<void>` when it is **accepted into the
target activation** — never when the turn completes. Fire-and-forget with backpressure and
error accounting, instead of a floating promise that has neither.</p>

```ts
await actor(Notifier, userId).with({ oneWay: true }).notify(event);
```

Locally that is at enqueue; remotely it is when the transport reply comes back from the
receiving host's enqueue. Awaiting it still tells you the runtime has taken responsibility for
the call — you just do not pay for the turn.

It works on every proxy — the browser client, the server entry and `ctx.actor(...)` — and the
type narrows to `Promise<void>` at the call site.

## Where failures fall

The line is **acceptance**.

| Failure | When | The caller sees |
|---|---|---|
| guard veto, unknown type, activation failure, wrong host, auth, unreachable peer, host shutting down | before acceptance | a normal rejection |
| the method throws, a deadline expires mid-turn | after acceptance | **nothing** — dropped, counted as `oneWayFailures` in [`metrics()`](/actors/docs/metrics) on the host that ran the turn, plus a dev-mode console warning |

So a one-way call still fails loudly for everything that would have stopped it from being
delivered, and silently for everything that happens once it is the runtime's problem. If you
need to know that the *work* succeeded, do not use `oneWay` — or have the actor report
completion some other way, such as a [topic](/actors/docs/topics).

## What follows from "the caller is gone"

**Ordering holds.** The call was enqueued before the promise resolved, so an awaited call
issued afterwards runs after it — the same [turn ordering](/actors/docs/turns) as always.

**A one-way self-call cannot deadlock.** Awaited, `A → A` on a non-reentrant actor is a
detected [`ActorDeadlockError`](/actors/docs/errors). One-way, it is "schedule more work for
myself" and simply queues behind the current turn. That makes it a clean way to express
follow-up work without widening [reentrancy](/actors/docs/reentrancy).

**The caller's deadline race is skipped** — there is no caller left to race. The deadline
still rides the context and bounds the turn's own nested awaited calls.

**Streams refuse it** — a stream is consumed, not fired and forgotten. A
[declared read](/actors/docs/cacheable-reads) goes out as a `POST` even under `get: true`,
because an acknowledgement must never be served from an HTTP cache.

## On the wire

The proxy sends `x-sigx-one-way: 1` and the endpoint answers at acceptance. Host-to-host, the
flag rides the envelope as an additive `ow` field — no protocol bump.

That header is a custom one, so it triggers a CORS preflight on a cross-origin call. Same
origin, the usual case, is unaffected.

**Mixed-version clusters degrade gracefully.** An older receiving host ignores the flag and
answers at turn completion: the call is still delivered exactly once, the sender just waits
longer, and a post-acceptance failure can reach it as a rejection during the rolling deploy.

**Delivery is at-most-once after the ack**, exactly as for normal calls. A connection lost
between acceptance and the reply can be retried by the cluster's routing — the same window
every unary call already has.

## When to use it

Good fits: notifications, analytics, cache warming, kicking off follow-up work on another
actor, anything where the caller genuinely does not need the result and you would otherwise
have written `void client.method()`.

Poor fits: anything a user is waiting on, and anything where a dropped post-acceptance failure
would go unnoticed. For long work that must survive and report progress, use a
[job](/actors/docs/jobs) instead.

## Watching for the failures you cannot await

Because a post-acceptance failure has no caller to reject, the counter **is** the signal.
`oneWayFailures` surfaces on every observability path:

| Where | What to look for |
|---|---|
| [Prometheus](/actors/docs/observability#prometheus) | `{prefix}one_way_failures_total` |
| [OTel](/actors/docs/observability#the-metrics-bridge) | `sigx.actors.calls.one_way_failures` |
| [CLI](/actors/packages/actors-cli/overview) | a `one-way fail` row under `calls` in `sigx actors stats`, and `N one-way` appended to the dashboard's call rows |

The CLI surfaces it **only when it is non-zero**, so a quiet dashboard means there is nothing
to see rather than that nobody is counting.

Worth an alert: a rising `oneWayFailures` is work you believed had happened.

## Next steps

- [Observability](/actors/docs/observability) — exporting the counter.
- [Tasks](/actors/docs/tasks) — detached work that still belongs to the actor.
- [Jobs](/actors/docs/jobs) — durable, resumable, observable work.
- [Topics](/actors/docs/topics) — actor-to-actor fan-out.

---
url: https://sigx.dev/actors/docs/wire-protocol/
title: Wire protocol
description: The actor endpoint is the serverFn protocol verbatim — the request shape, the callable surface, reserved symbols and the GET form
---

# Wire protocol

<p class="lede">`handleActorRequest` *is* `handleServerFnRequest` with a host-backed resolver.
Everything you configured for server functions applies here unchanged.</p>

```
POST {base}/r/{token}/{Type}/{method}
{"args": [key, ...args]}

→ {"data": …}  |  {"error": …}          (NDJSON for streams)
```

Same origin policy, body caps, prototype-pollution guards, error masking and
[codec](/server/packages/serialize/overview) — because it is literally the same endpoint
implementation. See
[Actors or server functions?](/actors/docs/actors-or-server-functions#they-are-the-same-wire).

The `/r/{token}/` segment is an optional [routing hint](/actors/docs/locality-routing). Under
`route: 'none'`, and for the reserved symbols below, the URL is plain
`{base}/{Type}/{method}` and everything else is unchanged.

`configureActors()` from `@sigx/actors/client` points remote and native clients at another
base, independently of `configureServerFn`.

## The path

The separator between type and method is a **real path separator**, and encoding is
per segment — so a normal call spends no `%` at all:

```
Cart#addItem          →  /_sigx/actor/Cart/addItem
acme/greeter#greet    →  /_sigx/actor/acme/greeter/greet
$live#subscribe       →  /_sigx/actor/$live/subscribe
$watch:Counter#read   →  /_sigx/host/$watch:Counter/read
```

**A type may itself contain `/`** — `acme/greeter` is the packaged-actor convention — so the
reading half splits on the **last** separator. The last segment is always the method.

Three characters are restored after encoding: **`@`, `$` and `:`**. The runtime's own reserved
vocabulary spends `$` and `:` (`$live`, `$watch:`, `$sigx:host`), and all three are RFC 3986
`pchar`, so they are legal literal path characters. The other legal sub-delims — `&`, `+`,
`,`, `;`, `=` — stay escaped deliberately; `+` especially, because a naive query-ish parser
decodes it as a space.

**The routing token stays percent-encoded**, and that asymmetry is deliberate. The symbol
spans several segments; the token is escaped so it stays exactly **one**, which is what keeps
`{base}/r/{token}/{symbol}` parseable from the left — the first segment after `r/` is the
whole token, and everything after it is the whole symbol.

**The in-memory symbol is the same string everywhere else.** It is `` `${type}#${method}` `` everywhere that is not
a URL: it is what the per-call HMAC signs, what `ServerFnInfo.symbol` reports to a policy, and
what a frame transport like [`@sigx/actors-tcp`](/actors/packages/actors-tcp/overview) carries
with no URL anywhere near it. Only the URL spelling differs.

Two names are refused, both because the alternative is a silent misroute rather than an error:

- **A `type` with an empty, `.` or `..` path segment** — `new URL()` would resolve it away and
  quietly retarget the route.
- **A `method` containing `/`** — `Type#a/b` would encode to `Type/a%2Fb`, and the reading
  half decodes each segment before it splits on the last `/`, so the symbol would come back as
  `Type/a#b`: a different actor, silently. This one throws in production as well as dev, since
  escaping it would not save the round trip.

## The GET form

A method with a [`reads:` declaration](/actors/docs/cacheable-reads) also answers:

```
GET {base}/r/{token}/{Type}/{method}?a0=p-9&a1=EUR
```

Same codec, same envelope, plus the `Cache-Control` the declaration asked for.

**Arguments ride as named params when every one of them is a simple scalar** — `null`, a
string, a boolean, or a finite number. Argument 0 is the actor key, so it is `a0`. A string
that would read back as a number, `true`, `false` or `null`, or that already starts with a
quote, is JSON-quoted (`a0="42"`).

Anything richer — an object, a `Date` — falls back to the `?args=<JSON>` blob, and does so
**all-or-nothing**, so one call never mixes the two encodings and the cache key stays a pure
function of the arguments.

This grammar is core's, character for character: the same declared read must decode
identically on `/_sigx/fn` and `/_sigx/actor`, so the actor endpoint delegates to
`handleServerFnRequest` and never re-derives it.

## The callable surface

**The callable surface is the method table's own keys.** A name that is not an own, callable
key of `methods:` or `streams:` is a `404 method-not-found`.

That means inherited `Object.prototype` members — `toString`, `constructor`, `valueOf`,
`__proto__` — are not callable. It also means a `methods:` factory returning a **class
instance** does not work, because its methods live on a prototype:

```ts
methods: (ctx) => ({ async addItem(i) { /* … */ } }),   // ✓ own keys
methods: (ctx) => new CartMethods(ctx),                 // ✗ prototype methods
```

Dev builds warn on the second form.

Shadowing a prototype name in the literal does not help either: `async toString()` is an own
key the *server* would dispatch, but the [client proxy answers those names
locally](/actors/docs/client#refs-are-inspectable) and never issues the call. Pick another
name.

## Reserved symbols

Two `$`-prefixed shapes exist, which is why `defineActor` refuses a `type` starting with `$`
or `@`:

| Symbol | On the wire | What it is |
|---|---|---|
| `$live#subscribe` | `{base}/$live/subscribe` | the multiplexed [live-read](/actors/docs/live-reads) mount — the only one a browser talks to |
| `$watch:{Type}#{method}` | `/_sigx/host/$watch:{Type}/{method}` | internal host-to-host watch forwarding, on the internal mount — not a public endpoint |

`@` is reserved for data keys (`['@actor', …]` — see
[Reads & writes in components](/actors/docs/in-components)).

## The request-context bag

A small string-only key/value bag that rides the call envelope, for **app data** a method needs
but should not take as an argument — a request id, a tenant hint, a feature flag.

Stamp it at the edge and read it in the method:

```ts
// in a middleware or policy, server-side
stampCallBag(rq, { tenant: 'acme', reqId });

// in an actor method
methods: (ctx) => ({
    async post(text: string) {
        log(ctx.bag.reqId, ctx.key, text);
    },
}),
```

Server-side callers can also pass entries explicitly, and explicit wins on conflict:

```ts
await actor(RoomActor, id).with({ bag: { tenant: 'acme' } }).post(text);
```

`ctx.bag` is frozen and rebuilt per read, and it is **empty outside a turn** — that empty
value is exported from the root entry as `EMPTY_CALL_BAG`, so a caller comparing against it
does not have to mint its own.
`ctx.actor` and `ctx.publish` hops inherit it; detached [task](/actors/docs/tasks) bodies and
volatile timer ticks deliberately read it empty, the same way `traceparent` does.

### Caps, and what happens at the edges

| limit | value |
|---|---|
| entries | 8 |
| key length | 64 B |
| value length | 256 B |
| total | 1 KiB |

Exported as `CALL_BAG_MAX_*`. The posture differs by who made the mistake: **your own** input
throws, so you find it in development; a bag arriving **en route** that is malformed or over
cap is dropped **whole** and silently — never a 400.

<div class="alert alert-warning not-prose my-4">
  <div>
    Because an en-route bag drops whole, <strong>a missing entry must read as
    unauthenticated</strong>, never as "allow". The bag is never populated from a request
    header — client-settable identity would be an authorization bypass — and it is not where
    identity belongs at all. Use <a href="/actors/docs/guards"><code>ctx.principal</code></a>
    for that.
  </div>
</div>

The envelope decode rebuilds the bag into a fresh null-prototype object. Between hosts its
integrity is the envelope's perimeter posture: the cluster HMAC signs the call identity, not
the body, so run mTLS or a private network between hosts.

## Pluggable transports

The client proxy never speaks HTTP itself — it delegates to an `ActorTransport`, so batching,
a different auth scheme, or a protocol other than fetch drops in without any call site
changing:

```ts
import { configureActors, fetchTransport } from '@sigx/actors/client';

configureActors({ endpoint: '/actors', headers: () => ({ authorization: token() }) });
// …sugar for fetchTransport(config). Or supply the whole seam:
configureActors({
    name: 'batching',
    call: (symbol, args, init) => /* … */,
    stream: (symbol, args, init) => /* … */,
    live: () => /* optional push channel */,
});
```

`fetchTransport()` is the default and implements exactly the contract above. `init.endpoint`
carries the endpoint the build baked into the ref, so `configureActors({ headers })` can
override headers alone without restating where the server is.

`live()` is the one **optional** member. Leave it out and `@sigx/actors/app` drives the
`$live` mount over your `stream()` instead — which is how the default transport gets live
reads without carrying a line of push logic in `./client`, whose bytes ride every bundle that
touches an actor. Implement it, as a WebSocket transport would, and the app uses yours.

**Server-side, a transport is a plugin.** `PluginRegistry.route()` lets one contribute its own
mount, which `createAppHandler` and `createFetchHandler` serve in dev and prod alike.

> One current limit: `ActorRoute.handle` returns a `Response`, which cannot express a Node
> WebSocket upgrade — that needs the raw socket. This applies to the **client-facing**
> transport. A [host-to-host transport](/actors/docs/transports) is not bound by it, because
> it may bring its own listener instead of a route.

## The socket wire

`@sigx/actors/socket-wire` is the protocol a socket speaks, published as its own subpath so an
adapter written outside this repo reaches the one true wire instead of copying it — the same
standing `./cluster/frames` has for host transports.

```ts
import { encodeWire, parseWire, reviveWire, wireFail } from '@sigx/actors/socket-wire';
import type { SocketReply, SocketRequest } from '@sigx/actors/socket-wire';
```

Replies are `{i,v}` for a value and `{i,e}` for an error, and those **are** the `$live`
`LiveFrame` shapes by construction, not a parallel spelling of them. Calls and subscriptions
share **one id namespace**, which is why a reply carries only `i` and needs no kind tag.

`parseWire` is pollution-safe and `wireFail` is branded, so a malformed message is a typed
failure rather than something that has to be guessed at.

Two things live here rather than in either channel, so the two cannot fork: identity
coalescing with late-subscriber replay and `fingerprint()` re-seed suppression, and
`createSocketLiveChannel`.

What it deliberately is **not**: there is no principal field, no envelope and no
inbound-call direction. That is the browser trust model expressed as a shape — a client may
ask, and may subscribe, and may do nothing else. The
[cluster frames](/actors/docs/transports) are a different protocol for a different perimeter.

## Next steps

- [The client](/actors/docs/client) — configuring transports and routers.
- [Locality routing](/actors/docs/locality-routing) — the token and what it is for.
- [Cacheable reads](/actors/docs/cacheable-reads) — the GET form in depth.

---
url: https://sigx.dev/core/docs/getting-started/
title: Getting Started
description: Learn how to build reactive web applications with SignalX
---

# Getting Started

SignalX is a lightweight reactive component framework that brings fine-grained reactivity to your applications with minimal overhead.

## What is SignalX?

SignalX combines the best ideas from modern reactive frameworks:

- **Signals** - Fine-grained reactive primitives with deep object reactivity
- **Components** - Intuitive `component` API with props, slots, and events
- **TypeScript** - Full type inference and IDE support out of the box
- **Tiny** - Lightweight core runtime with tree-shakeable packages
- **Multi-platform** - One component model across the browser, native iOS & Android, terminals, and the server

## Quick Installation

Create a new SignalX project with our CLI:

```bash
npm create @sigx@latest my-app
cd my-app
npm install
npm run dev
```

Or add to an existing Vite project:

```bash
npm install sigx @sigx/vite
```

Configure Vite:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { sigxPlugin } from '@sigx/vite';

export default defineConfig({
    plugins: [sigxPlugin()],
});
```

## Your First Component

```tsx
import { component, render } from 'sigx';

const Counter = component(({ signal }) => {
    // Create reactive state - objects use direct property access
    const state = signal({ count: 0 });
    
    return () => (
        <div>
            <p>Count: {state.count}</p>
            <button onClick={() => state.count++}>
                Increment
            </button>
        </div>
    );
});

render(<Counter />, "#sandbox");
```

## Key Concepts

### Signals with Objects (Recommended Pattern)

```tsx
import { component, render } from 'sigx';

const MyComponent = component(({ signal }) => {
    // Group state in an object - properties are directly reactive
    const state = signal({
        count: 0,
        name: 'World',
        items: []
    });
    
    return () => (
        <div>
            <p>{state.name}: {state.count}</p>
            <button onClick={() => state.count++}>+</button>
        </div>
    );
});

render(<MyComponent />, "#sandbox");
```

### Typed Props and Events

```tsx
import { component, render, type Define } from 'sigx';

type CounterProps = 
    & Define.Prop<'initialValue', number, false>
    & Define.Event<'change', number>;

const Counter = component<CounterProps>(({ signal, props, emit }) => {
    const state = signal({ 
        count: props.initialValue ?? 0 
    });
    
    const increment = () => {
        state.count++;
        emit('change', state.count);
    };
    
    return () => (
        <div>
            <span>{state.count}</span>
            <button onClick={increment}>+</button>
        </div>
    );
});

const App = component(() => {
    const handleChange = (newCount: number) => {
        console.log('Count changed to:', newCount);
    };
    
    return () => (
        <Counter initialValue={10} onChange={handleChange} />
    );
});
// Usage
render(<App />, "#sandbox");
```

## Application Setup

Use `defineApp` to create and mount your application:

```tsx
import { defineApp, component } from 'sigx';

const App = component(({ signal }) => {
    const state = signal({ message: 'Hello SignalX!' });
    
    return () => <h1>{state.message}</h1>;
});

// Create and mount the app
defineApp(<App />).mount('#sandbox');
```

### With Plugins

```tsx
import { defineApp, component, type Plugin } from 'sigx';

const loggingPlugin: Plugin = {
    name: 'logging',
    install(app) {
        app.hook({
            onComponentMounted: (instance) => {
                console.log(`Mounted: ${instance.name}`);
            }
        });
    }
};

const App = component(({ signal }) => {
    const state = signal({ message: 'Hello SignalX!' });
    
    return () => <h1>{state.message}</h1>;
}, { name: 'App' });

defineApp(<App />)
    .use(loggingPlugin)
    .mount('#sandbox');
```

## Beyond the Browser

SignalX is multi-platform — the same components and signals render past the DOM. Bring your component tree to:

- [Lynx](/lynx) - Native iOS & Android from one component tree
- [Terminal](/terminal) - Terminal UIs (TUIs) in TSX
- [Server](/server) - Streaming server-side rendering with hydration

## Next Steps

- [Signals](/core/docs/signals) - Deep dive into reactive state
- [Components](/core/docs/components) - Component model and patterns
- [Computed](/core/docs/computed) - Derived reactive values
- [Effects](/core/docs/effects) - Side effects and reactions
- [Lifecycle](/core/docs/lifecycle) - Component lifecycle hooks

---
url: https://sigx.dev/core/docs/two-way-binding/
title: Two-Way Binding
description: Learn how to use model binding for two-way data synchronization in SignalX
---

# Two-Way Binding

SignalX provides a powerful `model` directive for two-way data binding between your reactive state and form elements or custom components.

## Overview

The model binding system separates concerns cleanly:

- **For callers**: Use `model={() => state.property}` to create a two-way binding
- **For components**: Access `props.model` to read/write values and forward bindings

This architecture enables seamless binding forwarding to child components while maintaining full reactivity.

## Model on Native Elements

The simplest way to use two-way binding is with native HTML elements. Just use `model={() => state.property}`:

```tsx
import { component, render } from 'sigx';

const TextInputDemo = component(({ signal }) => {
    const state = signal({ name: '' });
    
    return () => (
        <div style="padding: 16px;">
            <input 
                model={() => state.name} 
                placeholder="Type your name"
            />
            <p style="margin-top: 12px;">Hello, {state.name || 'stranger'}!</p>
        </div>
    );
});

render(<TextInputDemo />, "#sandbox");
```

The `model` prop accepts a **getter function** that returns a property from a reactive signal. SignalX automatically:
- Sets the element's value from your state
- Updates your state when the user types

### Supported Elements

#### Text & Number Inputs

```tsx
import { component, render } from 'sigx';

const InputsDemo = component(({ signal }) => {
    const form = signal({ 
        username: '', 
        age: 25 
    });
    
    return () => (
        <div style="padding: 16px;">
            <div style="display: flex; gap: 8px; margin-bottom: 12px;">
                <input type="text" model={() => form.username} placeholder="Username" />
                <input type="number" model={() => form.age} style="width: 80px;" />
            </div>
            <p>User: {form.username || '(empty)'}, Age: {form.age}</p>
        </div>
    );
});

render(<InputsDemo />, "#sandbox");
```

#### Checkbox (Boolean)

For a single checkbox, bind to a boolean value:

```tsx
import { component, render } from 'sigx';

const CheckboxDemo = component(({ signal }) => {
    const state = signal({ agreed: false });
    
    return () => (
        <div style="padding: 16px;">
            <label style="display: flex; align-items: center; gap: 8px; cursor: pointer;">
                <input type="checkbox" model={() => state.agreed} />
                I agree to the terms
            </label>
            <p style="margin-top: 12px;">Agreed: <strong>{state.agreed ? 'Yes ✓' : 'No'}</strong></p>
        </div>
    );
});

render(<CheckboxDemo />, "#sandbox");
```

#### Checkbox (Array)

For multiple checkboxes, bind to an array. The checkbox's `value` is added/removed from the array:

```tsx
import { component, render } from 'sigx';

const MultiCheckboxDemo = component(({ signal }) => {
    const state = signal({ 
        selectedFruits: [] as string[] 
    });
    
    const labelStyle = "display: flex; align-items: center; gap: 8px; cursor: pointer; margin-bottom: 8px;";
    
    return () => (
        <div style="padding: 16px;">
            <label style={labelStyle}>
                <input type="checkbox" value="apple" model={() => state.selectedFruits} />
                🍎 Apple
            </label>
            <label style={labelStyle}>
                <input type="checkbox" value="banana" model={() => state.selectedFruits} />
                🍌 Banana
            </label>
            <label style={labelStyle}>
                <input type="checkbox" value="orange" model={() => state.selectedFruits} />
                🍊 Orange
            </label>
            <p style="margin-top: 12px;">Selected: <strong>{state.selectedFruits.join(', ') || 'none'}</strong></p>
        </div>
    );
});

render(<MultiCheckboxDemo />, "#sandbox");
```

#### Radio Buttons

Radio buttons update the bound value with their `value` attribute:

```tsx
import { component, render } from 'sigx';

const RadioDemo = component(({ signal }) => {
    const state = signal({ size: 'medium' });
    
    const labelStyle = "display: flex; align-items: center; gap: 8px; cursor: pointer; margin-bottom: 8px;";
    
    return () => (
        <div style="padding: 16px;">
            <label style={labelStyle}>
                <input type="radio" value="small" model={() => state.size} />
                Small
            </label>
            <label style={labelStyle}>
                <input type="radio" value="medium" model={() => state.size} />
                Medium
            </label>
            <label style={labelStyle}>
                <input type="radio" value="large" model={() => state.size} />
                Large
            </label>
            <p style="margin-top: 12px;">Size: <strong>{state.size}</strong></p>
        </div>
    );
});

render(<RadioDemo />, "#sandbox");
```

#### Select

```tsx
import { component, render } from 'sigx';

const SelectDemo = component(({ signal }) => {
    const state = signal({ country: 'us' });
    
    const countries: Record<string, string> = {
        us: 'United States',
        uk: 'United Kingdom', 
        ca: 'Canada'
    };
    
    return () => (
        <div style="padding: 16px;">
            <select 
                model={() => state.country}
            >
                <option value="us">United States</option>
                <option value="uk">United Kingdom</option>
                <option value="ca">Canada</option>
            </select>
            <p style="margin-top: 12px;">Country: <strong>{countries[state.country]}</strong></p>
        </div>
    );
});

render(<SelectDemo />, "#sandbox");
```

#### Textarea

```tsx
import { component, render } from 'sigx';

const TextareaDemo = component(({ signal }) => {
    const state = signal({ bio: '' });
    
    return () => (
        <div style="padding: 16px;">
            <textarea 
                model={() => state.bio} 
                placeholder="Tell us about yourself"
                rows={4}
                style="width: 100%; max-width: 300px;"
            />
            <p style="margin-top: 12px;">Characters: <strong>{state.bio.length}</strong></p>
        </div>
    );
});

render(<TextareaDemo />, "#sandbox");
```

---

## Model on Custom Components

To create a component that supports `model` binding, use the `Define.Model<T>` type helper. Components receive model bindings through a dedicated `models` object in the setup context, separate from `props`.

### The Model Object

When a component receives a `model` binding, SignalX provides a `Model<T>` object on `props` with:

| Property | Description | Use Case |
|----------|-------------|----------|
| `props.model.value` | Current value (read/write) | Reading or updating the value |
| `props.model` | The model object itself | Forwarding to child components |

For named models like `model:title`, you get `props.title.value` and `props.title`.

Model props are available during **server** setup too, so `props.model.value`
reads the bound value inside `renderToString` exactly as it does on the client.
A component taking a model needs no SSR guard around it.

### Why Model Objects?

The `Model<T>` object on props provides several benefits:

1. **Clean forwarding**: `props.model` can be passed directly to child components
2. **Always reactive**: Model value reads in render are tracked
3. **Unified access**: Read and write via `props.model.value`
4. **Type safety**: Full TypeScript inference for model types

### Define.Model Type

`Define.Model<T>` creates:
- A `props.model` object with `.value` accessor
- The model object for forwarding to children
- An `update:modelValue` event for emitting updates

```tsx
import { component, render, type Define } from 'sigx';

// Define a component that accepts model binding
type RatingProps = Define.Model<number>;

const Rating = component<RatingProps>(({ props }) => {
    const stars = [1, 2, 3, 4, 5];
    
    return () => (
        <div style="display: flex; gap: 4px;">
            {stars.map(star => (
                <button 
                    onClick={() => { if (props.model) props.model.value = star; }}
                    style={{
                        background: 'none',
                        border: 'none',
                        fontSize: '24px',
                        cursor: 'pointer',
                        color: star <= (props.model?.value ?? 0) ? '#fbbf24' : '#d1d5db',
                        transition: 'color 0.15s'
                    }}
                >
                    ★
                </button>
            ))}
        </div>
    );
});

// Usage with model binding
const App = component(({ signal }) => {
    const state = signal({ rating: 3 });
    
    return () => (
        <div style="padding: 16px;">
            <Rating model={() => state.rating} />
            <p style="margin-top: 12px;">Rating: <strong>{state.rating}</strong> stars</p>
        </div>
    );
});

render(<App />, "#sandbox");
```

### Named Model Props

For components that need multiple two-way bindings, use the two-argument form of `Define.Model`:

```tsx
import { component, render, type Define } from 'sigx';

// Define.Model<'propName', Type> creates:
// - props.propName (Model object for forwarding)
// - props.propName.value (current value)
// - update:propName event
type RangeProps = 
    & Define.Model<'min', number>
    & Define.Model<'max', number>;

const RangeSlider = component<RangeProps>(({ props }) => {
    const labelStyle = "display: flex; align-items: center; gap: 12px; margin-bottom: 12px;";
    const valueStyle = "min-width: 30px; font-weight: bold;";
    
    return () => (
        <div>
            <label style={labelStyle}>
                <span style="min-width: 40px;">Min:</span>
                <input 
                    type="range" 
                    min={0} 
                    max={100}
                    value={props.min?.value ?? 0}
                    onInput={(e) => { if (props.min) props.min.value = Number((e.target as HTMLInputElement).value); }}
                    style="flex: 1;"
                />
                <span style={valueStyle}>{props.min?.value}</span>
            </label>
            <label style={labelStyle}>
                <span style="min-width: 40px;">Max:</span>
                <input 
                    type="range"
                    min={0}
                    max={100}
                    value={props.max?.value ?? 100}
                    onInput={(e) => { if (props.max) props.max.value = Number((e.target as HTMLInputElement).value); }}
                    style="flex: 1;"
                />
                <span style={valueStyle}>{props.max?.value}</span>
            </label>
        </div>
    );
});

// Usage with named model bindings
const Filter = component(({ signal }) => {
    const range = signal({ min: 20, max: 80 });
    
    return () => (
        <div style="padding: 16px; max-width: 320px;">
            <RangeSlider 
                model:min={() => range.min}
                model:max={() => range.max}
            />
            <p style="margin-top: 8px; padding: 8px; background: #e5e7eb; border-radius: 6px; text-align: center; color: #111;">
                Range: <strong>{range.min}</strong> – <strong>{range.max}</strong>
            </p>
        </div>
    );
});

render(<Filter />, "#sandbox");
```

---

## Forwarding Model Bindings

One of the most powerful features of SignalX's model architecture is seamless forwarding to child components.

### Direct Forwarding

Since `props.model` is a `Model<T>` object, you can pass it directly to child components:

```tsx
import { component, type Define } from 'sigx';

type WrapperProps = Define.Model<string>;

const Wrapper = component<WrapperProps>(({ props, slots }) => {
    return () => (
        <div class="wrapper">
            {/* Forward model binding directly to child */}
            <Input model={props.model} />
        </div>
    );
});

// Usage: binding flows through Wrapper to Input
<Wrapper model={() => form.email} />
```

The child component receives the same reactive binding—changes propagate all the way back to the original signal.

### Forwarding Named Models

For named models, use the corresponding model object from props:

```tsx
type FormFieldProps = 
    & Define.Model<'text', string>
    & Define.Model<'error', string>;

const FormField = component<FormFieldProps>(({ props }) => {
    return () => (
        <div class="field">
            {/* Forward to different child components */}
            <Input model={props.text} />
            <ErrorMessage model={props.error} />
        </div>
    );
});

// Usage
<FormField 
    model:text={() => form.email}
    model:error={() => form.emailError}
/>
```

### Forwarding via Context

For deeply nested components (like menu items in a menu), provide the binding through context. Use a getter for clean reactive access:

```tsx
import { component, defineInjectable, defineProvide, type Define } from 'sigx';

// Context with value getter and setter
const menuContext = defineInjectable<{
    readonly value: string | undefined;
    setValue: (v: string) => void;
}>(() => ({ 
    value: undefined, 
    setValue: () => {} 
}));

type MenuProps = Define.Model<string>;

const Menu = component<MenuProps>(({ props, slots }) => {
    // Provide reactive value access via getter
    defineProvide(menuContext, () => ({
        get value() { return props.model?.value; },
        setValue: (v: string) => { if (props.model) props.model.value = v; }
    }));
    
    return () => (
        <ul class="menu">
            {slots.default?.()}
        </ul>
    );
});

type MenuItemProps = Define.Prop<'value', string>;

const MenuItem = component<MenuItemProps>(({ props, slots }) => {
    const ctx = menuContext();
    
    return () => {
        const isActive = ctx.value === props.value;
        
        return (
            <li 
                class={isActive ? "active" : ""}
                onClick={() => ctx.setValue(props.value)}
            >
                {slots.default?.()}
            </li>
        );
    };
});

// Usage
const Nav = component(({ signal }) => {
    const nav = signal({ active: 'home' });
    
    return () => (
        <Menu model={() => nav.active}>
            <MenuItem value="home">Home</MenuItem>
            <MenuItem value="about">About</MenuItem>
            <MenuItem value="contact">Contact</MenuItem>
        </Menu>
    );
});
```

This approach:
- **Clean reads**: `ctx.value` — the getter is called automatically
- **Clean writes**: `ctx.setValue(v)` — explicit setter call
- **Stays reactive**: The getter accesses `props.model.value` inside the render function

---

## How It Works

When you write `model={() => state.property}`:

1. **Getter function**: The `() => state.property` is a function that accesses a reactive property
2. **Detection**: SignalX's `detectAccess()` function intercepts the property access to extract `[stateObj, "property"]`
3. **JSX Processing**: The JSX runtime transforms this into:
   - For components: A `Model<T>` object on `props` with `value` accessor and binding info
   - For native elements: Sets up value binding and event listeners
4. **Component receives**: The model object is available on `props.model`

### Component Model Flow

```
Caller: model={() => state.property}
    ↓
JSX Runtime: detectAccess → [state, "property"]
    ↓
VNode: props.$models = { model: Model<T> }
    ↓
Renderer: Merges model into props
    ↓
Component: Access via props.model.value
    ↓
Update: props.model.value = newValue → state.property = newValue
```

### Forwarding Flow

```
Parent receives: model={() => nav.active}
    ↓
Parent's props.model = Model<string>
    ↓
Forward: <Child model={props.model} />
    ↓
Child receives same model object
    ↓
Child props.model.value = x updates original nav.active
```

---

## Best Practices

### Use props.model for Model Values

Access model values from the `props` object:

```tsx
const Input = component<Define.Model<string>>(({ props }) => {
    return () => (
        <input 
            value={props.model?.value ?? ''}
            onInput={(e) => { if (props.model) props.model.value = (e.target as HTMLInputElement).value; }}
        />
    );
});
```

### Use Signals or Writable Computed

Bind to signal properties or writable computed values:

```tsx
// ✅ Good - binds to signal property
<input model={() => state.name} />

// ✅ Good - writable computed works with model
<input model={() => fullName.value} />

// ❌ Bad - read-only computed isn't settable
<input model={() => readOnlyComputed.value} />

// ❌ Bad - expressions aren't bindable
<input model={() => state.name.toUpperCase()} />
```

### Writable Computed Example

Writable computed values work seamlessly with model binding, enabling transformations in both directions:

```tsx
import { component, computed, render } from 'sigx';

const TemperatureConverter = component(({ signal }) => {
    const state = signal({ celsius: 20 });
    
    // Writable computed for Fahrenheit conversion
    const fahrenheit = computed({
        get: () => state.celsius * 9/5 + 32,
        set: (f) => { state.celsius = (f - 32) * 5/9; }
    });
    
    return () => (
        <div style="padding: 16px;">
            <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 16px;">
                <label style="display: flex; align-items: center; gap: 8px;">
                    <input 
                        type="number" 
                        model={() => state.celsius}
                        style="width: 80px; text-align: center;"
                    />
                    <span>°C</span>
                </label>
                <span style="color: #6b7280;">=</span>
                <label style="display: flex; align-items: center; gap: 8px;">
                    <input 
                        type="number"
                        model={() => fahrenheit.value}
                        style="width: 80px; text-align: center;"
                    />
                    <span>°F</span>
                </label>
            </div>
            <p style="color: #6b7280; font-size: 14px;">
                Edit either field — both stay in sync!
            </p>
        </div>
    );
});

render(<TemperatureConverter />, "#sandbox");
```

The `fahrenheit` computed automatically converts between units. When you type in the Fahrenheit field, the setter updates `state.celsius`, which in turn updates the Fahrenheit display.

### Forward with props.model

When forwarding bindings, pass the model object from props:

```tsx
// ✅ Good - forwards the model object
<ChildInput model={props.model} />

// ✅ Good - named model forwarding
<ChildInput model={props.title} />
```

### Type Your Define.Model Props

For TypeScript users, always specify the type:

```tsx
type FormProps = Define.Model<string>;  // For string values
type ToggleProps = Define.Model<boolean>;  // For boolean values
type CounterProps = Define.Model<number>;  // For number values

// Named models
type EditorProps = Define.Model<'content', string>;
```

### Combine with Other Props

`Define.Model` composes with other type helpers:

```tsx
import { type Define } from 'sigx';

type InputProps = 
    & Define.Model<string>
    & Define.Prop<'placeholder', string, false>
    & Define.Prop<'disabled', boolean, false>
    & Define.Event<'blur', FocusEvent>;
```

---

## Model Type

For advanced use cases, you can import the `Model<T>` type:

```tsx
import { Model } from 'sigx';

// Model<T> provides:
// - .value: T (read/write)
// - .binding: [stateObj, key, handler] (internal)

type ContextType = {
    model?: Model<string>;
};
```

This is useful when:
- Creating context types for model forwarding
- Building wrapper components that pass bindings
- Writing utility functions that work with models

---

## Custom Model Handling

`model={() => …}` on native elements is handled by the platform's model processor (the DOM processor knows about text inputs, checkboxes, radios, selects, and textareas). To teach `model` about a **custom element or widget library**, register an extension processor with `registerModelProcessor`:

```tsx
import { registerModelProcessor } from 'sigx';

// Add model handling for a custom <color-picker> element
registerModelProcessor((type, props, [obj, key], originalProps) => {
    if (type !== 'color-picker') return false; // defer to other processors

    props.value = obj[key];
    props.onColorChange = (e: any) => { obj[key] = e.detail.value; };
    return true; // handled — skip the generic fallback
});
```

Extension processors run **before** the platform processor, in registration order, and the **first one returning `true` wins**. This means packs and apps can *add* model behaviors without replacing the platform's built-in handling — the platform processor remains the final fallback. (Platform packages register their processor via the separate `setPlatformModelProcessor` seam, which is part of platform identity and unaffected.)

---

## Complete Example

Here's a complete form example showing the full model binding architecture:

```tsx
import { component, render, type Define } from 'sigx';

// Reusable form field with text and error models
type FormFieldProps = 
    & Define.Model<'text', string>
    & Define.Model<'error', string>
    & Define.Prop<'label', string>;

const FormField = component<FormFieldProps>(({ props }) => {
    function handleInput(e: Event) {
        const text = (e.target as HTMLInputElement).value;
        if (props.text) props.text.value = text;
        if (props.error?.value) {
            props.error.value = '';
        }
    }
    
    return () => (
        <div style="margin-bottom: 16px;">
            <label style="display: block; margin-bottom: 4px; font-weight: 500;">
                {props.label}
            </label>
            <input 
                value={props.text?.value ?? ''}
                style={{
                    width: '100%',
                    padding: '8px 12px',
                    border: props.error?.value ? '2px solid #ef4444' : '1px solid #d1d5db',
                    borderRadius: '6px',
                    fontSize: '14px',
                    outline: 'none',
                    boxSizing: 'border-box'
                }}
                onInput={handleInput}
            />
            {props.error?.value && (
                <span style="color: #ef4444; font-size: 12px; margin-top: 4px; display: block;">
                    {props.error.value}
                </span>
            )}
        </div>
    );
});

// Main form component
const ContactForm = component(({ signal }) => {
    const form = signal({
        name: '',
        nameError: '',
        email: '',
        emailError: ''
    });
    
    function validate() {
        let valid = true;
        if (!form.name) {
            form.nameError = 'Name is required';
            valid = false;
        }
        if (!form.email.includes('@')) {
            form.emailError = 'Invalid email';
            valid = false;
        }
        return valid;
    }
    
    function handleSubmit() {
        if (validate()) {
            alert(`Submitted: ${form.name}, ${form.email}`);
        }
    }
    
    return () => (
        <form 
            style="max-width: 320px; padding: 20px;"
            onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}
        >
            <FormField 
                label="Name"
                model:text={() => form.name}
                model:error={() => form.nameError}
            />
            <FormField 
                label="Email"
                model:text={() => form.email}
                model:error={() => form.emailError}
            />
            <button type="submit">
                Submit
            </button>
        </form>
    );
});

render(<ContactForm />, "#sandbox");
```

---
url: https://sigx.dev/use/docs/use-color-scheme/
title: useColorScheme
description: The system light/dark preference as the cross-platform ColorScheme contract — the same shape Lynx returns
---

# useColorScheme

The system color-scheme preference as the cross-platform `ColorScheme` contract. Browser composable — import from `@sigx/use-web`.

```tsx
import { component, render } from 'sigx';
import { useColorScheme } from '@sigx/use-web';

const Scheme = component(() => {
    const scheme = useColorScheme();
    return () => <p>System prefers: {scheme.value}</p>;
});

render(<Scheme />, "#app");
```

The return is a [`ReadSignal<ColorScheme>`](/use/docs/conventions#outputs-single-value--readsignalt) where `ColorScheme` is `'light' | 'dark'` — `no-preference` maps to `'light'`:

```ts
import { effect } from 'sigx';

const scheme = useColorScheme();
effect(() => (document.documentElement.dataset.theme = scheme.value));
```

> `ReadSignal` preserves the literal union: `scheme.value` is typed `'light' | 'dark'`, not widened to `string`. That's the whole reason single-value returns are structural — see [Outputs](/use/docs/conventions#outputs-single-value--readsignalt).

## Signature

```ts
function useColorScheme(options?: UseColorSchemeOptions): ReadSignal<ColorScheme>;
```

`ColorScheme` is a [cross-platform contract](/use/docs/conventions#cross-platform-contracts) — the same return shape as Lynx's `useSystemColorScheme`, so theme code ports across platforms unchanged.

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `ssrDefault` | `ColorScheme` | `'light'` | Value reported on the server / where `matchMedia` is unavailable. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). See [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides). |

## SSR

On the server (no `matchMedia`) the signal reads `ssrDefault` — `'light'` by default — then reads the real preference on mount.

## See also

- [`useMediaQuery`](/use/docs/use-media-query) — the `prefers-color-scheme` query underneath, untyped.
- [`useStorage`](/use/docs/use-storage) — persist a user override of the system scheme.
- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — the `ColorScheme` shape shared with Lynx.

---
url: https://sigx.dev/use/docs/use-element-size/
title: useElementSize
description: "An element's content size as one reactive { width, height } object, driven by a ResizeObserver"
---

# useElementSize

An element's content size as **one** reactive `{ width, height }` object. Browser composable — import from `@sigx/use-web`.

It builds on [`useResizeObserver`](/use/docs/use-resize-observer), and returns a [`ReactiveView`](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — read `size.width` / `size.height` by property access, each tracked per key.

```ts
import { signal, computed } from 'sigx';
import { useElementSize } from '@sigx/use-web';

const el = signal<HTMLElement | null>(null);
// <div ref={el}> …

const size = useElementSize(el);
const isNarrow = computed(() => size.width < 480);
```

Pass any [element target](/use/docs/conventions#element-targets-web). An `initialSize` (default `{ width: 0, height: 0 }`) seeds the value before the first measurement, and options pass straight through to the underlying `ResizeObserver`.

To pull fields out without snapshotting them, use core's [`toSignals()`](/core/docs/signals):

```ts
import { toSignals } from 'sigx';
const { width, height } = toSignals(useElementSize(el)); // each a live signal
```

## Signature

```ts
function useElementSize(
    target: MaybeSignalElement,
    initialSize?: WindowSizeState,
    options?: UseResizeObserverOptions,
): ReactiveView<WindowSizeState>;

interface WindowSizeState { width: number; height: number; }
```

## SSR

Stays at `initialSize` (no observer runs on the server).

## See also

- [`useResizeObserver`](/use/docs/use-resize-observer) — the observer this wraps; use it when you need the raw entries.
- [`useWindowSize`](/use/docs/use-window-size) — the same `{ width, height }` shape for the viewport.
- [`useElementVisibility`](/use/docs/use-element-visibility) — the intersection counterpart.

---
url: https://sigx.dev/vite/docs/deploy-adapters/
title: Deploy adapters
description: The SigxAdapter build seam — ssr.adapter, platform entries, and the virtual:sigx-app build artifact
---

# Deploy adapters

<p class="lede">`ssr.adapter` is the plugin's deployment seam: a plain object that shapes how the server bundle is built — externalized for Node, fully bundled for the edge — and generates whatever your platform needs around it. The adapter packages for [Cloudflare, Vercel and Netlify](/deploy/packages/) ride this contract; so can yours.</p>

## The adapter option

```ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import { cloudflare } from '@sigx/cloudflare';

export default defineConfig({
    plugins: [
        sigx({
            ssr: {
                entry: 'src/entry-server.tsx',
                adapter: cloudflare(),
            },
        }),
    ],
});
```

The default — no `adapter` — is `nodeAdapter()`: today's externalized Node
output, byte-identical to pre-adapter builds. Only an explicit adapter changes
the build. Adapters cannot be combined with library mode.

## The SigxAdapter contract

An adapter is a **plain object**, not a second Vite plugin — the sigx plugin
stays the one authority over the ssr environment:

```ts
interface SigxAdapter {
    name: string;                              // 'node', 'cloudflare', …
    serverBuild: 'external' | 'bundled';
    conditions?: string[];                     // e.g. ['workerd', 'worker']
    runtimeExternal?: (string | RegExp)[];     // kept as runtime imports when bundled
    entry?: string;                            // platform entry; default: ssr.entry
    target?: string;                           // default 'esnext' for 'bundled'
    setup?(ctx: AdapterSetupContext): void | Promise<void>;
    generate?(ctx: AdapterGenerateContext): void | Promise<void>;
    dev?(server: ViteDevServer): void | Promise<void>;
}
```

- **`serverBuild`** is deliberately binary. `'external'` resolves dependencies
  from `node_modules` at runtime (Node and Bun hosts). `'bundled'` produces a
  fully self-contained server build — the ssr **environment**'s
  `resolve.noExternal: true` (the environments-API home of the classic
  `ssr.noExternal`), your platform `conditions` replacing the Node defaults,
  target `esnext`. The
  partially-external middle ground is unrepresentable on purpose: it is the
  dangerous zone for DI-token identity, while a total bundle lands the entry,
  strategy packs, handlers and registry in **one** module graph.
- **`runtimeExternal`** keeps platform builtins as runtime imports in a bundled
  build — `/^cloudflare:/`, `/^jsr:/`.
- **`setup`** runs before any environment builds and scaffolds build inputs —
  most importantly the platform entry — **iff absent**: written once when
  missing, never touched again. The file is user-owned from that moment.
- **`generate`** runs after both environments have written: copy statics, emit
  platform config, validate. This is where `.vercel/output` assembly lives.
- **`dev`** hooks the Vite dev server for platform-binding proxies (how
  `cloudflare({ devProxy: true })` boots wrangler's local bindings).

## The platform entry

Each adapter scaffolds `src/entry.<platform>.ts` on first build and never
overwrites it. Its composition order **is** your app's routing policy —

```
static assets → server functions → document render
```

— and every entry exports the portable `{ fetch }` shape around
[`createFetchHandler`](/server/packages/server-renderer/fetch-handler). No sigx
handler serves static files; the static tier is platform-native and sits in
front.

## virtual:sigx-app

A production fetch handler needs the document-side artifacts — with no
filesystem in the output. `virtual:sigx-app` inlines the client build's outputs
as literals (also materialized as `dist/server/sigx-app.js`, so a Node
`server.mjs` collapses four `readFile`s into one import):

```ts
import { template, assets, manifest, islandsManifest, resumeManifest }
    from 'virtual:sigx-app';
```

| Export | What it is |
|---|---|
| `template` | the built `index.html` with the outlet marker |
| `assets` | precomputed `collectAssets()` preloads for every client entry |
| `manifest` | the client `.vite/manifest.json` |
| `islandsManifest` | the islands pack manifest, or `undefined` |
| `resumeManifest` | the resume pack manifest, or `undefined` |

To resolve preloads yourself instead — per route, say — import `collectAssets`
from **`@sigx/vite/assets`**:

```ts
import { collectAssets } from '@sigx/vite/assets';
import { manifest } from 'virtual:sigx-app';

const resolvedAssets = collectAssets(manifest, ['src/entry-client.tsx']);
```

That entry imports nothing at all — no `node:` builtins, no `process` — so it
runs on workerd, Deno and Bun. Keep `@sigx/vite/ssr` for the dev half
(`createDevRequestHandler`), which is Node-only by nature; it re-exports
`collectAssets` as well, so an existing import keeps working.

`virtual:sigx-app` is a **build artifact**: importing it under `vite dev` throws, pointing you at
`createDevRequestHandler` (dev resolves template and assets live). The narrower
sibling `virtual:sigx-manifests` exports just the two pack manifests and resolves
in every mode — that's the one your `entry-server` app factory imports to
construct its packs without threading manifests through server wiring.

## Where to go next

- [Deploying SignalX](/deploy/docs/overview) — the platform matrix: Node,
  Cloudflare, Deno, Bun, Vercel, Netlify
- [The fetch handler](/server/packages/server-renderer/fetch-handler) — the
  WinterCG runtime the adapters wire up
- [Vite SSR mode](/vite/docs/ssr) — entries, the islands transform and the dev
  handler

---
url: https://sigx.dev/vite/docs/getting-started/
title: Getting Started
description: "@sigx/vite — Vite plugin with HMR for SignalX components"
---

# Getting Started with Vite

`@sigx/vite` is the official Vite plugin for SignalX. It wires SignalX into
Vite's dev server and production build so you get:

- **Component-level HMR** — edit a `component(...)` and see it update in place,
  with per-instance signal state preserved across reloads. In middleware-mode dev
  servers it also picks a free HMR websocket port automatically, so concurrent
  servers never collide on Vite's default `24678`.
- **Singleton reactivity** — the plugin guarantees a single physical copy of the
  SignalX runtime in both dev and build by excluding **all** `@sigx/*` packages
  from `optimizeDeps` and unifying them in the SSR graph (`ssr.noExternal`), so
  signal mutations always re-render after hydration.
- **Optimized production builds** — runtime packages are deduped and forced into
  a single chunk to keep that singleton guarantee.

The plugin is the heart of the package. A separate `@sigx/vite/lib` subpath
provides a helper for building `@sigx/*` libraries, and a `sigx-types` CLI
generates type definitions for tag-named components.

## Install

```bash
npm install -D @sigx/vite
```

`@sigx/vite` has two required peer dependencies: `vite` (>= 8.0.0) and `sigx`.
See [Installation](/vite/docs/installation) for peer deps, versions, and the
full config wiring.

## Minimal Setup

Add the plugin to your Vite config. The default export is the plugin factory:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [sigx()],
});
```

That single line enables HMR injection and the dev/build singleton handling. A
named import works identically:

```ts
import { sigxPlugin } from '@sigx/vite';

export default defineConfig({
    plugins: [sigxPlugin()],
});
```

## End-to-End Example

A typical app needs the plugin plus TypeScript JSX settings pointed at SignalX.

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [sigx()],
});
```

```json
// tsconfig.json
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "sigx"
    }
}
```

```tsx
// src/main.tsx
import { component, signal, defineApp } from 'sigx';

const Counter = component(() => {
    const count = signal(0);
    return () => (
        <button onClick={() => count.value++}>
            Count: {count.value}
        </button>
    );
});

defineApp(<Counter />).mount('#app');
```

Run `vite` and edit `Counter` — the button re-renders in place while its
`count` value survives the reload. Because the file contains a `component(`
usage in serve mode, the plugin automatically injects the HMR runtime; you do
not import anything HMR-related yourself.

## Next Steps

- [Installation](/vite/docs/installation) — peer deps, versions, and config wiring
- [HMR for Components](/vite/docs/hmr) — how component hot-reload works
- [Library Builds](/vite/docs/library-builds) — build `@sigx/*` packages with `defineLibConfig`
- [API Reference](/vite/docs/api) — every export and option

---
url: https://sigx.dev/actors/docs/design-notes/
title: Design notes & limits
description: What v1 deliberately does not do, the reserved names, and where the extension seams are
---

# Design notes & limits

<p class="lede">The things this version deliberately does not do, stated so you can plan around
them rather than discover them.</p>

## One host per process

Many processes via [`@sigx/actors/cluster`](/actors/docs/clustering). The `ActorDispatcher`
and `ActorPlacement` seams remain the extension point for other distributed backends —
[Cloudflare Durable Objects](/actors/docs/cloudflare-workers) map onto them naturally.

Every call already flows through those seams, and dev-mode `devSerializeChecks` verifies your
arguments would survive a remote hop, so single-node code does not quietly depend on being
single-node.

## Keys and the wire

**String keys.** `POST` by default, with `GET` for methods that declare
[`reads:`](/actors/docs/cacheable-reads). No form posts or 303 PRG yet.

**The default public wire is plain HTTP**, no push layer required: NDJSON covers
server→client both per call ([`streams:`](/actors/docs/streams)) and multiplexed per page
([live reads](/actors/docs/live-reads)). A socket is an *option*
([`@sigx/actors-ws`](/actors/packages/actors-ws/overview)), never a requirement — the wire has
to work over the one protocol every runtime and every proxy already agrees on.

The socket transport attaches to your server rather than contributing a route, and that is
structural: `ActorRoute.handle` returns a `Response`, which cannot express a Node WebSocket
upgrade — that needs the raw socket. On Workers a 101 *is* a `Response`, which is why
[`workerSocket()`](/actors/packages/actors-cloudflare/overview) can be an ordinary route
contribution there.

## Topic delivery is best-effort

[Topics](/actors/docs/topics) are at-most-once with **no persistence, no retry and no
replay**. A durable mode is an explicit non-goal for v1, with API room reserved on
`PublishOptions`.

Explicit runtime subscribe and unsubscribe is likewise deferred; `ctx.topics.*` stays free
for it.

## Reserved names

| Reserved | Where |
|---|---|
| actor types starting with `$` or `@` | refused by `defineActor` |
| actor types starting with `$sigx:` | runtime-internal |
| topic names starting with `$` or `@` | refused by `topic()` |
| method names `$sigx:reminder`, `$sigx:topic` | runtime deliveries |
| `$live#subscribe` | the live-read mount |
| `$watch:{Type}#{method}` | internal host-to-host watch forwarding |
| `$sigx:host#stats` | the cluster ops channel |

`$sigx:host#stats` is answered **before any definition lookup**, so an actor type named
`$sigx:host` would simply be uncallable across hosts.

The public endpoint refuses every `$sigx:`-prefixed method outright — those are the runtime's
own deliveries and arrive over the authenticated internal mount only.

## Transport encryption is out of scope

Host-to-host hops are authenticated per request with an HMAC signature derived from the shared
`secret`, bound to the call and freshness-windowed. **Encryption is deliberately not
provided** — run mTLS or a private network between hosts.

## The conformance suite is contributor-facing

`transportConformance` is real and is the definition of correct transport behaviour, but it is
**not in the published `exports` map**. It is reachable inside the actors workspace through a
tsconfig and vitest alias only. Promoting the subpath is a deliberate step for whenever a
transport ships outside that repo.

## What holds it all together

Under every layer, the storage etag CAS is the **integrity floor**. A briefly stale route
costs a rejected save and a fault-and-reload — never corrupted state. That is what lets
routing, placement and membership all be optimizations that are allowed to be wrong.

## Next steps

- [Entry points](/actors/docs/entry-points) — the package layout.
- [Clustering](/actors/docs/clustering) — the seams in practice.
- [The actor model](/actors/docs/actor-model) — the guarantees these limits protect.

---
url: https://sigx.dev/actors/docs/entry-points/
title: Entry points
description: The twelve subpath exports of @sigx/actors, what each contains and which runtimes each is safe on
---

# Entry points

<p class="lede">`@sigx/actors` is one package with twelve subpaths. The split is about what may
reach a browser and what may reach a Worker — not about tree-shaking.</p>

| Entry | Contents |
|---|---|
| `@sigx/actors` | `defineActor`, `defineWorker`, `actor`, `useActor`, `actorKey`, `topic`, errors, types — isomorphic, light |
| `@sigx/actors/host` | `defineActorApp`, `createHost`, `memoryStorage`, `metrics()`, `health()`, `ops()`, storage/placement/plugin seams — **server-only** |
| `@sigx/actors/server` | `handleActorRequest`, `matchesActorRequest`, `createActorResolver`, `createFetchHandler` — WinterCG-clean |
| `@sigx/actors/node` | `createAppHandler` (all mounts), `createActorHandler`, `attachSignalHandlers`, `fileStorage` |
| `@sigx/actors/client` | `__actorRef`, `configureActors`, `fetchTransport`, the `ActorTransport` and `ActorRouter` seams — the build-swap target |
| `@sigx/actors/app` | `actorsPlugin()`, `useActorState`, `useActorAction` — the sigx integration, and the only entry that imports `@sigx/runtime-core` |
| `@sigx/actors/job` | `defineJob` — durable long-running operations |
| `@sigx/actors/cluster` | `cluster()`, `clusterPlacement`, `clusterStats`, `handleHostRequest`, `memoryClusterHub`, provider seams — WinterCG-clean |
| `@sigx/actors/cluster/frames` | the shared frame codec, for host-transport authors |
| `@sigx/actors/socket-wire` | the client-facing socket protocol and codec, for adapter authors — WinterCG-clean |
| `@sigx/actors/vite` | `sigxActors()`, `extractActors` |
| `@sigx/actors/vite-client` | ambient types for `virtual:sigx-actors` (types only) |

## What the split protects

**`./client` rides every bundle that touches an actor.** Its size budget is 5 kB, and 2 kB for
`{ __actorRef, configureActors, fetchTransport }` alone. That is why
[live reads](/actors/docs/live-reads) are driven from `./app` over the transport's `stream()`
rather than shipping push logic here.

**`./cluster` is WinterCG-clean and zero-dependency**, so Cloudflare Workers keep working.
That constraint is why [`httpTransport()` must stay the default](/actors/docs/transports) — a
default needing `node:net` would break Workers outright.

**`./host` is server-only.** Importing it from a component is a mistake the build swap
normally prevents; if you have reached for it in shared code, you want `@sigx/actors` instead.

## Size budgets

| Entry | Budget |
|---|---|
| `@sigx/actors` | 4.4 kB (`{ actor }` alone ≤ 2 kB) |
| `./client` | 5 kB (≤ 2.3 kB with no router pulled in) |
| `./app` | 6.5 kB |
| `./job` | 3.1 kB |
| `./server` | 8 kB |
| `./cluster` | 14.2 kB |
| `./cluster/frames` | 4.1 kB |
| `./socket-wire` | 2.5 kB |

Enforced in CI by `size-limit`, with the tree-shaking guards as their own entries — so a
change that quietly drags the router into a bundle that never asked for one fails the build.

## Dual dev and production builds

Every non-Vite entry ships `development` and `production` conditions. The production build
strips dev-only warnings — slow-turn warnings, the class-instance `methods:` warning, the
dispatch-middleware `dispatchStream` warning — which is why a bundler that does not define
`__DEV__` throws on first request. See
[Cloudflare Workers](/actors/docs/cloudflare-workers).

## Peer dependencies

`@sigx/reactivity`, `@sigx/serialize` and [`@sigx/server`](/server/packages/server/overview)
are required; `@sigx/runtime-core`, `@sigx/vite` and `vite` are optional. There are **no
runtime dependencies**.

Core 0.14 or later. Every satellite package peer-depends on `@sigx/actors` itself.

## Next steps

- [Design notes](/actors/docs/design-notes) — the deliberate limits.
- [Installation](/actors/docs/installation) — which entries a normal app touches.
- [The packages](/actors/packages) — the nine optional satellites.

---
url: https://sigx.dev/actors/docs/installation/
title: Installation
description: Install @sigx/actors, add the Vite plugin, and write the app module that dev and production both load
---

# Installation

<p class="lede">One package, one Vite plugin, one app module. The plugin runs a dev host for
you and mounts the endpoint; the app module is the single config that every runtime loads.</p>

## Install

```bash
pnpm add @sigx/actors
```

That is the whole runtime. Backends, transports and tooling are
[separate packages](/actors/packages) you add only when you need them.

`@sigx/actors` declares **no runtime dependencies of its own** — only peers:

| Peer | Range | |
|---|---|---|
| `@sigx/reactivity` | `^0.15.3` | required |
| `@sigx/serialize` | `^0.15.0` | required |
| [`@sigx/server`](/server/packages/server/overview) | `^0.15.0` | required |
| `@sigx/runtime-core` | `^0.15.0` | optional — the `./app` integration |
| `@sigx/vite` | `^0.15.0` | optional — the build plugin |
| `vite` | `>=6` | optional — the build plugin |

**`@sigx/reactivity` has a higher floor than the rest**: `^0.15.3`, meaning 0.15.3 or newer
*within* 0.15 — not 0.16. The host's change tracking imports `deepTrack` from
`@sigx/reactivity/internals`, which landed in that release, and a missing named export is a
hard resolution failure rather than a graceful degradation.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Raising a floor does not re-resolve a dependency that is already satisfied.</strong>
    A package depending on <code>@sigx/reactivity ^0.15.0</code> can sit on 0.15.2 alongside
    actors on 0.15.3, and two copies split core's module-local singletons. The symptom is
    <code>signal is not a function</code> — not a version warning.
    <code>pnpm dedupe</code> fixes it.
  </div>
</div>

## Add the Vite plugin

```ts
// vite.config.ts
import { sigxActors } from '@sigx/actors/vite';

export default {
    plugins: [sigxActors({ app: '/src/actors.app.ts' })],
};
```

Actors live in **`*.actor.ts`** modules. The build swaps them wholesale for typed client
stubs, so implementations never reach the browser — values are swapped, types are not, which
is why the client proxy stays fully typed with no duplicate interface to maintain.

`sigxActors({ app })` points dev at the same app module your production entry imports, so
storage, placement, codec handlers, defaults and every plugin are identical in both. Before
this existed, dev could not receive any of them.

Add the virtual module's types once, next to your other Vite types:

```ts
// src/env.d.ts
/// <reference types="@sigx/actors/vite-client" />
```

## Write the app module

```ts
// src/actors.app.ts — no `actors`, no virtual import
import { defineActorApp } from '@sigx/actors/host';
import { fileStorage } from '@sigx/actors/node';

export const app = defineActorApp({
    storage: fileStorage({ dir: '.actors' }),
    defaults: { idleAfterMs: 60_000 },
});

/** Bound to this app's plugin set — import it from your actor modules. */
export const { defineActor } = app;
```

Two things about this file are deliberate:

**It leaves out its registry.** Because it imports nothing Vite-specific, it loads under any
runtime — which is what lets a plain-Node entry share it, and what makes it safe for your
actor modules to import the bound `defineActor` from it. Under Vite the plugin supplies the
registry it already builds; anywhere else you name the actors yourself:

```ts
// server.mjs — the SAME app module
const host = await app.withActors([Counter]).start();
```

`withActors` throws if the app already declared `actors`, so a host can never silently replace
what the author configured.

**You export `defineActor` from it, not from the package.** That is what carries your plugins'
context extensions into `ctx` with types attached. See [The app](/actors/docs/the-app).

> **Watch out under Vite:** if your storage `dir` sits inside the project root, add it to
> `server.watch.ignored`. Saves are temp-file-then-rename, and the HMR file watcher races
> them — you get an `ENOENT … .tmp` error overlay. Actor state is not source; it should
> reload nothing.
>
> ```ts
> server: { watch: { ignored: ['**/.actors/**'] } }
> ```

## Authorization is required by default

An actor endpoint **is** a server function, so it inherits core's fail-closed pipeline: an actor
that says nothing about access, with no server app configured, denies every call.

The usual answer is one line — point the plugin at your
[server app](/server/packages/server/usage#the-app) and its default policy covers every actor:

```js
sigxActors({ app: '/src/actors/app.ts', serverApp: '/src/server-app.ts' })
```

Otherwise an actor declares its own policy, or opts out explicitly:

```ts
defineActor({ type: 'Counter', allowAnonymous: true, /* … */ });
```

The Vite plugin enforces the choice at build time (`requireAuthorization: true` by default,
`'warn'` to soften it). It cannot see inside `node_modules`, so
[actors shipped in a package](/actors/docs/shipping-actors-in-packages) are the author's
responsibility. See [Authorization](/actors/docs/guards).

## Verify

```bash
pnpm dev
```

The plugin starts a dev host and mounts the endpoint at `/_sigx/actor`. Add an actor, call it
from a component, and edit the actor file — HMR keeps working, because the plugin's loaders go
through the module runner.

## Next steps

- [Your first actor](/actors/docs/your-first-actor) — a counter, end to end.
- [The app](/actors/docs/the-app) — plugins, context extensions and lifecycle.
- [Running a host on Node](/actors/docs/node) — the production entry.

---
url: https://sigx.dev/actors/docs/ops-endpoint/
title: The ops endpoint
description: ops() — the authenticated view inside a running host, the reportOps seam, and why the secret is mandatory
---

# The ops endpoint

<p class="lede">`health()` answers *may I take traffic?* in a status code. `ops()` answers
*what is going on in here?* in a body — which is why it is authenticated and that one is
not.</p>

```ts
import { ops } from '@sigx/actors/host';
import { clusterStats } from '@sigx/actors/cluster';

export const app = defineActorApp({ actors, storage })
    .use(metrics())
    .use(health())
    .use(ops({
        secret: process.env.SIGX_OPS_SECRET,
        cluster: (signal) => clusterStats(placement, { signal }),
    }));
```

| Route | Returns |
|---|---|
| `GET /_sigx/ops` | `OpsSnapshot` — `{ v, at, uptimeMs, stats, health, ops }` |
| `GET /_sigx/ops/cluster` | a [`clusterStats()`](/actors/docs/cluster-stats) fan-out; 404 when unwired |

## The secret is mandatory

`ops()` throws at construction without one outside `__DEV__`.

> An ops endpoint that is unauthenticated by omission publishes your deployment, and nothing
> in the response says so. Actor type names, cluster topology and — if you ask for them —
> actor keys.

`SIGX_OPS_SECRET` is the conventional way to supply it, and it is what the
[CLI](/actors/packages/actors-cli/overview) reads.

## Why the cluster fan-out is a thunk

`ops()` lives in `@sigx/actors/host` and `clusterStats` in `@sigx/actors/cluster`. Passing the
call as a thunk keeps the cluster bundle out of a single-node host that will never use it:

```ts
ops({ secret, cluster: (signal) => clusterStats(placement, { signal }) });
```

`ops({ cluster })` also takes an optional second argument — the parsed query — so
`GET /_sigx/ops/cluster?detail=1&activations=20&host=<id>` reaches through. The one-argument
form still works.

## Contributing a section

```ts
registry.reportOps('queue', () => ({ depth: queue.length, oldestMs: queue.oldestAge() }));
registry.ops();   // the aggregate
```

Providers run **per read** and must stay **synchronous**. Names must be unique. A throwing
provider costs only its own section, which comes back as `{ error }` — one broken provider
never takes down the endpoint.

`reportDigest(name, (options?) => …)` is the mergeable sibling, used by
[cluster stats](/actors/docs/cluster-stats) to fold metrics across hosts.

## Actor keys are off by default

The activation list is not in the default response, and requested limits are clamped by the
responder rather than trusted from the query.

> Actor keys can be personal data — a user id, an email, an order number. Turning the list on
> is a deliberate act, over an authenticated channel, and it is worth knowing what your keys
> contain before you do.

## Next steps

- [Cluster stats](/actors/docs/cluster-stats) — the fleet-wide view.
- [The CLI](/actors/packages/actors-cli/overview) — a terminal dashboard over this endpoint.
- [Observability](/actors/docs/observability) — Prometheus alongside it.

---
url: https://sigx.dev/core/docs/dom-properties/
title: DOM Properties
description: Control how props are applied to DOM elements — attributes vs properties and the prop prefix
---

# DOM Properties

When you pass props to intrinsic HTML/SVG elements in JSX, SignalX decides whether to set each prop as an **HTML attribute** (`setAttribute`) or as a **DOM property** (direct assignment on the element object). Understanding this distinction matters when you need precise control over how values reach the DOM.

## How SignalX resolves props

Props are resolved in priority order:

| Priority | Condition | Method |
|----------|-----------|--------|
| 1 | `style` | Object → `el.style[prop]`, string → `el.style.cssText` |
| 2 | `on*` events | `addEventListener` / `removeEventListener` |
| 3 | `className` | `setAttribute('class', ...)` |
| 4 | **`prop:` prefix** | **Direct DOM property** — strips prefix, sets `el[prop] = value` |
| 5 | SVG element | `setAttribute` (case-preserving), except `innerHTML`/`textContent` |
| 6 | `value`/`checked` on form elements | DOM property (direct assignment) |
| 7 | Key exists on element (`key in el`) | DOM property (with `setAttribute` fallback) |
| 8 | Custom element (tag contains `-`) | DOM property |
| 9 | Fallback | `setAttribute` / `removeAttribute` |

For most HTML props, step 7 handles things automatically — if the browser's DOM interface defines the property (e.g. `hidden`, `tabIndex`, `title`), SignalX sets it as a property. Unknown keys fall through to `setAttribute`.

## The `prop:` prefix

To **force** any value to be set as a DOM property, prefix the prop name with `prop:`:

```tsx
// Direct property assignment: element.innerHTML = html
<div prop:innerHTML={renderMarkdownToHtml(content)} />

// Force .value on any element, bypassing the attribute path
<input prop:value={rawValue} />

// Works for any DOM property
<div prop:textContent="plain text" />
<div prop:innerText="formatted text" />
```

At runtime, the `prop:` prefix is stripped and the value is assigned directly:

```ts
// <div prop:innerHTML={html} />
// becomes:
element.innerHTML = html;
```

### When to use `prop:`

| Scenario | Use `prop:`? | Why |
|----------|-------------|-----|
| Setting `innerHTML` with HTML strings | **Yes** | Makes intent explicit — you're setting a DOM property, not an attribute |
| Setting `value` on `<input>` | Optional | Form element `value`/`checked` are already handled as properties (step 6) |
| Setting a property not in the DOM interface | **Yes** | Unknown keys would fall through to `setAttribute` otherwise |
| Standard HTML attributes (`class`, `id`, `href`) | No | These work correctly through the normal attribute path |

### TypeScript support

The `prop:` prefix is typed via an index signature on `HTMLAttributes`:

```ts
[key: `prop:${string}`]: any;
```

This means any `prop:`-prefixed prop is accepted on any element without TypeScript errors. The value type is `any` because DOM property types vary per element and property.

## SVG elements

SVG attributes are **always** set via `setAttribute` to preserve case sensitivity (e.g. `viewBox`, `preserveAspectRatio`). The exceptions are `innerHTML` and `textContent`, which are set as properties even on SVG elements when accessed without a prefix.

To force a property on an SVG element, use the `prop:` prefix:

```tsx
<svg prop:innerHTML='<circle cx="50" cy="50" r="40" />' />
```

## Null and undefined handling

- **DOM property path** (`key in el`): `null`/`undefined` → removes the attribute via `removeAttribute`
- **setAttribute path**: `false`/`null`/`undefined` → removes the attribute
- **`prop:` prefix**: value is assigned directly (including `null`/`undefined`)

```tsx
// Removes the title attribute from the DOM
<div title={null} />

// Sets element.textContent = null (becomes empty string)
<div prop:textContent={null} />
```

---
url: https://sigx.dev/core/docs/error-handling/
title: Error Handling
description: Scope render and setup errors with errorScope, and catch everything else with app.onError — the value-first error model
---

# Error Handling

SignalX routes errors by **where they come from**, and it never uses a wrapper component or a magic thrown value:

| Source | Goes to |
|---|---|
| A `useData` / `useAction` fetcher rejects | the cell's `.error` — rendered through `match()` (value-first) |
| A component's setup or render throws (including a descendant's, and reactive re-renders) | the nearest **`errorScope`**, then `app.onError` |
| A DOM event-handler throws | **`app.onError`** |
| A `match()` `error` arm is omitted for an errored cell | bubbles to the nearest `errorScope`, then `app.onError` |

Fetch failures are values — you handle them inline with the `error` arm (see [Data loading](/core/docs/data-loading)). This page covers the other two: `errorScope` for a subtree, `app.onError` for the app.

## errorScope

`errorScope` is a setup-time error boundary for the **calling component's own subtree**. It is not a wrapper component — call it inside setup and the component's subtree is scoped:

```tsx
import { component, errorScope } from 'sigx';

const Widget = component(() => {
    errorScope({
        fallback: (error, retry) => (
            <div class="error">
                <p>{error.message}</p>
                <button onClick={retry}>Try again</button>
            </div>
        ),
    });

    return () => <RiskyTree />;
});
```

It catches: the component's own render throwing, and any descendant's setup / render / reactive re-render throwing. It also receives unhandled data errors bubbled by `match()` (a cell that errored with no `error` arm). It does **not** catch fetcher rejections (those are values on `.error`) or DOM event-handler throws (those go to `app.onError`).

`retry` is a **real teardown**, not a flag flip: the subtree renders under a keyed Fragment whose key bumps on retry, forcing a full unmount (every descendant effect stopped, `onUnmounted` run) and a fresh mount — so a retry re-runs setup and re-fetches from a clean slate.

### Options

| Option | Type | Notes |
|---|---|---|
| `fallback` | `(error, retry) => JSXElement` | Rendered in place of the subtree while errored. Omitted ⇒ renders nothing (the scope still stops propagation). |
| `onError` | `(error, instance, info) => void` | Observer called before the fallback renders — log or report. Its own throws are swallowed. |

```tsx
errorScope({
    fallback: (e, retry) => <Oops error={e} retry={retry} />,
    onError: (e, instance, info) => telemetry.report(e, { component: instance?.name, info }),
});
```

## app.onError

`app.onError` is the app-wide catch-all — the last stop for everything no `errorScope` took, plus DOM event-handler throws and unhandled data errors. Register it on the app instance:

```tsx
import { defineApp } from 'sigx';

const app = defineApp(App)
    .onError((err, instance, info) => {
        telemetry.report(err, { component: instance?.name, info });
        return true; // suppress default logging; omit / return falsy to let it propagate
    });

app.mount('#app');
```

The handler receives the `error`, the `instance` it originated from (may be `null`), and an `info` string describing the phase. Return `true` to mark the error handled and stop it propagating (e.g. to the console); return nothing to let default handling continue.

Reach for `errorScope` to keep part of the UI alive with a local fallback, and `app.onError` as the safety net for reporting and for errors with no natural place to render.

## Error codes

Errors the runtime itself throws — a missing mount target, a required injectable that was never provided — carry a `SIGX###` code. Production builds print the code with a link to its page, since the full message is stripped from the production bundle:

```
SIGX202 "Router" — see https://sigx.dev/errors/SIGX202/
```

The [error codes reference](/errors) lists every code with its cause and fix, and `SigxError` lets you branch on `code` in a `try`/`catch`.

## Next Steps

- [Error codes](/errors) - Every `SIGX###` the runtime throws, with fixes
- [Data loading](/core/docs/data-loading) - `useData`, `useAction`, `all`
- [App & Plugins](/core/docs/app-plugins) - Configure and extend the app
- [Lifecycle](/core/docs/lifecycle) - Mount, update and cleanup hooks

---
url: https://sigx.dev/cli/docs/getting-started/
title: Getting Started
description: "@sigx/cli — project scaffolding, plugin discovery and platform commands"
---

# Getting Started with the CLI

`@sigx/cli` is the command-line tool for SignalX projects. It does three things:

- **Scaffolds new projects** with `sigx create` — interactive prompts (or headless flags) that copy a bundled template into a new directory.
- **Reports environment & project info** with `sigx info`, including the Lynx native toolchain when a Lynx config is detected.
- **Discovers plugins at runtime** so packages like `@sigx/vite`, `@sigx/ssg`, and `@sigx/lynx-cli` can contribute commands such as `dev`, `build`, `preview`, and the platform commands.

The CLI ships a single binary, `sigx`, and is ESM-only.

## Quick start

The fastest way to a new project is `sigx create`. You can run it without installing anything:

```bash
npx sigx create
```

This walks you through interactive prompts — a name, a project type, and a styling option — then writes the project into `./<name>`. To skip the prompts and scaffold headlessly, pass flags:

```bash
npx sigx create my-app --type ssr --styling tailwind
```

## Installing into a project

Generated projects depend on `@sigx/cli` directly, so most commands are available via `npx sigx <command>`. To add it to an existing project:

```bash
npm i -D @sigx/cli
```

Then run any command through your package runner:

```bash
npx sigx info
```

See [Installation](/cli/docs/installation) for peer-dependency details and which plugin packages enable which commands.

## A minimal end-to-end example

Scaffold a basic web app, install dependencies, and start it:

```bash
npx sigx create my-app --type basic
cd my-app
npm install
npm run dev
```

The `basic` web template uses Vite scripts directly (`vite`, `vite build`, `vite preview`). The other templates wire npm scripts differently:

- **`ssg`** maps `dev`, `build`, and `preview` to `sigx dev` / `sigx build` / `sigx preview`.
- **`lynx`** maps `dev` and `build` to `sigx dev` / `sigx build` (plus `sigx doctor` and `sigx prebuild`), but has no `preview` script.
- **`ssr`** does not use `sigx` scripts at all: it runs a custom Express server via `node server.js` for `dev`, `start`, and `preview`, and builds with `vite build`.

Where a template uses `sigx` commands, those resolve to commands contributed by the corresponding plugin packages.

## Where to go next

- [Installation](/cli/docs/installation) — install, peer dependencies, and the plugin packages behind each command.
- [Commands](/cli/docs/commands) — every command with its usage and flags.
- [Authoring Plugins](/cli/docs/plugins) — extend the CLI with your own commands.
- [API Reference](/cli/docs/api) — `definePlugin`, `runCreate`, and the plugin type contract.

---
url: https://sigx.dev/lynx/docs/project-layout/
title: Project layout
description: How a SignalX Lynx project is organized
---

# Project layout

<p class="lede">What the scaffold gives you and where things live.</p>

## Structure

```
hello-lynx/
├── src/
│   ├── App.tsx          # root component
│   └── screens/         # one file per screen
├── lynx.config.ts       # build plugin config (BG/MT bundles)
├── ios/                 # generated by `sigx prebuild`
└── android/             # generated by `sigx prebuild`
```

## The two bundles

The build plugin compiles your source twice: a **background** bundle (your components and signals) and a **main-thread** bundle (worklets, animation drivers). You rarely think about this — `@sigx/lynx-plugin` handles the split and the worklet transform.

## Native projects

`ios/` and `android/` are generated — treat them as build output. Re-run `sigx prebuild` after adding native modules; the autolinker wires them up.

---
url: https://sigx.dev/lynx/docs/your-first-app/
title: Your first app
description: Scaffold, run and make your first SignalX Lynx app reactive
---

# Your first app

<p class="lede">Scaffold a Lynx project, run it on a simulator and make it reactive — in about five minutes.</p>

## Prerequisites

You'll need the toolchain from [Installation](/lynx/docs/installation) — run `sigx doctor` if you're not sure.

## Scaffold the app

### Using the CLI

```bash
npm create @sigx@latest hello-lynx -- --template lynx
cd hello-lynx && pnpm install
```

### Run on a simulator

```bash
sigx dev
sigx run:ios        # or run:android
```

The dev client connects to the dev server — edits hot-reload straight into the simulator.

## Your first component

```tsx
import { component } from 'sigx';
import { View, Text } from '@sigx/lynx';

export const Hello = component(() => {
    return () => (
        <View style={{ padding: 24 }}>
            <Text style={{ fontSize: 24, fontWeight: '600' }}>Hello, Lynx!</Text>
        </View>
    );
});
```

The same `component()` you use on the web — only the elements differ: `View`, `Text`, `Image` and friends render to real native views.

## Adding reactivity

```tsx
import { component } from 'sigx';
import { View, Text, Pressable } from '@sigx/lynx';

export const Counter = component(({ signal }) => {
    const state = signal({ count: 0 });
    return () => (
        <View style={{ padding: 24, gap: 12 }}>
            <Text style={{ fontSize: 32 }}>{state.count}</Text>
            <Pressable onPress={() => state.count++}>
                <Text>Tap me</Text>
            </Pressable>
        </View>
    );
});
```

When `state.count` changes, only the `Text` node that reads it updates — the op streams to the main thread and patches one native view.

## Next steps

- Learn the [native elements](/lynx/docs/elements) and [styling model](/lynx/docs/styling)
- Add screens with [Navigation](/lynx/modules/navigation/overview)
- Browse the [module catalog](/lynx/modules)

---
url: https://sigx.dev/ssg/docs/getting-started/
title: Getting Started
description: "@sigx/ssg — static site generation with MDX and island hydration"
---

# Getting Started with SSG

`@sigx/ssg` is the static site generator for SignalX. It turns a folder of pages into a fast, pre-rendered site:

- **File-based routing** — files in `src/pages` become routes (`index.tsx` to `/`, `blog/[slug].tsx` to `/blog/:slug`, and so on).
- **MDX and Markdown** — author content with frontmatter, Shiki syntax highlighting, GFM, and automatic heading slugs.
- **Collections and navigation** — group content under a path prefix and get a sidebar generated from your frontmatter.
- **Layouts and themes** — wrap pages in shared shells, or pull a full theme from a package (such as [`@sigx/ssg-theme-daisyui`](/ssg/docs/themes)).
- **Island hydration** — ship static HTML and hydrate only what needs to be interactive.
- **Build, dev, and preview** — a zero-config dev server, a static production build, sitemap and robots.txt generation.
- **Built for content sites** — built-in search, an npm/pnpm/yarn/bun code-fence switcher, copy-code buttons, redirects, link checking, and SPA navigation all ship in the box.

The current package version is .

## Install

```bash
npm install @sigx/ssg sigx @sigx/router
npm install -D vite @sigx/vite
```

Vite 8 or newer is required. See [Installation](/ssg/docs/installation) for peer dependencies, the two ways to wire it up, and zero-config entry detection.

## A minimal end-to-end example

### 1. Create `ssg.config.ts`

`defineSSGConfig` is a type-safe helper that applies sensible defaults and merges your config. Export the result as the default from `ssg.config.ts` in your project root.

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    site: {
        title: 'My Site',
        description: 'Built with @sigx/ssg',
        url: 'https://example.com',
    },
});
```

### 2. Add a page

Files under `src/pages` are routed automatically. `src/pages/index.tsx` becomes `/`.

```tsx
import { component } from 'sigx';

export default component(() => {
    return () => (
        <main>
            <h1>Hello from @sigx/ssg</h1>
            <p>This page was pre-rendered to static HTML.</p>
        </main>
    );
});

export const meta = {
    title: 'Home',
    description: 'Welcome to my site',
};
```

You can also author pages in MDX. `src/pages/about.mdx` becomes `/about`:

```mdx
---
title: About
description: About this site
---

# About

Markdown content with **GFM**, frontmatter, and Shiki highlighting.
```

### 3. Run dev, then build

If you have the CLI plugin available, drive everything through `sigx`:

```bash
npx sigx ssg dev
npx sigx ssg build
npx sigx ssg preview
```

The dev server defaults to port 5173, preview to 4173. The build renders every route to `dist/<path>/index.html` and writes `sitemap.xml` and `robots.txt`.

## Where to go next

- [Installation](/ssg/docs/installation) — install command, peer deps, and the required config / Vite wiring.
- [Configuration & Content](/ssg/docs/configuration) — routing, layouts, collections, MDX, and the full config surface.
- [Client Runtime](/ssg/docs/client-runtime) — search, the package-manager switcher, copy-code, and SPA navigation.
- [Themes](/ssg/docs/themes) — authoring and consuming themes, and the prebuilt daisyUI theme.
- [Commands](/ssg/docs/commands) — every `sigx ssg` command with usage and flags.
- [API Reference](/ssg/docs/api) — every public export with its signature.

---
url: https://sigx.dev/terminal/docs/components/
title: Components
description: Every @sigx/terminal-ui component, grouped by category
---

# Components

The themed component library (`@sigx/terminal-ui`, re-exported from `@sigx/terminal`) covers the building blocks of a TUI, grouped by role. Every component is token-themed — colors resolve against the active theme (see [Theming](/terminal/docs/theming)) — and the interactive ones plug into the [focus and layered key dispatch](/terminal/docs/input-and-components) model.

Import any component from the umbrella:

```tsx
import { Input, Select, Spinner, Table, Gradient } from '@sigx/terminal';
```

> Terminal components render to ANSI lines in a real terminal, so the examples on these pages are shown as code rather than live in-browser previews. Run them with a TSX-capable runner or under [dev mode](/terminal/packages/terminal-dev/overview/).

## Forms

Focusable input widgets with two-way `model` binding.

- [Input](/terminal/docs/components/input) — single-line text field.
- [TextArea](/terminal/docs/components/textarea) — growing multi-line editor.
- [Checkbox](/terminal/docs/components/checkbox) — boolean toggle.
- [Confirm](/terminal/docs/components/confirm) — inline yes/no.
- [Select](/terminal/docs/components/select) — single-choice menu.
- [Radio](/terminal/docs/components/radio) — always-visible single-choice group.
- [MultiSelect](/terminal/docs/components/multiselect) — checkbox list with grouping.

## Feedback

Status and progress indicators.

- [ProgressBar](/terminal/docs/components/progressbar) — determinate progress, with gradient variants.
- [Spinner](/terminal/docs/components/spinner) — animated activity indicator.
- [Badge](/terminal/docs/components/badge) — a small labelled tag.

## Navigation

Switchers, footers and popups.

- [Tabs](/terminal/docs/components/tabs) — horizontal tab switcher.
- [StatusBar](/terminal/docs/components/statusbar) — keyed status chips.
- [KeyHints](/terminal/docs/components/keyhints) — a key-shortcut footer.
- [SuggestionList](/terminal/docs/components/suggestionlist) — an intellisense-style popup.

## Layout

Structural containers (the neutral primitives `Box`, `Row`, `Col`, `Spacer`, `Divider` are covered in [Layout & Styling](/terminal/docs/layout-and-styling)).

- [Card](/terminal/docs/components/card) — a titled panel.
- [Shell](/terminal/docs/components/shell) — a dashboard frame that hands its body the content box it has to fill.

## Data

Structured data display.

- [Table](/terminal/docs/components/table) — columns and rows of text.
- [DataTable](/terminal/docs/components/datatable) — a table with a cursor, a viewport and a sort.
- [Sparkline](/terminal/docs/components/sparkline) — a time series in one line.
- [BarChart](/terminal/docs/components/barchart) — labelled bars on one shared scale.
- [Meter](/terminal/docs/components/meter) — a bare gauge for a single ratio.
- [Trend](/terminal/docs/components/trend) — a value and its direction of travel.
- [DetailList](/terminal/docs/components/detaillist) — aligned label/value pairs.
- [StatusGrid](/terminal/docs/components/statusgrid) — a dense grid of status cells.
- [QRCode](/terminal/docs/components/qrcode) — a scannable QR block.

## Effects

Decorative text rendering.

- [Gradient](/terminal/docs/components/gradient) — multi-stop colored text.
- [Shimmer](/terminal/docs/components/shimmer) — an animated highlight sweep.
- [Banner](/terminal/docs/components/banner) — large block-font headings.
- [PixelArt](/terminal/docs/components/pixelart) — palette-mapped pixel grids.

## Tasks

Logs and pipeline status.

- [TaskList](/terminal/docs/components/tasklist) — a build-pipeline status list.
- [LogView](/terminal/docs/components/logview) — a scrollable log viewport.
- [LogPanel](/terminal/docs/components/logpanel) — a bounded log tail.

---
url: https://sigx.dev/monaco/docs/installation/
title: Installation
description: Install @sigx/monaco-editor, peer deps, and the required Vite wiring
---

# Installation

## Install

```bash
pnpm add @sigx/monaco-editor monaco-editor
```

## Peer dependencies

| Package | Version | Required |
| --- | --- | --- |
| `monaco-editor` | `>=0.50.0` | Optional in the package metadata, but install it — the loader fetches Monaco at runtime |
| `sigx` | `>=0.4.0` | Required |
| `vite` | `>=5.0.0` | Optional (needed to use the Vite plugin) |

If you use the Shiki subpath (`@sigx/monaco-editor/shiki`), also install its optional peers:

```bash
pnpm add @shikijs/monaco shiki
```

## Vite wiring (required)

The Vite plugin is mandatory for normal usage. It intercepts every `monaco-editor` import and replaces it with a stub that throws at runtime, then excludes `monaco-editor` from `optimizeDeps` so the bundler never touches Monaco. As a result you must load Monaco through `loadMonaco()` (or the `<MonacoEditor />` component / `createEditor()`, which call it for you). Importing `'monaco-editor'` directly in client code will throw.

Add `monacoPrebundledPlugin()` to your Vite config. For SignalX apps, also include the SignalX Vite plugin and set the JSX import source to `sigx`:

```tsx
// vite.config.ts
import { defineConfig } from 'vite';
import { sigxPlugin } from '@sigx/vite';
import { monacoPrebundledPlugin } from '@sigx/monaco-editor/vite';

export default defineConfig({
    plugins: [
        sigxPlugin(),
        monacoPrebundledPlugin({ strategy: 'prebundled', publicPath: '/monaco-bundle' }),
    ],
    oxc: { jsx: { runtime: 'automatic', importSource: 'sigx' } },
});
```

The plugin runs with `enforce: 'pre'` and also injects a `window.__MONACO_LOADER_CONFIG__` snippet into your `index.html` head so the runtime loader picks up the same strategy and paths without a separate `define` step.

## Choosing an asset strategy

The plugin (and loader) support two strategies, selected via the `strategy` option:

### `prebundled` (default)

Monaco's runtime, CSS, and workers are committed to the package under `public/monaco-bundle/` (built with esbuild from `scripts/bundle-monaco.ts`). In dev, the plugin serves them through a middleware (with a path-traversal guard and immutable cache headers); in a production build it emits the bundle files (read from `manifest.json`) into your output. At runtime the loader loads `<basePath>/monaco.min.js` via a `<script>` tag (reading `window.monaco`) and injects `monaco.min.css` via a `<link>`. Vite never bundles Monaco, giving a fast cold start.

```tsx
monacoPrebundledPlugin({ strategy: 'prebundled', publicPath: '/monaco-bundle' });
```

The bundle is committed for Monaco `v0.55.1` and ships: `monaco.min.js`, `monaco.min.css`, `editor.worker.min.js`, `ts.worker.min.js`, `css.worker.min.js`, `html.worker.min.js`, `json.worker.min.js`, plus `codicon.ttf` and source maps.

### `cdn`

Monaco is loaded from a CDN (unpkg by default) at a pinned version using Monaco's AMD loader. Nothing Monaco-related ships in your build; the plugin marks `monaco-editor` as a Rollup external.

```tsx
monacoPrebundledPlugin({ strategy: 'cdn', version: '0.55.1' });
```

You can override the CDN host with the `cdnUrl` option. The `version` option defaults to `'0.55.1'` and is only used in `cdn` mode.

## Regenerating the prebundled assets

The prebundled assets are committed to the package. If you upgrade Monaco, regenerate them inside the package with the internal `bundle:monaco` npm script (it runs `scripts/bundle-monaco.ts` via `tsx`; there is no installed CLI binary):

```bash
pnpm bundle:monaco
```

To limit the worker set, pass `--workers` with a comma list (`editor.worker` is always included). Worker aliases: `ts`/`typescript`, `js`/`javascript`, `css`/`scss`/`less`, `html`/`handlebars`/`razor`, `json`:

```bash
pnpm bundle:monaco --workers ts,json
```

Configuration may also live in a `monaco.bundle.config.json` next to the package `package.json`.

## Next steps

- [Language packs and IntelliSense](/monaco/docs/language-packs)
- [Imperative editors and Shiki highlighting](/monaco/docs/imperative-and-shiki)
- [API Reference](/monaco/docs/api)

---
url: https://sigx.dev/use/docs/use-breakpoints/
title: useBreakpoints
description: "Reactive breakpoint queries over a { name: width } map — greater/smaller/between and the active breakpoint"
---

# useBreakpoints

Reactive breakpoint queries over a `{ name: width }` map — `greater`, `smaller`, `between`, and the currently `active` breakpoint. Browser composable — import from `@sigx/use-web`.

```tsx
import { component, render } from 'sigx';
import { useBreakpoints, breakpointsTailwind } from '@sigx/use-web';

const Layout = component(() => {
    const bp = useBreakpoints(breakpointsTailwind);
    const isMobile = bp.smaller('md');
    return () => (
        <p>{isMobile.value ? '📱 mobile' : '🖥️ desktop'} — active: {bp.active().value || 'xs'}</p>
    );
});

render(<Layout />, "#app");
```

Each query method returns its own [`ReadSignal<boolean>`](/use/docs/conventions#outputs-single-value--readsignalt) (or `ReadSignal<K | ''>` for `active`). One `matchMedia` subscription is created lazily per distinct comparison and memoized, so calling the same query twice is free.

## Signature

```ts
function useBreakpoints<K extends string>(
    breakpoints: Record<K, number | string>,
    options?: ConfigurableWindow,
): UseBreakpointsReturn<K>;
```

A breakpoint value is a **number** (px) or **any CSS length string**. Pass `{ window }` to drive it from another document — see [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides).

## Returns

| Method | Returns | Description |
|---|---|---|
| `greater(k)` | `ReadSignal<boolean>` | Viewport strictly wider than breakpoint `k`. |
| `greaterOrEqual(k)` | `ReadSignal<boolean>` | Viewport at least as wide as `k` (`min-width`). |
| `smaller(k)` | `ReadSignal<boolean>` | Viewport strictly narrower than `k`. |
| `smallerOrEqual(k)` | `ReadSignal<boolean>` | Viewport at most as wide as `k` (`max-width`). |
| `between(a, b)` | `ReadSignal<boolean>` | Viewport within `[a, b)`. |
| `active()` | `ReadSignal<K \| ''>` | The widest breakpoint currently matched, or `''` below the smallest. |

## `breakpointsTailwind`

A ready-made map of Tailwind CSS's default breakpoints, exported alongside the composable:

```ts
import { breakpointsTailwind } from '@sigx/use-web';
// Record<'sm' | 'md' | 'lg' | 'xl' | '2xl', number>
const bp = useBreakpoints(breakpointsTailwind);
```

## SSR

On the server every query reads `false` and `active()` reads `''`; real matches resolve on mount.

## See also

- [`useMediaQuery`](/use/docs/use-media-query) — the `matchMedia` primitive underneath.
- [`useWindowSize`](/use/docs/use-window-size) — the raw dimensions when a numeric threshold isn't enough.
- [Conventions → Outputs](/use/docs/conventions#outputs-single-value--readsignalt) — why each method hands back a `ReadSignal`.

---
url: https://sigx.dev/terminal/docs/typography/
title: Typography
description: Token-aware Text and Heading spans, and the SGR text attributes the renderer supports
---

# Typography

For styled text, the foundation provides two components — `Text` and `Heading` — that resolve theme tokens and carry the full set of SGR (Select Graphic Rendition) attributes. They are the typed, themed alternative to the raw `<text>` intrinsic: use `Text` for app content, the `<text>` intrinsic when you want a plain colored run.

## Text

`Text` is an inline span with attribute props. `color` and `bg` take a theme token or a raw `#hex`; the boolean attributes map to terminal SGR codes:

```tsx
import { component, defineApp, Text } from '@sigx/terminal';

const App = component(() => {
    return () => (
        <box border="single" label="Type">
            <Text bold color="accent">Bold accent</Text>
            <br />
            <Text faint>Faint / dimmed</Text>
            <br />
            <Text italic>Italic</Text>
            <br />
            <Text underline color="info">Underlined</Text>
            <br />
            <Text lineThrough>Struck through</Text>
            <br />
            <Text inverse>Inverse video</Text>
            <br />
            <Text color="warn" bg="panel">Warning on a panel fill</Text>
        </box>
    );
});

defineApp(<App />).mount({ clearConsole: true });
```

### Props

| Prop | Type | Effect |
| --- | --- | --- |
| `color` | token \| `#hex` | foreground color |
| `bg` | token \| `#hex` | background fill behind the text |
| `bold` | boolean | bold weight |
| `faint` | boolean | dim / faint |
| `italic` | boolean | italic |
| `underline` | boolean | underline |
| `lineThrough` | boolean | strikethrough |
| `inverse` | boolean | swap foreground and background |

Attributes combine — `<Text bold underline color="accent">` is all three. Because `color`/`bg` resolve through the theme, a `Text` styled with tokens re-colors when the theme changes (see [Theming](/terminal/docs/theming)).

## Heading

`Heading` is a section title — an accent-weighted line. It takes a `color` token (defaulting to the theme's accent) and renders its children as a prominent heading:

```tsx
<box>
    <Heading>Settings</Heading>
    <br />
    <Text faint>Configure your project.</Text>
</box>
```

## SGR attributes and color depth

The boolean attributes emit standard SGR codes, so `bold`, `underline`, `inverse` and friends work on any ANSI terminal. Colors degrade by terminal: truecolor and 256-color terminals get the resolved hex; 16-color terminals get the nearest ANSI name. `faint` and `italic` are honoured where the terminal supports them. You write the same attributes regardless — the renderer adapts the output. See [Render modes](/terminal/docs/render-modes) for the color-depth detection.

## Next steps

- [Layout & Styling](/terminal/docs/layout-and-styling) — boxes, borders and the line layout model.
- [Theming](/terminal/docs/theming) — the tokens `color`/`bg` resolve against.
- [Components](/terminal/docs/components) — components that build on `Text`.

---
url: https://sigx.dev/use/docs/use-interval-fn/
title: useIntervalFn
description: Run a callback on an interval, with pause/resume controls and a reactive period that restarts the timer
---

# useIntervalFn

Run `cb` every `interval` ms (default `1000`), returning a [`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop) to control it. Cross-platform — import from `@sigx/use`.

```ts
import { useIntervalFn } from '@sigx/use';

const { pause, resume, isActive } = useIntervalFn(() => tick(), 1000);
pause();  // stop ticking; isActive.value === false
resume(); // start again
```

A **reactive `interval`** restarts the running timer whenever it changes — pass a signal or getter to drive the cadence from state:

```ts
import { signal } from 'sigx';
import { useIntervalFn } from '@sigx/use';

const period = signal(1000);
useIntervalFn(() => poll(), period);
period.value = 250; // timer restarts at the new period
```

The timer clears automatically with the owning scope (component setup or the innermost `effectScope()`); `pause()`/`resume()` control it manually.

## Signature

```ts
function useIntervalFn(
    cb: () => void,
    interval?: MaybeSignal<number>,
    options?: UseIntervalFnOptions,
): Pausable;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `immediate` | `boolean` | `true` | Start the timer on creation. |
| `immediateCallback` | `boolean` | `false` | Also invoke `cb` right away whenever the timer (re)starts. |

## Returns

A [`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop):

| Field | Type | Description |
|---|---|---|
| `isActive` | `ReadSignal<boolean>` | Whether the timer is currently running. |
| `pause` | `() => void` | Stop the timer. |
| `resume` | `() => void` | Start the timer. |

**Platform:** everywhere (`setInterval`).

## See also

- [`useTimeoutFn`](/use/docs/use-timeout-fn) — the one-shot equivalent.
- [`useNow`](/use/docs/use-now) — a reactive clock built on the same timer.
- [Conventions → Control handles](/use/docs/conventions#control-handles-pausable-and-stop) — the shared `Pausable`/`Stop` contract.

---
url: https://sigx.dev/use/docs/use-media-query/
title: useMediaQuery
description: Reactive matchMedia — a media query string as a boolean signal, re-subscribing when the query changes
---

# useMediaQuery

Reactive `matchMedia` — a media query string as a boolean signal. Browser composable — import from `@sigx/use-web`.

```ts
import { useMediaQuery } from '@sigx/use-web';

const isWide = useMediaQuery('(min-width: 1024px)');
const reduced = useMediaQuery('(prefers-reduced-motion: reduce)');
```

The query is a [`MaybeSignal<string>`](/use/docs/conventions#inputs-maybesignalt-and-tovalue): pass a reactive query and it re-subscribes when the string changes. The change listener detaches with the owning scope. The result is a [`ReadSignal<boolean>`](/use/docs/conventions#outputs-single-value--readsignalt).

## Signature

```ts
function useMediaQuery(query: MaybeSignal<string>, options?: ConfigurableWindow): ReadSignal<boolean>;
```

Pass `{ window }` to drive the query from a different document or a mock — see [`Configurable*` overrides](/use/docs/conventions#ssr-safety-and-configurable-overrides).

## SSR

On the server the signal reads `false` and never subscribes; the real match is read on mount.

## See also

- [`useBreakpoints`](/use/docs/use-breakpoints) — named breakpoints built on top of this.
- [`useWindowSize`](/use/docs/use-window-size) — the raw dimensions when you need the number, not a threshold.
- [`useColorScheme`](/use/docs/use-color-scheme) — the `prefers-color-scheme` query as a typed contract.

---
url: https://sigx.dev/use/docs/watch-debounced/
title: watchDebounced
description: watch with a debounced callback — bursts of source changes collapse into one run carrying the latest value
---

# watchDebounced

`watch` with a **debounced callback** — a burst of source changes collapses into a single callback run carrying the latest value. Cross-platform — import from `@sigx/use`.

```ts
import { signal } from 'sigx';
import { watchDebounced } from '@sigx/use';

const query = signal('');
watchDebounced(query, q => api.search(q), { debounce: 300, maxWait: 2000 });
```

It takes the same `source`/`cb` as core's `watch`, plus debounce options that extend [`WatchOptions`](/core/docs/effects). The callback's `onCleanup` behaves as in `watch`: the registered cleanup runs before the next (debounced) invocation and on stop.

`watchDebounced` returns core's [`WatchHandle`](/core/docs/effects) shape — a callable stop, plus `.stop()`, `.pause()`, and `.resume()`:

```ts
const handle = watchDebounced(query, run, { debounce: 300 });
handle.pause();
handle.resume();
handle();        // stop — cancels any pending run
```

## Signature

```ts
function watchDebounced<T>(
    source: WatchSource<T> | ReadSignal<T>,
    cb: WatchCallback<T, T | undefined>,
    options?: WatchDebouncedOptions,
): WatchHandle;

interface WatchDebouncedOptions extends WatchOptions {
    debounce?: MaybeSignal<number>;
    maxWait?: number;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `debounce` | `MaybeSignal<number>` | `200` | Debounce window in ms. |
| `maxWait` | `number` | — | Upper bound (ms) between callback runs while the source keeps changing. |

Plus every [`WatchOptions`](/core/docs/effects) field (`immediate`, `deep`, …).

**Platform:** everywhere (setTimeout). Stopping — or scope disposal — cancels any pending run.

## See also

- [`watchThrottled`](/use/docs/watch-throttled) — run at most once per window instead.
- [`useDebouncedSignal`](/use/docs/use-debounced-signal) — derive a debounced signal rather than run a callback.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/use/docs/use-window-size/
title: useWindowSize
description: Reactive window inner size as one { width, height } view — on the cross-platform WindowSizeState contract
---

# useWindowSize

Reactive window inner size as one `{ width, height }` view, on the cross-platform `WindowSizeState` contract. Browser composable — import from `@sigx/use-web`.

```tsx
import { component, render } from 'sigx';
import { useWindowSize } from '@sigx/use-web';

const Size = component(() => {
    const size = useWindowSize();
    return () => <p class="font-mono">{size.width} × {size.height}</p>;
});

render(<Size />, "#app");
```

## Usage

The return is a [`ReactiveView<WindowSizeState>`](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — read `width`/`height` by direct property access, each tracked independently:

```ts
import { computed } from 'sigx';
import { useWindowSize } from '@sigx/use-web';

const size = useWindowSize();
const cols = computed(() => (size.width < 768 ? 1 : 3)); // re-runs on width only
```

To pull a field out without snapshotting it, use core's [`toSignals()`](/core/docs/signals) rather than a plain destructure.

## Signature

```ts
function useWindowSize(options?: UseWindowSizeOptions): ReactiveView<WindowSizeState>;
```

`WindowSizeState` is a [cross-platform contract](/use/docs/conventions#cross-platform-contracts) — Lynx implements the same `{ width, height }` shape from its viewport APIs, so layout code ports across targets unchanged. (`useElementSize` returns the same shape for a single element.)

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `initialWidth` | `number` | `Infinity` | Width reported on the server / before mount. |
| `initialHeight` | `number` | `Infinity` | Height reported on the server / before mount. |
| `listenOrientation` | `boolean` | `true` | Also re-measure on orientation changes. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). See [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides). |

## SSR

On the server (no `window`) the view stays at `initialWidth`/`initialHeight`, then reads the real size on mount.

> The initial values default to **`Infinity`, not `0`**, on purpose: a desktop-first computed like `size.width < 768 ? 1 : 3` then resolves to the desktop branch on the server. A wrong desktop layout fails **visibly** during review; a `0`-seeded default would silently render the mobile branch to every server response instead. Set `initialWidth`/`initialHeight` if you have a better guess for first paint.

## See also

- [`useBreakpoints`](/use/docs/use-breakpoints) — named breakpoint queries instead of raw pixels.
- [`useMediaQuery`](/use/docs/use-media-query) — the underlying `matchMedia` primitive.
- [`useScroll`](/use/docs/use-scroll) — reactive scroll position for the same window.
- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — the `WindowSizeState` shape a platform pack fulfils.

---
url: https://sigx.dev/use/docs/watch-throttled/
title: watchThrottled
description: watch with a throttled callback — runs at most once per window, always with the latest value
---

# watchThrottled

`watch` with a **throttled callback** — it runs at most once per `throttle` ms, always with the latest value. Cross-platform — import from `@sigx/use`.

```ts
import { signal } from 'sigx';
import { watchThrottled } from '@sigx/use';

const scrollY = signal(0);
watchThrottled(scrollY, y => updateMinimap(y), { throttle: 100 });
```

It takes the same `source`/`cb` as core's `watch`, plus throttle options that extend [`WatchOptions`](/core/docs/effects), and returns core's [`WatchHandle`](/core/docs/effects) shape (a callable stop, plus `.stop()`, `.pause()`, `.resume()`). `leading` runs on the leading edge of the window; `trailing` runs the latest pending change on the trailing edge (both default `true`).

## Signature

```ts
function watchThrottled<T>(
    source: WatchSource<T> | ReadSignal<T>,
    cb: WatchCallback<T, T | undefined>,
    options?: WatchThrottledOptions,
): WatchHandle;

interface WatchThrottledOptions extends WatchOptions {
    throttle?: MaybeSignal<number>;
    leading?: boolean;
    trailing?: boolean;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `throttle` | `MaybeSignal<number>` | `200` | Throttle window in ms. |
| `leading` | `boolean` | `true` | Run on the leading edge of the window. |
| `trailing` | `boolean` | `true` | Run the latest pending change on the trailing edge. |

Plus every [`WatchOptions`](/core/docs/effects) field (`immediate`, `deep`, …).

**Platform:** everywhere (setTimeout). Stopping — or scope disposal — cancels any pending trailing run.

## See also

- [`watchDebounced`](/use/docs/watch-debounced) — collapse bursts into one run after quiet instead.
- [`useThrottledSignal`](/use/docs/use-throttled-signal) — derive a throttled signal rather than run a callback.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/actors/docs/actor-model/
title: The actor model
description: Activation, turns, identity and deactivation — what the runtime guarantees about an actor and what it costs
---

# The actor model

<p class="lede">An actor is `(type, key)`. The runtime finds it or creates it, runs one call at
a time against it, and puts it away when it goes quiet. You never construct one and you never
destroy one.</p>

## Identity

`actor(CartActor, 'user-42')` names a cart. It does not create one, look one up, or return a
handle you have to keep — it is an address, and it stays valid forever. Call it in one request
and again an hour later; the second call reaches the same logical object, whether or not
anything was in memory in between.

That is what *virtual* means: the actor always conceptually exists. What varies is whether it
is currently **activated**.

```ts
const cart = actor(CartActor, 'user-42');   // no I/O, no allocation on the server
await cart.addItem(item);                   // this is what activates it
```

The key is a string and it is part of your data model. It shows up in the storage record, the
cluster directory and — unless you configure otherwise — the routing token on the wire, so
prefer opaque ids over anything you would not want in a log. See
[Locality routing](/actors/docs/locality-routing).

## Activation

The first call to an inactive actor **activates** it: the runtime loads its state from
[storage](/actors/docs/storage), runs `migrateState` if the record predates this deploy,
builds the context, runs `onActivate`, and then runs your method.

Two calls racing to be first do not produce two activations. They join one:

```ts
const [a, b] = await Promise.all([client.increment(1), client.increment(1)]);
// [1, 2] — one activation, two turns, in some order
```

This is the single-activation invariant, and in a cluster it is what the actor directory
exists to preserve.

```mermaid
sequenceDiagram
    participant A as Caller A
    participant B as Caller B
    participant H as Host
    participant C as Cart/user-42
    A->>H: increment(1)
    B->>H: increment(1)
    H->>C: activate once (load state, onActivate)
    Note over C: one activation, two queued turns
    C-->>A: 1
    C-->>B: 2
```

## Turns

A **turn** is one method call, and a turn ends when the method's promise *settles* — so an
awaited `fetch` inside a method keeps that actor busy for its whole duration. By default one
turn runs at a time, which is what makes `ctx.state.items.push(item)` safe with no lock.

That mechanism is the single idea the rest of this model rests on, and it has its own page:
**[Turns & concurrency](/actors/docs/turns)** — the two lanes an activation runs turns in, why
an `await` blocks the serial one, and what runs outside the turn sequence entirely.

## Deactivation

An actor deactivates after `idleAfterMs` without a call (default 20 minutes), or when the
host is shutting down, or when a `maxActivations` cap sheds it, or when a
[cluster](/actors/docs/clustering) migrates it. `onDeactivate(ctx, reason)` receives which.

Deactivation is not deletion. State is in storage; the next call activates again and reads it
back. What is lost is anything you kept *outside* `ctx.state` — a cached connection, an
in-memory index — which is exactly why `ctx.save()` matters.

> **On Cloudflare Durable Objects, eviction is not deactivation.** The platform destroys the
> isolate, the host and the activation together, so `onDeactivate` never runs and there is no
> idle sweeper. An actor that flushes in `onDeactivate` must `ctx.save()` in the turn instead.
> See [Cloudflare Workers](/actors/docs/cloudflare-workers).

## What is callable

The callable surface is the **own keys** of the object your `methods:` factory returns, plus
`streams:`. Nothing else — an inherited `Object.prototype` member like `toString` or
`constructor` answers a clean `404 method-not-found`, not a result.

One shape this rules out:

```ts
// ✗ class instances put methods on the prototype — not own keys
methods: () => new CartMethods(ctx),

// ✓ an object literal
methods: (ctx) => ({ async addItem(item) { /* … */ } }),
```

Dev builds warn if a `methods:` factory returns something whose methods are not own keys.
Declaring a method that *shadows* a prototype name is fine — `async toString()` in the literal
is an own key and is callable.

Type names starting with `$` or `@` are refused: the runtime reserves them for the wire
(`$live`, `$watch:`) and data keys (`@actor`).

## Deadlock detection

Every call carries its chain. A cycle `A → B → A` into a non-reentrant actor throws
[`ActorDeadlockError`](/actors/docs/errors) **immediately**, with the full chain, rather than
hanging until `callTimeoutMs` fires.

```
ActorDeadlockError: Cart/user-42 → Pricing/eu → Cart/user-42
```

This is a deliberate design choice over the alternative — a call that simply never returns and
surfaces as a timeout half an hour later in production.
[`reentrant: 'call-chain'`](/actors/docs/reentrancy) allows the cycle to run inline;
`reentrant: 'always'` makes it impossible by construction.

## Next steps

- [State & persistence](/actors/docs/state-and-persistence) — `ctx.save()`, write-behind and
  `migrateState`.
- [Lifecycle](/actors/docs/lifecycle) — idle collection, caps and deactivation reasons.
- [Reentrancy & interleaving](/actors/docs/reentrancy) — when serial is too strict.
- [Errors](/actors/docs/errors) — the error kinds and what to do about each.

---
url: https://sigx.dev/actors/docs/rebalancing/
title: Rebalancing
description: cluster({ rebalance }) — shedding your own idlest actors down toward the mean, and why it cannot oscillate
---

# Rebalancing

<p class="lede">[Placement](/actors/docs/placement-policies) only ever decides where a **new**
activation goes. Once a workload has gone lumpy, the actors do not move back on their own.
Rebalancing is the correction, and it is off unless configured.</p>

```ts
cluster({
    providers, advertise, secret,
    policy: activationCountPolicy(),     // where shed actors land
    rebalance: { intervalMs: 60_000 },   // { threshold, maxMoves, minIdleMs, timeoutMs }
});
```

## How it works

Each host runs `placement.rebalance()` on the cadence:

1. Probe peer loads over the authenticated ops channel.
2. If **this host** is over `threshold × mean` (default 1.2), `migrate()` a bounded batch —
   `maxMoves`, default 10 — of its **idlest** activations.
3. Skip anything kept alive by a stream, watch or task; anything with queued turns; and
   anything active within `minIdleMs`.

The shed actors deactivate with reason `'migrated'`, their claims release, and the next call
re-activates them wherever the policy chooses.

## Why it cannot oscillate

Two properties do the work.

**A host only ever sheds its own actors, and only downward.** There is no instruction to
another host to take work, and no host pulls. A host at or below the mean does nothing at all,
so two hosts cannot hand the same actors back and forth.

**It never acts on missing data.** If peer loads cannot be gathered, the round is skipped
rather than run against a partial view — which is the case where a naive implementation would
decide it is the most loaded host in a one-host cluster and shed everything.

## Pair it with `activationCountPolicy()`

Rebalancing decides *what leaves*; the policy decides *where it lands*. With the default
random policy, shed actors scatter — which is fine and still converges. With
[`activationCountPolicy()`](/actors/docs/placement-policies) they land cold, on the hosts that
have room, so the fleet converges in far fewer rounds.

## When you need it

- A **skewed load balancer** concentrated ownership — the 80× row in the placement table.
- A **scale-up** left the old hosts full and the new ones empty; placement alone only fills
  the new hosts as actors happen to be created.
- `preferLocalPolicy()` ran under the wrong edge for a while.

If none of those apply, leave it off. A steady cluster with random placement holds an
ownership spread around 2.9 without any help.

## Watching it

`rebalanceRounds` and `rebalanceMigrations` counters tell you whether it is doing anything.
Rounds climbing with migrations flat means the fleet is inside `threshold` — healthy.
Migrations that never settle mean the threshold is too tight for your churn, or the policy is
putting actors back where they came from.

`placement.rebalance()` is also callable directly, returning a `RebalanceReport` — useful from
an admin endpoint or a one-off script after a known-bad deploy.

## Next steps

- [Placement policies](/actors/docs/placement-policies) — where shed actors land.
- [Cluster stats](/actors/docs/cluster-stats) — ownership spread and the counters.
- [Clustering](/actors/docs/clustering) — the plugin options.

---
url: https://sigx.dev/actors/docs/vite-plugin/
title: The Vite plugin
description: sigxActors() — the build swap that keeps implementations out of the browser, the dev host, and what HMR does to actor state
---

# The Vite plugin

<p class="lede">`sigxActors()` does two jobs: it swaps `*.actor.ts` modules for typed client
stubs in the browser bundle, and it runs a dev host so calls actually go somewhere.</p>

```ts
import { sigxActors } from '@sigx/actors/vite';

export default {
    plugins: [sigxActors({ app: '/src/actors.app.ts' })],
};
```

## Options

| Option | Default | What it does |
|---|---|---|
| `app` | — | root-relative path to your [app module](/actors/docs/the-app) |
| `include` | `['**/*.actor.ts', '**/*.actor.tsx']` | which modules are actor modules |
| `exclude` | `node_modules`, `dist` | never transformed |
| `base` | `/_sigx/actor` | where the endpoint mounts |
| `endpoint` | `= base` | what the client ref is stamped with |
| `requireAuthorization` | `true` | `'warn'` to soften while migrating |
| `origin` | — | `'same-origin'`, `'verify-when-present'`, an allowlist, or `false` |
| `maxBodyBytes` | — | request body cap |
| `onMiss` | `'proxy'` | what to do when the actor is on another host |

The virtual module is `virtual:sigx-actors`; the production chunk is `sigx-actors.js`.

## The build swap

Actor modules are replaced wholesale in the client bundle. **Values are swapped, types are
not** — which is why `actor(Counter, id).increment(1)` is fully typed in the browser with no
second interface to maintain, and why no implementation, no database import and no secret from
an actor file can reach the browser.

`exclude` covers `node_modules`, so a package shipping actors must
[do its own swap](/actors/docs/shipping-actors-in-packages).

## One config for dev and production

`sigxActors({ app })` points dev at the same app module your production entry imports, so
storage, placement, codec handlers, defaults and every plugin are identical in both. There is
no second place to configure the dev host, and nothing to keep in sync.

The app module gets its registry from `virtual:sigx-actors` under Vite, and from
`withActors([...])` anywhere else. Add the virtual module's types once:

```ts
// src/env.d.ts
/// <reference types="@sigx/actors/vite-client" />
```

> `virtual:sigx-actors` only resolves under Vite. A non-Vite production entry should take its
> registry as a parameter rather than importing the virtual module.

## Dev & HMR

The dev host lives in the SSR module runner's graph and is reachable through the
`__SIGX_ACTOR_HOST__` seam.

Editing a `*.actor.ts` file deactivates that type through storage, so **state survives edits
if — and only if — your app configures persistent storage.** `sigxActors({ app })` runs your
real config, so it does. With the bare in-memory default it resets, and the dev log says so
once.

Mid-edit syntax errors never reach the browser: the last good client stub is served, or a loud
refusal.

> If your storage `dir` sits inside the project root, add it to `server.watch.ignored`. Saves
> are temp-file-then-rename and the HMR watcher races them, surfacing as an `ENOENT … .tmp`
> overlay. Actor state is not source.
>
> ```ts
> server: { watch: { ignored: ['**/.actors/**'] } }
> ```

## Next steps

- [The app](/actors/docs/the-app) — what the `app` option points at.
- [Running a host on Node](/actors/docs/node) — the production entry.
- [Authorization](/actors/docs/guards) — the `requireAuthorization` gate.

---
url: https://sigx.dev/daisyui/docs/components/
title: Components
description: Browse all available @sigx/daisyui components
---

# Components

<p class="lede">Every component in @sigx/daisyui, by category. All form components support the <strong>model binding pattern</strong> for two-way data synchronization.</p>

---
url: https://sigx.dev/ssg/docs/client-runtime/
title: Client Runtime
description: "The @sigx/ssg/client helpers: the package-manager switcher, built-in search, copy-code buttons, prefetch, and SPA navigation"
---

# Client Runtime

`@sigx/ssg` ships a small set of interactive behaviors for the rendered site, all exported from `@sigx/ssg/client`. The generated client entry wires every one of them automatically — this page is for when you author a custom client entry, or want to drive them programmatically.

```tsx
import {
    setupPrefetch,
    installSpaNavigation,
    installPackageManagerSwitcher,
    installCodeCopy,
} from '@sigx/ssg/client';

// after `.hydrate('#app')` in a custom entry:
setupPrefetch();
installSpaNavigation(router);
installPackageManagerSwitcher();
installCodeCopy();
```

Each `install*` helper is idempotent, client-only, and returns a disposer that removes its listeners.

## Package-manager switcher

A shell code fence whose lines are `npm`/`pnpm`/`yarn`/`bun` commands (install/add, run, dlx, create, remove, …) is rendered with an npm/pnpm/yarn/bun tab strip, with all four variants pre-rendered server-side. The client only flips which variant is visible and persists the choice — it never rewrites highlighted text, so it never fights hydration.

```bash
npm install @sigx/ssg
npm install -D vite @sigx/vite
```

`installPackageManagerSwitcher()` registers the tab clicks, a cross-tab `storage` sync, and a coalesced `MutationObserver` for windows that mount after first paint (SPA navigation, late hydration). The first-shown variant comes from `markdown.shiki.defaultPackageManager` (default `'pnpm'`); a visitor's saved choice overrides it.

### Reading and setting the selection

```ts
import {
    getPackageManager,
    setPackageManager,
    onPackageManagerChange,
} from '@sigx/ssg/client';

getPackageManager(); // 'pnpm' | 'npm' | 'yarn' | 'bun'

setPackageManager('bun'); // updates every window, persists, notifies subscribers

const off = onPackageManagerChange((pm) => {
    console.log('package manager is now', pm);
});
```

`getPackageManager` resolves the in-page selection, else the persisted one, else the first window's server-rendered default, else `'pnpm'`. `setPackageManager` throws on an unknown value. `onPackageManagerChange` returns an unsubscribe function.

### Translating a command yourself

The pure parser/renderer behind the switcher is exported too — no DOM required, so it works in SSR and tests:

```ts
import {
    parsePackageManagerCommand,
    translatePackageManagerCommand,
    PACKAGE_MANAGERS,
    DEFAULT_PACKAGE_MANAGER,
} from '@sigx/ssg/client';

translatePackageManagerCommand('npm install -D vite', 'pnpm');
// → 'pnpm add -D vite'

PACKAGE_MANAGERS; // ['pnpm', 'npm', 'yarn', 'bun']
DEFAULT_PACKAGE_MANAGER; // 'pnpm'
```

## Search

Set `search: true` in `ssg.config.ts` to emit a `search-index.json` at build time (see [Configuration → Built-in search](/ssg/docs/configuration#built-in-search)). On the client, load it once and rank queries against it:

```ts
import { loadSearchIndex, searchPages } from '@sigx/ssg/client';

const index = await loadSearchIndex();
const results = searchPages(index, 'island hydration', { limit: 10 });

for (const r of results) {
    // r.path, r.title, r.score, r.excerpt?, r.anchor?
    const href = r.anchor ? r.path + r.anchor : r.path;
}
```

`loadSearchIndex({ base })` handles subpath deploys (pass `url` to override the location entirely). `searchPages` is pure and dependency-free: every whitespace-separated term must match the title, a heading, the description, or the body (AND semantics), and title matches rank highest. Each result carries an `excerpt` around the first body match and an `anchor` (`#id`) for the best-matching heading, for deep links.

To surface a theme's built-in search UI (such as the daisyUI theme's ⌘K command palette) instead of wiring your own, set `site.search: true` alongside `search: true` — it reaches layouts via `LayoutProps.site`. See [Themes](/ssg/docs/themes).

## Copy-code buttons

Shiki emits a copy button in every code-window header. `installCodeCopy()` wires them with one delegated listener; package-manager windows copy only the currently visible variant. It is safe to call on pages without any code blocks.

## Prefetch on hover

Prefetch-on-hover is enabled by default (config `prefetch`, with a 100 ms delay) and wired automatically. Call the helpers directly in a custom entry:

```ts
import { prefetch, setupPrefetch } from '@sigx/ssg/client';

setupPrefetch({ delay: 150 });
prefetch('/blog/hello-world');
```

## SPA navigation

`installSpaNavigation(router, { base, trailingSlash })` routes same-origin internal anchor clicks — including the plain `<a>` elements MDX content links compile to — through the router instead of full page reloads. The browser keeps handling modified clicks, external/`mailto:`/`tel:` links, `target`/`download` anchors, same-document `#hash` scrolls, `data-no-spa` opt-outs, and anything that already called `preventDefault()`. Pass the deploy `base` on subpath deploys (it is stripped before the push). `trailingSlash` (default `'always'`) makes pushed URLs match the canonical hard-load form — folder routes gain the trailing slash, while paths with a file extension like `/sitemap.xml` are pushed verbatim. Returns an uninstall function.

It is wired automatically in the generated client entry; opt out globally with `spaNavigation: false` (see [Configuration → SPA navigation](/ssg/docs/configuration#spa-navigation)).

## Rendering-mode helpers

```ts
import { isStaticPage, getInitialState } from '@sigx/ssg/client';

if (!isStaticPage()) {
    const state = getInitialState<{ user: string }>();
}
```

`isStaticPage()` is `true` when the document was statically generated (no `data-ssr` attribute); `getInitialState()` parses the JSON embedded in `#__SSG_STATE__`, or returns `null`.

## Next steps

- [Configuration & Content](/ssg/docs/configuration) — the config options these helpers back.
- [Themes](/ssg/docs/themes) — a prebuilt theme that wires all of this for you.
- [API Reference](/ssg/docs/api) — every `@sigx/ssg/client` export with its signature.

---
url: https://sigx.dev/vite/docs/library-builds/
title: Library Builds
description: Build @sigx/* libraries with defineLibConfig from @sigx/vite/lib
---

# Library Builds

The `@sigx/vite/lib` subpath exports `defineLibConfig`, a helper that produces a
Vite 8 / Rolldown library-build config for `@sigx/*` packages. It normalizes
entries, externalizes the SignalX runtime, and applies sensible defaults so
every package builds consistently.

```ts
import { defineLibConfig } from '@sigx/vite/lib';
```

A direct re-export of Vite's own `defineConfig` is also available from the same
subpath, for composing custom configs alongside `defineLibConfig`:

```ts
import { defineLibConfig, defineConfig } from '@sigx/vite/lib';
```

## Single Entry

The simplest config builds one entry to ES modules:

```ts
// vite.config.ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: 'src/index.ts',
});
```

Output files use the format `${entryName}.js` (ES format only). Sourcemaps are
on by default, and output is minified in place by Oxc unless you set
`minify: false`.

## Multiple Entries

Pass a record (or an array of `LibEntry` objects) to build multiple entries —
useful for packages with subpath exports:

```ts
// vite.config.ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: {
        index: 'src/index.ts',
        'server/index': 'src/server/index.ts',
        'client/index': 'src/client/index.ts',
    },
    external: ['sigx', /@sigx\/.*/],
});
```

The keys become output file names (without extension). The array form is
equivalent:

```ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: [
        { name: 'index', entry: 'src/index.ts' },
        { name: 'utils', entry: 'src/utils.ts' },
    ],
});
```

## Runtime Externals Are Always Added

Whatever you pass as `external`, `defineLibConfig` always prepends the SignalX
runtime tier — `sigx`, `@sigx/reactivity`, `@sigx/runtime-core`,
`@sigx/runtime-dom`, `@sigx/server-renderer`, and their subpaths — and dedupes
the result. This keeps the runtime out of your bundle and preserves singleton
reactivity for consumers.

## Bundling Sibling Packages with Aliases

When you need to bundle sibling packages in a monorepo, use `alias` to map

```ts
// vite.config.ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: {
        sigx: 'src/index.ts',
        hydration: 'src/hydration.ts',
    },
    alias: {
        '@sigx/reactivity': '../reactivity/src/index.ts',
        '@sigx/runtime-core': '../runtime-core/src/index.ts',
        '@sigx/runtime-dom': '../runtime-dom/src/index.ts',
    },
    minify: true,
    root: import.meta.url,
});
```

`root` accepts a `file://` URL (such as `import.meta.url`) or a directory path.
Always set it when you use `alias`.

## JSX Libraries

Set `jsx: true` to enable Oxc's automatic JSX transform with import source
`sigx`:

```ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: 'src/index.ts',
    jsx: true,
});
```

### Targeting a non-web runtime

`sigx` is the **web** umbrella — it carries `@sigx/runtime-dom`, and with it the
DOM `JSX.IntrinsicElements`. A component library for another target (terminal,
lynx, or a custom renderer) must compile against that target's runtime instead,
or every JSX element in the consuming app is typed against the DOM.

`importSource` is that dial:

```ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: 'src/index.ts',
    jsx: true,
    importSource: '@sigx/runtime-core',   // default: 'sigx'
});
```

It is read only when `jsx` is enabled, and it defaults to `'sigx'` — existing
library builds are unaffected.

> **This replaces per-file pragmas.** Before `importSource`, the only way to
> retarget the JSX runtime was a `/** @jsxImportSource … */` comment at the top
> of every `.tsx` source, because oxc honours a pragma over config. One config
> line now does what a pragma per file used to.

## Node and CLI Builds

For a Node-targeted build, set `platform: 'node'` (targets `node18`). For a CLI
that needs a shebang, use `banner`:

```ts
import { defineLibConfig } from '@sigx/vite/lib';

export default defineLibConfig({
    entry: 'src/cli.ts',
    platform: 'node',
    banner: '#!/usr/bin/env node',
});
```

## Dual-dist (development + production) builds

`defineLibConfig` returns a config **function** that branches on Vite's `--mode`.
Run it twice to emit a development dist and a parallel production dist into the
same `outDir`:

```jsonc
// package.json
{
    "scripts": {
        "build": "vite build && vite build --mode prod-dist"
    }
}
```

- **`vite build`** — the default (development) dist. Files are `${entryName}.js`
  and `emptyOutDir` is on, so the directory starts clean.
- **`vite build --mode prod-dist`** — the production dist, written **alongside**
  the dev output (it does not empty the directory). `process.env.NODE_ENV` is
  defined away to `'production'` so dev-only warnings and devtools plumbing are
  stripped, and every file gets a `.prod.js` suffix.

Point the package's `production` export condition at the `.prod.js` files so
consumers building for production pick up the stripped-down runtime automatically:

```jsonc
// package.json (sketch)
{
    "exports": {
        ".": {
            "production": "./dist/index.prod.js",
            "default": "./dist/index.js"
        }
    }
}
```

## Defaults Summary

| Option | Default | Effect |
|---|---|---|
| `outDir` | `'dist'` | Output directory; `emptyOutDir` is on for the default build and off for the `prod-dist` pass, so the two builds sit side by side. |
| `sourcemap` | `true` | Emit sourcemaps. |
| `external` | `[/@sigx\/.*/]` | Runtime tier is always added on top. |
| `minify` | `true` | Minify output in place via Oxc (or `false`). |
| `jsx` | `false` | Automatic JSX with import source `sigx` when `true`. |
| `importSource` | `'sigx'` | The module the automatic JSX runtime imports from. Read only when `jsx` is `true`. |
| `platform` | `'browser'` | `'node'` targets `node18`; `'neutral'` is also accepted. |

## Next Steps

- [API Reference](/vite/docs/api) — `defineLibConfig`, `LibBuildOptions`, and `LibEntry`
- [HMR for Components](/vite/docs/hmr) — component hot-reload in app builds

---
url: https://sigx.dev/store/docs/installation/
title: Installation
description: Install @sigx/store and wire it into a SignalX project
---

# Installation

`@sigx/store` builds on the SignalX reactive core, so it is designed to be used inside a project that already renders SignalX components with the `sigx` package.

## Install

```bash
npm install @sigx/store
```

The package is ESM-only and ships two entry points:

- `@sigx/store` — `defineStore`, `storeToSignals`, `onStoreCreated`, and their supporting types.
- `@sigx/store/persist` — the `persist` composable and its types (see [Persistence](/store/docs/persistence)).

## Dependencies

`@sigx/store` builds on the reactive core but never bundles its own copy — it always uses the *same* core your components do. This matters because core keeps process-wide singletons: the topic registry, the DI app-context token, `instanceof` identity. A second, separate copy would silently split that shared state.

You don't install core separately, though. The `sigx` umbrella your app already runs on bundles `@sigx/reactivity` and `@sigx/runtime-core`, so `npm install @sigx/store` above is all you add — `sigx` provides `component`, `render`, `signal`, and `computed`, and `@sigx/store` adds `defineStore` on top. (Starting from scratch? Install `sigx` first — see [Project setup](#project-setup) below.)

## Project setup

No special Vite or build configuration is required beyond a standard SignalX + TSX/JSX setup. If your project already renders SignalX components, you can import and use `defineStore` immediately:

```ts
import { defineStore } from '@sigx/store';
```

If you are setting up a SignalX project from scratch, follow [Core → Installation](/core/docs/installation) for the JSX/TSX and Vite configuration, then add `@sigx/store` on top.

## Verify

Define a tiny store and read it in a component to confirm everything is wired up:

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const usePing = defineStore('ping', ({ defineState }) => {
    const { signals } = defineState({ message: 'store is working' });
    return { ...signals };
});

const App = component(() => {
    const store = usePing();
    return () => <p>{store.message}</p>;
});

render(<App />, '#app');
```

## Next steps

- [Getting Started](/store/docs/getting-started) — the core mental model with live examples.
- [Defining a Store](/store/docs/defining-a-store) — state, actions, derived values, and events.
- [Using Stores in Components](/store/docs/using-in-components) — sharing, lifetimes, and cleanup.

---
url: https://sigx.dev/use/docs/try-on-mounted/
title: tryOnMounted
description: Run fn after mount inside a component, or immediately when standalone — defer environment reads without failing outside components
---

# tryOnMounted

Run `fn` after mount when called during a component's setup; immediately otherwise (standalone scopes, tests, plain scripts). Cross-platform — import from `@sigx/use`.

```ts
import { tryOnMounted } from '@sigx/use';

tryOnMounted(() => {
    // inside a component: runs after mount
    // standalone: runs right now
    measure();
});
```

Web composables use this to defer environment reads (storage, layout) to the client-mounted moment without failing outside components — so the same code works in a component, an `effectScope()`, or a bare script.

## Signature

```ts
function tryOnMounted(fn: () => void): void;
```

**Platform:** everywhere.

## See also

- [`tryOnScopeDispose`](/use/docs/try-on-scope-dispose) — the teardown counterpart.
- [Conventions → Lifecycle helpers](/use/docs/conventions#lifecycle-helpers) — how these two power the cleanup model.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/use/docs/use-cycle-list/
title: useCycleList
description: Cycle through a (possibly reactive) list with wrap-around next/prev/go
---

# useCycleList

Steps through a list with wrap-around — `next`, `prev`, and `go` move the current item and wrap past either end. Cross-platform — import from `@sigx/use`.

```tsx
import { component, render } from 'sigx';
import { useCycleList } from '@sigx/use';

const ThemePicker = component(() => {
    const { state, next, prev } = useCycleList(['light', 'dark', 'system']);

    return () => (
        <div class="flex items-center gap-3">
            <button class="btn" onClick={() => prev()}>‹</button>
            <span class="font-mono w-16 text-center">{state}</span>
            <button class="btn" onClick={() => next()}>›</button>
        </div>
    );
});

render(<ThemePicker />, "#app");
```

## Usage

```ts
import { useCycleList } from '@sigx/use';

const { state, index, next, prev, go } = useCycleList(['light', 'dark', 'system']);
next();   // state.value === 'dark',  index.value === 1
next();   // 'system'
next();   // wraps to 'light'
prev();   // wraps back to 'system'
go(0);    // 'light'
```

The list is a [`MaybeSignal<T[]>`](/use/docs/conventions#inputs-maybesignalt-and-tovalue) — pass a reactive list and the cycle follows it. If the current value drops out of a changed list, `state` falls back to the item at `fallbackIndex`; an empty list keeps the last known value (and `index` reports `-1`).

## Signature

```ts
function useCycleList<T>(list: MaybeSignal<T[]>, options?: UseCycleListOptions<T>): UseCycleListReturn<T>;

interface UseCycleListOptions<T> {
    initialValue?: T;
    fallbackIndex?: number;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `initialValue` | `T` | the list item at `fallbackIndex` | Starting value. |
| `fallbackIndex` | `number` | `0` | Index used when the current value is not in the (possibly changed) list. |

## Returns

`useCycleList` returns a `UseCycleListReturn<T>` object:

| Field | Type | Description |
|---|---|---|
| `state` | `ReadSignal<T>` | The current item. Falls back to `fallbackIndex` if the list no longer contains it; an empty list keeps the last known value. |
| `index` | `ReadSignal<number>` | Index of the current item in the list (`-1` while the list is empty). |
| `next` | `(n?: number) => T` | Advance `n` steps (default 1), wrapping around. Returns the new item. |
| `prev` | `(n?: number) => T` | Go back `n` steps (default 1), wrapping around. Returns the new item. |
| `go` | `(index: number) => T` | Jump to `index` (wrapped into range). Returns the new item. |

**Platform:** everywhere. No cleanup needed.

## See also

- [`useToggle`](/use/docs/use-toggle) — cycle between exactly two states.
- [`useCounter`](/use/docs/use-counter) — step a number instead of a list.
- [Conventions](/use/docs/conventions) — `MaybeSignal` inputs and `ReadSignal` outputs.

---
url: https://sigx.dev/use/docs/use-timeout-fn/
title: useTimeoutFn
description: A restartable one-shot timer — cb fires once after a delay, with start/stop controls and a reactive isPending flag
---

# useTimeoutFn

A restartable one-shot timer: `cb` fires once, `ms` (default `1000`) after the latest `start()`. Cross-platform — import from `@sigx/use`.

```ts
import { signal } from 'sigx';
import { useTimeoutFn } from '@sigx/use';

const toast = signal<string | null>(null);
const { start, isPending } = useTimeoutFn(() => (toast.value = null), 3000);

toast.value = 'Saved';
start(); // clear the toast 3s from now
```

Calling `start()` again **replaces** any pending run — the delay restarts from the latest call. Arguments passed to `start()` flow through to `cb`:

```ts
const { start } = useTimeoutFn((id: number) => dismiss(id), 3000);
start(42); // cb receives 42 when it fires
```

The timer is auto-cancelled when the owning scope disposes (component setup or the innermost `effectScope()`).

## Signature

```ts
function useTimeoutFn<A extends unknown[] = []>(
    cb: (...args: A) => void,
    ms?: MaybeSignal<number>,
    options?: UseTimeoutFnOptions,
): UseTimeoutFnReturn<A>;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `immediate` | `boolean` | `true` | Arm the timer on creation. |

## Returns

| Field | Type | Description |
|---|---|---|
| `isPending` | `ReadSignal<boolean>` | True while a run is armed and hasn't fired. |
| `start` | `(...args: A) => void` | (Re)arm the timer, replacing any pending run. Arguments pass through to `cb`. |
| `stop` | `() => void` | Cancel the pending run, if any. |

**Platform:** everywhere (`setTimeout`).

## See also

- [`useIntervalFn`](/use/docs/use-interval-fn) — the repeating equivalent.
- [`useDebouncedSignal`](/use/docs/use-debounced-signal) — a debounced signal built on the same timer.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/actors/docs/clustering/
title: Clustering
description: The cluster() plugin — membership, the actor directory, and the shutdown sequence that keeps a rolling restart from resetting connections
---

# Clustering

<p class="lede">Many hosts, one actor system. The single-activation guarantee still holds
across the fleet — that is what the directory is for.</p>

```ts
import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { redisCluster } from '@sigx/actors-redis';

export const app = defineActorApp({ actors, storage }).use(
    cluster({
        providers: redisCluster({ url: process.env.REDIS_URL }), // membership + directory
        advertise: 'http://10.0.4.7:7311',   // this host's peer-reachable origin
        secret: process.env.HOST_SECRET,     // declared ONCE
    }),
);
```

## The two providers

**Membership** answers "which hosts are alive?" — a heartbeat plus a view of peers.
[Fencing](#fencing) falls out of it: a host that has lost its place in membership refuses
every activation.

**The directory** answers "which host owns this actor?" — the claim that makes single
activation true cluster-wide.

They are independent choices. [Redis](/actors/packages/actors-redis/overview),
[Postgres](/actors/packages/actors-pg/overview) and
[SurrealDB](/actors/packages/actors-surreal/overview) provide both;
[Kubernetes](/actors/packages/actors-k8s/overview) provides membership only, on Leases you are
already running, and pairs with either directory:

```ts
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(client) },
    advertise,
    secret: process.env.HOST_SECRET,
});
```

## One handler, both mounts

The plugin contributes the internal host-to-host mount as a **route**, so `secret` and
`internalBase` are stated once instead of repeated at the endpoint, and any adapter that
mounts `app.routes` picks up host-to-host traffic automatically.

```ts
const handler = createAppHandler(app);   // public endpoint AND internal route

let stopping = false;
const server = createServer((req, res) => {
    if (stopping) res.setHeader('connection', 'close');
    handler(req, res);
});

// Listen BEFORE starting: app.start() joins membership, and from that moment
// peers may place actors here and call them. Bind first and there is no
// window where this host is routable but nothing is listening.
await new Promise<void>((resolve) => server.listen(7311, resolve));
const host = await app.start();

attachSignalHandlers(host, { server, onStopBegin: () => (stopping = true) });
```

## Shutdown: pass the server, not just the host

Stopping the actors is only half a graceful shutdown. An orchestrator's preStop sleep and
readiness-503 steer *new* connections away, but connections already established survive
endpoint removal — conntrack — and ride into the exiting pod, where they are reset when the
process exits.

On a real cluster that measured as **122 lost calls out of ~1.7M** on a rolling restart. All
connection-level, none of them visible from the actor layer, which reported a clean hand-off.

The sequence is deliberately not the obvious one:

1. **`onStopBegin()`** — start answering `connection: close`. This is what actually drains the
   pools, one response at a time, interrupting nothing.
2. **`host.stop()`** — the actor drain. Pooled connections keep flowing; peers whose dials are
   refused see `unreachable`, which is retryable by design.
3. **`server.close()` + `closeAllConnections()`** — **last**.

> Closing the listener first looks more decisive and is worse. On Node ≥ 19, `close()` also
> destroys idle connections, and "idle" from the server's side includes a socket the client is
> at that instant writing its next request onto — producing exactly the reset the sequence
> exists to prevent.

## Options

| Option | Default | Notes |
|---|---|---|
| `providers` | — | membership + directory |
| `advertise` | — | this host's **internal** peer-reachable origin |
| `publicAddress` | — | where *clients* reach this host; never guessed — see [Locality routing](/actors/docs/locality-routing) |
| `secret` | — | **Required outside development.** HMAC for the host-to-host mount — see below |
| `internalBase` | `/_sigx/host` | where that mount lives |
| `refreshCoalescer` | provider default | coalesces push-notification refreshes — see [below](#membership-refresh-coalescing) |
| `transport` | `httpTransport()` | see [Transports](/actors/docs/transports) |
| `policy` / `typePolicies` | random | see [Placement policies](/actors/docs/placement-policies) |
| `rebalance` | off | see [Rebalancing](/actors/docs/rebalancing) |
| `retries` / `retryBackoffMs` | 3 / 100ms | |

`fetch` and `endpoint` remain as sugar for exactly those two `httpTransport()` options, and
passing either *alongside* an explicit `transport` throws.

## The secret is not optional

`cluster()` **throws at construction** without a `secret`, in every build but development.

The internal host-to-host mount runs **no policies** — the public edge is expected to have
decided already — and it is contributed as an ordinary route, so it lands on the same listener
as the public actor endpoint. Without a secret, every registered actor type, key and method is
reachable unauthenticated by anything that can address that listener.

```ts
cluster({ providers, advertise, secret: process.env.HOST_SECRET });   // normal
cluster({ providers, advertise, secret: null });                     // explicit opt-out
```

`secret: null` is for a mount genuinely unreachable by an untrusted caller — an mTLS mesh, a
private network with no other tenant. It is a claim you are making, which is why it has to be
written down. An empty or whitespace-only secret throws in **every** build, development
included.

The HMAC authenticates the **peer**, not the payload.

## Fencing

A host fences itself when it can no longer prove it holds its place in membership. Fenced is
**terminal**: activations are refused, liveness fails, and an orchestrator restart is the way
back — a host that has been aged out by its peers cannot talk itself back in.

Three things trigger it:

| Trigger | Why it counts |
|---|---|
| A heartbeat **failed** and the presence window has lapsed | the classic case |
| A heartbeat **landed** past the window | a stalled loop or a suspended container; the write may have taken longer than the whole TTL to return, and there is no way to tell *when* it landed |
| The host is **absent from its own membership view** | peers have already stopped counting it |

A fenced host also **withdraws from membership**, so peers stop routing to it immediately
rather than waiting out its TTL.

### Writing a provider

Drive `heartbeatClock()` from your heartbeat rather than hand-rolling a TTL comparison:

```ts
import { heartbeatClock } from '@sigx/actors/cluster';

const clock = heartbeatClock({ ttlMs, onSuspect: () => fenceThisHost() });

clock.arm();                                    // once, when beating starts
// each beat:
clock.beat();                                   // before the write
try { await writeHeartbeat(); clock.confirmed(); }
catch { clock.failed(); }
```

It watches the **monotonic and the wall clock together**, because `CLOCK_MONOTONIC` does not
advance across a VM suspend — and `setTimeout` rides that same clock, so a suspended host
would otherwise conclude every beat had been punctual. The window is stamped when the beat is
**armed**, not at the join write, so a slow join cannot fence a host at startup.

`clock.lost()` is the fourth door, for a provider holding **proof** its record is gone rather
than a suspicion inferred from elapsed time — a Kubernetes Lease deleted out from under its
host, say. It fires immediately whatever the clocks say, because the next write would succeed
promptly and look perfectly healthy. Like every other trigger it is latched, cleared by the
next `confirmed()`, and silent before `arm()`.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>A live host MUST appear in its own <code>view()</code>.</strong> Placement reads
    its own absence as lost membership. An <em>empty</em> view is exempt — that reads as
    solo-or-not-started, so a store failing over to a cold replica cannot fence the whole
    cluster — and absence only counts once this host has been seen in a view at all. Placement
    confirms against a fresh <code>refresh()</code> before acting.
  </div>
</div>

### Testing it

`memoryClusterHub()` can simulate both shapes of loss:

```ts
hub.kill(hostId);      // a crash the host notices — fires onSelfSuspect
hub.expire(hostId);    // a TTL lapse it is never told about
```

`expire()` is the one worth reaching for: no cleanup, no notification, exactly the case a
provider has to detect for itself.

## Membership refresh coalescing

Membership providers that support push notifications coalesce their refreshes: leading-edge
immediate, then single-flight with version-gated hint skipping, so a burst of N changes costs
one re-read rather than N per subscriber.

`coalesceMs` (default `0`) is the knob, on `redisCluster`/`redisMembership`,
`pgCluster`/`pgMembership` and `surrealCluster`/`surrealMembership`:

```ts
redisCluster({ url, coalesceMs: 50 })
```

`0` keeps the leading-edge behaviour with no trailing window — every notification that is not
already in flight refreshes immediately. Raise it when a noisy membership channel is costing
more than the staleness it saves.

Writing a custom `ClusterMembership`? `refreshCoalescer()` from `@sigx/actors/cluster` is the
same primitive: `demand()` preserves `ClusterMembership.refresh()`'s started-at-or-after
contract, and `settled()` is for teardown.

## What clustering does not change

Your actor code. Nothing in a definition knows whether it is running on one host or fifty —
placement, the directory and the transport are all host concerns.

Two things are worth knowing anyway: a
[live subscription](/actors/docs/live-reads) is never routed or redirected, so it keeps paying
the cross-host hop; and [stateless workers](/actors/docs/stateless-workers) are always local
and invisible to the directory entirely.

## Next steps

- [Placement policies](/actors/docs/placement-policies) — where new activations go.
- [Transports](/actors/docs/transports) — how hosts talk, and which to pick.
- [Locality routing](/actors/docs/locality-routing) — getting the edge to help.
- [Rebalancing](/actors/docs/rebalancing) — correcting a lumpy fleet.

---
url: https://sigx.dev/actors/docs/live-reads/
title: Live reads
description: "useActorState({ live: true }) — the actor re-runs your read after every mutating turn and pushes the result, over one connection per page"
---

# Live reads

<p class="lede">Ordinary reads refresh only the tab that wrote. `{ live: true }` is what makes a
second browser update without a reload.</p>

```ts
const messages = useActorState(RoomActor, room, 'recent', 20, { live: true });
const topic = useActorState(RoomActor, room, 'topic', { live: true });
```

The actor re-runs **the read you declared** after every turn that mutated its state — whoever
caused it — and pushes the result.

That is why the feed is per *subscription* rather than a state snapshot: `topic` is a method,
and only the actor can compute a method's result from its state. The derivation *is* the
method.

## What it costs and what it guarantees

**One connection for the whole page.** Every live read rides a single held-open NDJSON
response (`$live#subscribe`), multiplexed by subscription index, pinging every 30 seconds so
proxies and mobile NATs leave it alone. Twelve live components do not open twelve connections.

```mermaid
sequenceDiagram
    participant P as Page
    participant L as live mount
    participant R as RoomActor/lobby
    participant F as ActivityFeed/all
    P->>L: subscribe recent, topic, activity
    L->>R: watch recent, watch topic
    L->>F: watch recent
    R-->>L: chunk i=0
    R-->>L: chunk i=1
    F-->>L: chunk i=2
    L-->>P: one NDJSON response, multiplexed by index
    Note over L,P: ping every 30s while idle
```

**The first paint is unchanged.** The ordinary read still seeds the cell, SSR still serializes
it, and hydration still costs no request. `live` is purely additive — note that options go
last in the positional form, after the method arguments.

**A set change reopens the connection.** A `fetch` POST body is not duplex, so a newly mounted
component cannot be pushed onto an open stream. The channel coalesces set changes (~20 ms),
aborts, and reopens carrying the new set. Every subscription re-seeds on open, which is why a
reconnect needs no resume token.

**An unchanged value is dropped, not delivered.** Two things produce one routinely: the
re-seed above — one widget mounting must not look like the whole page updating — and the fact
that a mutating turn re-runs *every* subscription on that actor, so changing a room's topic
re-runs its `recent(20)` watch too and gets an identical list back. These are views of current
state, not an event log, so a subscriber cannot need to know that a value it already holds was
recomputed.

**It reconnects by itself.** A long-lived response dies for reasons that are nobody's bug — a
proxy timeout, a rolling restart, a laptop lid. Backoff doubles 1s → 30s with jitter and
resets on any healthy frame, and the re-seed doubles as the catch-up read.

**A dead feed degrades to "not live", never to "broken".** One subscription's failure — a
guard rejection, say — is delivered to that read alone and leaves the rest of the page live. A
read whose feed cannot be established at all keeps working as a plain read.

**A subscriber costs the actor almost nothing per turn.** A watch re-invokes the read method
and the pump reads only the iterator's `done` flag, so a subscriber whose value nobody is
waiting on receives a value-free tick and the runtime builds no snapshot for it at all. State
size is a question for your own reads, not a reason to avoid `live: true`.

**Nothing subscribes during SSR.** The subscription lives in `onMounted`.

**Security is the read's own.** A subscription runs the same policy as a unary call, at
subscribe time, so it exposes nothing a polling client could not already read. There is
deliberately **no** per-actor `live` opt-in to configure.

## Cross-host works without configuration

Each subscription dispatches through placement, so watching an actor another host owns rides
the [host-to-host transport](/actors/docs/transports). Nothing to set up.

`$live` is never routed or redirected — one held-open response fans out to many actors, so no
single actor can claim it. Two consequences worth knowing:

- The [routing token](/actors/docs/locality-routing) does not apply, so a live subscription
  keeps paying the cross-host hop even in a cluster tuned for ~100% locality.
- An open watch counts as activity, so [idle collection](/actors/docs/lifecycle) cannot
  deactivate an actor out from under a subscriber.

**Clients never connect to an actor's owning host.** Hosts relay, and the relay hop is cheap
— which is what lets the fan-out scale.

### Subscribers share one stream

Each relaying host holds **one** cross-host stream per
`(actor, method, throttleMs, args, principal)` and fans it out locally. Owner-side delivery is
therefore **O(hosts), not O(subscribers)**: the write ceiling moves *with* fleet size instead
of against it.

The shared stream is pulled at the **fastest** consumer's rate. A slower subscriber drops
oldest at a 16-value buffer, so a stalled tab cannot backpressure anyone else on the stream —
superseded live values are worthless by definition.

A shared-stream failure fails **every** subscriber on it and drops the entry. Recovery is the
`$live` channel's ordinary reconnect-and-reseed, unchanged.

Two counters report it: `remoteWatches` counts remote watch **streams**, and
`coalescedWatches` counts attaches that joined an existing one.

### Identity-dependent reads split automatically

A watch loop is shared per `(method, args, throttleMs)`, which would be wrong for a read whose
result depends on who is asking. So the runtime observes whether a read actually consults
`ctx.principal`, and **only then** splits that key's loop per encoded principal.

Reads that never touch identity keep one shared loop however many subscribers it has;
same-principal subscribers still share. There is no API for this and nothing to opt into — a
caller observes only that the value is theirs.

Distinct authenticated principals do not yet share a stream even where the read is
identity-independent in practice.

## Live reads or streams?

Use **`{ live: true }`** for *current state* — a message list, a topic, a presence count, a
score. The value is always the latest, and you never see intermediate frames.

Use a [**`streams:` method**](/actors/docs/streams) for a *feed that is not a read* — a log
tail, a progress sequence, an event history where every item matters and dropping an
unchanged one would be wrong.

## Tuning

```ts
actorsPlugin({ live: { debounceMs, retryMs, maxRetryMs, onError } });
```

A transport that brings its own `live()` channel — a WebSocket transport, say — is used
instead of the NDJSON one, with no call site changing.

### Bounding the subscription array

`$live#subscribe` caps its subscription array at **256** by default.

The mount fans out one watch per entry, all started at once, and each can force a distinct
activation pinned for `idleAfterMs`. A minimal entry is about 25 bytes, so the 1 MiB body cap
alone bought tens of thousands of activations from a single unauthenticated request — and the
per-subscription policies run *inside* that fan-out, so they never bounded it.

```ts
handleActorRequest(request, { host, maxLiveSubscriptions: 64 });
```

The option flows through `createFetchHandler` and `createAppHandler` too, and `0` disables it.
An over-cap array is a `400` for the whole request, checked before the per-entry walk —
answering per index would mean doing the work first.

Anything that is not a non-negative integer **throws**: under a plain `> 0` test a typo like
`-1` would silently turn the cap off, which is the exact state the option exists to prevent.

The cap joins the resolver cache key, so two mounts on one host with different caps do not
share whichever resolver happened to be built first.

## Under the hood

The mount is a synthesized server function, so it inherits the origin policy, codec,
`ServerFnError` masking, body caps, `onError` and the request scope. Its shape:

```
POST {base}/%24live%23subscribe
{"args":[[ {"t":"Room","k":"lobby","m":"recent","a":[20]}, … ]]}
→ {"chunk":{"i":0,"v":<encoded>}}
  {"chunk":{"i":1,"e":{message,status}}}   ← failure is per subscription
  {"chunk":{"p":1}}                        ← keepalive ping
  {"done":1}
```

An error frame carries the status the same call would have received as a unary request.

## Next steps

- [Streams](/actors/docs/streams) — when a feed is not a read.
- [Reads & writes in components](/actors/docs/in-components) — the non-live half.
- [Wire protocol](/actors/docs/wire-protocol) — reserved symbols and the endpoint.

---
url: https://sigx.dev/actors/docs/kubernetes/
title: Kubernetes
description: Deploying an actor cluster on Kubernetes — probes, the preStop and shutdown ordering, and Lease-based membership
---

# Kubernetes

<p class="lede">An actor host is an ordinary HTTP service with two unusual requirements: it
needs a startup probe, and its shutdown order matters more than most.</p>

## Membership without an extra store

[`@sigx/actors-k8s`](/actors/packages/actors-k8s/overview) implements membership on
`coordination.k8s.io` Leases — one Lease per host, `renewTime` as the heartbeat, peers
discovered by a label-selected Lease watch, and [self-fencing](/actors/docs/clustering#fencing)
when the host loses its place in membership.

```ts
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(client) },
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
});
```

You still need a directory — Leases answer *which hosts are alive*, not *which host owns this
actor*. Redis, Postgres and SurrealDB each provide one; pair the Lease membership with
whichever you already run.

RBAC needs `get`/`list`/`watch`/`create`/`update` on `leases` in the namespace. No kubeconfig
is parsed; in-cluster service-account credentials are used, and `kubectl proxy` covers local
development.

### A deleted Lease fences the host

The Lease **is** the membership token, so a renewal answering `404` fences — it does not
recreate it. By the time the Lease is gone, peers have aged the host out of their views,
`evictHost` has released every directory claim it held, and a survivor may already be serving
those actors. Recreating the Lease would re-advertise a host whose claims are forfeit, and no
elapsed-time check could catch it: the recreate succeeds promptly and everything looks
healthy.

So the host fences, liveness fails, and the restart mints a fresh identity that rejoins
cleanly.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Deleting a host's Lease by hand restarts its pod.</strong> That is the intended
    outcome, not a bug to work around — there is no silent re-registration.
  </div>
</div>

The one exception is the host's own `leave()` racing an in-flight renewal: a graceful exit,
and it never fences.

## Probes

```yaml
startupProbe:
  httpGet: { path: /_sigx/health, port: 7311 }
  failureThreshold: 30
  periodSeconds: 2
livenessProbe:
  httpGet: { path: /_sigx/health, port: 7311 }
readinessProbe:
  httpGet: { path: /_sigx/health/ready, port: 7311 }
```

> **The `startupProbe` is not optional.** Before `app.start()` the whole mount answers 503,
> *including liveness* — so without it a slow boot gets the pod killed in a loop.

The two probes are [allowed to disagree](/actors/docs/health-and-readiness), and the states
they distinguish map onto exactly what you want Kubernetes to do: a draining host stays live
and goes not-ready; a **fenced** host answers `503 {status:'fatal'}` on liveness so the pod
restarts.

## Shutdown

```yaml
terminationGracePeriodSeconds: 45
lifecycle:
  preStop:
    exec: { command: ["sleep", "10"] }
```

The `preStop` sleep gives endpoint removal time to propagate before the process starts
draining. It is necessary but **not sufficient** — connections already established survive
endpoint removal via conntrack and ride into the exiting pod.

That is why the entry must answer `connection: close` from the moment shutdown begins, and
why the [ordering](/actors/docs/clustering#shutdown-pass-the-server-not-just-the-host) is
`onStopBegin` → `host.stop()` → `server.close()`. Skipping it measured as 122 lost calls out
of ~1.7M on a rolling restart.

Set `terminationGracePeriodSeconds` above your preStop sleep plus the actor drain plus
`taskGraceMs`.

## Scaling

An HPA works normally. Two things to know:

- **New pods start cold** and attract work only as new activations are created — unless you
  run [`activationCountPolicy()`](/actors/docs/placement-policies), which reads a host with no
  known load as cold and steers to it immediately.
- **Scaling down does not move actors back.** After a scale event the fleet can stay lumpy
  indefinitely; [rebalancing](/actors/docs/rebalancing) is the correction, and it is off
  unless configured.

## What to expose

The public actor endpoint goes behind your ingress. `/_sigx/host`, `/_sigx/ops` and
`/_sigx/health*` are **internal only** — probes cannot be authenticated, and
[`ops()`](/actors/docs/ops-endpoint) is authenticated but still not something to publish.

If you configure [locality routing](/actors/docs/locality-routing), the ingress is where the
routing token gets hashed.

A worked rig — Helm chart with deployment, HPA, PDB, service, RBAC, Redis and a load
generator, plus a runbook — is `perf/aks` in the actors repo.

## Next steps

- [`@sigx/actors-k8s`](/actors/packages/actors-k8s/overview) — options and Lease anatomy.
- [Health & readiness](/actors/docs/health-and-readiness) — the three states.
- [Clustering](/actors/docs/clustering) — the shutdown sequence in full.

---
url: https://sigx.dev/actors/docs/reentrancy/
title: Reentrancy & interleaving
description: "reentrant: 'call-chain' and 'always', per-method methodReentrancy, and what interleaving changes about saves and lifecycle"
---

# Reentrancy & interleaving

<p class="lede">By default an actor is strictly serial and a call cycle back into it is a
detected deadlock. `reentrant` widens that in two steps, and `methodReentrancy` does it for one
method at a time.</p>

```ts
reentrant: 'call-chain'                  // alias: true
reentrant: 'always'                      // full interleaving, per actor
methodReentrancy: { stats: 'always' }    // full interleaving, per method
```

## The three modes

**Serial (default).** One turn at a time; `A → B → A` throws
[`ActorDeadlockError`](/actors/docs/errors). State is turn-consistent: between two `await`s
nothing else touched it.

**`'call-chain'`** (alias `true`). A cycle back into this actor runs **inline** against your
own up-stack turn instead of deadlocking. Unrelated calls still serialize, so there is no
foreign interleaving and state stays turn-consistent. This is the conservative widening: it
only unblocks the call graph you already had.

**`'always'`.** Every call is its own turn, launched immediately, so unrelated calls interleave
at every `await`.

> **What `'always'` gives up.** The single-threaded guarantee narrows to what JavaScript
> itself gives you: no two turns run *between* awaits, but **your state can change across
> every `await`**. Re-read anything another turn may have moved; do not cache it in a local
> across an await.

In-chain calls under `'always'` complete as concurrent turns rather than inline, so a
self-cycle cannot deadlock by construction.

## What re-enters, and what does not

`reentrant` governs three kinds of in-chain open, and they do not all behave alike:

| In-chain, under `'call-chain'` | Behaviour |
|---|---|
| A **method call** — `A → B → A.method()` | runs inline against the up-stack turn |
| A **stream open** — `A → B → A.someStream()` | runs inline, the same way |
| A **watch open** | throws `ActorDeadlockError` (`kind: 'deadlock'`) |

**Stream opens re-enter** because the setup is synchronous where it matters: it sets the call
context, resolves the generator and restores it with **no `await` in between** — invoking an
async generator function runs none of its body — so no other turn can interleave. Iteration is
detached from turns either way.

**Watches refuse**, and throw rather than hang. A watch is a long-lived subscription whose
reads are ordinary turns, so only its very first read could ever be inline; and the loop is
shared per `(method, args, throttleMs)`, so a subscriber joining one whose initial read is
already queued would deadlock regardless of who opened it.

No `ctx` API opens a watch, so this is a runtime guarantee rather than something an actor body
can trip over today.

## Per-method interleaving

`methodReentrancy` marks individual methods `'always'` on an otherwise serial (or
`'call-chain'`) actor:

```ts
defineActor({
    type: 'Room',
    methodReentrancy: { stats: 'always' },
    methods: (ctx) => ({
        async post(text: string) { /* slow write */ },
        async stats() { return { members: ctx.state.members.length }; },
    }),
});
```

The canonical case is a read-only method that must not queue behind a slow write — it pairs
naturally with [cacheable reads](/actors/docs/cacheable-reads).

The semantics are worth stating precisely: **a mapped method never waits and is never waited
for.** Unlisted methods keep the actor-level behaviour, including their mutual exclusion with
each other.

Constraints: keys must name real `methods:` entries; the runtime's own deliveries
(`$sigx:reminder`, `$sigx:topic`) follow the actor-level setting only; and the option is
redundant next to `reentrant: 'always'`, so that combination is refused.

## What interleaving changes elsewhere

- **Saves are single-flighted per activation.** Whole-state last-writer-wins;
  `ctx.save()` resolves once a snapshot at-or-after your mutations is durable.
- **A write-behind flush may capture mid-logical-turn state.** It is still a
  synchronously-consistent frame, but it may not be a point you would have chosen.
- **Deactivation drains all in-flight turns** before `onDeactivate` runs.
- **Turn observers see overlapping intervals** — `queuedMs` is ~0 and `elapsedMs` is run time.
  See [Metrics](/actors/docs/metrics).

## Requirements and validation

Interleaving needs `AsyncLocalStorage` for the per-turn call context. That is built into Node,
Deno and Bun; on Cloudflare Workers it rides the `nodejs_compat` flag the
[Durable Objects package](/actors/docs/cloudflare-workers) already requires. Serial actors
never touch it.

Declarations are validated at the type's first activation, loudly, in every build.
[`defineWorker`](/actors/docs/stateless-workers) accepts neither option — a stateless worker
has no state to be serial about.

## Choosing

Start serial. Reach for `'call-chain'` when you hit a legitimate cycle in your call graph, and
for `methodReentrancy` when one read is starving behind writes. Reach for `'always'` only when
you genuinely want concurrency inside one actor and are prepared to re-read state after every
`await` — at which point ask whether the thing wants to be
[several actors](/actors/docs/actor-model) instead.

## Next steps

- [Turns & concurrency](/actors/docs/turns) — the two lanes, in depth.
- [Cacheable reads](/actors/docs/cacheable-reads) — the other way to keep reads off the queue.
- [Tasks](/actors/docs/tasks) — for long work that should not hold a turn at all.

---
url: https://sigx.dev/actors/docs/transports/
title: Host transports
description: Which host-to-host transport to use — the measured table, why HTTP stays the default, and the two caveats to carry
---

# Host transports

<p class="lede">How hosts talk to each other is a seam. HTTP is the default and the only
portable option; TCP collapses connection count on Node.</p>

```ts
cluster({ providers, advertise, secret, transport: httpTransport({ fetch: tuned }) });
```

## The measured comparison

| | Portable? | Connections per peer | Relative throughput |
|---|---|---:|---:|
| `httpTransport()` **(default)**, unbounded pool | **everywhere, incl. Workers** | 2 × concurrency | 0.9× |
| `httpTransport()` with a bounded pool | **everywhere, incl. Workers** | concurrency | 1.0× (baseline) |
| [`tcpTransport()`](/actors/packages/actors-tcp/overview) | Node only | **1** | 4.9× |

Throughput is relative to **bounded** HTTP, because that is the fair baseline — the shipped
default is the first row, and bounding it is a free improvement.

**On Node, prefer TCP.** It is the socket transport for hosts.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>This page is about host-to-host traffic.</strong> The transport a
    <em>browser</em> uses to reach a host is a different seam —
    <a href="/actors/docs/client"><code>fetchTransport()</code></a> by default, or
    <a href="/actors/packages/actors-ws/overview"><code>socketTransport()</code></a> from
    <code>@sigx/actors-ws</code>. The two never meet.
  </div>
</div>

**HTTP stays the default, and must.** `@sigx/actors/cluster` is zero-dependency and
WinterCG-clean so Cloudflare Workers keep working, and HTTP is the only transport that runs
everywhere.

## Two caveats worth carrying

> **The throughput ratio is a loopback *software* number.** TCP is ~70µs/call against ~14µs —
> a 56µs difference that a real LAN round trip of 200–1000µs largely absorbs. On a real
> network that is about **1.1×, not 4.9×**. Do not publish "4.9× faster" unqualified.

The **connection-count** win is the one that survives a real network, and it is usually the
reason to move: at concurrency 64 across 99 peers, HTTP wants roughly 12,600 sockets per host.
TCP wants 99.

## Bounding the HTTP pool

Node's global `fetch` uses an unbounded undici pool. Bounding it is the cheapest improvement
available:

```ts
import { Agent, fetch as undiciFetch } from 'undici';

const agent = new Agent({ connections: 64 });   // match per-peer concurrency

cluster({
    providers, advertise, secret,
    transport: httpTransport({
        fetch: (url, init) => undiciFetch(url, { ...init, dispatcher: agent }),
    }),
});
```

**Match `connections` to your per-peer concurrency.** Measured against undici 7.x — what
current Node bundles — at concurrency 64: the unbounded default opens 128 sockets;
`connections: 64` opens 64 and runs **6% faster**; `connections: 8` costs about 3× throughput;
`connections: 1` costs ~57%.

So halving the sockets is free, and going below your concurrency trades throughput steeply —
worth it only when file descriptors are the real constraint.

> These numbers are **undici-major-specific**. Figures measured on undici 8.x do not hold.

**HTTP/2 does not help, and it is worth knowing why before you try it.** `allowH2: true`
measures identical to plain keep-alive at every pool size, because `createAppHandler` serves
over `node:http` — HTTP/1.1 only — so the client negotiates nothing and falls back.
Multiplexing would need a `node:http2` server first: a much larger change than the pool cap,
for the same reduction in sockets.

`undici` is a **recipe, not an API** — it is not a dependency of `@sigx/actors`.

## Fallback chains make adoption safe

```ts
transport: [tcpTransport({ port: 11111 }), httpTransport()];
```

A transport publishes its peer-reachable address under `addresses[name]` in the host
descriptor, and a list is tried in order. Mid-deploy, hosts advertising the new transport use
it and the rest are reached over HTTP — no window of unreachability.

A descriptor without `addresses` reads as HTTP-only. A **single** transport is strict: a peer
advertising no address for it is unreachable, loudly. That is deliberate — a silent fallback
means you deploy a transport, benchmark it, and measure the old one without knowing.

Fallbacks that do occur are counted (`counters().transportFallbacks`), reported in the host
report, and dev-warned once per peer.

> **A socket-only cluster has no internal HTTP endpoint at all.** `/_sigx/host` is just a
> route a transport declares, so dropping `httpTransport()` from the chain removes it —
> smaller attack surface, nothing to `curl`. Ops runbooks that poke that path are assuming the
> HTTP transport.

The public actor wire is unaffected by any of this.

## Writing one

`transportConformance` holds the cases a transport must pass — supply a harness that builds an
N-host cluster over your wire and every case runs against it. The rule it enforces throughout
is *assert on the error `kind`, never on an HTTP status*, which is what makes the contract
expressible off HTTP at all.

It is currently **contributor-facing only**: reachable inside the actors workspace as
`@sigx/actors/cluster/testing` through a tsconfig and vitest alias, but not in the published
`exports` map, so an out-of-repo package cannot import it yet.

The frame codec, however, **is** published:
[`@sigx/actors/cluster/frames`](/actors/docs/entry-points) carries it, including the
message-oriented `FrameLink` variant. A WebSocket host-to-host transport, or anything else
message-shaped, can be built on it outside this repo.

## Next steps

- [TCP transport](/actors/packages/actors-tcp/overview) — the Node default choice.
- [Clustering](/actors/docs/clustering) — where the transport plugs in.
- [The client](/actors/docs/client) — the other seam, browser to host.

---
url: https://sigx.dev/core/docs/installation/
title: Installation
description: How to install SignalX in your project
---

# Installation

SignalX can be installed in several ways depending on your project setup.

## Create a New Project

The fastest way to get started is with our CLI:

```bash
npm create @sigx@latest my-app
```

This will scaffold a new project with:
- Vite for development and building
- TypeScript configuration
- SignalX and the Vite plugin pre-configured

## Add to Existing Project

### Using npm

```bash
npm install sigx @sigx/vite
```

### Using pnpm

```bash
pnpm add sigx @sigx/vite
```

### Using yarn

```bash
yarn add sigx @sigx/vite
```

## Configure Vite

Add the SignalX plugin to your Vite configuration:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { sigxPlugin } from '@sigx/vite';

export default defineConfig({
    plugins: [sigxPlugin()],
});
```

## TypeScript Configuration

For the best TypeScript experience, update your `tsconfig.json`:

```json
{
    "compilerOptions": {
        "jsx": "preserve",
        "jsxImportSource": "sigx",
        "moduleResolution": "bundler"
    }
}
```

## Package Versions

SignalX follows semantic versioning. The versions below are pulled from npm at build time, so they track the current `latest` release without hand-editing (falling back to the last committed values if npm is unreachable):

| Package | Version | Description |
|---------|---------|-------------|
| `sigx` |  | Core runtime |
| `@sigx/vite` |  | Vite plugin |
| `@sigx/router` |  | Client-side router |
| `@sigx/store` |  | State management |
| `@sigx/daisyui` |  | UI components |

## Development and Production Builds

Every SignalX package ships **two** builds:

- `dist/*.js` — the **development** build: dev warnings, the devtools integration, and runtime `process.env.NODE_ENV` checks.
- `dist/*.prod.js` — the **production** build: warnings and the devtools plumbing are compiled out.

Bundlers pick the right one automatically through the `development` / `production` [export conditions](https://nodejs.org/api/packages.html#conditional-exports) — **Vite needs no configuration**. A `vite build` resolves the production build; `vite dev` resolves the development build. Resolvers that don't understand those conditions fall back to the development build, where a consumer-side `NODE_ENV` define still strips the dev branches — the same behavior as before.

For **plain Node SSR** (running the server renderer outside a bundler), opt into the stripped build with the `production` condition:

```bash
node --conditions=production server.js
```

There's nothing to configure in your app — devtools and dev-only warnings simply disappear from production output.

## Next Steps

- [Quick Start](/core/docs/getting-started) - Build your first component
- [Signals](/core/docs/signals) - Learn about reactive state

---
url: https://sigx.dev/core/docs/lazy-loading/
title: Lazy Loading
description: Code splitting and async component loading in SignalX with lazy() and Defer
---

# Lazy Loading

SignalX provides built-in support for code splitting through `lazy()` and `<Defer>`. Load components on demand to reduce initial bundle size and improve performance.

`<Defer>` is the one tree-positional async wrapper, and its fallback covers **lazy chunk loading** — code-splitting. It is not a data-loading wrapper: a pending `useData` read renders through its own component's `match()` (value-first), never through a wrapper. See [Data loading](/core/docs/data-loading) for that side.

## Lazy Loading Components

Use `lazy()` to create a component that loads on first render:

```tsx
import { lazy, Defer } from 'sigx';

// Component will be loaded when first rendered
const HeavyChart = lazy(() => import('./components/HeavyChart'));

// Usage with Defer
function App() {
    return (
        <Defer fallback={<div>Loading chart...</div>}>
            <HeavyChart data={chartData} />
        </Defer>
    );
}
```

The `lazy()` function accepts an import function and returns a component that:
- Loads the component module on first render
- Renders `null` while the chunk loads — the nearest enclosing `<Defer>` shows its fallback
- Renders the component in place once loaded
- Caches the loaded component for subsequent renders

Registration is deterministic: a lazy wrapper registers its load promise with the nearest `<Defer>` at **setup** time (before its own children set up), so there is no thrown-promise protocol and no render-ordering to reason about.

## Defer Boundaries

`<Defer>` components define loading boundaries in your component tree:

```tsx
import { lazy, Defer, component } from 'sigx';

const Dashboard = lazy(() => import('./Dashboard'));
const Charts = lazy(() => import('./Charts'));
const Reports = lazy(() => import('./Reports'));

const App = component(() => {
    return () => (
        <div class="app">
            {/* Each section can load independently */}
            <Defer fallback={<Skeleton type="dashboard" />}>
                <Dashboard />
            </Defer>

            <div class="grid">
                <Defer fallback={<Skeleton type="chart" />}>
                    <Charts />
                </Defer>

                <Defer fallback={<Skeleton type="report" />}>
                    <Reports />
                </Defer>
            </div>
        </div>
    );
});
```

The children stay mounted while a chunk loads (a pending lazy renders `null`), so sibling state survives and the resolved component appears in place.

### Fallback Options

The `fallback` prop accepts either a JSX element or a function:

```tsx
// Static fallback
<Defer fallback={<Spinner />}>
    <LazyComponent />
</Defer>

// Dynamic fallback (called on each render)
<Defer fallback={() => <Spinner size={spinnerSize} />}>
    <LazyComponent />
</Defer>
```

### Nested Defer

Multiple lazy components under the same `<Defer>` wait together:

```tsx
<Defer fallback={<Loading />}>
    {/* Both chunks must load before content shows */}
    <LazyHeader />
    <LazyContent />
</Defer>
```

Nest `<Defer>` boundaries for more granular loading states:

```tsx
<Defer fallback={<AppSkeleton />}>
    <LazyLayout>
        <Defer fallback={<ContentSkeleton />}>
            <LazyContent />
        </Defer>
    </LazyLayout>
</Defer>
```

On the server, `<Defer>` streams its fallback with the shell and swaps in a single replacement once everything pending beneath it — chunks **and** keyed data — resolves.

## Preloading Components

Lazy components expose a `preload()` method to start loading before render:

```tsx
const HeavyEditor = lazy(() => import('./HeavyEditor'));

// Preload on hover
<button onMouseEnter={() => HeavyEditor.preload()}>
    Open Editor
</button>

// Or preload on route navigation
router.beforeEach((to) => {
    if (to.path === '/editor') {
        HeavyEditor.preload();
    }
});
```

## Checking Load Status

Use `isLoaded()` to check if a lazy component has finished loading:

```tsx
const LazyComponent = lazy(() => import('./Component'));

// Check status
if (LazyComponent.isLoaded()) {
    console.log('Component is ready');
}

// Useful for conditional logic
function showStatus() {
    return LazyComponent.isLoaded()
        ? 'Ready'
        : 'Loading...';
}
```

## API Reference

### `lazy(loader)`

Creates a lazy-loaded component wrapper.

| Parameter | Type | Description |
|-----------|------|-------------|
| `loader` | `() => Promise<Component>` | Function returning a dynamic import |

**Returns:** `LazyComponentFactory` - Component with `preload()` and `isLoaded()` methods

```tsx
// Default export
const Comp = lazy(() => import('./Component'));

// Named export
const Comp = lazy(() =>
    import('./Components').then(m => m.SpecificComponent)
);
```

### `Defer`

Wrapper that shows fallback content while lazy children load.

| Prop | Type | Description |
|------|------|-------------|
| `fallback` | `JSXElement \| () => JSXElement` | Content to show while a chunk beneath it loads |

### `isLazyComponent(component)`

Check if a component is a lazy-loaded component.

```tsx
import { isLazyComponent } from 'sigx';

if (isLazyComponent(SomeComponent)) {
    SomeComponent.preload();
}
```

## Error Handling

If a chunk fails to load, the lazy wrapper throws the load error from render — it routes through the standard error path (the nearest [`errorScope`](/core/docs/error-handling), then `app.onError`), exactly like any render throw:

```tsx
import { component, errorScope, lazy, Defer } from 'sigx';

const FailingComponent = lazy(() => import('./Broken')); // this import fails

const Section = component(() => {
    errorScope({ fallback: (e, retry) => <LoadFailed error={e} retry={retry} /> });

    return () => (
        <Defer fallback={<Loading />}>
            <FailingComponent />
        </Defer>
    );
});
```

`retry` remounts the subtree, so it re-attempts the import from a clean slate. See [Error handling](/core/docs/error-handling) for the full model.

## Best Practices

1. **Route-level splitting** - Lazy load page components for the biggest impact:
   ```tsx
   const routes = [
       { path: '/', component: lazy(() => import('./pages/Home')) },
       { path: '/dashboard', component: lazy(() => import('./pages/Dashboard')) },
   ];
   ```

2. **Preload on intent** - Start loading before the user needs it:
   ```tsx
   <Link
       href="/dashboard"
       onMouseEnter={() => DashboardPage.preload()}
   >
       Dashboard
   </Link>
   ```

3. **Group related components** - Put related lazy components under one `<Defer>`:
   ```tsx
   <Defer fallback={<DashboardSkeleton />}>
       <DashboardHeader />
       <DashboardCharts />
       <DashboardTable />
   </Defer>
   ```

4. **Meaningful fallbacks** - Use skeleton screens that match the content layout:
   ```tsx
   <Defer fallback={<TableSkeleton rows={10} columns={5} />}>
       <LazyDataTable />
   </Defer>
   ```

## Next Steps

- [Data loading](/core/docs/data-loading) - `useData`, `useAction`, `all`
- [Error handling](/core/docs/error-handling) - `errorScope` and `app.onError`
- [Portal](/core/docs/portal) - Render content outside the component tree
- [Components](/core/docs/components) - Component patterns and best practices

---
url: https://sigx.dev/i18n/docs/installation/
title: Installation
description: Install @sigx/i18n, its entry points, and the Vite plugin that generates types from your catalogs
---

# Installation

<p class="lede">Install the package, install the plugin on your app, and — optionally — add the Vite plugin that types your catalogs.</p>

```bash
pnpm add @sigx/i18n
```

<p class="mod-meta-row"></p>

## Entry points

| Import path | Use it for |
|---|---|
| `@sigx/i18n` | Everything an app needs — `createI18n`, `useTranslation`, `<T>`, detection, the store |
| `@sigx/i18n/server` | Request-side translation: `createServerT`, `forLocale`, the SSR state seam |
| `@sigx/i18n/server/node` | The Node flavour of the above |
| `@sigx/i18n/vite` | The build plugin — catalog scanning, type generation, the consistency check |
| `@sigx/i18n/virtual` | Types for the generated virtual module |

**No `sigx` dependency.** The package never imports the DOM umbrella — not even as an optional peer — so it is importable from a lynx or terminal app without dragging the DOM JSX intrinsics into your program. See [renderer-neutral](/i18n/docs/overview#it-is-renderer-neutral).

**No `Intl` requirement either.** The default formatter resolves interpolation, plurals and selects without `Intl`, so the package works on engines that do not ship it — lynx/PrimJS among them. See [`Intl` is optional too](/i18n/docs/overview#intl-is-optional-too).

## Install the plugin

```tsx
import { defineApp } from 'sigx';
import { createI18n } from '@sigx/i18n';

const app = defineApp(<Root />).use(createI18n({
    fallbackLocale: 'en',
    supported: ['en', 'sv'],
    namespaces: ['common'],
    load: (target, locale, ns) => import(`./locales/${target}/${locale}/${ns}.json`),
}));
```

The store itself is created lazily on the first `useI18n()` / `useTranslation()` **during render** — so under SSR it is constructed inside the request render and its state registration attaches to the correct per-request context.

## The Vite plugin

```ts
// vite.config.ts
import { i18n } from '@sigx/i18n/vite';

export default {
    plugins: [i18n({ localesDir: 'src/locales', masterLocale: 'en' })],
};
```

It scans the catalog tree, generates a `.d.ts` so namespaces and keys are typed, and reports catalogs that have drifted from the master locale. Rewrites happen only when the content changed.

`runI18nCheck`, `writeI18nTypes`, `checkCatalogs` and `formatReport` are exported for wiring the same check into CI without running a build.

## Without a client app

`@sigx/resume` upgrades a boundary by hydrating its component directly — there is no client app, so nothing installed `createI18n` and DI has nothing to resolve. Call `provideI18nConfig` from a module the translating boundary's chunk imports:

```ts
// src/i18n.ts — imported by the app entry AND by resumable components
export const i18nOptions = { fallbackLocale: 'en', supported: ['en', 'sv'], load };
provideI18nConfig(i18nOptions);
```

This is **client-only by design**, and a no-op on the server. A server-side config would be shared by every request in a long-lived process, and detection context is per-request — so on the server, install the plugin, which is per-app and per-request correct.

## Next steps

- [Translating](/i18n/docs/usage) — `useTranslation`, `<T>`, plurals and rich text.
- [Locales](/i18n/docs/locales) — detection, switching and persistence.

---
url: https://sigx.dev/core/docs/data-loading/
title: Data Loading
description: Load async data with useData, run writes with useAction, combine with all, and stream text with useStream — SSR-aware with automatic hydration state transfer
---

# Data Loading

SignalX is **value-first**: an async read returns reactive state you render through, not a promise you throw to a wrapper. There is no loading wrapper and no thrown-promise protocol — a component owns its own pending and error branches and renders them with `match()`.

Three primitives cover it, all imported from `'sigx'` and called synchronously during component setup:

- **`useData(key, fetcher)`** — a keyed read. Auto-runs, SSR-transferable, deduped.
- **`useAction(fn)`** — a write. Runs on demand via `.run(input)`; never auto-runs.
- **`all(...)`** — combine several reads into one all-or-nothing state.

Plus **`useStream(key, source)`** for progressive, token-at-a-time text.

## useData

Every read has a **key** — data always has identity. The key is the reactive trigger, the cache / SSR identity, and the fetcher's input, all at once. The fetcher runs untracked; only the key getter is reactive, so anything that should re-run the fetch belongs in the key.

`useData` returns a reactive `AsyncState<T>` with a `state` of `idle | pending | ready | refreshing | errored`, the last-good `value`, a `hasValue` flag, the `error`, a `loading` flag (`state === 'pending'` only), a `match()` dispatcher, and a `refresh()` method. It is a discriminated union, so `if (q.state === 'ready')` or `if (q.hasValue)` narrows `value` to `T` with no cast.

```tsx
import { component, render, useData } from 'sigx';

const Joke = component(() => {
    const joke = useData('joke', async (key, { signal }) => {
        const res = await fetch('https://icanhazdadjoke.com/', {
            headers: { Accept: 'application/json' },
            signal,
        });
        return (await res.json()).joke as string;
    });

    return () => (
        <div style="padding: 16px;">
            {joke.match({
                pending: () => <p>Loading…</p>,
                error: (e, { retry }) => (
                    <p>Failed: {e.message} <button onClick={retry}>Retry</button></p>
                ),
                ready: (text) => <p>{text}</p>,
            })}
            <button
                onClick={() => joke.refresh()}
                disabled={joke.loading || joke.state === 'refreshing'}
            >
                Another one
            </button>
        </div>
    );
});

render(<Joke />, "#sandbox");
```

The fetcher receives the resolved key as its first argument and an `AbortSignal` on the context — pass it straight to `fetch`. The signal aborts only when this cell is the fetch's sole consumer and the run is superseded (keyed fetches may be shared, so they de-dupe rather than abort).

### match — the value-first render

`match()` is the type-safe way to render every state at once. The `ready` arm is the only route to a **present** `T`:

| Arm | When | Notes |
|---|---|---|
| `idle` | conditional fetch not started | defaults to `pending` if omitted |
| `pending` | nothing to show yet | omitted ⇒ renders nothing while pending |
| `error(e, ctx)` | fetch failed | `ctx.retry` re-runs; `ctx.value`/`ctx.hasValue` are the last-good (for "keep content + toast"); omitted ⇒ bubbles to an [error scope](/core/docs/error-handling) |
| `ready(value)` | the happy path | **required** |

The error arm's second parameter is a **context object**, not positional arguments — destructure what you need:

```tsx
error: (e, { retry }) => <Banner error={e} onRetry={retry} />,

// The last-good value, if the cell ever had one:
error: (e, ctx) => (
    <>
        <Banner error={e} onRetry={ctx.retry} />
        {ctx.hasValue && <Table rows={ctx.value} />}
    </>
),
```

You never have to use `match` — `state`, `value`, `error` and `loading` are plain reactive reads — but it keeps the four states exhaustive.

### An error keeps the last-good value

`value` survives a failed fetch. A cell that succeeded once and then errored still
holds its data, so content next to an error banner stays on screen instead of
blanking — the SWR posture. `'errored'` splits on `hasValue`: a cell that never
succeeded has `value: null`, `hasValue: false`.

Two consequences worth knowing:

- **`q.error && !q.value` no longer means "errored"**, because an errored cell may
  well have a value. To blank deliberately, check `q.state === 'errored'`.
- **Retrying from errored-after-success goes to `'refreshing'`, not `'pending'`** —
  no skeleton flash over content the user can still see.

### Presence is not the value

`value` is not a presence signal. A fetch that legitimately resolves `null` — a
"not found" read — has a value, and `ready` is the correct arm for it. Presence
is `state` (`'ready'` or `'refreshing'`) or the `hasValue` flag:

```tsx
const profile = useData(() => ['profile', props.id], loadProfile);

// A nullable T reaches `ready` with null, and stays there across a refresh.
profile.match({
    pending: () => <Skeleton />,
    ready: (p) => p ? <Profile data={p} /> : <p>No profile yet</p>,
});

// The flag, when you're reading the cell directly rather than matching.
if (profile.hasValue) { /* value is what the fetcher returned, null included */ }
```

Because presence is tracked separately, a cell holding `null` moves to
`refreshing` on `refresh()` rather than back to `pending`, so the content on
screen survives a background revalidate.

`hasValue` is on every `AsyncState` — `useData` cells, [`@sigx/cache`](/core/packages/cache/overview) cells, `all()` and SSR-side state.

There is no need to wrap a nullable result in an envelope to survive SSR
transfer. The `__SIGX_ASYNC__` transfer is presence-based — own-key membership —
so a transferred `null` or `undefined` round-trips as a hit.

### Reactive keys

Pass a getter to make the key reactive. Return a string or a tuple; a falsy result skips the fetch and holds the read in `idle` (for "type to search" and other conditional reads):

```tsx
// re-fetches whenever props.id changes; tuple keys serialize to canonical JSON
const user = useData(() => ['user', props.id], async ([, id], { signal }) => {
    const res = await fetch(`/api/users/${id}`, { signal });
    return res.json();
});

// conditional: no fetch until the box has text
const results = useData(() => query.value && ['search', query.value], searchApi);
```

A tuple exists to carry parameters, so a *static* tuple is rejected by design — a static key is a plain string; parameters that change belong in a reactive getter.

### Stale-while-revalidate with refresh

`refresh()` re-runs the fetcher **in place**. It keeps the current `value` visible and moves `state` to `refreshing` (not `pending`), so a revalidation indicator reads `state === 'refreshing'` while the ready arm keeps rendering. It never rejects — a failed refresh lands on `.error`:

```tsx
const feed = useData('feed', loadFeed);

<button onClick={() => feed.refresh()} disabled={feed.state === 'refreshing'}>
    {feed.state === 'refreshing' ? 'Refreshing…' : 'Refresh'}
</button>
```

A **key change** is different: it's a hard reset — `value` is cleared and `state` returns to `pending`, so a wrong-key value never flashes.

### SSR + hydration

A **static** string key makes the read SSR-transferable automatically:

```tsx
import { component, useData } from 'sigx';

const UserProfile = component<{ id: string }>(({ props }) => {
    const user = useData(`user:${props.id}`, async (key, { signal }) => {
        const res = await fetch(`/api/users/${props.id}`, { signal });
        return res.json();
    });

    return () => user.match({
        pending: () => <p>Loading…</p>,
        ready: (u) => <h1>{u.name}</h1>,
    });
});
```

With a static (or resolved reactive) key, `useData`:

- **Runs on the server**, serializing the resolved value under the key into [`window.__SIGX_ASYNC__`](/core/docs/advanced/globals) — a prototype-pollution-safe, page-lifetime cache the server renderer emits. It is **readable from the browser console**, so return only what the page renders; see [what the page exposes](/core/docs/advanced/globals#what-the-page-exposes-is-yours-and-unfiltered).
- **Restores on hydration** from that cache — no refetch on first client render.
- **Dedupes per key** — two components with the same key share one in-flight request and one cached value.

Pass `{ server: false }` for a client-only keyed read: SSR renders the pending arm and the fetch runs after hydration. It still keeps its key for dedupe and future cache coverage — there is no unkeyed form.

### Server functions as keys

A [server function](/server/packages/server/overview) already carries a stable identity, so it *is* a key. Pass one straight to `useData` and the function is both the key and the fetcher — no string to invent, no fetcher to write:

```tsx
import { useData } from 'sigx';
import { getVotes } from './votes.server';

const votes = useData(getVotes);          // the fn is the key and the fetcher
```

For arguments, return a `[fn, ...args]` tuple from a getter. It's reactive and idle-skips on a falsy result, exactly like a normal tuple key:

```tsx
const post = useData(() => [getPost, props.id]);   // re-runs when props.id changes
```

The build stamps each server function with a stable key derived from its id and name, so these reads are SSR-transferable and deduped just like string-keyed ones. (Move a function between files without pinning an explicit `id` and its key changes — set `id` on anything you invalidate by reference.)

To refresh a server-function read after a write, declare what it invalidates **by reference** — a bare server-function reference prefix-matches every parameterized read of it, and the same declaration drives single-flight refresh of the server boundaries that rendered it. That declaration can live on the server function's own [options](/server/packages/server/usage) (its `invalidates`, which runs on every transport) or on a client action via [`@sigx/cache`](/core/packages/cache/overview); with neither, refresh the read explicitly with `.refresh()` (below).

### What invalidates reaches

An `invalidates` pattern matches a read's **canonical key**, and that is the
whole rule. A pattern is an exact key string, a tuple prefix, or a bare
server-function reference that matches every read of that function:

```ts
export const addItem = serverFn({
    input: ItemInput,
    handler,
    invalidates: () => [getCart],        // every useData(getCart) read
});
```

Every mounted `useData` read whose key matches is refetched — a read needs no
`cache` option to be reachable, and no cache pack has to be installed. A pattern
that matches nothing warns in development rather than failing silently.

> Reading and writing an **actor** works the same way, with its own pair of
> composables — `useActorState` and `useActorAction` from
> [`@sigx/actors`](/actors/) — built on these primitives, so a write
> invalidates the reads it staled without a manual `refresh()`. See
> [Reads & writes in components](/actors/docs/in-components).

Invalidation also drops matching keys from the `__SIGX_ASYNC__` transfer blob.
Keys transferred from SSR live for the page's lifetime and a fresh mount restores
from them as `ready` without fetching, so clearing them is what makes leaving a
route and coming back show the post-mutation value.

## useAction

`useAction` is the write counterpart: the manual sibling of `useData` that never auto-runs. Trigger it with `.run(input)`. `run` **never rejects** — it resolves a settled `RunResult<T>` (`{ ok: true, value }` or `{ ok: false, error }`), so both fire-and-forget and `const r = await save.run()` are safe.

```tsx
import { component, useAction } from 'sigx';

const SaveButton = component<{ draft: Draft }>(({ props }) => {
    const save = useAction(async (draft: Draft, { signal }) => {
        const res = await fetch('/api/save', { method: 'POST', body: JSON.stringify(draft), signal });
        if (!res.ok) throw new Error('Save failed');
        return res.json();
    });

    return () => (
        <button
            disabled={save.loading}
            onClick={async () => {
                const r = await save.run(props.draft);
                if (r.ok) toast('Saved'); else toast(r.error.message);
            }}
        >
            {save.loading ? 'Saving…' : 'Save'}
        </button>
    );
});
```

An action exposes `state` (`idle | pending | ready | errored`), `value` (last success — a search box renders from this), `error`, `loading` (`state === 'pending'`, the blessed double-submit guard), `match()`, `run(input)`, and `reset()`.

In-flight writes are **never aborted** — an aborted POST is not an undone POST. A newer `run()` or a `reset()` only supersedes the *observation*: the older run's promise resolves `{ ok: false, error: SupersededError }` and never writes state. `reset()` returns the action to `idle`, clearing value and error (dismiss a success message, reuse a form).

Cross-read invalidation is explicit — after a successful write, refresh the reads it affects:

```tsx
const r = await save.run(draft);
if (r.ok) user.refresh();   // re-pull the read this write invalidated
```

## all

`all()` combines several `AsyncState`s into one — a single `match` for a whole dashboard. It's a pure derived view (no fetching), with named or positional forms:

```tsx
import { useData, all } from 'sigx';

const user = useData(`user:${id}`, loadUser);
const posts = useData(`posts:${id}`, loadPosts);

const page = all({ user, posts });          // named: page.value.user, page.value.posts
// const page = all(user, posts);           // positional: page.value[0], page.value[1]

return () => page.match({
    pending: () => <Spinner />,
    error: (e) => <Error error={e} />,
    ready: ({ user, posts }) => <Dashboard user={user} posts={posts} />,
});
```

The combined state follows all-or-nothing rules: any member `idle` ⇒ `idle` (a conditional member holds the gate); else any `errored` ⇒ `errored`; else any `pending` ⇒ `pending` (until all first settle); else any `refreshing` ⇒ `refreshing` (values exist, so the ready arm keeps rendering); else `ready`. `.error` is first-error-wins; `.errors` collects them all (named or positional to match). Partial loading — where each section shows its own spinner — wants independent `match` calls instead.

## useStream

`useStream(key, source)` accumulates a streamed `AsyncIterable<string>` into a reactive string — built for progressive, token-at-a-time content like LLM output. It returns a `{ value }` signal that grows as chunks arrive:

```tsx
import { component, useStream } from 'sigx';

const Answer = component<{ prompt: string }>(({ props }) => {
    const answer = useStream(`answer:${props.prompt}`, () => streamCompletion(props.prompt));

    return () => <p>{answer.value}</p>;
});
```

Like a keyed `useData`, `useStream` is SSR-aware:

- **Server, streaming:** tokens append into the page as they arrive; the final text swaps in through the replacement pipeline and is serialized under the key.
- **Server, blocking:** the source is drained fully and the final text is rendered inline.
- **Client, hydrating:** the final text is restored from the key — the source is **not** re-run, so there are no duplicate calls.
- **Client navigation:** the source runs live and the signal updates per chunk.

`useStream` is text-only, and the appended tokens are XSS-safe by construction (text nodes, never raw HTML). It stops pulling from the source when the component unmounts.

## Errors

Fetcher rejections are **values**, not throws: they land on `.error` and render through the `error` arm of `match()`. When you omit the `error` arm, the error bubbles to the nearest [`errorScope`](/core/docs/error-handling), then to the app's `onError` handler — so uncaught data errors still surface without wrapping every read. See [Error handling](/core/docs/error-handling) for the full model.

## Server rendering

The server side of keyed data loading is owned by `@sigx/server-renderer`'s document renderers (`renderDocument` and friends), which run the fetchers, inject the `window.__SIGX_ASYNC__` state blob, and stream replacements. See the [server renderer guide](/server) for the document-rendering APIs; from a component's point of view, `useData` / `useAction` / `useStream` are all you import.

## Caching

Everything above is core's *mechanism* — keyed reads, dedup, SSR transfer, and key-addressable refresh. Freshness and retention are **policy**, and policy lives in a pack. Add [`@sigx/cache`](/core/packages/cache/overview) and the same `useData`/`useAction` gain a `cache` option: `staleTime`, focus and interval revalidation, `keepPreviousData`, cache-aware `invalidate()` and optimistic `mutate()` — one plugin, no change to your call sites.

```tsx
const user = useData('user', fetchUser, {
    cache: { staleTime: 60_000, revalidateOnFocus: true },
});
```

## Next Steps

- [Cache policy](/core/packages/cache/overview) - `staleTime`, revalidation and optimistic writes with `@sigx/cache`
- [Error handling](/core/docs/error-handling) - `errorScope` and `app.onError`
- [Lazy Loading](/core/docs/lazy-loading) - Code-split components with `Defer`
- [Effects](/core/docs/effects) - React to signal changes
- [Components](/core/docs/components) - Component model and patterns

---
url: https://sigx.dev/lynx/docs/installation/
title: Installation
description: Install SignalX Lynx and set up the native toolchain
---

# Installation

<p class="lede">Scaffold a Lynx app with the SignalX CLI, or add Lynx rendering to an existing SignalX project.</p>

## Prerequisites

- Node.js 20.19+ (or 22.12+)
- For iOS: Xcode + an iOS simulator
- For Android: Android Studio + an emulator

## New project

```bash
npm create @sigx@latest my-app -- --template lynx
cd my-app
pnpm install
```

## Existing project

```bash
pnpm add @sigx/lynx @sigx/lynx-plugin
pnpm add -D @sigx/lynx-cli
```

The CLI plugin registers the `dev`, `build`, `prebuild`, `doctor` and `run:ios` / `run:android` commands; the build plugin splits your source into the background + main-thread bundles Lynx requires.

## Verify the toolchain

```bash
sigx doctor
```

`doctor` checks your native toolchains and reports anything missing.

## Next steps

Continue with [your first app](/lynx/docs/your-first-app).

---
url: https://sigx.dev/router/docs/navigation/
title: Navigation
description: Learn how to navigate programmatically with @sigx/router
---

# Navigation

SignalX Router provides multiple ways to navigate between routes.

## RouterLink Component

The declarative way to navigate:

```tsx
import { RouterLink } from '@sigx/router';

// Basic link
<RouterLink to="/about">About</RouterLink>

// With query parameters
<RouterLink to="/search?q=hello">Search</RouterLink>

// With route object
<RouterLink to={{ path: '/users', query: { page: '1' } }}>
    Users
</RouterLink>
```

### Active State

RouterLink automatically applies classes when the route is active:

```tsx
<RouterLink 
    to="/about"
    class="nav-link"
    activeClass="nav-link-active"
    exactActiveClass="nav-link-exact"
>
    About
</RouterLink>
```

## Programmatic Navigation

Use `useRouter` for programmatic navigation:

```tsx
import { component } from 'sigx';
import { useRouter } from '@sigx/router';

const LoginForm = component(() => {
    const router = useRouter();
    
    const handleLogin = async () => {
        await performLogin();
        router.push('/dashboard');
    };
    
    return () => (
        <button onClick={handleLogin}>Login</button>
    );
});
```

### Navigation Methods

```tsx
const router = useRouter();

// Navigate to a path
router.push('/users');

// Navigate with params
router.push('/users/123');

// Navigate with query
router.push({ path: '/search', query: { q: 'hello' } });

// Replace current entry (no history)
router.replace('/login');

// Go back
router.back();

// Go forward
router.forward();

// Go to specific history entry
router.go(-2);
```

## Accessing Route Information

Use `useRoute` to access current route information:

```tsx
import { component } from 'sigx';
import { useRoute } from '@sigx/router';

const UserProfile = component(() => {
    const route = useRoute();
    
    return () => (
        <div>
            <p>Path: {route.path}</p>
            <p>User ID: {route.params.id}</p>
            <p>Query: {JSON.stringify(route.query)}</p>
        </div>
    );
});
```

Route properties are reactive - they update automatically when navigation occurs.

## Scroll Restoration

By default, the router does not manage scroll behavior. To enable scroll restoration — scroll-to-top on push, scroll-restore on back/forward, and hash-to-element scrolling — provide a `scrollBehavior` callback in router options:

```tsx
import { createRouter, createWebHistory } from '@sigx/router';

const router = createRouter({
    history: createWebHistory(),
    routes,
    scrollBehavior(to, from, savedPosition) {
        // Back/forward navigation — restore previous scroll position
        if (savedPosition) return savedPosition;
        // Hash navigation — scroll to the target element
        if (to.hash) return { el: to.hash };
        // New navigation — scroll to top
        return { top: 0 };
    },
});
```

The `savedPosition` parameter is `{ left, top }` when navigating with the browser back/forward buttons, and `null` for push/replace navigations. The router automatically saves and restores scroll positions across the history stack.

### Smooth Scrolling

Pass `behavior: 'smooth'` in the returned position:

```tsx
scrollBehavior(to, from, savedPosition) {
    if (savedPosition) return { ...savedPosition, behavior: 'smooth' };
    return { top: 0, behavior: 'smooth' };
}
```

### Scroll to Element with Offset

When scrolling to a hash target, you can add a `top` offset — useful with fixed headers:

```tsx
scrollBehavior(to) {
    if (to.hash) {
        return { el: to.hash, top: -80 };
    }
    return { top: 0 };
}
```

### Async Scrolling

Return a `Promise` to delay scrolling — for example, to wait for lazy-loaded content to render:

```tsx
scrollBehavior(to) {
    return new Promise((resolve) => {
        setTimeout(() => resolve({ top: 0 }), 300);
    });
}
```

### Skipping Scroll

Return `false` to prevent any scrolling for a specific navigation:

```tsx
scrollBehavior(to, from) {
    // Don't scroll when only the query changes
    if (to.path === from?.path) return false;
    return { top: 0 };
}
```

---
url: https://sigx.dev/ssg/docs/configuration/
title: Configuration & Content
description: File-based routing, layouts, collections, navigation, MDX, hydration, and sitemap with @sigx/ssg
---

# Configuration & Content

This guide covers the day-to-day building blocks of an `@sigx/ssg` site: configuration, file-based routing, layouts, collections, MDX, hydration, and the generated sitemap. Every snippet uses the public `@sigx/ssg` import path.

## Configuration

Author your config with `defineSSGConfig` (or its alias `defineConfig`) and export it as the default from `ssg.config.ts`:

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    pages: 'src/pages',
    layouts: 'src/layouts',
    outDir: 'dist',
    base: '/',
    site: {
        title: 'My Site',
        description: 'Built with @sigx/ssg',
        url: 'https://example.com',
        lang: 'en',
    },
    defaultLayout: 'default',
});
```

`defineSSGConfig` applies defaults before merging your config:

- `pages` is `src/pages`, `layouts` is `src/layouts`, `content` is `src/content`.
- `defaultLayout` is `default`, `outDir` is `dist`, `base` is `/`.
- `prefetch` and `spaNavigation` are enabled, `site.lang` is `en`.
- `markdown.shiki` is on; `toc` uses `minLevel: 2`, `maxLevel: 3`.
- `linkCheck` is `'warn'`; `search` is off.
- `trailingSlash` is `'always'` — derived public URLs (canonical, `og:url`, sitemap `<loc>`) end with `/` for folder routes, matching the `<path>/index.html` output that static hosts serve with 200. Set `'never'` only when your host serves the slash-less URL directly.

`base` works in both directions: when not set, SSG inherits Vite's `base`; when set in `ssg.config.ts`, it is passed to the production Vite builds, so the sitemap, canonical URLs, router, and asset URLs all stay in sync for sub-path deploys.

The `markdown.*` and `toc.*` options apply whether you set them in `ssg.config.ts` or pass them as `ssgPlugin()` arguments — both feed the same MDX pipeline, with plugin arguments taking precedence.

Other notable options:

- `spaNavigation` (default `true`) — internal anchor clicks (including plain markdown links in MDX) navigate through the router instead of full page reloads. Opt out per link with a `data-no-spa` attribute, or globally with `spaNavigation: false`. See [SPA navigation](#spa-navigation).
- `sitemap` — `SitemapOptions`, or `false` to skip sitemap.xml/robots.txt entirely. See [Sitemap and robots.txt](#sitemap-and-robotstxt).
- `redirects` — a `{ '/old': '/new/' }` map of static redirects. See [Redirects](#redirects).
- `search` — `true` (or `SearchOptions`) to emit a `search-index.json` over the rendered pages. See [Built-in search](#built-in-search).
- `llms` — `true` (or `LlmsOptions`) to emit `llms.txt`, `llms-full.txt`, and per-page markdown renditions for LLM consumption. See [LLM-friendly output](#llm-friendly-output-llmstxt).
- `linkCheck` — `'warn'` (default), `'error'`, or `'off'` for internal link & anchor validation. See [Link checking](#link-checking).
- `routes` — a function that returns programmatic routes merged with the filesystem scan. See [Programmatic routes](#programmatic-routes).
- `data` — build-time data loaders exposed via `virtual:ssg-data`. See [Build-time data loaders](#build-time-data-loaders).
- `hooks` — build pipeline hooks. See [Build hooks](#build-hooks).
- `clientEntry` / `serverEntry` / `htmlTemplate` — explicit entry/template paths that win over convention detection (`htmlTemplate: false` forces the generated template). A configured path that doesn't exist fails the build.
- `navigation.sectionOrder` — sidebar category order. See [Sidebar order](#sidebar-order).
- `clientImports` — side-effect imports added to the generated client entry; the usual home for `'@sigx/ssg/styles.css'`, the base stylesheet for ssg-emitted markup (code windows, package-manager tabs, heading anchors, dual-theme Shiki). See [The base stylesheet](#the-base-stylesheet).

## File-based routing

Files under `src/pages` map to routes by their path. Supported page extensions are `.tsx`, `.jsx`, `.mdx`, and `.md`.

| File | Route |
| --- | --- |
| `index.tsx` | `/` |
| `about.tsx` | `/about` |
| `blog/index.tsx` | `/blog` |
| `blog/[slug].tsx` | `/blog/:slug` |
| `docs/[...path].tsx` | `/docs/*path` |

Optional segments are also supported: `[[id]]` becomes `:id?` and `[[...slug]]` becomes `*slug`.

Routes are sorted by specificity: static beats dynamic (`:param`) beats catch-all (`*`).

### Excluded from routing

- Root-level `components/`, `hooks/`, `utils/`, and `lib/` folders.
- Any file or folder starting with `_` (at any level).
- `*.test.*` and `*.spec.*` files.

### Dynamic routes need `getStaticPaths`

A dynamic route must export `getStaticPaths()` returning an array of `StaticPath` objects, each with `params` and optional `props`. The build resolves `getStaticPaths` from the built SSR bundle, so it can live in `.tsx` and `.mdx` pages alike. Routes without it are skipped with a warning (`SSG102`); a `getStaticPaths` that throws fails the build.

Route params and per-path `props` arrive as component props (`props.params.slug`, plus your `props` spread at the top level) — in SSR, at hydration (the build embeds them), and after client-side navigation.

A `src/pages/404.*` page is emitted as a root `404.html` — the not-found convention static hosts serve.

```tsx
import { component } from 'sigx';

export async function getStaticPaths() {
    return [
        { params: { slug: 'hello-world' } },
        { params: { slug: 'second-post' }, props: { featured: true } },
    ];
}

export default component<{ params: { slug: string } }>(({ props }) => {
    return () => <article>Post: {props.params.slug}</article>;
});
```

## Layouts

Layouts live in `src/layouts`. A layout default-exports a component and renders the page content through `slots.default?.()`:

```tsx
import { component } from 'sigx';
import type { LayoutProps, LayoutSlots } from '@sigx/ssg';

export default component<LayoutProps, unknown, LayoutSlots>(({ slots }) => {
    return () => (
        <div class="site">
            <header>My Site</header>
            <main>{slots.default?.()}</main>
        </div>
    );
});
```

A page selects its layout, in order of precedence, via:

1. Frontmatter `layout:` (MDX/Markdown).
2. An exported `export const layout = '...'`.
3. The collection config.
4. The config `defaultLayout` (defaults to `default`).

Themes bundle layouts, components, and CSS in a package referenced by the config `theme` field. A theme's exported `config` can also contribute markdown plugins, head tags, CSS imports, build hooks, and a default layout — your own config always wins. Layouts receive the whole site config as `props.site` (including the `site.nav`, `site.logo`, and `site.repo` branding fields), so themes render your branding instead of hardcoding their own. See [Themes](/ssg/docs/themes) for authoring and consuming a theme, and the prebuilt `@sigx/ssg-theme-daisyui`.

Layouts also receive the current page's `meta` as `props.meta` and the route `path` as `props.path`, so they can render edit-this-page links, last-updated stamps, and breadcrumbs (see [Per-page metadata](#per-page-metadata)).

## MDX and Markdown

Frontmatter is parsed with gray-matter and is available in MDX expressions through `frontmatter`:

```mdx
---
title: My Post
description: A post written in MDX
category: Blog
order: 10
---

# {frontmatter.title}

Body content with **GFM**, autolinked headings, and Shiki highlighting.
```

Defaults that apply to content pages:

- **Shiki** syntax highlighting is on (light: `github-light`, dark: `github-dark`).
- **GFM**, `rehype-slug`, and autolinked headings are enabled.
- **Table of contents** headings are extracted between `toc.minLevel` (2) and `toc.maxLevel` (3).

Navigation-related frontmatter fields come from `PageMeta`: `category` (a string, or an array for nesting), `order`, `sidebar`, `draft`, `toc`, and `ssr`. SEO and per-page chrome fields are documented under [Per-page metadata](#per-page-metadata).

### Code highlighting and Shiki

Set `markdown.shiki` to a `ShikiConfig` to tune highlighting:

```ts
import { defineSSGConfig } from '@sigx/ssg';
import { transformerNotationDiff } from '@shikijs/transformers';

export default defineSSGConfig({
    markdown: {
        shiki: {
            light: 'github-light',
            dark: 'github-dark',
            langs: ['ts', 'bash'],
            transformers: [transformerNotationDiff()],
            skipLanguages: ['mermaid', 'math'],
        },
    },
});
```

- `transformers` — Shiki transformers applied to every highlighted block (including each package-manager variant). The raw fence meta is exposed to transformers as `options.meta.__raw`, so the `@shikijs/transformers` meta-driven features (line highlighting `{1,3-5}`, diff, focus, word highlight) work without any core changes.
- `skipLanguages` — fence languages the highlighter leaves untouched, so the raw `<pre><code class="language-…">` survives in the output for a later rehype plugin or island to claim — e.g. `['mermaid', 'math']`. [`@sigx/mermaid`](/mermaid/docs/ssg) is the ready-made consumer for the first of those.

### Package-manager code fences

A shell fence whose lines are `npm`/`pnpm`/`yarn`/`bun` commands (install/add, run, dlx, create, remove, …) is rendered with an npm/pnpm/yarn/bun tab strip and all four variants pre-rendered server-side. The client switcher (from `@sigx/ssg/client`) only flips which variant is visible — it never rewrites highlighted text. `shiki.defaultPackageManager` (default `'pnpm'`) chooses which variant shows first; a visitor's saved choice overrides it. See [Client runtime → Package-manager switcher](/ssg/docs/client-runtime#package-manager-switcher) for the programmatic API.

### Draft pages

Pages with `draft: true` frontmatter are visible in dev but excluded from production builds and the sitemap. To preview drafts in a production build, pass `--drafts` to `sigx ssg build` (or `drafts: true` to the programmatic `build()`).

## Collections and navigation

A collection groups pages under a path prefix and generates its own sidebar from their `category` / `order` frontmatter. A page is assigned to a collection on a **path-segment boundary** — `/docs` claims `/docs` and `/docs/intro`, but never `/docs-internal` — and to the **most specific (longest-matching)** collection when several apply, so nested collection paths are fully supported. A page like `/modules/updates-ui/x` belongs to the `/modules/updates-ui` collection, not the shorter `/modules/updates` one.

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    collections: {
        docs: {
            path: '/docs',
            layout: 'docs',
            showDrafts: 'dev',
        },
    },
});
```

You can also supply explicit navigation, or rely on auto-generation (the default):

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    navigation: {
        autoGenerate: true,
        showDrafts: 'dev',
        sidebar: [
            {
                title: 'Getting Started',
                order: 1,
                items: [
                    { title: 'Introduction', href: '/docs/intro' },
                    { title: 'Setup', href: '/docs/setup' },
                ],
            },
        ],
    },
});
```

At runtime, navigation is consumed through the `virtual:ssg-navigation` module, which exposes `getSidebar`, `getCollectionNav`, and `detectCollection`:

```ts
import nav, { getSidebar, detectCollection } from 'virtual:ssg-navigation';

const collection = detectCollection('/docs/intro');
const sidebar = collection ? getSidebar(collection) : nav.navigation;
```

`detectCollection` applies the same rule the build uses: it matches on a path-segment boundary and returns the longest-matching collection, so a path under a nested collection resolves to that nested collection rather than its parent.

## Client and island hydration

The auto-generated client entry imports `ssrClientPlugin` (re-exported from `@sigx/ssg/client`) and hydrates `#app`; the server entry uses the SignalX server renderer's `renderToString`. The wiring it generates looks like this:

```tsx
import { defineApp, component } from 'sigx';
import { createRouter, createWebHistory } from '@sigx/router';
import { ssrClientPlugin } from '@sigx/ssg/client';
import routes from 'virtual:ssg-routes';
import { setupLayouts, LayoutRouter } from 'virtual:generated-layouts';

const router = createRouter({
    history: createWebHistory({ base: '/' }),
    routes: setupLayouts(routes),
    scrollBehavior(to, from, savedPosition) {
        if (savedPosition) return savedPosition;
        if (to.hash) return { el: to.hash };
        return { top: 0 };
    },
});

const App = component(() => () => <LayoutRouter />);

defineApp(<App />).use(router).use(ssrClientPlugin).hydrate('#app');
```

Selective hydration (islands) works with `@sigx/ssr-islands` via `client:*` directives, so you can ship static HTML and hydrate only the interactive parts.

### Link prefetch

Prefetch-on-hover is enabled by default (config `prefetch`, with a 100 ms delay). The generated client entry wires it automatically. From `@sigx/ssg/client` you can also call the helpers directly:

```ts
import { prefetch, setupPrefetch } from '@sigx/ssg/client';

setupPrefetch({ delay: 150 });
prefetch('/blog/hello-world');
```

Other client helpers detect rendering mode and read embedded state:

```ts
import { isStaticPage, getInitialState } from '@sigx/ssg/client';

if (!isStaticPage()) {
    const state = getInitialState<{ user: string }>();
}
```

## Build hooks

Three `hooks` in `ssg.config.ts` extend the production build (they run on builds only, not the dev server) — the slots for feeds, custom indexing, HTML post-processing, and other build-time side effects:

```ts
export default defineSSGConfig({
    hooks: {
        transformHtml(html, page) {
            // page: { path, params, props?, meta?, route }
            return html.replace('</head>', '<meta name="generator" content="@sigx/ssg"></head>');
        },
        onPageRendered(page) {
            // page is the build-result entry plus the final html: { path, file, time, size, meta?, html }
        },
        async postBuild(result, ctx) {
            // result.pages lists every written page; ctx is { outDir, config }
        },
    },
});
```

- `transformHtml(html, page)` runs per page after head tags and app HTML are injected, returning the HTML to write.
- `onPageRendered(page)` observes each page after it is written (the build-result entry plus its `html`).
- `postBuild(result, ctx)` runs exactly once after every page is written and the sitemap is generated; `ctx` is `{ outDir, config }`.

The per-page hooks run concurrently and in no guaranteed order, so avoid unsynchronized shared state beyond append-only collection. A hook that throws fails the build. A theme can contribute its own hooks; the theme's run first, then yours (`transformHtml` chains the output through both).

## Sitemap and robots.txt

`build()` writes `sitemap.xml` and `robots.txt` automatically. You can also generate them programmatically:

```ts
import { build, generateSitemap, generateRobotsTxt } from '@sigx/ssg';

const result = await build();

const xml = generateSitemap(
    [{ path: '/', priority: 1.0, changefreq: 'weekly' }],
    config,
);
const robots = generateRobotsTxt(config);
```

Entries are prefixed with `site.url` + `base`, and folder-route paths are normalized per the `trailingSlash` policy (default `'always'`: `/about` → `https://example.com/about/`), byte-identical with the canonical and `og:url` emitted in each page's head. The same normalization is exported as `normalizePagePath(path, trailingSlash?)`. When mapping built pages, priority is derived from depth (`/` = 1.0, depth 1 = 0.8, depth 2 = 0.6, otherwise the default 0.5) and the default change frequency is `weekly`. Pages with `robots: noindex` and the `/404` page are excluded automatically, and a `public/robots.txt` you ship is never overwritten.

`SitemapOptions` carries `exclude` (glob/exact path matches), `additionalUrls`, `defaultChangefreq`, and `defaultPriority`. Freshness has three layers, applied in order — the later wins:

```ts
export default defineSSGConfig({
    sitemap: {
        exclude: ['/draft/**'],
        lastmod: 'git', // 'git' | 'mtime' | false (default)
        transform(entry, page) {
            // adjust an entry, or return null/undefined to drop it
            return entry;
        },
    },
});
```

- `sitemap.lastmod` — derive `<lastmod>` per page from the source file. `'git'` uses each file's last commit date (one repo-wide `git log` walk — needs full history, so set `fetch-depth: 0` in CI); `'mtime'` uses the filesystem timestamp. Default `false`.
- Per-page frontmatter `lastmod`, `changefreq`, and `priority` override the derived/default values for that page (an explicit `lastmod` always wins over the `git`/`mtime` derivation).
- `sitemap.transform(entry, page)` runs last as a per-entry escape hatch — adjust the entry, or return `null`/`undefined` to drop it.

## Redirects

A `redirects` map points old paths at new ones:

```ts
export default defineSSGConfig({
    redirects: {
        '/old-guide': '/docs/guide/',
        '/legacy': 'https://example.org/elsewhere',
    },
});
```

For each entry the build emits, at the old path, a static page with `<meta http-equiv="refresh">`, a canonical pointing at the target, `noindex`, and a fallback link — so the redirect works on any static host. It also writes a `_redirects` file (Netlify / Cloudflare Pages format) so hosts that support it answer with a real `301` before HTML is involved. Relative targets are prefixed with `base`; absolute URLs pass through untouched. A redirect whose source would overwrite a rendered page fails the build, and a `_redirects` file you ship via `public/` is appended to (your hand-written rules stay first, so they keep precedence).

## Built-in search

Set `search: true` to emit a `search-index.json` over the rendered pages at build time — one entry per page with its title, description, headings, tags, and visible text (`noindex` pages and the 404 page are excluded, like the sitemap):

```ts
export default defineSSGConfig({
    search: true,
    // or tune it:
    // search: { output: 'search-index.json', maxTextLength: 8000 },
});
```

Consume the index on the client with `loadSearchIndex()` and `searchPages()` from `@sigx/ssg/client` — see [Client runtime → Search](/ssg/docs/client-runtime#search). To surface a theme's search UI (such as the daisyUI theme's ⌘K command palette), also set `site.search: true`; it reaches layouts via `LayoutProps.site`. Pair it with the top-level `search: true` so the index actually exists.

## LLM-friendly output (llms.txt)

Set `llms: true` (or an `LlmsOptions` object) to emit the [llms.txt convention](https://llmstxt.org/) over the built pages, so LLMs and agents can ingest the site as markdown instead of scraping HTML:

- **`llms.txt`** — a markdown index: `# title`, a `> description` blockquote, your `intro` markdown, then one `## section` per group of `- [Title](/path.md): description` links pointing at the pages' markdown renditions.
- **`llms-full.txt`** — the renditions concatenated, each prefixed with a `---` block carrying its canonical `url`.
- **Per-page `.md` renditions** — a cleaned markdown file next to each markdown-sourced page's HTML: route `/docs/guide/` → `dist/docs/guide.md`, served as `/docs/guide.md`.
- **Per-area sub-indexes** — `areas: { '/docs': {} }` emits `/docs/llms.txt` scoped to pages under that prefix, for consumers that only need one area (a per-area `llms-full.txt` is opt-in via the area's `full`).

```ts
export default defineSSGConfig({
    llms: {
        intro: 'Read [the cheatsheet](/start.md) first.',
        sections: [
            { title: 'Guides', collections: ['docs'] },
            { title: 'More', links: [{ title: 'Playground', href: '/play', note: 'interactive' }] },
        ],
        full: { exclude: ['/changelog/**'] },
        areas: { '/docs': {} },
        exclude: ['/internal/**'],
    },
});
```

Behavior and knobs:

- **Visibility follows the sitemap** — `robots: noindex` pages and the 404 page are excluded (drafts never reach production builds) — plus `exclude` route globs, per-page frontmatter `llms: false`, and a `transform(md, page)` escape hatch that can adjust a rendition or return `null` to drop the page.
- **Sections** default to one `##` per collection (declaration order, links in sidebar order, frontmatter `description` as the note), with uncollected pages under `## Other`. Curate with `sections` — each entry pulls `collections`, explicit `pages`, and/or hand-authored `links`.
- **Renditions are source-based**: the page's `.md`/`.mdx` source with frontmatter replaced by a minimal `url`/`title`/`description` header, MDX imports/exports/JSX stripped by a fence-aware scanner (fenced code is never touched), and fence info strings normalized to the bare language. `.tsx`/`.jsx` pages have no rendition — they appear in the index only when named in `sections[].links`, linked to their HTML route.
- **`public/` wins** — an `llms.txt` (or any `llms*` file) you ship via `public/` is never overwritten, same courtesy as robots.txt.
- **Build-time only** — like the sitemap, the outputs are written by `sigx ssg build`; the dev server doesn't serve them.

The helper family (`prepareLlmsPages`, `buildLlmsIndex`, `buildLlmsFullText`, `renderPageMarkdown`, `getMarkdownPath`, `writeLlmsOutputs`) is exported for programmatic use — see [API Reference → LLM output](/ssg/docs/api#llm-output).

## Link checking

After rendering, every internal `<a href>` is validated: the path must resolve to an emitted page (or a redirect source, or an on-disk asset in `public/`), and any `#fragment` must match an element id on the target page. `linkCheck` controls the outcome:

```ts
export default defineSSGConfig({
    linkCheck: 'warn', // 'warn' (default) | 'error' | 'off'
});
```

`'warn'` reports findings, `'error'` fails the build (use it in CI), `'off'` disables the check. External, protocol-relative, and `mailto:`/`tel:` links are skipped. The same logic is exported as `checkLinks` / `formatLinkCheckReport` for programmatic use.

## Programmatic routes

`routes` adds pages that don't come from the filesystem scan — CMS-backed pages, tag archives, generated indexes. It returns an array (or a promise) of routes, each pointing at a component file, and is merged with the scanned routes everywhere (dev, build, navigation):

```ts
export default defineSSGConfig({
    routes: (ctx) => [
        { path: '/tags/sigx', file: './src/templates/tag.tsx', meta: { title: 'sigx' } },
        { path: '/changelog', file: './src/templates/changelog.tsx' },
    ],
});
```

Each route has a `path` (concrete or with `:params`), a `file` (absolute or relative to the project root), and optional `layout` and `meta`. A path collision with a scanned page, or a missing `file`, fails the build.

## Build-time data loaders

`data` runs a set of loaders once per build (shared across the client and SSR builds) and once per dev-server start, exposing the results through the `virtual:ssg-data` module:

```ts
export default defineSSGConfig({
    data: {
        versions: async () => fetch('https://registry.npmjs.org/sigx').then((r) => r.json()),
    },
});
```

```tsx
import data from 'virtual:ssg-data';

console.log(data.versions);
```

The module also emits one named export per key (`import { versions } from 'virtual:ssg-data'`) plus the default object. Each key must be a valid identifier (it becomes an export name), and each value must be JSON-serializable — values are baked into the bundle for both the server render and the client, so a loader that returns `undefined`, a function, or a non-serializable value fails the build. To type named imports, augment `virtual:ssg-data` in your project.

## Sidebar order

`navigation.sectionOrder` sets the order of categories in an auto-generated sidebar — either a name → weight map (lower first, merged over the built-in defaults) or an explicit list (listed categories come first in list order; unlisted ones follow the defaults):

```ts
export default defineSSGConfig({
    navigation: {
        sectionOrder: ['Getting Started', 'Guides', 'API Reference'],
    },
    collections: {
        // a collection can override the site-wide order with its own
        blog: { path: '/blog', sectionOrder: { Featured: 0, Archive: 10 } },
    },
});
```

A collection's own `sectionOrder` wins over the site-wide one for that collection.

## SPA navigation

By default (`spaNavigation: true`) same-origin internal anchor clicks — including the plain `<a>` elements that MDX content links compile to — are routed through the client router instead of triggering a full page reload. The browser keeps handling modified clicks, external/`mailto:` links, `target`/`download` anchors, same-document `#hash` scrolls, and anything that already called `preventDefault()`. Opt out per element (or any ancestor container) with a `data-no-spa` attribute, or globally with `spaNavigation: false`. Navigation honours `trailingSlash`: under the default `'always'` it pushes the canonical trailing-slash URL — the same form the hard load and the static host's 301 redirect both serve — so client and server URLs match without any pushState shim; paths with a file extension (e.g. `/sitemap.xml`) are pushed verbatim. The generated client entry wires this automatically; in a custom entry call `installSpaNavigation(router, { base, trailingSlash })` from `@sigx/ssg/client`.

## Per-page metadata

Beyond navigation, `PageMeta` (frontmatter or an exported `meta`) carries SEO and page-chrome fields the layout/theme can render:

- `robots`, `canonical`, `keywords`, `jsonLd`, and extra `head` tags feed the page's head.
- `lastmod`, `changefreq`, and `priority` override sitemap values for the page (see [Sitemap](#sitemap-and-robotstxt)).
- `sourceFile` (the page's root-relative source path, embedded automatically) combines with `site.editBase` to produce an edit-this-page link.
- Frontmatter `date` becomes the page's `<lastmod>` fallback.

Site-wide page chrome lives on `SiteConfig` and reaches layouts via `LayoutProps.site`:

- `site.editBase` — base URL for edit-this-page links (e.g. `'https://github.com/org/repo/edit/main/'`); the page's `sourceFile` is appended.
- `site.announcement` — `{ text, href?, id? }` rendered by the theme above the header. Change `id` to re-show an announcement a visitor dismissed.
- `site.jsonLd`, `site.head`, `site.nav`, `site.logo`, `site.repo` — global structured data, head tags, and branding.

When no `/404` page exists, the build still writes a default `404.html`.

## The base stylesheet

`@sigx/ssg` emits markup with its own class names — code-window chrome, the package-manager tab strip, heading anchors, copy-code buttons, and dual-theme Shiki output. Import the base stylesheet so that markup is styled, usually via `clientImports`:

```ts
export default defineSSGConfig({
    clientImports: ['@sigx/ssg/styles.css'],
});
```

A theme that styles this markup itself contributes the import through its `config.css`, so you don't add it twice.

## Next steps

- [Client runtime](/ssg/docs/client-runtime) — the package-manager switcher, search, copy-code, prefetch, and SPA navigation helpers.
- [Themes](/ssg/docs/themes) — authoring and consuming themes, and the prebuilt daisyUI theme.
- [Commands](/ssg/docs/commands) — every `sigx ssg` command with its flags.
- [API Reference](/ssg/docs/api) — the full list of public exports.

---
url: https://sigx.dev/use/docs/unref-element/
title: unrefElement
description: Resolve an element target — raw element, getter, signal, computed, or a sigx template-ref — to the raw DOM element or null
---

# unrefElement

Resolve a flexible element target to the **raw** DOM element (or `null`). The primitive every DOM-attaching composable uses to accept `ref`s, signals, getters, and plain elements interchangeably. Browser composable — import from `@sigx/use-web`.

```ts
import { signal } from 'sigx';
import { unrefElement } from '@sigx/use-web';

const el = signal<HTMLElement | null>(null);
// <div ref={el}> …

unrefElement(el);              // the raw <div>, or null before mount
unrefElement(() => document.body); // getter form
unrefElement(someElement);     // passed straight through
```

It accepts every shape in the [element-target convention](/use/docs/conventions#element-targets-web): a raw element or `EventTarget`, a getter, a branded sigx handle (a `PrimitiveSignal`, a `computed`, or a `toSignal`/`toSignals` view), or a sigx template-ref `{ current }` object — the shape sigx's JSX `ref` prop writes into. Reading a reactive handle **tracks**, so a watcher calling `unrefElement` re-runs when the element changes.

> Detection is brand-based (`isSignal`/`isComputed`), so an arbitrary plain `{ value }` object is **not** unwrapped. If you hold an element in a plain object, pass it as a getter (`() => obj.value`).

The result is passed through `toRaw`: reactive object-signal reads wrap elements in proxies, and **raw identity** is what `removeEventListener` pairing, observer bookkeeping, and native element methods require.

## Signature

```ts
function unrefElement<T extends EventTarget = EventTarget>(
    target:
        | MaybeSignalElement
        | T
        | ReadSignal<T | null | undefined>
        | { current: T | null | undefined }
        | (() => T | null | undefined)
        | null
        | undefined,
): T | null;
```

## See also

- [Conventions → Element targets (web)](/use/docs/conventions#element-targets-web) — the target shapes and why raw identity matters.
- [`useEventListener`](/use/docs/use-event-listener) — the canonical consumer, re-attaching when the target changes.

---
url: https://sigx.dev/store/docs/persistence/
title: Persistence
description: Persist store state to localStorage or any sync/async storage with @sigx/store/persist
---

# Persistence

`@sigx/store/persist` is a composable that persists a state slice to storage and rehydrates it when the store is created. Call it inside a store setup, passing the setup context and the `{ state, patch }` pair from `defineState`:

```ts
import { defineStore } from '@sigx/store';
import { persist } from '@sigx/store/persist';

const useSettings = defineStore('settings', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ theme: 'dark', locale: 'en' });

    const { hydrated } = persist(ctx, { state, patch });

    return { ...signals, hydrated };
}, 'singleton');
```

With no options, this persists every key of the slice to `localStorage` under the key `sigx:settings` (`sigx:<storeName>`), hydrates on store creation, and saves on every change.

## See it survive a reload

Type something below, then **reload this page** — the text comes back. The sandbox can only import the package root, so this demo hand-wires the few lines `persist()` does for you (hydrate with one atomic `patch`, save on change, same `{ v, data }` envelope); in your app the whole block below the comment is one `persist(ctx, { state, patch })` call.

```tsx
import { component, render } from 'sigx';
import { defineStore } from '@sigx/store';

const KEY = 'sigx:persist-demo';

const useNoteStore = defineStore('persist-demo', (ctx) => {
    const { state, signals, events, patch } = ctx.defineState({ note: '' });

    // --- in a real app, replace everything down to the actions with:
    // const { hydrated } = persist(ctx, { state, patch });

    // hydrate: one atomic patch over the defaults
    try {
        const raw = localStorage.getItem(KEY);
        if (raw) patch(JSON.parse(raw).data);
    } catch { /* corrupted entry → keep defaults */ }

    // save on change (persist uses a deep watch; a key event works here).
    // Like persist(), writes are isolated: quota/privacy failures are
    // logged, never thrown into the app.
    events.note.subscribe((value) => {
        try {
            localStorage.setItem(KEY, JSON.stringify({ v: 1, data: { note: value } }));
        } catch (err) {
            console.error('persist-demo: write failed:', err);
        }
    });

    const actions = ctx.defineActions({
        reset() { state.note = ''; },
    });

    return { ...signals, ...actions };
});

const Demo = component(() => {
    const store = useNoteStore();
    return () => (
        <div class="space-y-2">
            <input
                class="input input-bordered w-full"
                placeholder="Type something, then reload the page…"
                value={store.note}
                onInput={(e) => { store.note = (e.target as HTMLInputElement).value; }}
            />
            <p class="text-xs opacity-70">
                Stored under <code>sigx:persist-demo</code> in localStorage — open devtools and watch it update as you type.
            </p>
            <button class="btn btn-ghost btn-sm" onClick={() => store.reset()}>reset</button>
        </div>
    );
});

render(<Demo />, "#sandbox");
```

## How it behaves

- **Hydration is one atomic `patch()`** — a single reactivity flush applies the stored values over the defaults.
- **Saving is a deep watch** over the picked keys, optionally debounced — direct mutation, `patch`, and `$patch` all trigger it.
- **Saving is paused until hydration completes**, so async hydration can never be overwritten by the defaults racing it to storage (see [the hydration race](#the-hydration-race) below).
- **No storage available (SSR)** — `persist` is a no-op: the store renders with defaults, never writes, and `hydrated` is immediately `true`. (Merely *accessing* `localStorage` can throw in some privacy modes — that is treated as "no storage" too.)
- **Failures never break the store** — a corrupted entry, a throwing `migrate`, or a quota error is logged and the store continues from defaults (see [failure isolation](#failure-isolation)).
- **Everything is cleaned up** when the store is disposed; pending async hydration of a disposed store is discarded.

## Options

```ts
persist(ctx, { state, patch }, {
    key: 'sigx:settings',     // storage key — default `sigx:<storeName>`
    storage: localStorage,    // any StorageLike — default globalThis.localStorage
    pick: ['theme'],          // persist (and hydrate) only these keys — default: all
    version: 2,               // schema version stored alongside the data
    migrate(persisted, fromVersion) {
        // convert data persisted under an older version
        return { theme: (persisted as any).colourScheme ?? 'dark' };
    },
    debounce: 250,            // ms debounce for writes — default 0
    serialize: (snapshot) => JSON.stringify(snapshot),  // optional custom codec
    deserialize: (raw) => JSON.parse(raw),
});
```

`storage` accepts anything matching the minimal `StorageLike` contract — `getItem` / `setItem` (and optional `removeItem`) returning values either synchronously or as promises. `localStorage`, `sessionStorage`, and async stores like React Native's AsyncStorage all qualify.

> The default key uses the **logical store name**, not the instance id, so persistence survives across instances. With `'transient'` stores, multiple live instances would fight over one key — pass explicit `key`s there.

## The handle: hydrated, whenHydrated, clear

`persist` returns a `PersistHandle`:

- `hydrated` — a `{ readonly value: boolean }` view that flips to `true` once hydration completes (immediately for sync or absent storage). Return it from the setup to gate UI on it.
- `whenHydrated` — a promise that resolves when hydration completes; useful with async storage.
- `clear()` — removes the persisted entry from storage (a promise; resolves when the storage's `removeItem` settles).

## Versioning and migration — a worked example

Data is stored in an envelope `{ v, data }`. When the stored `v` differs from your current `version` and a `migrate` function is provided, `migrate(persisted, fromVersion)` receives the deserialized payload's data and returns the slice to apply. Without `migrate`, the stored data is applied as-is (only the picked keys are ever applied, so renamed keys simply drop).

Suppose v1 of your app persisted a boolean dark-mode flag, and v2 redesigns it as a theme string:

```ts
// v1 shipped with:
const { state, signals, patch } = ctx.defineState({ darkMode: false });
persist(ctx, { state, patch }, { version: 1 });
// → localStorage["sigx:settings"] = '{"v":1,"data":{"darkMode":true}}'
```

```ts
// v2 changes the shape — and migrates old entries on first load:
const { state, signals, patch } = ctx.defineState({
    theme: 'light' as 'light' | 'dark' | 'system',
});

persist(ctx, { state, patch }, {
    version: 2,
    migrate(persisted, fromVersion) {
        if (fromVersion === 1) {
            const old = persisted as { darkMode?: boolean };
            return { theme: old.darkMode ? 'dark' : 'light' };
        }
        return {};   // unknown / ancient version → keep defaults
    },
});
// first load:  reads v1 envelope → migrate({darkMode:true}, 1) → theme: 'dark'
// first write: '{"v":2,"data":{"theme":"dark"}}'  ← entry is now upgraded
```

Details worth knowing:

- `migrate` runs **only** when the stored version differs from `version` — steady-state loads skip it entirely.
- Data persisted before you adopted versioning (no envelope) arrives with `fromVersion: 0` and the raw payload as `persisted`.
- The returned partial passes through `pick` filtering like any hydration, then applies as one atomic `patch`.
- A **throwing `migrate` is not fatal**: the error is logged, the store starts from defaults, and the next write replaces the old entry with current-version data — migration failures self-heal.

## Async storage (React Native and friends)

Anything Promise-returning that satisfies `StorageLike` works unchanged — React Native's AsyncStorage is the canonical case. The differences from `localStorage` are *when* hydration completes and what your UI does until then:

```tsx
import AsyncStorage from '@react-native-async-storage/async-storage';
import { defineStore } from '@sigx/store';
import { persist } from '@sigx/store/persist';

const useSettings = defineStore('settings', (ctx) => {
    const { state, signals, patch } = ctx.defineState({
        theme: 'dark' as 'dark' | 'light',
        locale: 'en',
    });

    const { hydrated, whenHydrated, clear } = persist(ctx, { state, patch }, {
        storage: AsyncStorage,
    });

    const actions = ctx.defineActions({
        async resetToDefaults() {
            await clear();
            patch({ theme: 'dark', locale: 'en' });
        },
    });

    return { ...signals, ...actions, hydrated, whenHydrated };
}, 'singleton');
```

With sync storage, hydration happens during the `persist()` call and `hydrated.value` is already `true` when your setup returns. With AsyncStorage, the store is created **immediately with defaults**, and the stored values patch in when the `getItem` promise resolves. Gate any UI that must not flash defaults on `hydrated`:

```tsx
const Settings = component(() => {
    const store = useSettings();
    return () => store.hydrated.value
        ? <ThemePicker theme={store.theme} />
        : <Spinner />;
});
```

`hydrated` is a plain `{ readonly value }` view — reading `store.hydrated.value` in render re-renders when it flips. For imperative flows (e.g. deciding an initial route after settings load), return `whenHydrated` from the setup too (as above) and await it on the instance:

```ts
const store = useSettings();
await store.whenHydrated;      // resolves once stored values are applied
navigate(store.locale === 'en' ? '/home' : `/${store.locale}/home`);
```

`whenHydrated` always resolves — even when the read fails (the failure is logged and the store proceeds with defaults), so awaiting it can never hang your app on a broken storage backend.

## The hydration race

There is a classic bug in hand-rolled async persistence: the store is created with defaults, a save-on-change watcher starts immediately, something touches the state (or an eager watcher fires) — and the *defaults* get written to storage **before** the async read of the previous session's data comes back. The stored data is gone; the read then either applies stale data over fresher writes or gets discarded.

`persist` makes this impossible by ordering, not by luck:

1. On creation it starts the read (`getItem`) — but does **not** start the save watcher.
2. Until hydration completes, every would-be write is skipped (`hydrated` is still `false`).
3. When the read resolves, the stored values apply as one atomic `patch`, `hydrated` flips, **and only then** does the deep save watcher start.

So writes physically cannot precede hydration, and the hydration patch itself doesn't echo back into a save (the watcher starts after it). The cost of this guarantee is the thing to remember: **state changed before hydration completes is not saved, and persisted keys are overwritten by the stored values when hydration lands**. If users can interact before hydration, gate that UI on `hydrated` — that's exactly what the flag is for.

## Failure isolation

Persistence is a convenience layer; it must never take the store down with it. Every failure path is contained:

- **Corrupted data self-heals.** Bad JSON, a throwing `deserialize`, a throwing `migrate`, or a patch that throws: the error is logged (`[@sigx/store] persist("<key>"): hydration failed, continuing with defaults`), the store starts from defaults, `hydrated` still flips, and saving starts — the next successful write replaces the corrupted entry.
- **Write failures are logged, not thrown.** Quota exceeded, privacy-mode restrictions, a rejecting async `setItem`: the app keeps running from memory (`persist("<key>"): write failed`). Sync throws and async rejections are both caught — a failed save never surfaces as an unhandled rejection.
- **Read failures don't block.** A sync `getItem` throw or an async `getItem` rejection is logged; the store proceeds with defaults and `whenHydrated` resolves rather than hanging.
- **No storage at all** (SSR, or environments where touching `localStorage` throws): `persist` is a clean no-op — defaults, no writes, `hydrated` immediately `true`.
- **Disposal wins races.** If the store is disposed while an async read is still in flight, the late result is discarded — no patches and no watchers on a dead store.

## Multiple slices

`persist` works per slice, so a store with multiple `defineState` calls can persist them independently — pass an explicit `key` for each:

```ts
const usePrefs = defineStore('prefs', (ctx) => {
    const ui = ctx.defineState({ sidebar: 'open' });
    const drafts = ctx.defineState({ text: '' });

    persist(ctx, ui, { key: 'sigx:prefs:ui' });
    persist(ctx, drafts, { key: 'sigx:prefs:drafts', debounce: 500 });

    return { ...ui.signals, ...drafts.signals };
});
```

## Composing with SSR state transfer

`persist` covers device-local state; [`ssrState`](/store/docs/ssr-state) carries state from the server render to client hydration. They layer cleanly — call `ssrState` **first** so its synchronous seed lands before `persist`'s (possibly async) hydration overrides it with device-local data when present. See [composing with `persist()`](/store/docs/ssr-state#composing-with-persist) for the ordering.

## Next steps

- [SSR state transfer](/store/docs/ssr-state) — seed a store from the server render; composes with `persist`.
- [Composables & Plugins](/store/docs/composables-and-plugins) — `persist` is the case study for writing your own setup composables.
- [Defining a Store](/store/docs/defining-a-store) — state, actions, derived values, and events.
- [API Reference](/store/docs/api#sigxstorepersist) — `persist`, `StorageLike`, `PersistOptions`, and `PersistHandle` signatures.

---
url: https://sigx.dev/use/docs/use-clipboard/
title: useClipboard
description: Clipboard writes on the cross-platform UseClipboardReturn contract, with a copied flag for Copied! UI
---

# useClipboard

Clipboard writes on the cross-platform `UseClipboardReturn` contract — `copy()` resolves after writing, and `copied` stays true briefly so you can flash "Copied!". Browser composable — import from `@sigx/use-web`.

```tsx
import { component, render } from 'sigx';
import { useClipboard } from '@sigx/use-web';

const CopyButton = component(() => {
    const { copy, copied, isSupported } = useClipboard({ source: 'https://sigx.dev' });

    return () => (
        <button class="btn" disabled={!isSupported} onClick={() => copy()}>
            {copied ? 'Copied!' : 'Copy link'}
        </button>
    );
});

render(<CopyButton />, "#app");
```

## Signature

```ts
function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;

interface UseClipboardReturn {
    isSupported: ReadSignal<boolean>;
    text: ReadSignal<string>;
    copied: ReadSignal<boolean>;
    copy: (text?: string) => Promise<void>;
}
```

- **`isSupported`** — whether the platform clipboard is available in this context.
- **`text`** — the last text written through `copy()` (and clipboard reads, where supported).
- **`copied`** — true for a short window (`copiedDuring` ms) after a successful `copy()`; drive "Copied!" UI with it.
- **`copy(text?)`** — write `text`, or the resolved `source` when called without an argument.

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `source` | `MaybeSignal<string>` | — | Default payload for `copy()` when called without an argument. |
| `copiedDuring` | `number` | `1500` | How long (ms) `copied` stays true after a copy. |
| `legacy` | `boolean` | `false` | Fall back to `document.execCommand('copy')` where the async Clipboard API is missing. |
| `navigator` | `Navigator` | `defaultNavigator` | Override the navigator ([`ConfigurableNavigator`](/use/docs/conventions#ssr-safety-and-configurable-overrides)). |
| `document` | `Document` | `defaultDocument` | Override the document (used by the `legacy` path). |

The `copied` timer cleans up with the owning scope — no manual teardown.

## SSR

In SSR or an insecure (non-HTTPS) context `isSupported` is `false` and `copy()` resolves as a **no-op**. Gate the button on `isSupported` rather than assuming the write happened.

> `copied` reflects only writes made *through this hook's* `copy()`. It won't light up for copies made elsewhere on the page.

## See also

- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — the `UseClipboardReturn` contract a platform pack fulfils.
- [`useTitle`](/use/docs/use-title) — the other document-surface composable.

---
url: https://sigx.dev/vite/docs/installation/
title: Installation
description: Install @sigx/vite — peer dependencies, versions, and required Vite/TypeScript wiring
---

# Installation

`@sigx/vite` is an ESM-only package (`"type": "module"`, `sideEffects: false`).
It supports Node `^20.19.0 || >=22.12.0`.

## Install

```bash
npm install -D @sigx/vite
```

```bash
pnpm add -D @sigx/vite
```

```bash
yarn add -D @sigx/vite
```

## Peer Dependencies

Both peer dependencies are required and are not bundled — install them
yourself:

| Peer | Version range | Notes |
|---|---|---|
| `vite` | `>= 8.0.0` | The plugin targets Vite 8 (Rolldown). |
| `sigx` | `*` | The SignalX runtime the plugin shares as a singleton. |

```bash
npm install vite sigx
```

## Configure Vite

Add the plugin to the `plugins` array in `vite.config.ts`. The default export is
the plugin factory:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [sigx()],
});
```

The named export `sigxPlugin` is equivalent if you prefer it:

```ts
import { sigxPlugin } from '@sigx/vite';

export default defineConfig({
    plugins: [sigxPlugin()],
});
```

The plugin runs with `enforce: 'pre'` and only transforms first-party
`.ts`/`.tsx`/`.jsx` files — it skips `node_modules` and `/dist/`.

## Configure TypeScript

For JSX/TSX, point TypeScript's JSX transform at SignalX:

```json
// tsconfig.json
{
    "compilerOptions": {
        "jsx": "react-jsx",
        "jsxImportSource": "sigx"
    }
}
```

If you use the type-generation output (see the
[Commands](/vite/docs/commands) guide), add its output directory
to `include` so the editor picks it up:

```json
// tsconfig.json
{
    "include": ["src", "node_modules/.sigx/**/*.d.ts"]
}
```

### Types for the generated `virtual:` modules

`@sigx/vite/client` carries ambient declarations for every module the plugin
generates — `virtual:sigx-app`, `virtual:sigx-manifests`,
`virtual:sigx-server-fns`, `virtual:sigx-islands` and `virtual:sigx-resume/entry`.
One reference line replaces the hand-written `declare module` blocks apps used to
copy around:

```ts
/// <reference types="@sigx/vite/client" />
```

Put it in a `.d.ts` your `tsconfig` already includes (or `src/vite-env.d.ts`, if
you have one).

## Package Entry Points

The package exposes three entry points through its exports map:

| Import path | Purpose |
|---|---|
| `@sigx/vite` | The plugin (default and `sigxPlugin` export) plus HMR re-exports. |
| `@sigx/vite/hmr` | The browser-side HMR runtime (injected automatically). |
| `@sigx/vite/lib` | `defineLibConfig` for building `@sigx/*` libraries. |

## Next Steps

- [Getting Started](/vite/docs/getting-started) — the minimal end-to-end setup
- [HMR for Components](/vite/docs/hmr) — how component hot-reload works
- [Library Builds](/vite/docs/library-builds) — build packages with `defineLibConfig`
- [API Reference](/vite/docs/api) — every export and option

---
url: https://sigx.dev/actors/docs/lifecycle/
title: Lifecycle
description: onActivate, onDeactivate and why it ran — idleAfterMs, maxActivations, deactivation reasons and seeing which actors are live
---

# Lifecycle

<p class="lede">Activations come and go without you asking. What you control is how long they
linger, how many a host will hold, and what happens at each end.</p>

## The hooks

```ts
defineActor({
    type: 'Room',
    state: () => ({ members: [] as string[] }),
    async onActivate(ctx) {
        // runs after state is loaded and migrated, before the first turn
        ctx.index = new Map(ctx.state.members.map((m) => [m, true]));
    },
    async onDeactivate(ctx, reason) {
        // reason: 'idle' | 'shutdown' | 'capacity' | 'migrated' | …
    },
});
```

`onActivate` always observes [migrated](/actors/docs/state-and-persistence) state. A throw
from it fails activation with `ActorActivationError` and the call that triggered it rejects.

```mermaid
stateDiagram-v2
    [*] --> Activating: first call
    Activating --> Active: load, migrate, onActivate
    Activating --> Faulted: hook throws
    Faulted --> [*]: ActorActivationError
    Active --> Active: turns
    Active --> Deactivating: idle, shutdown, capacity, migrated
    Deactivating --> [*]: onDeactivate
```

Deactivation is not deletion: the next call activates again and reads the state back. What is
lost is anything kept *outside* `ctx.state`.

`onDeactivate` receives **why**, which matters because the reasons are not equivalent:

| Reason | Means |
|---|---|
| `idle` | no calls for `idleAfterMs` — the ordinary case |
| `shutdown` | the host is stopping; in-flight turns have drained |
| `capacity` | a `maxActivations` cap shed it (least-recently-used) |
| `migrated` | a [cluster](/actors/docs/clustering) moved it to another host |

## Idle collection

`idleAfterMs` (default 20 minutes) is how long an activation survives without a call. The
sweeper runs every `sweepIntervalMs` (default 60s); set either to `0` to disable.

Two things count as activity that people expect not to:

- An open [live watch](/actors/docs/live-reads) keeps the actor alive, deliberately — so idle
  collection cannot deactivate an actor out from under a subscriber.
- A running [task](/actors/docs/tasks) holds a keep-alive until it finishes.

A `ctx.timer` tick does **not** keep the actor alive, and that is intentional: a volatile
timer is a convenience, not a reason to pin an object in memory. If you need the actor to wake
up later regardless, use a [durable reminder](/actors/docs/timers-and-reminders).

## Capping activations

```ts
defaults: { maxActivations: 50_000 }
```

A **soft** LRU cap, enforced by the sweeper, with deactivation reason `capacity`. Soft is the
operative word:

- Busy actors and actors holding a keep-alive are never shed.
- The live count may therefore exceed the cap.
- State survives — a shed actor reactivates from storage on its next call.

It is a memory guardrail, not an admission-control mechanism. Watch `byReason.capacity` in
[metrics](/actors/docs/metrics): a cap that is shedding constantly is either too low or
hiding a key-cardinality problem.

## Seeing what is live

```ts
host.activations({ sortBy: 'queued', limit: 20 });
```

Returns `{ type, key, queued, ageMs, idleMs, keptAlive, tasks }` per activation. `sortBy`
accepts `'queued'`, `'age'` or `'idle'`, and `type` filters to one actor type.

`queued` is the one to look at first: a persistently non-zero queue depth is a hotspot, and
the fix is usually to shard the key or move I/O out of the turn — see
[Metrics](/actors/docs/metrics) for the `queueMs` versus `turnMs` distinction.

The same data is available over the wire through [the ops endpoint](/actors/docs/ops-endpoint)
and in the [CLI dashboard](/actors/packages/actors-cli/overview).

> Actor keys can be personal data. `host.activations()` returns them, which is why the ops
> endpoint keeps the activation list **off by default** and requires a secret.

## Shutdown

```ts
await host.stop({ timeoutMs: 10_000 });
```

Stops accepting new calls, drains in-flight turns, flushes pending write-behind saves, runs
`onDeactivate` for every activation and then the app's `onStop` hooks in reverse order.

On Node, wire it to signals with `attachSignalHandlers` — see
[Running a host on Node](/actors/docs/node). In a cluster, a graceful stop announces `leaving`
before handing off, which is why liveness and readiness
[are allowed to disagree](/actors/docs/health-and-readiness).

## Next steps

- [Timers & reminders](/actors/docs/timers-and-reminders) — waking an actor up.
- [Metrics](/actors/docs/metrics) — activation churn by reason.
- [Running a host on Node](/actors/docs/node) — graceful shutdown in practice.

---
url: https://sigx.dev/cli/docs/installation/
title: Installation
description: Install @sigx/cli, understand its peer/plugin packages, and wire up the commands
---

# Installation

## Installing the CLI

Add `@sigx/cli` as a dev dependency and run it through your package runner:

```bash
npm i -D @sigx/cli
```

```bash
npx sigx info
```

The package exposes a single binary, `sigx`. It is ESM-only (`"type": "module"`), so it requires a Node.js version with native ESM support.

You usually do not install the CLI by hand: projects created with `sigx create` already depend on `@sigx/cli`. You can also scaffold without a local install using `npx sigx create` or:

```bash
npm create @sigx@latest
```

## No config or Vite wiring required

There is **no Vite or config file wiring needed to use `@sigx/cli` itself**. The core commands (`sigx create`, `sigx info`) work as soon as the binary is available.

Everything beyond the two core commands is provided by plugins that the CLI discovers at runtime (see [Authoring Plugins](/cli/docs/plugins)). To enable those commands, install the relevant plugin package in your project.

## Runtime dependencies

`@sigx/cli` pulls in a small set of runtime dependencies:

- **`@sigx/args`** — the fluent, type-aware command/argument parser. It backs both the core commands and the `args` declared by plugins (see [Authoring Plugins](/cli/docs/plugins)).
- **`@sigx/terminal`** — the terminal UI used by the interactive `create` prompts and by the [shell runtime](/cli/docs/shell) that plugin commands host their dashboards in. The prompt kit is lazy-loaded, so it is only imported when you actually run `sigx create` interactively.

## Entry points

`@sigx/cli` exposes four entry points:

| Import | Provides |
| --- | --- |
| `@sigx/cli` | `definePlugin`, `a`, and the plugin types — the public API. |
| `@sigx/cli/plugin` | The same plugin surface (preferred for plugin authors). |
| `@sigx/cli/create` | `runCreate` — the `create` command entry point. |
| `@sigx/cli/shell` | `runShell` and the [shell runtime](/cli/docs/shell) for hosting a TUI dashboard. |

## Plugin packages behind each command

Only `info` and `create` ship inside `@sigx/cli`. The rest are contributed by plugins and require the matching package to be installed in your project:

| Command | Provided by | Used for |
| --- | --- | --- |
| `sigx create` | `@sigx/cli` (core) | Scaffolding new projects |
| `sigx info` | `@sigx/cli` (core) | Environment & project diagnostics |
| `sigx dev` | `@sigx/vite` (web) / `@sigx/lynx-cli` (Lynx) | Start the dev server |
| `sigx build` | `@sigx/vite` (web) / `@sigx/lynx-cli` (Lynx) | Production build |
| `sigx preview` | `@sigx/ssg` | Serve a built SSG site |
| `sigx prebuild` | `@sigx/lynx-cli` | Generate native iOS/Android project files |
| `sigx run:android` | `@sigx/lynx-cli` | Build & launch on Android |
| `sigx run:ios` | `@sigx/lynx-cli` | Build & launch on iOS |
| `sigx doctor` | `@sigx/lynx-cli` | Verify the Lynx toolchain |

A plugin's commands only register when its `detect(cwd)` check returns true for your project, so installing a plugin does not pollute your command list in unrelated projects.

## Lynx native toolchain

If you scaffold a Lynx project (or `sigx info` detects a Lynx config), the platform commands additionally rely on the native toolchain — rspeedy, the Android SDK (`ANDROID_HOME` / `ANDROID_SDK_ROOT`), a JDK, ADB, and on macOS Xcode and CocoaPods. Run `sigx info` to probe what is installed; `sigx doctor` (from `@sigx/lynx-cli`) verifies the toolchain in more detail.

## Next steps

- [Commands](/cli/docs/commands) — full reference for every command and its flags.
- [Authoring Plugins](/cli/docs/plugins) — add your own commands to the CLI.

---
url: https://sigx.dev/mermaid/docs/overview/
title: Overview
description: "@sigx/mermaid — a <Mermaid> component for any sigx app, plus drop-in mermaid fence support for @sigx/ssg"
---

# Mermaid

<p class="lede"><a href="https://mermaid.js.org/">Mermaid</a> diagrams for sigx — a <code>&lt;Mermaid&gt;</code> component for any app, and drop-in <code>```mermaid</code> fence support for <a href="/ssg/docs/getting-started">@sigx/ssg</a> sites.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> ESM-only <span class="mmr-dot" /> MIT</p>

```bash
pnpm add @sigx/mermaid mermaid
```

`mermaid` itself is a peer dependency — you control which version renders your diagrams.

## Why it exists

A docs site without diagrams explains architecture in prose. This package makes fences just work, without giving up the things a static site is for:

- **The diagram source stays in the HTML.** It is readable, greppable and indexable, and it survives with JavaScript off.
- **mermaid loads only on pages that have a diagram**, and only once one scrolls into view.
- **Diagrams re-theme when the reader flips light/dark**, rather than staying committed to the palette they were first drawn in.

## In an app

```tsx
import { Mermaid } from '@sigx/mermaid';

<Mermaid code={`
  sequenceDiagram
    Browser->>Server: GET /
    Server-->>Browser: HTML
`} />
```

## In an SSG site

Two lines. `remarkMermaid` claims the fence on the markdown tree, before the syntax highlighter ever sees it:

```ts
// ssg.config.ts
import { defineSSGConfig } from '@sigx/ssg';
import { remarkMermaid } from '@sigx/mermaid/ssg';

export default defineSSGConfig({
    markdown: {
        remarkPlugins: [remarkMermaid],
    },
    clientImports: ['@sigx/mermaid/styles', '@sigx/mermaid/client'],
});
```

Then write a fence:

````mdx
```mermaid title="Request flow"
sequenceDiagram
  Browser->>Server: HTML
```
````

See [SSG integration](/mermaid/docs/ssg) for the details.

## Why not render at build time?

Rendering to SVG during the build would mean zero client JavaScript, and it is the obvious thing to want.

mermaid cannot do it without a browser: it measures text with `getBBox`, which neither jsdom nor happy-dom implements faithfully. That leaves a headless Chromium — slow builds and a ~300 MB dependency — or `isomorphic-mermaid`, which is svgdom-based, young, and approximate on font metrics.

Neither is a good default. So this package renders on the client and keeps the cost honest: the source is always in the HTML, and mermaid is never loaded for a diagram nobody scrolled to.

## What's here

- [Usage](/mermaid/docs/usage) — the component, configuration and theming.
- [SSG integration](/mermaid/docs/ssg) — `remarkMermaid` and the client enhancer.
- [API reference](/mermaid/docs/api) — every export.

---
url: https://sigx.dev/core/docs/app-plugins/
title: App & Plugins
description: Application bootstrap, plugin system, dependency injection, and lifecycle hooks
---

# App & Plugins

SignalX provides a powerful application model with plugin support, dependency injection, and global lifecycle hooks. The `defineApp()` function is the entry point for configuring and bootstrapping your application.

## Mounting Your Application

SignalX provides two ways to render your application:

| Method | Plugins | DI | Lifecycle Hooks | Unmount |
|--------|---------|-----|-----------------|---------|
| `render()` | ❌ | ❌ | ❌ | ❌ |
| `defineApp()` | ✅ | ✅ | ✅ | ✅ |

### `render()` - Low-Level Rendering

The simplest way to render - directly mounts a JSX element to a container:

```tsx
import { render } from 'sigx';

// Using CSS selector
render(<App />, '#app');

// Using element reference
render(<App />, document.getElementById('app')!);
```

Use `render()` for simple cases, prototypes, or when you don't need plugins or dependency injection.

### `defineApp()` - Full Application Model

The recommended approach for production applications. Provides plugins, dependency injection, lifecycle hooks, and proper unmounting:

```tsx
import { defineApp } from 'sigx';
import App from './App';

const app = defineApp(<App />);

app.mount(document.getElementById('app')!);
```

The app instance provides a **chainable API** for configuration:

```tsx
defineApp(<App />)
    .use(routerPlugin)
    .use(devToolsPlugin, { debug: true })
    .provide(ConfigToken, myConfig)
    .mount(document.getElementById('app')!);
```

## App Configuration

Register the global error handler with `app.onError`, and configure warnings and performance via `app.config`:

```tsx
const app = defineApp(<App />);

// Global error handler — the app-wide catch-all for render/re-render throws,
// DOM event-handler throws, and unhandled data errors no errorScope took.
app.onError((err, instance, info) => {
    console.error(`Error in ${instance?.name || 'unknown'}:`, err);
    // Return true to suppress the error from propagating
    return false;
});

// Warning handler (dev mode)
app.config.warnHandler = (msg, instance, trace) => {
    console.warn(`[SignalX Warning] ${msg}`);
};

// Enable performance tracking
app.config.performance = true;
```

`app.onError` is the app-level safety net. To keep part of the UI alive with a local fallback instead, scope a subtree with `errorScope` — see [Error handling](/core/docs/error-handling).

## Plugins

Plugins extend the application with additional functionality. They can add global providers, register lifecycle hooks, and configure the app.

### Object-Style Plugin

```tsx
import { type Plugin } from 'sigx';

const myPlugin: Plugin<{ debug?: boolean }> = {
    name: 'my-plugin',
    install(app, options) {
        // Provide values to all components
        app.provide('myService', new MyService());

        // Register lifecycle hooks
        app.hook({
            onComponentMounted: (instance) => {
                if (options?.debug) {
                    console.log('Mounted:', instance.name);
                }
            }
        });

        // Configure error handling
        app.onError((err, instance, info) => {
            reportError(err, instance?.name, info);
            return true; // Error handled
        });
    }
};

// Install the plugin
app.use(myPlugin, { debug: true });
```

### The plugin surface: `app._context`

The high-level methods above — `app.provide`, `app.hook`, `app.onError` — cover
most plugins. A plugin that integrates at a lower level (providing through a
framework seam, or registering teardown) reaches for **`app._context`**, the
app's context object and the documented plugin-author surface:

```tsx
const myPlugin: Plugin = {
    name: 'my-plugin',
    install(app) {
        // Hand the context to a seam's provide-helper…
        provideMyEngine(app._context, createEngine());

        // …or use its maps directly.
        app._context.provides.set(MY_TOKEN, value);
        app._context.disposables.push(() => cleanup());
    },
};
```

The leading underscore marks it as an advanced surface — it's the seam packs like
[`@sigx/cache`](/core/packages/cache/overview) build on — but it's a supported one:
`provides` and `disposables` are the contract. (Other underscore-prefixed fields,
like `_isMounted` and `_container`, remain internal.)

### Function-Style Plugin

For simpler plugins, you can use a function:

```tsx
import { type PluginInstallFn } from 'sigx';

const simplePlugin: PluginInstallFn = (app) => {
    app.provide('logger', createLogger());
};

app.use(simplePlugin);
```

### Plugin Example: DevTools

Here's a complete example of a development tools plugin:

```tsx
const devToolsPlugin: Plugin<{ logMounts?: boolean }> = {
    name: 'devtools',
    install(app, options) {
        if (options?.logMounts) {
            app.hook({
                onComponentMounted: (instance) => {
                    console.log(`[DevTools] Mounted: ${instance.name || 'anonymous'}`);
                },
                onComponentUnmounted: (instance) => {
                    console.log(`[DevTools] Unmounted: ${instance.name || 'anonymous'}`);
                }
            });
        }

        // Global error handling
        app.onError((err, instance, info) => {
            console.error(`[DevTools] Error in ${instance?.name}:`, err, info);
            return false; // Don't suppress - let it propagate
        });
    }
};

app.use(devToolsPlugin, { logMounts: true });
```

### Plugins are Installed Once

SignalX automatically prevents duplicate plugin installation:

```tsx
app.use(myPlugin); // Installed
app.use(myPlugin); // Skipped with warning
```

## Dependency Injection

SignalX provides a powerful dependency injection system using `provide` and `inject`.

### App-Level Provides

Values provided at the app level are available to all components:

```tsx
// Simple value
app.provide('apiUrl', 'https://api.example.com');

// Object
app.provide('config', {
    version: '1.0.0',
    debug: true
});
```

### Using `defineInjectable`

For type-safe dependency injection with automatic fallback to singletons:

```tsx
import { defineInjectable, inject } from 'sigx';

// Define an injectable token with a factory function
const useApiConfig = defineInjectable(() => ({
    baseUrl: 'https://api.example.com',
    timeout: 5000
}));

// Provide a custom value at app level
app.provide(useApiConfig, {
    baseUrl: 'https://custom.api.com',
    timeout: 10000
});

// In any component - just call the function!
const MyComponent = component(({ }) => {
    const config = useApiConfig(); // Returns provided or default value
    
    return () => <div>API: {config.baseUrl}</div>;
});
```

### Required injectables

`defineInjectable` has a second form: pass a **name string** instead of a factory
and you get a *required* injectable — one with no singleton fallback.

```tsx
// Factory form — falls back to a module-global singleton if nobody provides it.
const useLogger = defineInjectable(() => new Logger());

// Required form — declared by name, no fallback.
const useRouter = defineInjectable<Router>('Router');
```

Using a required injectable that was never provided throws
[`SIGX202`](/errors/SIGX202/), naming the injectable — instead of silently
handing back a shared global. That's the point of the form: a per-request
dependency like a router or an auth session must be provided per app, and a global
fallback would leak state between requests on a server. Provide it before anything
resolves it:

```ts
const app = createApp(App);
app.defineProvide(useRouter, () => createRouter(url));
app.mount('#app');
```

Two related refinements make provides more predictable:

- **Providing `undefined` now shadows the fallback.** An explicit
  `defineProvide(useThing, () => undefined)` means "the value is `undefined`
  here", not "fall through to the default".
- **App provides are looked up live.** `app.defineProvide(...)` called *after*
  `app.mount()` is visible to components mounted afterwards — useful for plugins
  that provide lazily.

In development, a factory-form injectable that falls back to its module-global
singleton on the **server** while an app exists logs a one-time warning — that
singleton is shared across every SSR request in the process. The fix is to provide
it per app, or declare it required. (The warning is server-only and stripped from
production.)

### Component-Level Provides

Components can also provide values to their descendants:

```tsx
import { provide, inject } from 'sigx';

const Parent = component(({ }) => {
    // Provide to all descendants
    provide('theme', { primary: '#3498db' });
    
    return () => <Child />;
});

const Child = component(({ }) => {
    // Inject from parent or app
    const theme = inject('theme');
    
    return () => (
        <div style={`color: ${theme?.primary}`}>
            Themed content
        </div>
    );
});
```

### `defineProvide`

Create and provide an instance in one step:

```tsx
import { defineInjectable, defineProvide } from 'sigx';

const useAuthService = defineInjectable(() => new AuthService());

const App = component(({ }) => {
    // Creates instance AND provides it to descendants
    const auth = defineProvide(useAuthService);
    
    return () => <LoginForm />;
});
```

### Resolving DI Outside Component Setup

Use-functions from `defineInjectable` / `defineFactory` (and `inject`) resolve against the *current* DI context, which is normally set up only while a component's setup runs. Code that runs **outside** setup — router navigation guards, socket message handlers, entry-scope bootstrap — has no current context, so those calls silently fall back to a realm-level instance instead of the app's.

`app.runWithContext(fn)` runs `fn` with the app's context current, so use-functions resolve to the **same** instances your components receive:

```tsx
const app = defineApp(<App />);

router.beforeEach((to) => {
    // Without runWithContext, useAuth() here resolves a different instance
    app.runWithContext(() => {
        const auth = useAuthService();
        if (to.meta.requiresAuth && !auth.isAuthenticated) {
            return '/login';
        }
    });
});

socket.on('message', (msg) => {
    app.runWithContext(() => {
        useMessageStore().receive(msg);
    });
});
```

The context applies to the **synchronous** portion of `fn` only — it's restored in a `finally`, so it never leaks past the first `await`. Nested calls restore the previous context, and plugins can capture the `app` they receive in `install()` to wrap their own callbacks.

Because the context is synchronous, an `async` callback resolves its later dependencies against the *wrong* context — everything after the first `await` runs with the context already restored. In development, `runWithContext` warns once per app when its callback returns a promise:

```tsx
// ⚠️ resolves useAuthService() correctly, but useMessageStore() after the await does not
app.runWithContext(async () => {
    const auth = useAuthService();          // ✅ synchronous — correct context
    await auth.refresh();
    useMessageStore().receive(msg);         // ❌ context already restored
});
```

Re-enter with another `runWithContext` after the `await` to resolve more dependencies. `runWithContext` returns its callback's value, so capture what you resolve synchronously:

```tsx
const auth = app.runWithContext(() => useAuthService());   // resolved in-context
await auth.refresh();
app.runWithContext(() => { useMessageStore().receive(msg); });
```

#### Tailoring the warning from a library

The warning above is written for the person who called `runWithContext`. That is the wrong reader when a **library** makes the call on someone else's behalf — a router running your navigation guard, a scheduler running your handler. Its users see a warning about an API they never called, naming a fix they can't apply.

`runWithContext` takes a second argument for that case:

```ts
interface RunWithContextOptions {
    asyncAdvice?: string | false;
}
```

Pass a string to replace the warning's **remediation sentence** — the sync-only diagnosis stays, so the reader still learns what went wrong, but the advice now points at the API they actually used:

```ts
// inside the router
app.runWithContext(() => guard(to, from), {
    asyncAdvice: 'Make the navigation guard synchronous, or resolve services before returning a promise.',
});
```

Pass `false` to suppress the warning for a call that is deliberately synchronous-only, or that re-enters the context itself per continuation:

```ts
app.runWithContext(() => useConfig().baseUrl, { asyncAdvice: false });
```

A suppressed call does not consume the once-per-app warning slot, so the next genuine offender still gets reported.

Both forms are dev-only and stripped from production builds. Older cores ignore the extra argument, so passing it is safe.

## Lifecycle Hooks

Register global hooks to observe all components in your application:

```tsx
app.hook({
    // Called after setup() completes
    onComponentCreated: (instance) => {
        console.log('Created:', instance.name);
    },

    // Called after component is mounted
    onComponentMounted: (instance) => {
        console.log('Mounted:', instance.name);
    },

    // Called after component re-renders
    onComponentUpdated: (instance) => {
        console.log('Updated:', instance.name);
    },

    // Called before component is unmounted
    onComponentUnmounted: (instance) => {
        console.log('Unmounted:', instance.name);
    },

    // Called when an error occurs
    // Return true to suppress the error
    onComponentError: (err, instance, info) => {
        console.error('Error:', err);
        return false;
    }
});
```

### Component Instance

The `instance` passed to hooks contains:

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string?` | Component name (if defined) |
| `ctx` | `ComponentSetupContext` | The component's setup context |
| `vnode` | `VNode` | The component's virtual node |

## Mounting

### Basic Mount

```tsx
app.mount(document.getElementById('app')!);
```

### Platform-Specific Mount

`app.mount(...)` automatically picks the correct mount function based on the runtime you imported (`sigx` itself wires up DOM mounting):

```tsx
import { defineApp } from 'sigx';
import { App } from './App';

defineApp(<App />).mount(document.getElementById('app')!);
```

Additional renderers (e.g. server, terminal) follow the same pattern — import the runtime package and call `app.mount(...)` with the target it expects.

### Unmounting

Clean up resources when the app is no longer needed:

```tsx
app.unmount();
```

## Router Plugin

The `@sigx/router` package provides a router that integrates with the app system:

```tsx
import { defineApp } from 'sigx';
import { createRouter, createWebHistory } from '@sigx/router';

const router = createRouter({
    history: createWebHistory(),
    routes: [
        { path: '/', component: Home },
        { path: '/about', component: About },
        { path: '/blog/:slug', component: BlogPost }
    ]
});

defineApp(<App />)
    .use(router) // Router implements Plugin interface
    .mount(document.getElementById('app')!);
```

Or use `createRouterPlugin` for more configuration:

```tsx
import { createRouterPlugin } from '@sigx/router';

const routerPlugin = createRouterPlugin({
    history: createWebHistory(),
    routes: [/* ... */],
    base: '/my-app'
});

app.use(routerPlugin);

// Access router instance
const router = routerPlugin.router;
```

## Complete Example

Here's a complete application setup:

```tsx
import { defineApp, defineInjectable, type Plugin, component } from 'sigx';
import { createRouter, createWebHistory, RouterView } from '@sigx/router';

// Define services
const useApi = defineInjectable(() => ({
    fetch: async (url: string) => {
        const res = await fetch(url);
        return res.json();
    }
}));

// Create router
const router = createRouter({
    history: createWebHistory(),
    routes: [
        { path: '/', component: HomePage },
        { path: '/users/:id', component: UserPage }
    ]
});

// Analytics plugin
const analyticsPlugin: Plugin = {
    name: 'analytics',
    install(app) {
        app.hook({
            onComponentMounted: (instance) => {
                trackPageView(instance.name);
            }
        });
    }
};

// App component
const App = component(({ }) => {
    return () => (
        <div>
            <nav>...</nav>
            <RouterView />
        </div>
    );
});

// Bootstrap
defineApp(<App />)
    .use(router)
    .use(analyticsPlugin)
    .provide(useApi, customApiImplementation)
    .hook({
        onComponentError: (err) => {
            Sentry.captureException(err);
            return false;
        }
    })
    .mount(document.getElementById('app')!);
```

## API Reference

### `defineApp(rootComponent)`

Creates an app instance.

**Returns:** `App<TContainer>`

### App Methods

| Method | Description |
|--------|-------------|
| `use(plugin, options?)` | Install a plugin |
| `provide(token, value)` | Provide a value to all components |
| `hook(hooks)` | Register lifecycle hooks |
| `runWithContext(fn)` | Run `fn` with the app's DI context current (for use-functions called outside setup) |
| `mount(container, mountFn?)` | Mount the app |
| `unmount()` | Unmount and cleanup |
| `config` | App configuration object |

### Injection Functions

| Function | Description |
|----------|-------------|
| `defineInjectable(factory)` | Create an injectable with a singleton fallback |
| `defineInjectable(name)` | Create a **required** injectable — no fallback; throws [`SIGX202`](/errors/SIGX202/) if used unprovided |
| `inject(token)` | Get a provided value |
| `provide(token, value)` | Provide a value (in component) |
| `defineProvide(useFn)` | Create and provide in one step |

### Types

```tsx
interface Plugin<Options = any> {
    name?: string;
    install(app: App, options?: Options): void;
}

type PluginInstallFn<Options = any> = (app: App, options?: Options) => void;

interface AppLifecycleHooks {
    onComponentCreated?(instance: ComponentInstance): void;
    onComponentMounted?(instance: ComponentInstance): void;
    onComponentUpdated?(instance: ComponentInstance): void;
    onComponentUnmounted?(instance: ComponentInstance): void;
    onComponentError?(err: Error, instance: ComponentInstance, info: string): boolean | void;
}

interface AppConfig {
    onError?(err: Error, instance: ComponentInstance | null, info: string): boolean | void;
    warnHandler?(msg: string, instance: ComponentInstance | null, trace: string): void;
    performance?: boolean;
}
```

---
url: https://sigx.dev/ssg/docs/installation/
title: Installation
description: Install @sigx/ssg, its peer dependencies, and the required config / Vite wiring
---

# Installation

## Install

```bash
npm install @sigx/ssg sigx @sigx/router @sigx/server-renderer
npm install -D vite @sigx/vite
```

## Peer dependencies

`@sigx/ssg` declares these peer dependencies:

- **`sigx@^0.14.0`** — the SignalX runtime.
- **`@sigx/router@^0.11.0`** — the router the generated client entry drives. Its version line does not mirror core's minor (router `0.11` pairs with core `0.14`) — read the peer range, not the version number.
- **`@sigx/server-renderer@^0.14.0`** — used for the SSR render and the hydration client plugin.
- **`vite@>=8.0.0`** — Vite 8 or newer is required. The generator uses Vite 8's `oxc` JSX transform rather than esbuild.
- **`@sigx/cli@>=0.4.0`** — optional, only needed for the `sigx ssg` CLI subcommands.

Optional, auto-detected when installed:

- **`@tailwindcss/vite`** — the zero-config dev server adds it automatically if present.
- Theme packages such as **`@sigx/ssg-theme-daisyui`**, referenced through the config `theme` field. See [Themes](/ssg/docs/themes).

Heavy build-time dependencies (MDX, Shiki, gray-matter, fast-glob, the unified / remark / rehype stack, and the SignalX server renderer) are bundled into the package, so you do not install them separately.

## Two ways to wire it up

### 1. CLI plugin (zero-config)

Drop an `ssg.config.ts` in your project root and run the CLI subcommands:

```bash
npx sigx ssg dev
npx sigx ssg build
npx sigx ssg preview
```

The package auto-registers as a `@sigx/cli` plugin. Its `detect` step activates when an `ssg.config.{ts,js,mjs}` file exists, so no Vite config is required.

### 2. Vite plugin

Import the plugin and add it to your Vite `plugins` array alongside `sigx()` from `@sigx/vite`. `ssgPlugin()` returns an **array** of plugins (the main plugin plus the MDX plugin), so spread it or pass it directly:

```ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';
import ssg from '@sigx/ssg/vite';

export default defineConfig({
    plugins: [sigx(), ssg()],
});
```

## TypeScript: virtual module types

To get ambient declarations for the virtual modules (`virtual:ssg-routes`, `virtual:ssg-navigation`, `virtual:ssg-data`, and `virtual:generated-layouts`), add the `@sigx/ssg/virtual` entry to `compilerOptions.types` in `tsconfig.json`:

```json
{
    "compilerOptions": {
        "types": ["@sigx/ssg/virtual"]
    }
}
```

This subpath provides type declarations only; it has no runtime.

## Zero-config entry detection

The generator auto-creates the client entry, server entry, and `index.html` unless you supply your own. It detects:

- **Client entry** — `src/main.{tsx,ts}`, `src/entry-client.{tsx,ts}`, or `src/entry.{tsx,ts}`.
- **Server entry** — `src/entry-server.{tsx,ts}`.
- **HTML template** — `index.html`.
- **Global CSS** — auto-imported if found at `src/styles/global.css` (or `main.css` / `index.css`), `src/style.css`, `src/global.css`, or `src/index.css`.

You can override any of these through config (`clientEntry`, `serverEntry`, `htmlTemplate` — set `htmlTemplate: false` to force the generated template).

## Next steps

- [Configuration & Content](/ssg/docs/configuration) — routing, layouts, collections, MDX, and the full config.
- [Commands](/ssg/docs/commands) — every `sigx ssg` command with its flags.
- [API Reference](/ssg/docs/api) — the public API surface.

---
url: https://sigx.dev/store/docs/typescript/
title: TypeScript
description: The store typing contract — inference, action signatures, $patch/$events keys, and policies
---

# TypeScript

`@sigx/store` is inference-first: you never write a generic to define or use a store. The contract is that **the setup return drives every type downstream** — the store surface, `$patch`, `$events`, `storeToSignals`, and the per-action subscriber signatures. This page pins that contract down and explains the two deliberate policies behind it.

## The store surface is computed from the setup return

A factory call returns `UnwrapStore<TReturn>`, where `TReturn` is whatever your setup returned. Conceptually, `UnwrapStore` sorts the return's keys into three buckets:

- **Key signals** (the `signals` you spread from `defineState`) become **read/write plain values**: `store.count: number`.
- **Computeds** become **read-only plain values**: `store.total: number`, and `store.total = 0` is a type error (and a runtime error).
- **Everything else** — actions, topics, helpers, the `hydrated` handle from [persist](/store/docs/persistence) — passes through unchanged.

On top of that sits `StoreMeta`: `$id`, `$patch`, `$events`, `$dispose`. You never name `UnwrapStore` yourself; it's what `useMyStore()` infers.

```ts
const useCart = defineStore('cart', ({ defineState, defineActions }) => {
    const { state, signals } = defineState({ items: [] as Item[], coupon: '' });
    const total = computed(() => state.items.reduce((s, i) => s + i.price, 0));
    const actions = defineActions({
        add(item: Item) { state.items.push(item); },
    });
    const { items } = signals;                  // expose items, keep coupon private
    return { items, ...actions, total };
});

const store = useCart();
store.items;        // Item[]           — read/write
store.total;        // number           — read-only
store.add;          // (item: Item) => void, plus pending/events
store.coupon;       // ✗ type error — not returned, not on the store
```

## `$patch` and `$events` follow the *returned* keys

`PublicState<TReturn>` extracts only the keys whose values are key signals — that's the store's public state, and it is exactly what `$patch` and `$events` are typed over:

```ts
store.$patch({ items: [] });          // ✔ returned key signal
store.$patch({ coupon: 'X' });        // ✗ type error — private (not returned)
store.$patch({ total: 0 });           // ✗ type error — computed, not state
store.$patch({ anything: 1 });        // ✗ type error — unknown key

store.$events.items;                  // ✔ StateKeyEvent<Item[]>
store.$events.coupon;                 // ✗ type error
```

The mutator form is typed the same way — `store.$patch(s => { ... })` gives `s` only the public keys. The runtime agrees with the types: an unknown key in `$patch` **throws**, it isn't silently added. Private keys aren't second-class inside the setup, though — `defineState`'s own `patch` and `events` cover the whole slice; it's only the *instance* surface that's restricted to what you returned.

Key signals are **branded**: a hand-rolled `{ value: 0 }` is not a `KeySignal` and won't become public state or appear in `$patch`/`$events`. Only the `signals` produced by `defineState` qualify.

## Action signatures are preserved exactly

`defineActions` wraps each function as `StoreAction<F> = F & { pending, onDispatching, onDispatched, onFailure }` — an intersection with the original `F`, so the call signature is your signature, unchanged: parameter names, optionals, rest args, return type.

### What subscribers receive

The three subscriber types are derived from `F`:

```ts
onDispatching:  (...args: Parameters<F>) => void
onDispatched:   (result: Awaited<ReturnType<F>>, ...args: Parameters<F>) => void
onFailure:      (error: unknown, ...args: Parameters<F>) => void
```

So for `async save(draft: Draft): Promise<SaveResult>`:

```ts
store.save.onDispatching.subscribe((draft) => { /* draft: Draft */ });
store.save.onDispatched.subscribe((result, draft) => { /* result: SaveResult — resolved, not the promise */ });
store.save.onFailure.subscribe((error, draft) => { /* error: unknown */ });
```

`Awaited<ReturnType<F>>` is why async `onDispatched` is typed (and [behaves](/store/docs/actions-and-async#the-lifecycle-events)) as the **resolved value**. `error` is `unknown` — the only honest type for a caught value; narrow it yourself.

## Policy: single-signature actions

Write each action as **one** function signature; model variants with union parameter types, not overloads:

```ts
// ✔ one signature — subscribers see (id: number | string)
load(id: number | string) { /* ... */ }

// ✗ overloads — subscribers would see only (id: string)
function load(id: number): void;
function load(id: string): void;
function load(id: number | string): void { /* ... */ }
```

The reason is mechanical: TypeScript's `Parameters<F>` and `ReturnType<F>` resolve an overloaded function type to its **last** overload only. The action would still be *callable* through every overload, but `onDispatching`/`onDispatched`/`onFailure` would be typed against just one of them — silently wrong for the rest. A union signature keeps the call site and the subscribers in agreement.

## Generic actions: subscribers see the constraint

An action can be generic, and its **call** sites keep full per-call inference:

```ts
const actions = defineActions({
    upsert<T extends Entity>(entity: T): T { /* ... */ return entity; },
});

const user = store.upsert(someUser);     // T = User → user: User
const order = store.upsert(someOrder);   // T = Order → order: Order
```

The subscribers, however, are typed at the **constraint**:

```ts
store.upsert.onDispatched.subscribe((result, entity) => {
    // result: Entity, entity: Entity — not User or Order
});
```

That's not a limitation to work around; it's the only sound typing. A subscriber is one persistent callback observing *every* invocation — `upsert(user)` and `upsert(order)` alike. No single type argument describes all calls, so the only type guaranteed for each of them is the upper bound, `Entity`. (An unconstrained `<T>` degrades to `unknown` — constrain your generics if subscribers should get something useful.)

## Setup parameters are tuple-typed

Extra setup parameters after the context infer as a tuple with no arity ceiling, and the factory demands exactly them:

```ts
const useList = defineStore('list',
    ({ defineState }, items: string[], cap?: number) => { /* ... */ },
'transient');

useList(['a'], 10);   // ✔
useList(['a']);       // ✔ (cap optional)
useList();            // ✗ type error — items required
```

(For non-`'transient'` lifetimes, remember the args are only *used* on first creation — see [Lifetimes & DI](/store/docs/lifetimes-and-di#parameterized-stores-first-creation-wins).)

## `storeToSignals` infers from the store

The store instance carries its setup-return type as a phantom type parameter, so `storeToSignals(store)` needs no annotation and returns precisely typed views: a writable `KeySignal<V>` per public state key, a `{ readonly value: V }` per computed. Actions and `$`-meta are excluded — at the type level and at runtime.

```ts
const { items, total } = storeToSignals(store);
items.value.push(item);   // ✔ KeySignal<Item[]> — still reactive
total.value;              // ✔ number
total.value = 0;          // ✗ type error — readonly view
```

See [Using Stores in Components](/store/docs/using-in-components#destructuring-safely-with-storetosignals) for when to reach for it.

## Quick reference

| You wrote | The type system gives you |
|---|---|
| returned `signals.x` (from `defineState({ x: ... })`) | `store.x` read/write; key in `$patch` and `$events` |
| unreturned state key | absent from the store, `$patch`, `$events` |
| returned `computed(...)` | `store.y` read-only; **not** in `$patch`/`$events` |
| action `f(a: A): Promise<R>` | `store.f(a)` exact; subscribers `(...[A])`, `(R, A)`, `(unknown, A)` |
| overloaded action | subscribers typed from the last overload only — don't |
| generic action `<T extends C>` | exact calls; constraint-typed (`C`) subscribers |
| setup `(ctx, ...args)` | factory requires exactly `...args` (tuple-inferred) |

## Next steps

- [Defining a Store](/store/docs/defining-a-store) — the public/private state split in practice.
- [Actions & Async](/store/docs/actions-and-async) — the runtime semantics behind the subscriber types.
- [API Reference](/store/docs/api#types) — `UnwrapStore`, `PublicState`, `StoreAction`, and friends in full.

---
url: https://sigx.dev/terminal/docs/theming/
title: Theming
description: The token contract, the built-in themes, resolveColor and the screen canvas
---

# Theming

Terminal components don't hard-code colors — they ask for **semantic tokens** (`accent`, `fg`, `line`, `success`, …) that resolve against the active theme at render time. Switching the theme repaints everything that read a token. This pipeline lives in `@sigx/terminal-zero`; `@sigx/terminal-ui` registers the concrete themes.

## The token contract

A theme is a flat record of color tokens. The roles:

| Group | Tokens |
| --- | --- |
| Surfaces | `bg`, `panel`, `chrome`, `line`, `shadow` |
| Text | `fg`, `dim`, `faint` |
| Accent | `accent`, `accentSoft`, `accentText`, `selSoft` |
| Status | `success`, `warn`, `danger`, `info` |
| ANSI | `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` |

Every token's value is a hex string. The `ColorToken` type is the union of these keys; component `color` props accept a `ColorValue` — a token name **or** a raw `#hex` (which passes straight through).

## resolveColor

`resolveColor(token)` turns a token into a concrete color the renderer can paint:

```ts
import { resolveColor } from '@sigx/terminal';

resolveColor('accent');    // active theme's accent hex
resolveColor('#ff8800');   // raw hex — passes through unchanged
resolveColor(undefined);   // '' (no color)
```

It is **reactive**: it reads both the active-theme signal and the renderer's detected color depth, so a component that resolves a token during render re-renders when you call `setTheme()`. On a 16-color terminal it degrades a token to the nearest ANSI name; on truecolor / 256-color terminals it hands the renderer the theme hex (the renderer quantizes for 256). This is how component colors stay legible across terminals without per-component code.

## Switching themes

Importing `@sigx/terminal-ui` (which the umbrella does) registers the five built-in SigX-tui themes and makes **obsidian** active. Switch at runtime:

```tsx
import { setTheme, getTheme, listThemes } from '@sigx/terminal';

listThemes();         // registered theme ids
getTheme();           // the active id
setTheme('paper');    // switch — repaints every component using tokens
```

`setTheme` throws on an unknown id. `getActiveTheme()` returns the active theme object, and `hasTheme(id)` tests for one.

The five built-in themes are **`obsidian`** (the default, dark), `nord`, `gum`, `classic` (dark) and `paper` (light). The `THEMES` record exports them all by id.

## Registering your own theme

Provide every token and register it. The first theme registered becomes active, so register before mount (or call `setTheme`):

```ts
import { registerTheme, setTheme, type Theme } from '@sigx/terminal';

const midnight: Theme = {
    name: 'Midnight', mode: 'dark',
    bg: '#0b0f1a', panel: '#121829', chrome: '#0b0f1a', line: '#2a3350',
    fg: '#d7dcea', dim: '#8b93a7', faint: '#4a516a', shadow: '#000000',
    accent: '#6ea8ff', accentSoft: '#16203a', accentText: '#0b0f1a', selSoft: '#161d33',
    success: '#5fd17f', warn: '#e0b341', danger: '#e0606a', info: '#5fc4e0',
    black: '#0b0f1a', red: '#e0606a', green: '#5fd17f', yellow: '#e0b341',
    blue: '#6ea8ff', magenta: '#b07cff', cyan: '#5fc4e0', white: '#d7dcea',
};

registerTheme('midnight', midnight);
setTheme('midnight');
```

## The screen canvas

The renderer can paint a screen background and default foreground from the active theme — the app-level canvas behind every line. `@sigx/terminal-ui` binds it automatically via `applyThemeCanvas()`, so a light theme is legible on a dark terminal. It is **on in fullscreen** and **off in inline** by default (full-width background padding looks broken once an inline frame persists into scrollback) — control it per mount with the `canvas` option:

```tsx
defineApp(<App />).mount({ mode: 'inline', canvas: true });
```

`disableThemeCanvas()` stops the binding and clears the canvas so the terminal's own background shows through.

## Next steps

- [Render modes](/terminal/docs/render-modes) — where the canvas applies.
- [Typography](/terminal/docs/typography) — `Text` and `Heading` consume tokens.
- [Components](/terminal/docs/components) — every component is token-themed.

---
url: https://sigx.dev/terminal/docs/prompts/
title: Prompts
description: Imperative CLI prompts — text, password, select, multiselect, confirm, spinner, and intro/outro/note/cancel
---

# Prompts

The prompt kit is for **linear CLI wizards** — ask a question, await the answer, ask the next — without building a JSX step machine. Each prompt mounts a one-shot inline UI, resolves on Enter, and collapses into a permanent `◇ message · answer` line, so a finished wizard reads as a tidy transcript in scrollback.

Import the prompts from `@sigx/terminal` (the umbrella re-exports `@sigx/terminal-ui/prompts`). No JSX pragma is needed — these are async functions, not components.

## A wizard

```ts
import { intro, text, select, confirm, outro, isCancel, cancel } from '@sigx/terminal';

intro('Create a project');

const name = await text({
    message: 'Project name',
    placeholder: 'my-app',
    validate: (v) => (v.length === 0 ? 'Required' : undefined),
});
if (isCancel(name)) { cancel('Aborted.'); process.exit(0); }

const template = await select({
    message: 'Template',
    options: [
        { value: 'spa', label: 'Single-page app' },
        { value: 'ssr', label: 'Server-rendered', description: 'With @sigx/server-renderer' },
    ],
});
if (isCancel(template)) { cancel('Aborted.'); process.exit(0); }

const install = await confirm({ message: 'Install dependencies now?' });

outro('Done — happy hacking!');
```

## Cancellation

Esc or Ctrl+C resolves a prompt to the `CANCEL` symbol instead of throwing. Test for it with `isCancel(value)`; until you do, the value's type still includes the symbol. This is why prompts set `exitOnCtrlC: false` under the hood — Ctrl+C becomes a graceful cancel, not a process kill.

```ts
import { text, isCancel } from '@sigx/terminal';

const value = await text({ message: 'Name' });
if (isCancel(value)) {
    // user pressed Esc or Ctrl+C
}
```

## The prompts

### `text(opts)` → `string | CANCEL`

Single-line text. Enter validates and resolves; editing is end-of-line.

```ts
await text({
    message: 'Email',
    placeholder: 'you@example.com',
    initialValue: '',
    validate: (v) => (v.includes('@') ? undefined : 'Enter a valid email'),
});
```

`TextOptions`: `message`, `placeholder?`, `initialValue?`, `validate?(value) => string | undefined` (return an error string to reject and keep editing), `mask?` (render every character as this string).

### `password(opts)` → `string | CANCEL`

`text` with masking — same options minus `placeholder`, plus a `mask` defaulting to a dot.

```ts
await password({ message: 'Password' });
```

### `select(opts)` → `T | CANCEL`

Single choice. ↑/`k` ↓/`j` move (wrapping), Enter resolves.

```ts
await select({
    message: 'Environment',
    options: [
        { value: 'dev', label: 'Development' },
        { value: 'prod', label: 'Production', description: 'Live' },
    ],
    initialValue: 'dev',
});
```

`SelectOptions<T>`: `message`, `options: PromptOption<T>[]`, `initialValue?`. A `PromptOption<T>` is `{ value, label?, description?, group? }` (`label` defaults to `String(value)`).

### `multiselect(opts)` → `T[] | CANCEL`

Multiple choice. ↑/`k` ↓/`j` move, Space toggles, `a` toggles all, Enter resolves the checked values in option order.

```ts
await multiselect({
    message: 'Features',
    options: [
        { value: 'ts', label: 'TypeScript' },
        { value: 'eslint', label: 'ESLint' },
        { value: 'vitest', label: 'Vitest' },
    ],
    required: true,
});
```

`MultiSelectPromptOptions<T>`: `message`, `options`, `initialValues?`, `required?` (block an empty Enter and show a hint; default `false`). Set an option's `group` to render a section header above it — pre-sort options by group.

### `confirm(opts)` → `boolean | CANCEL`

Yes/No. `y`/`n` answer immediately, ←/→ (or `h`/`l`) flip, Enter resolves the current value.

```ts
await confirm({ message: 'Overwrite?', initialValue: false, active: 'Yes', inactive: 'No' });
```

`ConfirmOptions`: `message`, `initialValue?`, `active?` (label for `true`, default `'Yes'`), `inactive?` (label for `false`, default `'No'`).

### `spinner()` → `SpinnerHandle`

An imperative spinner for the gaps between prompts:

```ts
import { spinner } from '@sigx/terminal';

const s = spinner();
s.start('Installing dependencies');
await install();
s.message('Almost there');
s.stop('Dependencies installed');           // leaves a permanent ✔ line
// s.stop('Install failed', 'error');       // ✖ line
```

`SpinnerHandle`: `start(label?)`, `message(label)` (update while spinning), `stop(label?, code?)` where `code` is `'success'` (default) or `'error'`. Don't `await` another prompt between `start()` and `stop()` — the spinner holds the live region and would deadlock. Ctrl+C stays the renderer default (exit) during a spinner so a long task is interruptible; on non-TTY output `start()` renders nothing and `stop()` prints the summary line.

## Static lines

These print a permanent line without prompting:

- `intro(title)` — open a wizard with a titled header.
- `outro(message)` — close it.
- `note(message, title?)` — a boxed note between steps.
- `cancel(message)` — a cancellation line (pair with `isCancel`).

## The `prompt` namespace

For collision-free imports, everything is also bundled on a `prompt` object:

```ts
import { prompt } from '@sigx/terminal';

const name = await prompt.text({ message: 'Name' });
if (prompt.isCancel(name)) prompt.cancel('Aborted.');
```

## Non-TTY behaviour

Piped or in CI, prompts fall back to their `initialValue` (or `initialValues`) without blocking, so a wizard can run unattended. Spinners print only their final summary line. See [Render modes](/terminal/docs/render-modes).

## Next steps

- [Components](/terminal/docs/components) — the same widgets as embeddable components.
- [Command-line args](/terminal/packages/args/overview/) — parse `argv` before you prompt.
- [API Reference](/terminal/docs/api) — `CANCEL`, `isCancel` and the option types.

---
url: https://sigx.dev/use/docs/use-previous/
title: usePrevious
description: A read-only signal holding the value a source had before its latest change (lag-by-one)
---

# usePrevious

Tracks the value a source held **before** its latest change — a lag-by-one view. Cross-platform — import from `@sigx/use`.

```ts
import { signal } from 'sigx';
import { usePrevious } from '@sigx/use';

const count = signal(0);
const prev = usePrevious(count); // prev.value === undefined until the first change

count.value = 5;   // prev.value === 0
count.value = 12;  // prev.value === 5
```

It accepts any [`MaybeSignal`](/use/docs/conventions#inputs-maybesignalt-and-tovalue) source — a signal, a computed, or a getter — and returns a [`ReadSignal`](/use/docs/conventions#outputs-single-value--readsignalt). Until the source changes for the first time it holds `initialValue` (default `undefined`), so the return type is `ReadSignal<T | undefined>`.

Values are kept **by reference** — objects are not proxied, so identity is preserved across the lag.

## Signature

```ts
function usePrevious<T>(source: MaybeSignal<T>, initialValue?: T): ReadSignal<T | undefined>;
```

**Platform:** everywhere. The internal watcher disposes with the owning scope.

## See also

- [`useCounter`](/use/docs/use-counter) — pair with a counter to diff against the last value.
- [`watchDebounced`](/use/docs/watch-debounced) — react to changes with a collapsed callback.
- [Conventions](/use/docs/conventions) — `MaybeSignal` inputs and `ReadSignal` outputs.

---
url: https://sigx.dev/actors/docs/overview/
title: Actors
description: Virtual actors for SignalX — addressable, single-threaded, persistent server objects that ride the serverFn wire
---

# Actors

<p class="lede">An actor is a server-side object with a name. You call it like a function, it
handles one call at a time, and its state outlives the call. `@sigx/actors` gives you that
without a queue, a lock or a lifetime to manage.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> MIT</p>

```ts
export const CartActor = defineActor({
    type: 'Cart',
    authorize: ownsIt,
    state: () => ({ items: [] as Item[] }),
    methods: (ctx) => ({
        async addItem(item: Item) {
            ctx.state.items.push(item); // single-threaded — no races
            await ctx.save();           // persisted via ActorStorage
            return ctx.state.items.length;
        },
    }),
});

// browser, server function, or SSR — the same expression:
await actor(CartActor, cartId).addItem(item);
```

## The model, in five guarantees

Everything else in these docs follows from these five.

1. **Addressable.** An actor is `(type, key)`. `actor(CartActor, 'user-42')` always reaches
   *the* `user-42` cart — one activation per key. You never hold a reference, and you never
   decide when one is created or destroyed.
2. **Single-threaded.** One turn — one method call — at a time per activation. Plain mutation
   on `ctx.state` is race-free. No locks, ever.
3. **`await` keeps the turn open.** A turn ends when the method's promise settles, so an awaited
   `fetch` inside a method blocks every queued call to that actor until it resolves. This is
   the model's central trade: state safety over intra-actor concurrency. Dev builds warn when
   a turn exceeds `slowTurnMs`.
4. **Persistent.** `ctx.save()` writes state through the pluggable `ActorStorage` with etag
   optimistic concurrency; activation loads it back. A conflicting writer faults the stale
   activation rather than silently losing a write.
5. **Deadlock-detected.** Every call carries its chain, so `A → B → A` into a non-reentrant
   actor throws [`ActorDeadlockError`](/actors/docs/errors) immediately with the full path —
   instead of hanging until a timeout.

Guarantees 2 and 3 are the ones worth sitting with. They are why you can write
`ctx.state.items.push(item)` and be finished, and they are also why a slow HTTP call inside a
method is a problem you will feel. [Reentrancy & interleaving](/actors/docs/reentrancy)
covers the opt-outs when you need them.

## Why this exists

Stateful server work usually gets built out of stateless request handlers plus a database,
and the coordination has to be reinvented every time: a row lock so two requests don't
double-spend, a version column so a stale write doesn't clobber a fresh one, a cache to avoid
re-reading, an invalidation story for the cache, a queue for work that must not run twice.

An actor collapses that into one object that happens to be the only writer of its own state.
Ordering is the [turn sequence](/actors/docs/turns). Consistency is single-threading. Durability is `ctx.save()`.

It is not a general answer. Most endpoints have no identity to be serial about, and for those
a [server function](/actors/docs/actors-or-server-functions) is simpler and faster.

## Where it runs

The runtime is one package with [twelve entry points](/actors/docs/entry-points). A
single-node app needs nothing else — `@sigx/actors` alone gives you a host, storage on disk
or in memory, timers, reminders, streams and the client proxy.

When one process stops being enough, the pieces you add are separate packages so you only pay
for what you use: [Redis](/actors/packages/actors-redis/overview),
[Postgres](/actors/packages/actors-pg/overview),
[SurrealDB](/actors/packages/actors-surreal/overview) or
[Kubernetes](/actors/packages/actors-k8s/overview) for membership and the actor directory;
[TCP](/actors/packages/actors-tcp/overview) or
[WebSocket](/actors/packages/actors-ws/overview) for host-to-host frames;
[Cloudflare Durable Objects](/actors/packages/actors-cloudflare/overview) if the platform is
your cluster. Your actor code does not change.

## Next steps

- [Actors or server functions?](/actors/docs/actors-or-server-functions) — read this before
  you write one.
- [Installation](/actors/docs/installation) — the plugin, the app module and the dev host.
- [Your first actor](/actors/docs/your-first-actor) — a counter, end to end.
- [The actor model](/actors/docs/actor-model) — activation, turns and identity in depth.

---
url: https://sigx.dev/daisyui/docs/theming/
title: Theming
description: Customize themes and colors with @sigx/daisyui
---

# Theming

SignalX DaisyUI supports DaisyUI's powerful theming system with 30+ built-in themes.

## Initializing Themes

Set up the theme system when your app loads:

```tsx
import { onMounted } from 'sigx';
import { initializeTheme } from '@sigx/daisyui';

onMounted(() => {
    initializeTheme({
        defaultTheme: 'dark',
        storageKey: 'theme',
    });
});
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultTheme` | `string` | `'light'` | Default theme if none is stored |
| `storageKey` | `string` | `'theme'` | localStorage key for persistence |

## Theme Toggle

Add a theme toggle button:

```tsx
import { ThemeToggle } from '@sigx/daisyui';

// Toggle between light and dark
<ThemeToggle />

// Custom themes
<ThemeToggle themes={['light', 'dark', 'cupcake', 'forest']} />
```

## Programmatic Theme Switching

Switch themes in code:

```tsx
import { setTheme, getTheme } from '@sigx/daisyui';

// Get current theme
const current = getTheme();

// Set a specific theme
setTheme('forest');
```

## Available Themes

DaisyUI includes 30+ themes:

**Light themes:**
- `light`, `cupcake`, `bumblebee`, `emerald`, `corporate`, `retro`, `cyberpunk`, `valentine`, `garden`, `lofi`, `pastel`, `fantasy`, `wireframe`, `cmyk`, `autumn`, `acid`, `lemonade`, `winter`

**Dark themes:**
- `dark`, `synthwave`, `halloween`, `forest`, `aqua`, `luxury`, `dracula`, `night`, `coffee`, `dim`, `nord`, `sunset`

## Custom Themes

You can create fully custom themes using the **[Theme Generator](/daisyui/docs/theme-generator)** — an interactive tool that lets you visually configure colors, radius, effects, sizes, and border width with live preview.

Define custom themes in your Tailwind config:

```js
// tailwind.config.js
module.exports = {
    plugins: [require('daisyui')],
    daisyui: {
        themes: [
            'light',
            'dark',
            {
                mytheme: {
                    'primary': '#570df8',
                    'secondary': '#f000b8',
                    'accent': '#37cdbe',
                    'neutral': '#3d4451',
                    'base-100': '#ffffff',
                    'info': '#3abff8',
                    'success': '#36d399',
                    'warning': '#fbbd23',
                    'error': '#f87272',
                },
            },
        ],
    },
};
```

Then use your custom theme:

```tsx
setTheme('mytheme');
```

## CSS Variables

Access theme colors via CSS variables:

```css
.my-element {
    background-color: hsl(var(--p)); /* primary */
    color: hsl(var(--pc)); /* primary-content */
    border-color: hsl(var(--b3)); /* base-300 */
}
```

### Available Variables

| Variable | Description |
|----------|-------------|
| `--p` | Primary color |
| `--pc` | Primary content (text on primary) |
| `--s` | Secondary color |
| `--sc` | Secondary content |
| `--a` | Accent color |
| `--ac` | Accent content |
| `--n` | Neutral color |
| `--nc` | Neutral content |
| `--b1` | Base 100 (background) |
| `--b2` | Base 200 |
| `--b3` | Base 300 |
| `--bc` | Base content |

## Responsive Theming

Apply different themes based on system preference:

```tsx
import { initializeTheme } from '@sigx/daisyui';

initializeTheme({
    defaultTheme: window.matchMedia('(prefers-color-scheme: dark)').matches 
        ? 'dark' 
        : 'light',
});
```

---
url: https://sigx.dev/core/docs/components/
title: Components
description: Learn how to create and compose SignalX components
---

# Components

Components are the building blocks of SignalX applications. They encapsulate UI logic, state, and rendering in a reusable package.

## Defining Components

Use `component` to create a component:

```tsx
import { component, render } from 'sigx';

const Greeting = component(() => {
    console.log('Greeting component created');
    return () => <h1>Hello, World!</h1>;
});

render(<Greeting />, "#sandbox");
```

The function passed to `component` is the **setup function**. It runs once when the component is created and returns a **render function**.

> **Setup runs untracked.** `setup()` — and the `created`/`mounted` hooks that run during mounting — execute without dependency tracking. Reactive reads in a child's setup do **not** become dependencies of an ancestor's render effect, so they can't trigger spurious ancestor re-renders. Component reactivity belongs to the per-component render function and to explicit `watch`/`computed` scopes (which create their own subscriptions). Put reactive reads you want tracked inside the returned render function, a `watch`, or a `computed` — not bare in `setup()`.

## Setup Context

The setup function receives a context object with everything you need:

```tsx
import { component, render } from 'sigx';

const MyComponent = component((ctx) => {
    // ctx.signal - Create reactive state
    const state = ctx.signal({ count: 0 });
    
    // ctx.props - Access component props
    // ctx.slots - Access named slots
    // ctx.emit - Emit events to parent
    // ctx.onMounted - Register mount callback
    // ctx.onUnmounted - Register unmount callback
    // ctx.expose - Expose API to parent via ref
    
    return () => <div>{state.count}</div>;
});

render(<MyComponent />, "#sandbox");
```

You can also destructure the context:

```tsx
import { component, render } from 'sigx';

const MyComponent = component(({ signal, props, slots, emit }) => {
    const state = signal({ count: 0 });
    return () => <div>{state.count}</div>;
});

render(<MyComponent />, "#sandbox");
```

## Props

Components can receive props from their parent:

```tsx
import { component, render, type Define } from 'sigx';

type GreetingProps = Define.Prop<'name', string, true>;  // required

const Greeting = component<GreetingProps>(({ props }) => {
    return () => <h1>Hello, {props.name}!</h1>;
});

render(<Greeting name="SignalX" />, "#sandbox");
```

### Optional Props

Mark props as optional with a `false` third type parameter:

```tsx
import { component, render, type Define } from 'sigx';

type ButtonProps = 
    & Define.Prop<'variant', 'primary' | 'secondary', false>  // optional
    & Define.Prop<'disabled', boolean, false>                 // optional
    & Define.Slot<'default'>;

const Button = component<ButtonProps>(({ props, slots }) => {
    return () => (
        <button 
            class={`btn btn-${props.variant || 'primary'}`}
            disabled={props.disabled}
        >
            {slots.default?.()}
        </button>
    );
});

render(<Button variant="primary">Click Me</Button>, "#sandbox");
```

### Forwarding Props

A component that wraps an element usually wants the consumer's leftover props to
reach that element. That's plain destructuring — take the props the component
handles itself, spread the rest:

```tsx
import { component, render, type Define } from 'sigx';

type ButtonProps =
    & Define.Prop<'variant', 'primary' | 'secondary'>
    & Define.Slot<'default'>
    & Define.Attrs;

const Button = component<ButtonProps>((ctx) => {
    return () => {
        const { variant, ...rest } = ctx.props;
        return (
            <button class={`btn btn-${variant ?? 'primary'}`} {...rest}>
                {ctx.slots.default?.()}
            </button>
        );
    };
});

// `title` and `onClick` are never named by Button — they ride the rest spread.
const App = component(() => {
    return () => (
        <Button
            variant="primary"
            title="forwarded straight through"
            onClick={() => console.log('clicked')}
        >
            Hover me
        </Button>
    );
});

render(<App />, "#sandbox");
```

`ctx.props` carries the props the parent declared and nothing else. `key` and
`ref` are peeled off before setup runs — alongside `children`, `slots` and
`$models` — because both are vnode-level concerns the renderer reads off the
vnode directly. So the spread above can't bind the consumer's `ref` a second
time with the element, and a spread onto a *child* can't stamp it with a key the
author never wrote.

At the element, framework-internal keys are skipped rather than rendered:
`client:*` hydration directives and `Model`-valued props never become DOM
attributes, on the client or in SSR output.

Forwarding is reactive in both directions. A wrapper that spreads its props —
`component((ctx) => () => <Child {...ctx.props} />)` — re-renders when the parent
starts passing a **new** prop key, not only when a prop it already passed
changes: enumerating a reactive object subscribes to its key set as well as to
the individual keys. The same holds for rest destructuring forwarded onto an
element.

> **Note:** two spellings of one event on the same element — `onClick` from the
> component and `onclick` arriving through a spread — resolve to the same
> `'click'` listener slot, so whichever is patched last wins and the other never
> runs. Development builds warn once per element when that happens.

### Host Attributes

A component accepts host attributes — `id`, `class`, `style`, `title`, `role`,
`tabIndex`, `hidden`, `dir`, `lang`, the rest of the universal set, plus
`data-*`, `aria-*` and the camelCase DOM handlers — when it declares
`Define.Attrs`:

```tsx
import { component, type Define } from 'sigx';

type ButtonProps =
    & Define.Prop<'variant', 'primary' | 'secondary'>
    & Define.Attrs;
```

Declare it only if the component really does forward its leftover props to an
element. The declaration is a promise to the consumer: a type that accepts
`title` on a component that drops it is exactly the failure the opt-in exists to
prevent.

When the component declares a prop whose name collides with a host attribute,
use `Define.WithAttrs<TOwn>` — the component's own declaration wins:

```tsx
// `title` here is a heading, not the HTML tooltip attribute.
type DialogProps = Define.WithAttrs<Define.Prop<'title', string, true>>;
```

Handlers are advertised in camelCase only. Both spellings reach the same DOM
listener slot, so offering `onclick` alongside `onClick` in the type would
advertise a collision.

> **Note:** TypeScript exempts JSX attribute names that aren't valid identifiers
> from excess-property checking, so `data-*` and `aria-*` compile on *any*
> component whatever its props type says. No declaration can make those an
> error — only forwarding them at runtime makes them work.

### Combining Prop Sources

A rest spread covers the common case, and needs no helper. What it can't do is
*combine* two sources. A JSX spread is lowered by the compiler into a single
object literal before the runtime sees anything, so in
`<button {...rest} {...bag} />` later keys clobber earlier ones — if the consumer
and the component both set `class`, one is lost.

`mergeProps(...sources)` combines the four kinds of key that must not overwrite:

| Key | How it combines |
|---|---|
| `class` / `className` | Concatenated in source order into one `class` |
| `style` | Merged left-to-right into an object; string sources are parsed first |
| `on*` handlers | Chained in source order, grouped by the event they resolve to, so `onClick` and `onclick` become one entry |
| `ref` | Chained into one ref that feeds every source's ref |
| everything else | Exact spread semantics — the last source with the key wins |

Sources may be objects or zero-argument thunks, and the result resolves on read,
so thunks stay reactive:

```tsx
import { component, mergeProps, render, type Define } from 'sigx';

type ButtonProps =
    & Define.Prop<'variant', 'primary' | 'secondary'>
    & Define.Slot<'default'>
    & Define.Attrs;

const Button = component<ButtonProps>((ctx) => {
    const onActivate = () => console.log('the component handler ran');

    const merged = mergeProps(
        () => { const { variant: _v, ...rest } = ctx.props; return rest; },
        () => ({ class: 'btn', onClick: onActivate })
    );

    return () => <button {...merged}>{ctx.slots.default?.()}</button>;
});

// The consumer sets `class` and `onClick` too — both sides survive.
const App = component(() => {
    return () => (
        <Button
            variant="primary"
            class="danger"
            onClick={() => console.log('the consumer handler ran')}
        >
            Click me
        </Button>
    );
});

render(<App />, "#sandbox");
```

Click it and both handlers log, in source order; inspect the button and its
class is `btn danger`. A plain `{...rest} {...bag}` spread would have kept only
one of each.

Three things to get right:

- **Call it once in setup**, as above. The derived `ref` and the chained
  handlers are identity-cached, which a per-render call throws away — the
  renderer then tears down and re-applies refs for nothing.
- **It is not a defaults helper.** It replaces a spread and behaves like one,
  so a later source's explicit `undefined` wins. Destructuring with defaults
  already covers defaulting.
- **Chaining can't express swallow.** A component that gates a consumer's
  handler — dropping `onClick` while disabled — keeps destructuring it out and
  calling it itself.

## Slots

Slots allow parent components to inject content:

```tsx
import { component, render, type Define } from 'sigx';

type CardProps = Define.Slot<'default'> & Define.Slot<'header'>;

const Card = component<CardProps>(({ slots }) => {
    return () => (
        <div class="card" style="border: 1px solid #ccc; border-radius: 8px; overflow: hidden;">
            <div class="card-header" style="background: #f5f5f5; padding: 12px; border-bottom: 1px solid #ccc;">
                {slots.header?.() ?? <span>Default Header</span>}
            </div>
            <div class="card-body" style="padding: 16px;">
                {slots.default?.()}
            </div>
        </div>
    );
});

render(
    <Card slots={{ header: () => <h2 style="margin: 0;">Card Title</h2> }}>
        <p style="margin: 0;">Card content goes here</p>
    </Card>,
    "#sandbox"
);
```

### Scoped Slots

Pass data back to the parent:

```tsx
import { component, render, type Define } from 'sigx';

type ListProps<T> = 
    & Define.Prop<'items', T[], true>
    & Define.Slot<'item', { item: T; index: number }>;

const List = component<ListProps<any>>(({ props, slots }) => {
    return () => (
        <ul>
            {props.items.map((item, index) => (
                <li key={index}>{slots.item?.({ item, index })}</li>
            ))}
        </ul>
    );
});

const fruits = ['Apple', 'Banana', 'Cherry'];

render(
    <List 
        items={fruits} 
        slots={{ item: ({ item, index }) => <span>{index + 1}. {item}</span> }}
    />,
    "#sandbox"
);
```

#### Two ways to fill a scoped slot

A function passed as **children** fills the default slot and receives the same
scoped props. The two forms are equivalent:

```tsx
// As a function child
<Row>{({ active }) => <span>{active ? 'on' : 'off'}</span>}</Row>

// As a `slots` prop
<Row slots={{ default: ({ active }) => <span>{active ? 'on' : 'off'}</span> }} />
```

The function child is what makes the `asChild` render-prop pattern work — a
component that owns behaviour and hands the caller its state, letting the caller
decide the markup:

```tsx
import { component, render, type Define } from 'sigx';

type ToggleProps = Define.Slot<'default', { on: boolean; toggle: () => void }>;

const Toggle = component<ToggleProps>(({ signal, slots }) => {
    const state = signal({ on: false });
    const toggle = () => state.on = !state.on;
    return () => slots.default?.({ on: state.on, toggle });
});

// The caller supplies the element — Toggle only owns the state.
const App = component(() => {
    return () => (
        <Toggle>
            {({ on, toggle }) => (
                <button onClick={toggle} aria-pressed={on}>{on ? 'On' : 'Off'}</button>
            )}
        </Toggle>
    );
});

render(<App />, "#sandbox");
```

The function is invoked once per accessor call, inside the consumer's render, so
reactivity is preserved — and the client and SSR agree, keeping hydration in
step. A fill returning `null` or `undefined` is dropped and an array is
flattened one level, exactly as the `slots`-prop form behaves.

Element children with a `slot="x"` attribute are unaffected: a function only
ever fills the default slot, because a function never satisfies the `slot`-prop
test that routes a child to a named one.

### What `slot=` routes, per child shape

`slot=` is the **HTML attribute**, so it routes host elements and fragments only:

| Child | Where it lands |
|---|---|
| `<div slot="header">` — host element | the `header` slot |
| `<><span slot="header"/></>` — fragment | the `header` slot |
| `{() => …}` — function child | the default slot, always |
| `<Chip slot="badge"/>` — **component** | the **default** slot |

A component child is the one to know about. The JSX types have always rejected
`slot=` on a component, so it was reachable only through a cast or from untyped
JS — and it now renders in the default slot, with `slot` arriving as an ordinary
undeclared prop plus a development warning.

The typed way to fill a named slot with a component is the `slots` prop, which is
checked against the consumer's declared slots:

```tsx
// Not routed — Chip lands in the default slot.
<Card><Chip slot="badge"/></Card>

// Routed, and type-checked against Card's declared slots.
<Card slots={{ badge: () => <Chip/> }}/>
```

### Fills are type-checked against the declaration

A slot declaration is a contract on both sides, and TypeScript enforces both
halves:

```tsx
// The declaration is what buys the checking.
type ListProps = Define.Slot<'row', { item: Item; active: boolean }>;

<List>{(p) => <Row item={p.item}/>}</List>   // p is INFERRED — no annotation
```

Two mistakes that used to compile are now errors:

- **A fill expecting props the slot does not declare.** Fix by declaring them:
  `Define.Slot<'default', { active: boolean }>`.
- **Calling a props-declaring slot with no arguments** — `slots.row?.()` where
  `row` declares props. Fix by passing them: `slots.row?.(props)`.

Together those were one runtime crash — a fill destructuring `{ active }` on a
slot that declares nothing, invoked with no argument — now unreachable rather
than merely survivable.

The payoff for correct code is inference: an unannotated fill parameter is typed
from the declaration, with no annotation and no cast.

A component that declares **no** `default` slot keeps `children?: any`. Children
are legal without a declaration and there is nothing to check them against, so
declaring the slot is what buys the checking. Element and function children still
mix freely in one default slot.

### Slot presence

A slot accessor is a **callable only when the parent actually provided content**;
when it didn't, the slot reads as `undefined`. So testing presence is a plain
truthiness check, and you always call a slot **optionally** with `?.()`:

```tsx
const Card = component<CardProps>(({ slots }) => {
    return () => (
        <div class="card">
            {/* render a header region only when one was passed */}
            {slots.header && <header>{slots.header?.()}</header>}

            {/* always call optionally — body is provided or it isn't */}
            <div class="body">{slots.default?.()}</div>

            {/* fall back when a slot is absent */}
            <footer>{slots.footer?.() ?? <small>No footer</small>}</footer>
        </div>
    );
});
```

Things to know:

- **Always call slots optionally** — `slots.default?.()`. Invoking a slot the
  parent never supplied (`slots.default()` when it's `undefined`) throws.
- **Presence is a plain check** — `slots.x` for "is it there?", `slots.x?.()` to
  render it, `slots.x?.() ?? fallback` to substitute when absent.
- **Presence is reactive.** A slot appearing or disappearing re-renders the
  consumer, so a region that depends on `slots.x` updates on its own.
- **A slot passed via the `slots` prop counts as present** regardless of what its
  function returns — even a slot that returns `null` is "provided", so the
  presence check reflects what the parent passed, not what it rendered.
- **SSR matches the client** — presence resolves identically on the server and
  during hydration, so there's no mismatch.

## Events

Components can emit events to their parent:

```tsx
import { component, render, type Define } from 'sigx';

type ButtonProps = 
    & Define.Event<'click', MouseEvent>
    & Define.Event<'customAction', { action: string }>
    & Define.Slot<'default'>;

const Button = component<ButtonProps>(({ slots, emit }) => {
    return () => (
        <button onClick={(e) => {
            emit('click', e);
            emit('customAction', { action: 'clicked' });
        }}>
            {slots.default?.()}
        </button>
    );
});

const App = component(({ signal }) => {
    const log = signal({ message: 'Click the button!' });
    
    return () => (
        <div>
            <Button 
                onClick={() => log.message = 'Clicked!'}
                onCustomAction={({ action }) => log.message = `Action: ${action}`}
            >
                Click me
            </Button>
            <p style="margin-top: 8px;">{log.message}</p>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Exposing Component API

Use `expose` to make methods available to parent via ref:

```tsx
import { component, Exposed, render, type Define } from 'sigx';

type CounterExpose = Define.Expose<{
    increment: () => void;
    reset: () => void;
}>;

const Counter = component<CounterExpose>(({ signal, expose }) => {
    const state = signal({ count: 0 });
    
    expose({
        increment: () => state.count++,
        reset: () => state.count = 0
    });
    
    return () => <div style="font-size: 24px; margin-bottom: 12px;">Count: {state.count}</div>;
});

const App = component(() => {
    let counterApi: Exposed<typeof Counter>;
    
    return () => (
        <div>
            <Counter ref={r => counterApi = r!} />
            <button onClick={() => counterApi?.increment()}>Increment</button>
            <button onClick={() => counterApi?.reset()} style="margin-left: 8px;">Reset</button>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Component Context Reference

| Property | Description |
|----------|-------------|
| `signal` | Create reactive state |
| `props` | Reactive props accessor |
| `slots` | Named slot functions (default always exists) |
| `emit` | Typed event emitter |
| `el` | The component's root element (after mount) |
| `parent` | Parent component instance (if any) |
| `onMounted(fn)` | Register mount callback |
| `onUnmounted(fn)` | Register unmount callback |
| `onCreated(fn)` | Register created callback |
| `onUpdated(fn)` | Register update callback |
| `expose(api)` | Expose API to parent via ref |
| `update()` | Force re-render (for HMR) |

## Two-Way Binding

SignalX provides powerful `model` binding for two-way data synchronization with form elements and custom components:

```tsx
import { component, render } from 'sigx';

const FormDemo = component(({ signal }) => {
    const state = signal({ name: '', agreed: false });
    
    return () => (
        <div>
            <input model={() => state.name} placeholder="Your name" />
            <label>
                <input type="checkbox" model={() => state.agreed} />
                I agree
            </label>
            <p>Hello, {state.name || 'stranger'}! Agreed: {state.agreed ? 'Yes' : 'No'}</p>
        </div>
    );
});

render(<FormDemo />, "#sandbox");
```

For complete documentation on two-way binding including:
- All supported native elements (text, checkbox, radio, select, textarea)
- Creating custom components with `Define.Model<T>`
- Named model props with `model:propName`

See the dedicated [Two-Way Binding](/core/docs/two-way-binding) guide.

## Fragment

Use `Fragment` to return multiple elements without a wrapper:

```tsx
import { component, Fragment, render, type Define } from 'sigx';

const ListItems = component(() => {
    return () => (
        <Fragment>
            <li>Item 1</li>
            <li>Item 2</li>
            <li>Item 3</li>
        </Fragment>
    );
});

type ConditionalProps = Define.Prop<'showExtra', boolean, false>;

const ConditionalItems = component<ConditionalProps>(({ props }) => {
    return () => (
        <ul>
            {props.showExtra && (
                <>
                    <li>Extra 1</li>
                    <li>Extra 2</li>
                </>
            )}
            <li>Always visible</li>
        </ul>
    );
});

const App = component(({ signal }) => {
    const state = signal({ showExtra: true });
    
    return () => (
        <div>
            <label>
                <input type="checkbox" model={() => state.showExtra} /> Show extra items
            </label>
            <ConditionalItems showExtra={state.showExtra} />
            <h4>Using Fragment:</h4>
            <ul><ListItems /></ul>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Component Options

Pass options as a second argument:

```tsx
import { component, render } from 'sigx';

const MyComponent = component(
    (ctx) => {
        return () => <div>Hello from named component!</div>;
    },
    { name: 'MyComponent' }  // Shows in DevTools
);

render(<MyComponent />, "#sandbox");
```

## Next Steps

- [Signals](/core/docs/signals) - Reactive state management
- [Lifecycle](/core/docs/lifecycle) - Component lifecycle hooks
- [Effects](/core/docs/effects) - Side effects and reactions

---
url: https://sigx.dev/core/docs/directives/
title: Directives
description: Create reusable element-level behavior with the directive system
---

# Directives

Directives provide reusable, element-level lifecycle hooks via the `use:name` prop syntax. They let you encapsulate DOM behavior — such as toggling visibility, adding tooltips, or integrating third-party libraries — and apply it declaratively to any element.

## Built-in Directives

### `show`

The `show` directive is built-in and always available. It toggles element visibility via the CSS `display` property. Unlike conditional rendering, `use:show` keeps the element in the DOM and only toggles its visibility:

```tsx
import { component, render } from 'sigx';

const ToggleDemo = component(({ signal }) => {
    const state = signal({ visible: true });

    return () => (
        <div style="padding: 16px;">
            <button onClick={() => state.visible = !state.visible}>
                {state.visible ? 'Hide' : 'Show'}
            </button>
            <div use:show={state.visible} style={{ 
                marginTop: '12px',
                padding: '12px',
                background: '#056b25ff',
                borderRadius: '8px'
            }}>
                This content is toggled with use:show
            </div>
        </div>
    );
});

render(<ToggleDemo />, "#sandbox");
```

Built-in directives like `show` are registered internally and resolve automatically — you just pass the value directly. No imports or registration needed.

#### When to Use `show` vs Conditional Rendering

| | `use:show` | Ternary / `&&` |
|---|---|---|
| **DOM** | Element stays in the DOM | Element is added/removed |
| **State** | Preserves scroll, focus, input values | State is lost on hide |
| **Cost** | Cheap toggle (just CSS) | Re-creates elements on show |
| **Best for** | Frequent toggling | Rarely shown content |

#### Preserving Display Values

`show` preserves the element's original `display` value. If your element uses `display: flex`, toggling show will restore it to `flex`, not the default `block`:

```tsx
import { component, render } from 'sigx';

const FlexDemo = component(({ signal }) => {
    const state = signal({ visible: true });

    return () => (
        <div style="padding: 16px;">
            <button onClick={() => state.visible = !state.visible}>
                Toggle Flex Container
            </button>
            <div 
                use:show={state.visible} 
                style={{ 
                    display: 'flex', 
                    gap: '8px', 
                    marginTop: '12px' 
                }}
            >
                <div style="padding: 8px; background: #bfdbfe; border-radius: 4px;">Item 1</div>
                <div style="padding: 8px; background: #93c5fd; border-radius: 4px;">Item 2</div>
                <div style="padding: 8px; background: #60a5fa; border-radius: 4px;">Item 3</div>
            </div>
        </div>
    );
});

render(<FlexDemo />, "#sandbox");
```

## Defining a Custom Directive

Use `defineDirective` to create a directive:

```tsx
import { defineDirective } from 'sigx';

const tooltip = defineDirective<string>({
    mounted(el, { value }) {
        el.title = value;
    },
    updated(el, { value }) {
        el.title = value;
    },
    unmounted(el) {
        el.title = '';
    }
});
```

The generic parameter (`<string>`) defines the type of the directive's binding value. SignalX will enforce this at the type level when the directive is used in JSX.

## Registering Custom Directives

Custom directives need to be registered so the runtime can resolve them by name when you write `use:myDirective={value}`. Register them globally on your app instance with `app.directive()`:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

// 1. Define the directive
const highlight = defineDirective<string>({
    mounted(el, { value }) {
        el.style.backgroundColor = value;
    },
    updated(el, { value }) {
        el.style.backgroundColor = value;
    },
    unmounted(el) {
        el.style.backgroundColor = '';
    }
});

const App = component(({ signal }) => {
    const state = signal({ color: '#fef08a' });

    const colors = ['#fef08a', '#bbf7d0', '#bfdbfe', '#fecaca', '#e9d5ff'];

    return () => (
        <div style="padding: 16px;">
            <div style="display: flex; gap: 6px; margin-bottom: 12px;">
                {colors.map(c => (
                    <button 
                        onClick={() => state.color = c}
                        style={{
                            width: '32px', height: '32px', borderRadius: '50%',
                            background: c, border: state.color === c ? '3px solid #333' : '2px solid #ccc',
                            cursor: 'pointer'
                        }}
                    />
                ))}
            </div>
            {/* 3. Use the shorthand — just pass a value, no imports needed */}
            <div use:highlight={state.color} style="padding: 12px; border-radius: 8px;">
                Highlighted with use:highlight
            </div>
        </div>
    );
});

// 2. Register on the app
const app = defineApp(<App />);
app.directive('highlight', highlight);
app.mount('#sandbox');
```

Once registered, `use:highlight={value}` works exactly like the built-in `use:show` — you just pass a value and the runtime resolves the directive by name. `app.directive()` registration works both on the client and during SSR.

### Layered Registration

Directive registration happens in layers:

- **Built-in directives** (`show`) register automatically. The platform package registers them as a side effect, and their JSX types are globally visible, so the runtime always resolves them — no import or setup needed.
- **Per-app** with `app.directive(name, def)` — the directive is available to that app's component tree, on the client and during SSR. This is the common case for custom and pack directives.
- **Globally** with `registerBuiltInDirective(name, def)` (from `@sigx/runtime-dom`) — registers a directive into the built-in tier so every app and every `render()` call resolves it by name without per-app wiring. Reach for this when shipping a directive pack that should be available everywhere.

```tsx
import { defineDirective } from 'sigx';
import { registerBuiltInDirective } from '@sigx/runtime-dom';

const focusOnMount = defineDirective<void, HTMLInputElement>({
    mounted(el) { el.focus(); }
});

// Available app-wide and in plain render() — no app.directive() call needed
registerBuiltInDirective('focusOnMount', focusOnMount);
```

### Resolution Priority

When the runtime encounters a `use:name` prop, it resolves the directive in this order:

1. **Explicit directive** — A directive definition or `[definition, value]` tuple passed directly (no registration needed)
2. **Built-in directives** — Directives in the built-in tier: `show` (registered automatically) and anything added globally via `registerBuiltInDirective()`
3. **App-registered directives** — Custom directives registered via `app.directive()`

This means built-in directives always take precedence, and you can always bypass registration by passing a directive explicitly.

## Using Directives

There are three ways to apply a directive to an element:

### Shorthand (registered directives)

For built-in and app-registered directives, pass the value directly:

```tsx
// Built-in — always works
<div use:show={isVisible}>Content</div>

// Custom — after calling app.directive('highlight', highlight)
<div use:highlight="#fef08a">Highlighted</div>
```

### Tuple Form (escape hatch)

Pass the directive definition and value as a tuple. This works without any registration — useful for one-off directives or when you don't have access to the app instance:

```tsx
import { component, defineDirective, render } from 'sigx';

const tooltip = defineDirective<string>({
    mounted(el, { value }) {
        el.title = value;
    },
    updated(el, { value }) {
        el.title = value;
    }
});

const Demo = component(() => {
    return () => (
        <div style="padding: 16px;">
            <div 
                use:tooltip={[tooltip, "I'm a tooltip! Hover to see."]}
                style="padding: 12px; background: #f0f0f0; border-radius: 8px; cursor: help;"
            >
                Hover me to see the tooltip (check title attribute)
            </div>
        </div>
    );
});

render(<Demo />, "#sandbox");
```

### Bare Form (no value)

If the directive doesn't need a binding value, pass the definition directly:

```tsx
import { component, defineDirective, render } from 'sigx';

const autoBorder = defineDirective<void>({
    mounted(el) {
        el.style.border = '2px dashed #6366f1';
        el.style.borderRadius = '8px';
    },
    unmounted(el) {
        el.style.border = '';
    }
});

const Demo = component(() => {
    return () => (
        <div style="padding: 16px;">
            <div use:border={autoBorder} style="padding: 12px;">
                This element got a dashed border from a directive
            </div>
        </div>
    );
});

render(<Demo />, "#sandbox");
```

## Lifecycle Hooks

Directives support four lifecycle hooks, all optional:

| Hook | When it runs |
|------|-------------|
| `created` | After the element is created, before it is inserted into the DOM |
| `mounted` | After the element is inserted into the DOM |
| `updated` | When the binding value changes |
| `unmounted` | Before the element is removed from the DOM |

Each hook receives the DOM element and a binding object:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

const lifecycle = defineDirective<string>({
    created(el, { value }) {
        el.dataset.log = 'created';
    },
    mounted(el, { value }) {
        el.dataset.log += ' → mounted';
        el.style.backgroundColor = value;
    },
    updated(el, { value, oldValue }) {
        el.dataset.log += ' → updated';
        el.style.backgroundColor = value;
    },
    unmounted(el) {
        // cleanup
    }
});

const Demo = component(({ signal }) => {
    const state = signal({ color: '#bbf7d0' });

    return () => (
        <div style="padding: 16px;">
            <div style="display: flex; gap: 8px; margin-bottom: 12px;">
                <button onClick={() => state.color = '#bbf7d0'}>Green</button>
                <button onClick={() => state.color = '#bfdbfe'}>Blue</button>
                <button onClick={() => state.color = '#fecaca'}>Red</button>
            </div>
            <div use:lifecycle={state.color} style="padding: 12px; border-radius: 8px; transition: background-color 0.2s;">
                Change colors to trigger the updated hook
            </div>
        </div>
    );
});

const app = defineApp(<Demo />);
app.directive('lifecycle', lifecycle);
app.mount('#sandbox');
```

## The Binding Object

The binding object (`DirectiveBinding<T>`) has two properties:

- **`value`** — The current value passed to the directive
- **`oldValue`** — The previous value (only available in the `updated` hook)

```tsx
interface DirectiveBinding<T> {
    value: T;
    oldValue?: T;
}
```

## Type-Safe Element Types

By default, the element parameter is typed as `any`. You can narrow it using the second generic parameter:

```tsx
import { defineDirective } from 'sigx';

// Only works on HTMLInputElement
const autoSelect = defineDirective<void, HTMLInputElement>({
    mounted(el) {
        el.select(); // Fully typed — .select() exists on HTMLInputElement
    }
});
```

## Typing a `use:*` Attribute

`JSX.DirectiveAttribute<T, El>` is the type of a directive's `use:*` attribute — it accepts the bare value, the directive definition, or the `[definition, value]` tuple in one alias:

```tsx
// JSX.DirectiveAttribute<T, El = HTMLElement> =
//   | T
//   | DirectiveDefinition<T, El>
//   | [DirectiveDefinition<T, El>, T]
```

To give a registered directive IntelliSense on `use:`, augment `JSX.DirectiveAttributeExtensions`:

```tsx
// Makes `use:highlight={'#fef08a'}` autocomplete and type-check
declare global {
    namespace JSX {
        interface DirectiveAttributeExtensions {
            'use:highlight'?: JSX.DirectiveAttribute<string>;
        }
    }
}
```

Without the augmentation, `use:*` attributes still work — they fall back to a permissive catch-all type. The augmentation is what surfaces the directive by name in editor completions.

## Custom Directive Examples

### Click Outside

Detect clicks outside an element — useful for closing dropdowns and modals:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

const clickOutside = defineDirective<() => void>({
    mounted(el, { value: callback }) {
        const handler = (e: MouseEvent) => {
            if (!el.contains(e.target as Node)) callback();
        };
        document.addEventListener('click', handler);
        (el as any).__clickOutsideCleanup = handler;
    },
    unmounted(el) {
        document.removeEventListener('click', (el as any).__clickOutsideCleanup);
        delete (el as any).__clickOutsideCleanup;
    }
});

const Demo = component(({ signal }) => {
    const state = signal({ open: false });

    return () => (
        <div style="padding: 16px;">
            <button onClick={(e: Event) => { e.stopPropagation(); state.open = true; }}>
                Open Dropdown
            </button>
            {state.open && (
                <div 
                    use:clickOutside={() => state.open = false}
                    style={{
                        marginTop: '8px', padding: '16px',
                        background: '#155e01ff', border: '1px solid #e5e7eb',
                        borderRadius: '8px', boxShadow: '0 4px 12px rgba(0,0,0,0.1)'
                    }}
                >
                    Click outside this box to close it
                </div>
            )}
        </div>
    );
});

const app = defineApp(<Demo />);
app.directive('clickOutside', clickOutside);
app.mount('#sandbox');
```

### Long Press

Trigger a callback after holding down an element:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

const longPress = defineDirective<{ duration?: number; onPress: () => void }>({
    mounted(el, { value: { duration = 600, onPress } }) {
        let timer: ReturnType<typeof setTimeout>;
        const start = () => { timer = setTimeout(onPress, duration); };
        const cancel = () => clearTimeout(timer);
        el.addEventListener('pointerdown', start);
        el.addEventListener('pointerup', cancel);
        el.addEventListener('pointerleave', cancel);
        (el as any).__longPressCleanup = () => {
            el.removeEventListener('pointerdown', start);
            el.removeEventListener('pointerup', cancel);
            el.removeEventListener('pointerleave', cancel);
        };
    },
    unmounted(el) {
        (el as any).__longPressCleanup?.();
    }
});

const Demo = component(({ signal }) => {
    const state = signal({ count: 0 });

    return () => (
        <div style="padding: 16px;">
            <button 
                use:longPress={{ onPress: () => state.count++, duration: 600 }}
                style="padding: 12px 24px; background: #6366f1; color: white; border: none; border-radius: 8px; cursor: pointer; user-select: none;"
            >
                Hold me for 600ms
            </button>
            <p style="margin-top: 12px;">Long presses: {state.count}</p>
        </div>
    );
});

const app = defineApp(<Demo />);
app.directive('longPress', longPress);
app.mount('#sandbox');
```

### Intersection Observer

Trigger a callback when an element enters the viewport:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

const whenVisible = defineDirective<() => void>({
    mounted(el, { value: onVisible }) {
        const observer = new IntersectionObserver(([entry]) => {
            if (entry.isIntersecting) {
                onVisible();
                observer.disconnect();
            }
        });
        observer.observe(el);
        (el as any).__observer = observer;
    },
    unmounted(el) {
        (el as any).__observer?.disconnect();
    }
});

const Demo = component(({ signal }) => {
    const state = signal({ seen: false });

    return () => (
        <div style="padding: 16px;">
            <p>Scroll down inside this box:</p>
            <div style="height: 150px; overflow-y: auto; border: 1px solid #e5e7eb; border-radius: 8px; padding: 12px;">
                <div style="height: 200px; display: flex; align-items: center; justify-content: center; color: #999;">
                    ↓ Keep scrolling ↓
                </div>
                <div 
                    use:whenVisible={() => state.seen = true}
                    style={{
                        padding: '16px', borderRadius: '8px', textAlign: 'center', color: "black", 
                        background: state.seen ? '#bbf7d0' : '#f3f4f6',
                        transition: 'background-color 0.3s'
                    }}
                >
                    {state.seen ? '✅ I was seen!' : '👀 Scroll to reveal me'}
                </div>
            </div>
        </div>
    );
});

const app = defineApp(<Demo />);
app.directive('whenVisible', whenVisible);
app.mount('#sandbox');
```

## Multiple Directives

You can apply multiple directives to the same element. Each directive manages its own lifecycle independently:

```tsx
import { component, defineDirective, defineApp, render } from 'sigx';

const bgColor = defineDirective<string>({
    mounted(el, { value }) { el.style.backgroundColor = value; },
    updated(el, { value }) { el.style.backgroundColor = value; }
});

const border = defineDirective<string>({
    mounted(el, { value }) { el.style.border = `2px solid ${value}`; },
    updated(el, { value }) { el.style.border = `2px solid ${value}`; }
});

const Demo = component(({ signal }) => {
    const state = signal({ bg: '#fef08a', bd: '#f59e0b' });

    return () => (
        <div style="padding: 16px;">
            <div style="display: flex; gap: 8px; margin-bottom: 12px;">
                <button onClick={() => { state.bg = '#fef08a'; state.bd = '#f59e0b'; }}>Warm</button>
                <button onClick={() => { state.bg = '#dbeafe'; state.bd = '#3b82f6'; }}>Cool</button>
                <button onClick={() => { state.bg = '#dcfce7'; state.bd = '#22c55e'; }}>Fresh</button>
            </div>
            <div 
                use:bgColor={state.bg}
                use:border={state.bd}
                style="padding: 16px; border-radius: 8px; transition: all 0.2s;color:black"
            >
                Two directives on one element
            </div>
        </div>
    );
});

const app = defineApp(<Demo />);
app.directive('bgColor', bgColor);
app.directive('border', border);
app.mount('#sandbox');
```

## SSR Support

When using `@sigx/server-renderer`, directives can provide SSR-specific props via the `getSSRProps` hook. This hook is available when the server-renderer package is installed — it extends the directive type automatically through TypeScript module augmentation.

```tsx
import { defineDirective } from 'sigx';

const hidden = defineDirective<boolean>({
    mounted(el, { value }) {
        el.style.display = value ? 'none' : '';
    },
    getSSRProps({ value }) {
        if (value) {
            return { style: { display: 'none' } };
        }
    }
});
```

`getSSRProps` returns an object whose properties are merged into the element's HTML attributes during server rendering. Custom directives registered via `app.directive()` work in SSR automatically — the server renderer resolves them from the app context just like the client renderer does. Built-in directives like `show` have their SSR support handled automatically.

## Summary

| Registration | How it works | Use case |
|---|---|---|
| **Built-in** (`show`) | Always available, no registration needed | Core framework directives |
| **`app.directive()`** | Register on your app instance (client + SSR) | Custom directives used across your app |
| **`registerBuiltInDirective()`** | Register into the built-in tier, every app + `render()` | Directive packs that should be globally available |
| **Tuple form** `[def, value]` | Pass definition inline, no registration | One-off usage, library directives |

---
url: https://sigx.dev/deploy/docs/overview/
title: Deploying SignalX
description: Deploy your SSR app to Node, Cloudflare Workers, Deno, Bun, Vercel or Netlify — one fetch handler, an adapter per platform
---

# Deploying SignalX

<p class="lede">Every platform runs the same app: a WinterCG `createFetchHandler` behind an
entry file you own. The Node server is built in; Cloudflare, Vercel and Netlify each have a
build adapter; Deno and Bun deploy from a few lines of config.</p>

## The deployment model

A SignalX SSR app deploys the same way everywhere:

1. **One runtime** — [`createFetchHandler`](/server/packages/server-renderer/fetch-handler)
   from `@sigx/server-renderer` turns a `Request` into a `Response` on any WinterCG
   runtime. Bots get a complete blocking document; everyone else streams shell-first;
   `useResponse` status/redirects resolve before the first byte.
2. **One build seam** — an adapter passed to
   [`sigx({ ssr: { adapter } })`](/vite/docs/deploy-adapters) in your Vite config
   decides how the server bundle is built (externalized for Node and Bun, fully
   bundled for the edge) and what platform output is generated.
3. **One entry you own** — `src/entry.<platform>.ts` is scaffolded on first build and
   never overwritten. It composes **static assets → server functions → document
   render**, and always exports the portable `{ fetch }` shape.

## The platform matrix

| Platform | Adapter | serverBuild | Statics | Deploy with |
|---|---|---|---|---|
| [Node](/deploy/docs/node/) | built-in `nodeAdapter()` (default) | external | `express.static` / `node:http` | `node --conditions production server.mjs` |
| [Cloudflare Workers](/deploy/packages/cloudflare/overview/) | `@sigx/cloudflare` | bundled, `['workerd','worker']` | wrangler `assets` — served before the worker runs | `wrangler deploy` |
| [Deno / Deno Deploy](/deploy/docs/deno/) | inline adapter object — no package | bundled, `['deno']` | `serveDir` (`@std/http`) fallthrough | `deno deploy` |
| [Bun](/deploy/docs/bun/) | reuses the Node build — no package | external | `Bun.serve` routes / `Bun.file` | `bun --conditions=production server.bun.ts` |
| [Vercel — Node runtime](/deploy/packages/vercel/overview/) | `@sigx/vercel` | bundled | Build Output `static/` + `filesystem` route | `vercel deploy --prebuilt` |
| [Vercel — Edge runtime](/deploy/packages/vercel/overview/) | `@sigx/vercel` with `{ runtime: 'edge' }` | bundled, `['edge-light','worker']` | Build Output `static/` + `filesystem` route | `vercel deploy --prebuilt` |
| [Netlify](/deploy/packages/netlify/overview/) | `@sigx/netlify` | bundled | publish dir CDN, `preferStatic` | `netlify deploy --prod` |

## The entry contract

Whatever the platform, the entry rhymes (Cloudflare shown):

```ts
// src/entry.cloudflare.ts — user-owned, ~20 lines
import { createFetchHandler } from '@sigx/server-renderer/server';
import { handleServerFnRequest, matchesServerFn } from '@sigx/server/server';
import { createBoundaryRefresh } from '@sigx/resume/server';
import { template, assets } from 'virtual:sigx-app';
import { serverFns, serverFnBase } from 'virtual:sigx-server-fns';
import { createApp } from './entry-server';

const handler = createFetchHandler({
    template,
    app: (url) => createApp(url),
    document: { assets }
});

const renderBoundaries = createBoundaryRefresh({ components: { /* … */ } });

export default {
    async fetch(request: Request) {
        if (matchesServerFn(request, serverFnBase)) {
            return handleServerFnRequest(request, {
                base: serverFnBase,
                resolve: (s) => serverFns[s]?.() ?? null,
                renderBoundaries
            });
        }
        return handler(request);
    }
};
```

The composition order **is** your routing policy: static assets first (served by
the platform wherever possible), then the server-function endpoint, then the
document render for everything else.

Two details in that entry are easy to leave out, and both fail silently:

- **`serverFnBase`** — `virtual:sigx-server-fns` exports the mount path the build
  actually used, so the predicate and the handler cannot disagree with each other
  or with `sigxServer({ base })`. Everything after the base *is* the symbol, so a
  base that is wrong only in part slices the symbol at the wrong offset — worse
  than a clean miss. Passing it to both is the fix; the plugin warns at build time
  when a non-default base is configured and an entry still calls
  `matchesServerFn(request)` bare.
- **`renderBoundaries`** — without it, [single-flight boundary
  refresh](/server/packages/resume/usage#single-flight-boundary-refresh) never
  happens. Nothing errors; mutations simply stop updating server-rendered
  boundaries, and the client converges a round trip later through `$cache`.
**You do not need to import your server app here.** Production builds inject a
side-effect import of it at the top of `virtual:sigx-server-fns`, so an entry that
imports the registry — as this one does — already has the pipeline stamped. Add an
explicit `import './server-app'` only in an entry that does not touch the registry
at all.

## The static-tier rules

Two rules hold on every platform — the adapters encode them, and the
hand-written entries (Deno, Bun) must keep them:

- **GET/HEAD-only.** POSTs belong to the server-function endpoint; a static tier
  that answers other methods (e.g. `serveDir`'s 405) would swallow them.
- **Never serve the raw outlet template.** The client build's `index.html` is
  the unrendered document shell — every adapter keeps it off `/` (wrangler
  `html_handling: "none"`, Vercel's `static/` omits it, Netlify strips it from
  the publish dir), because the platform's static tier would otherwise shadow
  the document render.

Security defaults are unchanged by deployment — the server-function endpoint
keeps its POST-only JSON, CSRF and origin gates on every platform; see
[Deployment & security](/server/packages/server/deployment).

## Where to go next

- [Node](/deploy/docs/node/) — the default, no adapter needed
- [Deno & Deno Deploy](/deploy/docs/deno/) / [Bun](/deploy/docs/bun/) — the
  package-less platforms
- [Cloudflare](/deploy/packages/cloudflare/overview/),
  [Vercel](/deploy/packages/vercel/overview/),
  [Netlify](/deploy/packages/netlify/overview/) — the adapter packages
- [Deploy adapters in @sigx/vite](/vite/docs/deploy-adapters) — the
  `SigxAdapter` contract behind all of them

Running [actors](/actors/) as well? A host is stateful and long-lived, so it has
requirements this page does not cover — readiness that distinguishes draining
from dead, a shutdown order that drains connections, and a backend for state.
See [Kubernetes](/actors/docs/kubernetes) and
[Cloudflare Workers](/actors/docs/cloudflare-workers).

---
url: https://sigx.dev/lynx/docs/directives/
title: Directives
description: Element-level use:* directives — lifecycle hooks on a native view, plus the built-in show
---

# Directives

<p class="lede">Attach reusable lifecycle behavior to a single element with the <code>use:*</code> prop syntax — including the built-in <code>show</code>, which toggles visibility while keeping the element mounted.</p>

A directive is a small object of lifecycle hooks that runs against the native element it's attached to. SignalX's runtime-core directive system is wired into the Lynx renderer, so directives work on the background-thread `ShadowElement` — no DOM required.

## The `use:*` syntax

Attach a directive with a `use:<name>` prop:

```tsx
import { signal } from '@sigx/lynx';

const isOpen = signal(true);

// Shorthand — `name` resolves a registered directive (built-in, then app):
<view use:show={isOpen.value}>Content</view>;
```

There are two ways to give a directive its definition and value:

```tsx
import { show } from '@sigx/lynx';

// Shorthand: use:name={value} — resolves `name` from the registry.
<view use:show={isOpen.value} />;

// Explicit tuple: use:name={[definition, value]} — pass the definition directly.
<view use:show={[show, isOpen.value]} />;
```

The shorthand resolves `name` first from the built-in registry (where `show` lives), then from per-app `app.directive()` registrations. The explicit tuple skips resolution by passing the definition itself — handy for custom directives you import locally.

## Lifecycle hooks

A directive definition has four optional hooks, all receiving the host element and a binding `{ value, oldValue }`:

| Hook | When |
|---|---|
| `created` | After the element is created, on the directive's first sight. |
| `mounted` | After the element is inserted into the tree. |
| `updated` | When the bound value changes (`oldValue` is the previous value). |
| `unmounted` | Before the element is removed — or when the `use:*` prop is removed from a still-mounted element. |

## Defining a directive

Use `defineDirective` (re-exported from `@sigx/lynx`). The `LynxDirective<T>` helper types the definition against Lynx's `ShadowElement` host:

```tsx
import { defineDirective, type LynxDirective } from '@sigx/lynx';

const autofocus: LynxDirective<boolean> = defineDirective({
  mounted(el, { value }) {
    if (value) {
      // focus the element…
    }
  },
});
```

To type the `use:autofocus` attribute on a `use:*` prop, the `DirectiveAttribute<T>` helper describes one directive attribute in a line.

## Registering directives

A directive must be resolvable for the shorthand `use:name={value}` form to work. Two options:

- **Globally** — `registerBuiltInDirective(name, def)` makes a directive available app-wide. This is the seam for directive packs.

  ```tsx
  import { registerBuiltInDirective } from '@sigx/lynx';
  registerBuiltInDirective('autofocus', autofocus);
  ```

- **Per app** — `app.directive(name, def)` registers on a single app context. Preferred when an app context exists.

  ```tsx
  app.directive('autofocus', autofocus);
  ```

You can always skip registration by using the explicit tuple form `use:name={[def, value]}` with an imported definition.

## The `show` directive

`show` ships built in and is registered with the platform automatically, so `use:show` works out of the box.

```tsx
import { signal } from '@sigx/lynx';

const isOpen = signal(false);

<view use:show={isOpen.value}>Content that stays mounted</view>;
```

`use:show` toggles the element's visibility via `display` while keeping it **mounted** — a single style op instead of an unmount/remount. Because the element stays alive, it preserves native state: input focus and value, scroll position, and any expensive subtree.

**Tradeoff:** a hidden subtree stays mounted as live native views, so it still costs memory. Prefer conditional rendering (`{cond && <view/>}`, which unmounts/remounts) for large branches that are rarely shown; reach for `use:show` when toggling is frequent or you want to keep element state.

`show` here is a **Lynx-native** implementation — it toggles a Lynx style op directly, distinct from the runtime-dom `show` on the web. It is mobile-only; there is no SSR for it.

## See also

- [Native elements](/lynx/docs/elements) — the built-in `view` / `text` / `image` set directives attach to.
- [Styling & layout](/lynx/docs/styling) — the style model `show` toggles.

---
url: https://sigx.dev/lynx/docs/reactivity/
title: Reactivity bridge
description: How signals cross the background → main-thread boundary
---

# Reactivity bridge

<p class="lede">Your components run on a background thread; the views live on the main thread. Signals bridge the two.</p>

## Two threads, one component tree

Lynx runs your app across two JavaScript contexts:

- The **background thread** (the "JS thread") runs everything you write: component setup, `signal` / `computed` / `effect`, and the SignalX renderer. This is where reactivity lives.
- The **main thread** (also called *Lepus*) is frame-locked to the UI. It applies native view updates, runs `'main thread'` worklets, and drives per-frame animation.

The split matters because it is what keeps the UI at 60fps even while JS is busy. Gestures and animations can run on the main thread without waiting for the background thread to wake up.

You almost never think about this when writing normal reactive UI — a `signal` change on the background thread streams to the main thread as a compact op and patches the affected native view. You only reach for the cross-thread primitives below when you need values the main thread reads *every frame*.

## Signals run on the background thread

`signal`, `computed` and `effect` are the same primitives you use on the web, re-exported from `@sigx/lynx`. On Lynx they all execute on the background thread:

```tsx
import { signal, computed, effect } from '@sigx/lynx';

const count = signal(0);
const doubled = computed(() => count.value * 2);

const runner = effect(() => {
    console.log('count is', count.value);
});

count.value = 1; // re-runs the effect, recomputes `doubled`

runner.stop(); // dispose the effect when you're done
```

Read `.value` to track a dependency; assign `.value` to trigger dependents. `effect` returns a runner with `.stop()` to dispose it. Inside a `component`, the framework manages effect lifetimes for you — you rarely call `effect` directly.

## The op queue

When a signal changes, the renderer does not re-serialize your component tree. It buffers a small set of ops and flushes them as one batched call to the main thread per microtask. The main-thread runtime (`@sigx/lynx-runtime-main`) applies that op stream through the Lynx PAPI, so only the native views that read a changed signal update.

This is the default path for all ordinary reactive UI. You opt into the primitives below only when a value must be readable on the main thread directly.

## Snapshot templates

Building a subtree the naive way means the background thread emits an op per element — create, set an attribute, append a child, and so on — and then hops threads so the main thread can apply them. For a list cell rebuilt on every fling, that adds up.

**Static JSX subtrees are compiled to main-thread templates instead.** The main thread *constructs* the subtree from a template it already holds: one snapshot op rather than ~10 element ops plus a thread hop, and hole-granular patches after mount. Cell construction measures roughly 25–30× cheaper on release builds.

This is on by default and there is nothing to write differently. What is worth knowing is when it *doesn't* apply:

- **The JSX must be statically analyzable.** Dynamic parts become holes; a subtree that can't be analyzed keeps the per-element path **automatically**, so nothing breaks — it is just not accelerated.
- **A file using `use:*` directives falls back wholesale.**
- **Library dists keep the per-element path** for now, so a subtree that comes from a package rather than your source is unaffected.

It works in development too: template registrations ride the main-thread hot-update bridge, stale templates are purged per edited file, and an op batch that outruns its registration parks and replays.

The kill switch is a plugin option:

```ts
// lynx.config.ts
pluginSigxLynx({ snapshots: false })   // default: true
```

One visible consequence, for raw `<list>` JSX: cells are now built **synchronously on the main thread, on demand** — so a fling no longer shows blank cells — and offscreen cell trees are recycled, keyed by template plus `reuse-identifier`. `@sigx/lynx-list` ships as a dist and so is unaffected for now.

## SharedValue: a value the main thread can write

A `SharedValue<T>` is a value the **main thread writes** and the **background thread reads**. It is the bridge in the other direction — main thread → background thread — and it is what powers gestures, scroll and animations.

Allocate one with `useSharedValue` inside a component:

```tsx
import { useSharedValue } from '@sigx/lynx';

const tx = useSharedValue(0);
```

You read `tx.value` on the background thread and it is reactive: an `effect` or `computed` that reads `tx.value` re-runs whenever the main thread publishes a new value.

```tsx
import { component, useSharedValue } from '@sigx/lynx';

export const DragReadout = component(() => {
    const tx = useSharedValue(0);
    return () => (
        <view style={{ padding: 24 }}>
            {/* a gesture/animation drives tx on the main thread */}
            <text>x = {tx.value}</text>
        </view>
    );
});
```

Each time the main thread updates `tx`, the `text` element that reads `tx.value` re-renders — frame data flows back into ordinary SignalX reactivity for free.

### Reading vs writing

The direction is asymmetric, and that is the whole point:

- **Main thread (writeable):** inside a `'main thread'` worklet you mutate `sv.current.value = newValue`. The bridge picks up the change at the next frame boundary.
- **Background thread (read-only):** you read `sv.value`. Writing `sv.value` on the background thread does nothing useful and warns in development — the source of truth lives on the main thread.

Under the hood a `SharedValue` is backed by a SignalX `PrimitiveSignal` on the background side. When the main thread publishes, that mirror signal is updated, which re-runs any effect or computed that read it on the scheduler's next tick. Many writes inside one frame collapse to a single published update, and identical writes are filtered out.

`SharedValue` holds primitives in practice — numbers (the default) and strings.

## MainThreadRef: a handle to a native element

A `MainThreadRef<T>` is a ref whose `.current` lives on the **main thread**. On the background thread `.current` is just the initial value (usually `null`); the real native element handle only exists inside main-thread code.

Create one with `useMainThreadRef` and bind it with `main-thread:ref`:

```tsx
import { component, useMainThreadRef } from '@sigx/lynx';
import type { MainThread } from '@sigx/lynx';

export const StickyHeader = component(() => {
    const elRef = useMainThreadRef<MainThread.Element>(null);

    function handleScroll(e: { detail: { scrollTop: number } }) {
        'main thread';
        const offset = e.detail.scrollTop;
        elRef.current?.setStyleProperties({
            transform: `translateY(${-offset}px)`,
        });
    }

    return () => (
        <scroll-view main-thread-bindscroll={handleScroll}>
            <view main-thread:ref={elRef}>
                <text>Sticky header</text>
            </view>
        </scroll-view>
    );
});
```

Inside the `'main thread'` handler, `elRef.current` is the real Lynx element, so you can call `setStyleProperties`, `getComputedStyleProperty` or `animate` synchronously — no thread hop, no frame delay.

## The 'main thread' directive

The `'main thread'` string at the top of a function is a build-time marker. A bundler plugin (`@sigx/lynx-plugin`) transforms any function carrying that directive: in the background bundle the body is replaced with a placeholder, and the real function is registered in the main-thread bundle. That is why these handlers can touch native elements directly — they actually run on the main thread.

This is also why you cannot just pass any closure across threads: a live JS function can't be serialized over the bridge, so the build step has to split it ahead of time. Make sure the plugin's worklet loader is wired in your bundler — without it, the cross-thread calls silently fall back to running on the background thread.

## runOnMainThread: call into the main thread

When you need to imperatively run code on the main thread from the background thread, wrap it with `runOnMainThread`. The wrapped function must carry the `'main thread'` directive:

```tsx
import { runOnMainThread, useMainThreadRef } from '@sigx/lynx';
import type { MainThread } from '@sigx/lynx';

const ref = useMainThreadRef<MainThread.Element>(null);

const updateOffset = runOnMainThread((offset: number) => {
    'main thread';
    ref.current?.setStyleProperties({
        transform: `translateX(${offset}px)`,
    });
});

updateOffset(100); // returns a Promise
```

`runOnMainThread` returns a callable that ships the worklet id and its arguments to the main thread on each invocation and resolves with a `Promise`. Any `MainThreadRef` captured by the worklet is sanitized so it survives serialization.

## runOnBackground: call back into the background thread

The mirror primitive runs in the other direction: from inside a `'main thread'` worklet, call `runOnBackground` to invoke a background-thread function (for example, to update a signal in response to a gesture):

```tsx
import { component, signal, runOnBackground, useMainThreadRef } from '@sigx/lynx';
import type { MainThread } from '@sigx/lynx';

export const ScrollTracker = component(() => {
    const top = signal(0);
    const ref = useMainThreadRef<MainThread.Element>(null);

    function handleScroll(e: { detail: { scrollTop: number } }) {
        'main thread';
        const offset = e.detail.scrollTop;
        runOnBackground((y: number) => {
            top.value = y;
        })(offset);
    }

    return () => (
        <scroll-view main-thread-bindscroll={handleScroll} main-thread:ref={ref}>
            <text>scrollTop = {top.value}</text>
        </scroll-view>
    );
});
```

`runOnBackground` returns a `Promise`. Note that promises returned by the background function itself are not transferable across the bridge — keep the return value a plain serializable value. Calling `runOnBackground` outside a `'main thread'` body throws, because the build transform only rewrites it inside worklets.

## Animating a SharedValue without crossing threads

For animation, the cheapest path keeps the per-frame work entirely on the main thread. `useAnimatedStyle` binds a `MainThreadRef` element's style to a `SharedValue` through a named mapper — the mapper runs on the main thread on every frame the value changed, with no thread crossing per frame:

```tsx
import { component, useSharedValue, useMainThreadRef, useAnimatedStyle } from '@sigx/lynx';
import type { MainThread } from '@sigx/lynx';

export const Ghost = component(() => {
    const tx = useSharedValue(0);
    const ghostRef = useMainThreadRef<MainThread.Element | null>(null);

    useAnimatedStyle(ghostRef, tx, 'translateX', { factor: 0.5 });

    return () => (
        <view main-thread:ref={ghostRef} style={{ width: 40, height: 40 }} />
    );
});
```

There is also a reactive form that takes an accessor returning a `{ sv, mapperName, params }` spec (or `null` for no binding); it re-binds when the spec changes. Multiple bindings on one element merge into a single style update per frame.

> `AnimatedValue` / `useAnimatedValue` were renamed to `SharedValue` / `useSharedValue`. Use the `SharedValue` names; the old ones are deprecated.

## A single import surface

Everything above comes from one barrel — `@sigx/lynx` re-exports the reactivity core, the runtime core, and the Lynx runtime:

```tsx
import {
    signal,
    computed,
    effect,
    useSharedValue,
    useMainThreadRef,
    runOnMainThread,
    runOnBackground,
    useAnimatedStyle,
} from '@sigx/lynx';
```

## Where to go next

- [Motion](/lynx/modules/motion/overview) builds animations on `SharedValue` — progress is observable from the background thread for free.
- [Gestures](/lynx/modules/gestures/overview) drive `SharedValue` from main-thread gesture handlers.
- [Runtime](/lynx/modules/runtime/overview) and [Runtime (main)](/lynx/modules/runtime-main/overview) document the two halves of the bridge.

---
url: https://sigx.dev/store/docs/ssr-state/
title: SSR state transfer
description: Seed a store on hydration from the server render with ssrState — fetch on the server, no client refetch
---

# SSR state transfer

`@sigx/store/ssr` is a composable that carries a state slice from the **server render** to the **client hydration**: you compute or fetch the data once on the server, ship it inside the page, and the store seeds itself from it on the client — no refetch. Call it inside a store setup, exactly like [`persist`](/store/docs/persistence), passing the setup context and the `{ state, patch }` pair from `defineState`:

```ts
import { defineStore } from '@sigx/store';
import { ssrState } from '@sigx/store/ssr';

const useTodos = defineStore('todos', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ items: [] as Todo[] });

    ssrState(ctx, { state, patch });

    return { ...signals };
});
```

On the server the store renders with whatever its actions put in `state` during the request; that final state is serialized into the page. On the client the same store seeds from the serialized value as it's created, so the first render matches the server's and nothing re-fetches.

## Server: register, serialize at emit time

On the server, `ssrState` registers the slice's **live** state under the key `store:<storeName>` on the per-request render context. It does not snapshot eagerly: the entry is `toJSON`-deferred, so the snapshot is taken when the shell is emitted — *after* rendering. Mutations the store makes during the request (an action that fetches, a computed that fills in) therefore ship with their **final** values.

The core `stateSerializationPlugin` emits that registry into `window.__SIGX_ASYNC__`. It runs automatically under `renderDocument` (and the other document renderers), or you can add it explicitly:

```ts
import { createSSR, stateSerializationPlugin } from '@sigx/server-renderer';

// a plain SSRPlugin — pass it when you create the SSR pipeline
const ssr = createSSR({ plugins: [stateSerializationPlugin()] });
```

Detection of the server is **duck-typed** via the component instance's `ssr` helper — `@sigx/store` has **no dependency on `@sigx/server-renderer`**. A store created on the server outside a render context (no instance to detect) serializes nothing; it never falls through to the client path, so one request's state can't leak into another.

## Client: seed on creation

On the client, `ssrState` seeds the slice from `window.__SIGX_ASYNC__['store:<storeName>']` as **one atomic `patch()`** — a single reactivity flush over the defaults, so the first render is already populated.

By default the seed is **shared**: reading it doesn't consume it. The entry stays on `window.__SIGX_ASYNC__`, so **every** store instance created in the client runtime seeds from it — each getting its own copy of the value (via `structuredClone`; see [Rich values](#rich-values-cross-the-wire-intact) for the fallback where that's unavailable). This is what a page needs whenever the same store is instantiated more than once: across [`@sigx/ssr-islands`](/server/packages/ssr-islands/overview) island roots or [`@sigx/resume`](/server/packages/resume/overview) boundaries, every instance hydrates from the server state instead of only the first one forking from the seed and the rest silently starting from defaults.

Client seeding only runs in a **browser-like environment** (`window` present); it never runs on the server. `ssrState` returns `{ hydrated }`, `true` only when a server seed was actually applied (always `false` on the server):

```ts
const useTodos = defineStore('todos', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ items: [] as Todo[] });

    const { hydrated } = ssrState(ctx, { state, patch });
    // hydrated === true on the client when the page carried server state for
    // this store; false on the server and on a cold client load.

    return { ...signals, hydrated };
});
```

## `scope` — shared across instances, or consume-once

`scope` decides what happens to the transfer entry once it's read:

```ts
ssrState(ctx, { state, patch }, {
    scope: 'instance',   // consume the seed on first read — default: 'shared'
});
```

- **`'shared'`** (default) — the seed persists for the page lifetime and every instance of the store seeds from it, each with its own copy ([via `structuredClone`](#rich-values-cross-the-wire-intact)). Use it for runtime-wide state that more than one instance reads: across [`@sigx/ssr-islands`](/server/packages/ssr-islands/overview) island roots or [`@sigx/resume`](/server/packages/resume/overview) boundaries a store now needs no extra wiring — every island or boundary hydrates from the same server state.
- **`'instance'`** — consume-once: the entry is removed as it's read, so a second instance of the same store starts from defaults. Use it for state that belongs to a single store instance rather than to the runtime as a whole.

> **Upgrading from consume-once?** Earlier releases always consumed the seed on first read. If you relied on that — a second instance intentionally starting from defaults — pass `scope: 'instance'` to keep the old behaviour.

## Rich values cross the wire intact

Transferred slices round-trip rich types — `Date`, `Map`, `Set`, `BigInt` — not just JSON primitives. The read goes through core's blob accessors, the same codec [`useData`](/core/docs/data-loading) uses, so a `Date` arrives on the client as a `Date`, not a tagged string.

Under the shared default each instance gets its own copy via `structuredClone`, which preserves those types. On a runtime without `structuredClone`, a value JSON can't represent exactly is shared **by reference** across instances — with a dev warning — rather than being flattened: handing a store a `Date` collapsed to a string is worse than sharing one.

## `pick` — limit what crosses the wire

By default every key of the slice is serialized and seeded. `pick` narrows it to a subset — the same list governs **both** the server snapshot and the client seed:

```ts
ssrState(ctx, { state, patch }, {
    pick: ['items'],   // serialize + seed only these keys — default: all slice keys
});
```

Whatever the page carries, only keys that actually exist on the slice are ever applied; unknown keys and reserved/`__proto__`-style keys are filtered out on both ends, so a tampered or mismatched blob can never assign unexpected keys onto your reactive state.

The filtering is **per key, not per entry**. A tampered entry is sanitized rather than rejected wholesale, so its surviving legitimate keys still seed the slice — one poisoned key does not cost you the rest of the page's state. Nothing that survives can reach the prototype.

## Composing with `persist()`

`ssrState` and [`persist`](/store/docs/persistence) layer cleanly — server-rendered data first, then device-local overrides. **Call `ssrState` first:**

```ts
import { persist } from '@sigx/store/persist';
import { ssrState } from '@sigx/store/ssr';

const useTodos = defineStore('todos', (ctx) => {
    const { state, signals, patch } = ctx.defineState({ items: [] as Todo[] });

    ssrState(ctx, { state, patch });   // 1. synchronous seed from the server render
    persist(ctx, { state, patch });    // 2. then device-local data, if any

    return { ...signals };
});
```

The ordering is what makes it work: `ssrState` seeds **synchronously** as the store is created. `persist`'s hydration — which may be **async** with stores like AsyncStorage — then overwrites with device-local data **when present**. So a returning visitor sees their saved state, while a first-time visitor keeps the server-rendered values. (See [the hydration race](/store/docs/persistence#the-hydration-race) for how `persist` orders its own writes.)

## Relationship to `useData` / `useStream`

This is the store-shaped entry point to the **same** SSR state-transfer mechanism that core's [`useData` and `useStream`](/core/docs/data-loading) use. They share one wire format — `window.__SIGX_ASYNC__`, a prototype-pollution-safe, page-lifetime blob the server renderer emits — and `store:<storeName>` is simply the **store keyspace** within it. Component-level fetches use `useData`; store-owned state uses `ssrState`. The server half of both is owned by `@sigx/server-renderer`'s document renderers; see the [data-loading guide](/core/docs/data-loading) for the component side and the [server renderer guide](/server) for the document-rendering APIs.

## Requirements

SSR state transfer needs the server renderer in the picture: `sigx` (or `@sigx/server-renderer` directly) on the server, rendering through `renderDocument` or a `createSSR()` pipeline with `stateSerializationPlugin()`. The store package itself adds no SSR dependency — on a purely client-rendered page `ssrState` is a no-op that returns `{ hydrated: false }`, and the store renders from defaults.

The shared default, the `scope` option, and the rich-value round-trip need `@sigx/store@0.11` or newer; per-key sanitizing of a tampered blob needs `0.13`. The current `@sigx/store`  pins the **0.15.x core line** (`@sigx/reactivity` / `@sigx/runtime-core` `^0.15.0`).

## Next steps

- [Persistence](/store/docs/persistence) — device-local state; composes with `ssrState`.
- [Data loading (`useData` / `useStream`)](/core/docs/data-loading) — the component-level half of the same SSR transfer.
- [Composables & Plugins](/store/docs/composables-and-plugins) — how setup composables like `ssrState` and `persist` are built.

---
url: https://sigx.dev/use/docs/conventions/
title: Conventions
description: The shared patterns behind every @sigx/use composable — MaybeSignal, toValue, reactive-view returns, element targets, and the cross-platform contracts
---

# Conventions

Every composable in `@sigx/use` shares a small set of input and output conventions. Learn them once here and each function page stays short — it only documents what's specific to that composable.

## Inputs: `MaybeSignal<T>` and `toValue()`

Anywhere a composable takes a "reactive-ish" argument, its type is **`MaybeSignal<T>`**. You can pass:

- a **plain value** — `useDebouncedSignal(query, 300)`
- a **signal-shaped `{ value }` handle** — a `PrimitiveSignal`, a `computed`, or a `toSignal` view
- a **getter function** — `() => scroll.y.value`

```ts
export type MaybeSignal<T> = T | ReadSignal<T> | (() => T);
```

Internally the composable resolves it with [`toValue`](/use/docs/to-value), which calls getters, unwraps `{ value }` handles, and passes plain values through. Reading inside a reactive context tracks as usual — a reactive argument makes the composable react to it.

> One sharp edge: a plain (non-signal) object that happens to have a `value` property is passed through **as-is**, not unwrapped. If you mean it as a value, wrap it in a getter: `() => obj`.

## Outputs: single value → `ReadSignal<T>`

Every composable that returns **one** reactive value returns a **`ReadSignal<T>`** — a read-only `{ value }` view. Read `.value` (or read it bare in JSX, where signals unwrap):

```ts
export interface ReadSignal<T> { readonly value: T; }
```

It's deliberately structural rather than `PrimitiveSignal<T> | Computed<T>`: `ReadSignal` **preserves literal unions** where `PrimitiveSignal` would widen them (`ReadSignal<'light' | 'dark'>` stays a union; `PrimitiveSignal<'light' | 'dark'>` degrades to `{ value: string }`). That's why `useColorScheme()` can hand you a `ReadSignal<'light' | 'dark'>`.

## Outputs: multiple fields → one `ReactiveView<T>`

A composable exposing **several** related fields (a mouse's `x`/`y`, an element's `width`/`height`) returns **one deep-reactive object**, not a bag of separate signals. Read it by **property access** — each key is tracked independently:

```ts
const mouse = useMouse();
effect(() => positionTooltip(mouse.x, mouse.y)); // no .value; per-key tracked
```

`ReactiveView<T>` is `Readonly<T>` — a typing contract that you must not write to it. To pull fields out **without losing reactivity**, use core's [`toSignals()`](/core/docs/signals) rather than a plain destructure (which would snapshot the values):

```ts
import { toSignals } from 'sigx';
const { x, y } = toSignals(useMouse()); // each a live signal
```

## Element targets (web)

Web composables that attach to a DOM element accept a flexible **element target** — resolved reactively, and re-attached when the element changes:

- a **raw element** (or `EventTarget`)
- a **getter** — `() => document.body`
- a **`{ value }` signal/computed** holding an element
- a **sigx template-ref `{ current }`** — the shape sigx's JSX `ref` prop writes into

```tsx
import { signal } from 'sigx';
import { useEventListener } from '@sigx/use-web';

const el = signal<HTMLElement | null>(null);
// <div ref={el}> …
useEventListener(el, 'click', onClick); // re-attaches if el changes
```

Targets are resolved by [`unrefElement`](/use/docs/unref-element), which always returns the **raw** element (via `toRaw`) — raw identity is what `removeEventListener` pairing and observer bookkeeping require. Detection is brand-based (`isSignal`/`isComputed`), so an arbitrary plain `{ value }` object is **not** unwrapped — pass those as a getter.

## SSR safety and `Configurable*` overrides

Every web composable is **SSR-safe**: on the server (no `window`) it returns sensible defaults and never touches the DOM, then reads the real environment on mount. Each function page states its exact server value (e.g. `useWindowSize` reports `Infinity`, `useOnline` reports `true`).

To make that testable — or to drive a composable from a different document, iframe, or a mock — web composables accept a `Configurable*` option:

```ts
interface ConfigurableWindow    { window?: Window; }
interface ConfigurableDocument  { document?: Document; }
interface ConfigurableNavigator { navigator?: Navigator; }
```

Pass `{ window }` / `{ document }` / `{ navigator }` to override the default global. `isClient`, `defaultWindow`, `defaultDocument`, and `defaultNavigator` are exported for the same purpose.

## Control handles: `Pausable` and `Stop`

Composables with ongoing work return an explicit handle so you can control (and, when standalone, tear down) that work:

```ts
export interface Pausable {
    isActive: ReadSignal<boolean>;
    pause: () => void;
    resume: () => void;
}
export type Stop = () => void;
```

A `Stop` detaches whatever was attached; a `Pausable` toggles it while tracking `isActive`. See [the cleanup model](/use/docs/overview#the-cleanup-model) for when you need these versus letting the owning scope clean up for you.

## Lifecycle helpers

Two small helpers power the cleanup model and are exported for your own composables:

- [`tryOnScopeDispose(fn)`](/use/docs/try-on-scope-dispose) — register teardown with the active scope (component setup or the innermost `effectScope()`); returns `false` when there's no scope, so the caller owns disposal.
- [`tryOnMounted(fn)`](/use/docs/try-on-mounted) — run `fn` after mount inside a component, or immediately when standalone. Web composables use it to defer environment reads (storage, layout) to the client-mounted moment without failing outside components.

## Cross-platform contracts

The composables that describe **platform capabilities** return **shared, platform-neutral contract types** — the same shapes a Lynx or terminal pack fulfils, so feature code ports across targets unchanged:

| Contract | Used by | Notes |
|---|---|---|
| `ColorScheme` (`'light' \| 'dark'`) | `useColorScheme` | Same shape as Lynx's `useSystemColorScheme`. |
| `ConnectionType`, `NetworkState` | `useNetwork`, `useOnline` | Field-for-field match with lynx-network; web reports `isInternetReachable: null`. |
| `WindowSizeState` (`{ width, height }`) | `useWindowSize`, `useElementSize` | |
| `StorageLike` / `StorageLikeAsync` | `useStorage` and presets | Sync (web `localStorage`) vs async-read (Lynx native) storage. |
| `UseClipboardReturn` | `useClipboard` | `{ isSupported, text, copied, copy }`. |

These live in `@sigx/use` (not `@sigx/use-web`), so a platform pack implements them against its own host APIs. See [Building a platform pack](/use/docs/overview#building-a-platform-pack).

## Next steps

- [`useToggle`](/use/docs/use-toggle) — the simplest composable, start here.
- [`useMouse`](/use/docs/use-mouse) — a reactive-view return in practice.
- [`useStorage`](/use/docs/use-storage) — the flagship deep-reactive persisted signal.

---
url: https://sigx.dev/use/docs/use-counter/
title: useCounter
description: A numeric signal with clamped inc/dec/set/reset mutators
---

# useCounter

A numeric counter signal paired with **clamped mutators** — `inc`, `dec`, `set`, and `reset` all respect the optional `min`/`max` bounds and return the new value. Cross-platform — import from `@sigx/use`.

```tsx
import { component, render } from 'sigx';
import { useCounter } from '@sigx/use';

const Stepper = component(() => {
    const { count, inc, dec, reset } = useCounter(0, { min: 0, max: 10 });

    return () => (
        <div class="flex items-center gap-3">
            <button class="btn" onClick={() => dec()}>−</button>
            <span class="font-mono text-lg w-8 text-center">{count}</span>
            <button class="btn" onClick={() => inc()}>+</button>
            <button class="btn btn-ghost" onClick={() => reset()}>reset</button>
        </div>
    );
});

render(<Stepper />, "#app");
```

## Usage

```ts
import { useCounter } from '@sigx/use';

const { count, inc, dec, set, reset } = useCounter(0, { min: 0, max: 10 });
inc();    // 1
inc(4);   // 5
dec(5);   // clamped to 0
set(20);  // clamped to 10
reset();  // back to the initial value (0)
```

> Writing `count.value` directly is allowed but **bypasses clamping** — the mutators are the clamped path. Reach for `set()` when you want the bound enforced.

## Signature

```ts
function useCounter(initial?: number, options?: UseCounterOptions): UseCounterReturn;

interface UseCounterOptions {
    min?: number;
    max?: number;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `min` | `number` | `-Infinity` | Lower clamp bound applied by every mutator. |
| `max` | `number` | `Infinity` | Upper clamp bound applied by every mutator. |

## Returns

`useCounter` returns a `UseCounterReturn` object:

| Field | Type | Description |
|---|---|---|
| `count` | `PrimitiveSignal<number>` | The counter signal. Read `.value` (or bare in JSX). |
| `inc` | `(delta?: number) => number` | Increment by `delta` (default 1), clamped. Returns the new value. |
| `dec` | `(delta?: number) => number` | Decrement by `delta` (default 1), clamped. Returns the new value. |
| `set` | `(value: number) => number` | Set to `value`, clamped. Returns the new value. |
| `reset` | `(value?: number) => number` | Reset to `value` (default: the initial value), clamped. Returns the new value. |

**Platform:** everywhere. No cleanup needed.

## See also

- [`useToggle`](/use/docs/use-toggle) — the boolean equivalent.
- [`useCycleList`](/use/docs/use-cycle-list) — step through a list instead of a number.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/use/docs/use-network/
title: useNetwork
description: Reactive network state on the cross-platform NetworkState contract, with web-only Network Information API extras
---

# useNetwork

Reactive network state on the cross-platform `NetworkState` contract, with web-only Network Information API extras riding along. Browser composable — import from `@sigx/use-web`.

```ts
import { effect } from 'sigx';
import { useNetwork } from '@sigx/use-web';

const network = useNetwork();
effect(() => console.log(network.isConnected, network.effectiveType));
```

The return is a [`ReactiveView<WebNetworkState>`](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — read fields by property access, each tracked independently. Destructure with core's [`toSignals()`](/core/docs/signals) to keep reactivity.

## Signature

```ts
function useNetwork(options?: ConfigurableWindow): ReactiveView<WebNetworkState>;

interface WebNetworkState extends NetworkState {
    effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
    downlink?: number;
    saveData?: boolean;
}
```

Pass `{ window }` to drive it from a mock — see [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides).

## Returns

| Field | Type | Description |
|---|---|---|
| `isConnected` | `boolean` | `navigator.onLine`. |
| `type` | `ConnectionType` | Network Information API `type` where available, else `'unknown'`. |
| `isInternetReachable` | `boolean \| null` | Always `null` on the web — the platform cannot know. |
| `effectiveType` | `'slow-2g' \| '2g' \| '3g' \| '4g' \| undefined` | Web-only extra; `undefined` where the API is missing. |
| `downlink` | `number \| undefined` | Web-only extra. |
| `saveData` | `boolean \| undefined` | Web-only extra. |

`isConnected`, `type`, and `isInternetReachable` are the [cross-platform `NetworkState` contract](/use/docs/conventions#cross-platform-contracts) — a **field-for-field match** with lynx-network's `NetworkState`, so connectivity code ports across targets. The web maps `navigator.onLine` → `isConnected` and reports `isInternetReachable: null`; Lynx fills that field from its native reachability API.

## SSR

On the server the view reads `{ isConnected: true, type: 'unknown', isInternetReachable: null }` (the extras are `undefined`), then reflects the real environment on mount.

## See also

- [`useOnline`](/use/docs/use-online) — the sugar form when you only need `isConnected`.
- [`useDocumentVisibility`](/use/docs/use-document-visibility) — pair with connectivity to pause work in the background.
- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — the `NetworkState` shape shared with Lynx.

---
url: https://sigx.dev/use/docs/use-storage/
title: useStorage
description: A signal persisted to storage — object defaults become a deep-reactive proxy that auto-persists, with cross-tab sync
---

# useStorage

A signal backed by browser storage (default `localStorage`). The flagship of the storage family: hand it an **object default** and you get a **deep-reactive proxy** — mutate a property and the change persists automatically, with cross-tab sync. Browser composable — import from `@sigx/use-web`.

```tsx
import { component, render } from 'sigx';
import { useStorage } from '@sigx/use-web';

const Prefs = component(() => {
    const prefs = useStorage('demo:prefs', { theme: 'light', fontSize: 14 });

    return () => (
        <div class="space-y-3">
            <div class="flex items-center gap-3">
                <button class="btn" onClick={() => (prefs.theme = prefs.theme === 'light' ? 'dark' : 'light')}>
                    theme: {prefs.theme}
                </button>
                <button class="btn" onClick={() => prefs.fontSize++}>font: {prefs.fontSize}px</button>
            </div>
            <p class="text-sm opacity-70">Edit, then reload the preview — it comes back persisted.</p>
        </div>
    );
});

render(<Prefs />, "#app");
```

## Object mode vs primitive mode

The return type follows the default value:

- **Object default → deep-reactive `Signal<T>`.** Mutate properties directly (`prefs.theme = 'dark'`) and every change persists (deep watch → serialize). Replace the whole value with `prefs.$set(next)`.
- **Primitive default → `PrimitiveSignal<T>`.** Writing `.value` persists.

```ts
const prefs = useStorage('prefs', { theme: 'light', fontSize: 14 }); // Signal<T>
prefs.theme = 'dark';            // persisted, reactive — no .value

const token = useStorage('token', '');  // PrimitiveSignal<string>
token.value = 'abc';                     // persisted
```

## Signature

```ts
function useStorage<T extends Primitive>(key: string, defaults: T, options?: UseStorageOptions<T>): PrimitiveSignal<T>;
function useStorage<T extends object>(key: string, defaults: T, options?: UseStorageOptions<T>): Signal<T>;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `storage` | `StorageLike` | `localStorage` | Backing store. Any [`StorageLike`](/use/docs/conventions#cross-platform-contracts) works. |
| `serializer` | `StorageSerializer<T>` | inferred | Custom `{ read, write }`. Default inferred from the default value's type (JSON for objects). |
| `listenToStorageChanges` | `boolean` | `true` | Sync across tabs via the `storage` event. |
| `writeDefaults` | `boolean` | `true` | Write the default value to storage when the key is absent. |
| `onError` | `(error: unknown) => void` | `console.error` | Called with storage/serialization errors. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). |

## SSR

On the server `useStorage` returns the **defaults untouched** and reads storage **on mount** — so the stored value wins *after* hydration. Don't render storage-dependent content above the fold unless you accept the post-hydration swap.

## See also

- [`useLocalStorage`](/use/docs/use-local-storage) / [`useSessionStorage`](/use/docs/use-session-storage) — presets bound to a specific store.
- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — the `StorageLike` contract a platform pack implements.
- [`@sigx/store` persistence](/store/docs/persistence) — for structured, per-user app state instead of a single key.

---
url: https://sigx.dev/actors/docs/metrics/
title: Metrics
description: The metrics() plugin, the queueMs vs turnMs split that tells you which problem you have, the runtime toggle and what it costs
---

# Metrics

<p class="lede">Pull-based counters and latency distributions for an actor host. No exporter,
no push pipeline, no metrics-library dependency.</p>

```ts
import { metrics } from '@sigx/actors/host';

const m = metrics();
export const app = defineActorApp({ actors, storage }).use(m);

m.snapshot();   // ActorMetricsSnapshot
m.reset();
```

What it collects: calls, failures, stream opens, activation churn by deactivation reason,
storage loads/saves/clears/conflicts, latency distributions, and live gauges from
`host.stats()`.

## `queueMs` vs `turnMs` — read this first

This split is the reason the plugin exists, and it is the thing that tells you *which* problem
you have.

| Symptom | Means | Fix |
|---|---|---|
| high **`turnMs`** | the method itself is slow | move I/O out of the turn, split the method, use a [task](/actors/docs/tasks) |
| high **`queueMs`** | the actor is a **hotspot** — callers are waiting in line | shard the key, reduce traffic, or [let reads interleave](/actors/docs/reentrancy) |

A dispatch middleware only ever sees the **sum**. That is precisely why `observeTurns` is a
separate seam rather than something you could have written yourself with `useDispatch`.

## Options

```ts
metrics({ enabled: false, histograms: true, maxTypes: 64, maxMethods: 32 });
```

`maxTypes` (default 64) folds overflow into `'(other)'` rather than growing unbounded.
`maxMethods: 0` drops the per-method breakdown.

## The runtime toggle

Collection switches at runtime, and switching it off genuinely stops paying for it:

```ts
const m = metrics({ enabled: false });   // wired in, collecting nothing
m.enable();                              // …investigate…
m.disable();                             // back to ~free; counters keep their values
m.enabled;                               // boolean
```

`disable()` **drops the turn subscription** rather than returning early inside it. That
distinction is the whole point: the runtime only takes per-turn timestamps while an observer is
attached, so an inert-but-attached observer would keep paying the larger half of the cost.
Counters freeze at their current values — `reset()` clears them.

> The intended shape is to leave `metrics({ enabled: false })` wired into production and switch
> it on when you need to look.

## What it costs

Measured on a `noop` dispatch — the cheapest call there is, ~0.5µs — each configuration in its
own process, median of 9 runs:

| | Throughput | vs no plugin |
|---|---:|---|
| no plugin | 2.05 M ops/s | — |
| an inert plugin (the control) | 2.08 M ops/s | ~0 |
| `metrics({ enabled: false })` | 2.05 M ops/s | **~0** |
| `metrics({ histograms: false })` | 1.88 M ops/s | −8% |
| `metrics()` | 1.43 M ops/s | −30% |

Three things to read off that. **Disabled is indistinguishable from not having the plugin at
all.** **Not attaching it is free** — with no observer the dispatch path is unchanged.
And **plugins themselves cost nothing**, which is what makes the other rows attributable to
metrics rather than to the plugin machinery.

Read the −30% in absolute terms before it alarms you: full metrics adds **~200ns per call**.
It looks like a third of throughput only because the measured call does nothing at all — for
an actor whose turn takes 100µs it is under **0.25%**.

Durations use `performance.now()` rather than the wall clock: one extra read per observed
turn, buying immunity to NTP or a VM host stepping the clock backwards mid-turn.

The per-method breakdown is ~3.5% of that per dispatch; `maxMethods: 0` gets the old cost
back. What it buys is per-method call counts, failure counts and the queue/turn split, which
is usually the trade you want.

## Conflicts deserve an alert, not a graph

Every `storage.conflicts` is an etag mismatch that discarded an activation. A steady trickle
means something in your cluster is wrong — a partition, a directory hiccup, a placement bug —
and the number is far more useful as a threshold alert than as a line on a dashboard.

## Scope of `observeTurns`

The seam behind the split, available to any plugin:

```ts
registry.observeTurns((ref, method, queuedMs, elapsedMs, failed, call) => { /* … */ });
```

It covers **dispatched turns only**, including reminder delivery. Deliberately excluded:
volatile `ctx.timer` ticks, write-behind flushes, and reentrant `ctx.actor` inline calls.

A throwing observer is swallowed and dev-logged; it never fails a turn. Both
`Host.observeTurns` and `PluginRegistry.observeTurns` return an unsubscribe, and when the last
observer leaves, the runtime stops timing turns entirely.

> If you write dispatch middleware, **forward `dispatchStream`** — see
> [The app](/actors/docs/the-app).

## Cross-host calls are split, not double-counted

A common worry, and the answer is reassuring: an inbound hop goes through the **raw local
dispatcher** and never touches `useDispatch`. So `calls.total` and `latencyMs` are recorded on
the *originating* host, and `queueMs`/`turnMs` on the *executing* host.

That is a split, not a duplicate — summing `calls.total` across hosts gives the true
cluster-wide number.

## Next steps

- [The ops endpoint](/actors/docs/ops-endpoint) — reading this over the wire.
- [Cluster stats](/actors/docs/cluster-stats) — merging it across the fleet.
- [Observability](/actors/docs/observability) — Prometheus and OpenTelemetry.

---
url: https://sigx.dev/actors/docs/storage/
title: Storage
description: The ActorStorage seam — load, save and clear with etags — the shipped providers, and what to run in production
---

# Storage

<p class="lede">`ActorStorage` is three methods and an etag. Everything the runtime promises
about persistence — conflict detection, migration write-back, crash-resumable tasks — rides
that one seam.</p>

## The shipped providers

| Provider | From | Use |
|---|---|---|
| `memoryStorage()` | `@sigx/actors/host` | tests and dev |
| `fileStorage({ dir })` | `@sigx/actors/node` | dev — one cat-able JSON file per actor |
| [`redisStorage`](/actors/packages/actors-redis/overview) | `@sigx/actors-redis` | production |
| [`pgStorage`](/actors/packages/actors-pg/overview) | `@sigx/actors-pg` | production |
| [`surrealStorage`](/actors/packages/actors-surreal/overview) | `@sigx/actors-surreal` | production |
| [`durableObjectStorage`](/actors/packages/actors-cloudflare/overview) | `@sigx/actors-cloudflare` | Cloudflare |

```ts
defineActorApp({ storage: fileStorage({ dir: '.actors' }) });
```

`memoryStorage()` is the default when you configure nothing, which is fine for a first look
and wrong for anything else — including dev, where it means every actor-file edit resets your
state.

## The seam

```ts
interface ActorStorage {
    load(type: string, key: string): Promise<ActorStorageRecord | undefined>;
    save(type: string, key: string, record: ActorStorageRecord): Promise<void>;
    clear(type: string, key: string): Promise<void>;
}
```

A record carries the encoded state and an **etag**. `save` must reject with
`ActorStorageConflict` when the etag it was handed is not the one currently stored — that
compare-and-set is what makes
[`ActorStateConflictError`](/actors/docs/state-and-persistence#conflicts) possible, and
without it a partition silently loses writes.

Implementing one is a small job for any database that can do a conditional update. What it
must get right:

- **Compare-and-set on the etag**, atomically. A read-then-write is not enough.
- **Round-trip the encoded record unchanged.** The codec has already run; do not re-serialize.
- **`undefined` for a missing record**, not an empty one — that is what selects the fresh
  `state(key)` path and skips [`migrateState`](/actors/docs/state-and-persistence).

### The ownership contract

Both halves of the seam say who owns the tree, and they say opposite things:

| | contract |
|---|---|
| `save(state)` | **takes ownership.** The caller must not mutate the tree afterwards; an implementation may store it by reference rather than copying. |
| `load()` | **hands ownership over.** The returned record is the caller's to mutate freely — never a shared, frozen or cached object. |

The host always passes `save` a codec-fresh tree, so a provider that keeps the reference is
safe and skips a clone. The load side is the one to be careful about: returning a cached
record means the next activation mutates the copy your provider is still holding.

This is what makes `memoryStorage` correct without cloning on save while still cloning on
load — a stored value never aliases live activation state.

## Choosing one in production

Two questions decide it.

**Do you already run one of these?** If Postgres is in your stack,
[`@sigx/actors-pg`](/actors/packages/actors-pg/overview) gives you storage, membership, the
directory *and* reminders on one pool, with the expiry running on the database clock. If Redis
is, [`@sigx/actors-redis`](/actors/packages/actors-redis/overview) gives you the same minus
reminders, on one client.

**Are you on Cloudflare?** Then the question does not arise — the Durable Object *is* the
storage, and the platform is the cluster. See
[Cloudflare Workers](/actors/docs/cloudflare-workers).

Storage and the cluster providers are independent choices. Kubernetes membership plus a Redis
directory plus Postgres storage is a perfectly ordinary configuration:

```ts
cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(client) },
    advertise,
    secret: process.env.HOST_SECRET,
});
```

## Decorating storage

A plugin can wrap the configured storage rather than replace it:

```ts
registry.decorateStorage((inner) => ({
    async load(type, key) {
        const t = performance.now();
        try { return await inner.load(type, key); }
        finally { record(performance.now() - t); }
    },
    save: inner.save,
    clear: inner.clear,
}));
```

Decorators chain, and the **last registered is outermost**. Encryption at rest, tenant
prefixing and audit logging all fit here without the actor code knowing.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>A decorator that caches a <code>load()</code> result is wrong.</strong> `load` hands
    the record to the caller to mutate, so serving the same object twice means the second
    activation is mutating the first one's state. Cache the encoded bytes and rebuild, or do not
    cache at all.
  </div>
</div>

## Next steps

- [State & persistence](/actors/docs/state-and-persistence) — what the runtime does with it.
- [Clustering](/actors/docs/clustering) — membership and the directory.
- [The app](/actors/docs/the-app) — `decorateStorage` and the other hooks.

---
url: https://sigx.dev/actors/docs/the-app/
title: The app
description: defineActorApp — one typed config that every runtime starts, the plugin registry, and how plugins add typed members to ctx
---

# The app

<p class="lede">`defineActorApp` is the composition root. It is an inert description until
`start()`, which is what lets the same module be started by a Node entry, the Vite dev server
or a Worker — and it is where plugins fold their contributions together.</p>

## Why it exists

`createHost` is still the low-level primitive, but it takes exactly **one** `placement` and
**one** `storage`, and `ActorPlacement.bind()` is its only lifecycle-hook shape. So two things
that both want `beforeActivate` cannot coexist.

`defineActorApp` fixes that by folding every plugin's contributions into the single placement,
storage and context `createHost` already understands.

```ts
// src/actors.app.ts — one typed source of truth
import { defineActorApp } from '@sigx/actors/host';
import { fileStorage } from '@sigx/actors/node';
import { metrics } from '@sigx/actors/host';

export const app = defineActorApp({
    actors,
    storage: fileStorage({ dir: '.actors' }),
    defaults: { idleAfterMs: 60_000 },
}).use(metrics());

/** Bound to this app's plugin set — import it from your actor modules. */
export const { defineActor } = app;
```

```ts
const host = await app.start();   // builds the host, starts it, runs onStart
await app.stop();                 // drains the host, then onStop in reverse
```

## A started app is single-use

`start()` is idempotent while running, but after `stop()` the app refuses to restart. That is
deliberate: a plugin placement mints its identity per run, and a cluster host id is gone once
its membership entry is. Build a new app instead.

A start that *fails* is the exception — the rejection is not cached, so fixing the cause and
calling `start()` again really retries.

## Writing a plugin

`setup()` receives a registry. Everything composes across plugins except `setPlacement`, which
is exclusive by nature — a second claim throws, naming both plugins.

```ts
import type { ActorPlugin } from '@sigx/actors/host';

interface Logger { info(message: string): void }

export function logging(logger: Logger): ActorPlugin<{ log: Logger }> {
    return {
        name: 'logging',
        setup(registry) {
            registry.extendContext(() => ({ log: logger }));
            registry.onBeforeActivate((ref) => logger.info(`activating ${ref.type}/${ref.key}`));
            registry.useDispatch((next) => ({
                dispatch: async (ref, method, args, call) => {
                    logger.info(`${ref.type}#${method}`);
                    return next.dispatch(ref, method, args, call);
                },
                // Forward streaming — `dispatchStream` is optional, so a
                // middleware that omits it silently breaks every
                // `streams:` method. Dev-warns if you forget.
                ...(next.dispatchStream && {
                    dispatchStream: (ref, method, args, call) =>
                        next.dispatchStream!(ref, method, args, call),
                }),
            }));
        },
    };
}
```

> **If you write dispatch middleware, forward `dispatchStream`.** It is optional on the
> interface, so omitting it does not fail to compile — it silently breaks every `streams:`
> method in the app. Dev builds warn.

## Typed context, per app

The `ActorPlugin<{ log: Logger }>` type argument is what makes `ctx.log` **typed inside every
actor** that imports the app-bound `defineActor`. There is no global declaration merging, so
the additions stay scoped to this app:

```ts
// src/counter.actor.ts
import { defineActor } from './actors.app';

export const Counter = defineActor({
    type: 'Counter',
    allowAnonymous: true,
    state: () => ({ count: 0 }),
    methods: (ctx) => ({
        increment(by: number) {
            ctx.log.info('increment');   // typed, contributed by .use(logging(...))
            return (ctx.state.count += by);
        },
    }),
});
```

This is the reason actor modules import `defineActor` from your app module rather than from
`@sigx/actors`. Both produce the same object at runtime; only the **type** differs.

## The registry hooks

| Registry hook | Composes? | Notes |
|---|---|---|
| `addTypeHandlers` | concatenated | codec handlers for state persistence |
| `decorateStorage` | chained | last registered is **outermost** |
| `setPlacement` | **exclusive** | a factory, run once the host exists; a second claim throws, naming both plugins |
| `onBeforeActivate` | in order | throwing **refuses** the activation |
| `onAfterDeactivate` | reverse order | errors caught per hook and dev-logged |
| `useDispatch` | outside-in | first registered is **outermost**; must forward `dispatchStream` |
| `onStart` / `onStop` | in order / reverse | `onStop` runs *after* the drain |
| `route` | collected | exposed as `app.routes` for adapters |
| `extendContext` | merged | never overwrites a built-in `ctx` member |
| `reportHealth` | collected | see [Health & readiness](/actors/docs/health-and-readiness) |
| `reportOps` / `reportDigest` | collected | see [The ops endpoint](/actors/docs/ops-endpoint) |

A placement's own hooks **bracket** the plugins'. Its `beforeActivate` — a cluster's directory
claim — runs first, and its `afterDeactivate` — the release — runs last, so plugin hooks
always observe an activation the placement already owns.

## The app factory pattern

On a runtime that constructs your app more than once — notably
[Cloudflare Durable Objects](/actors/docs/cloudflare-workers) — building the app at module
scope binds whichever instance constructed it first, and every other instance is then served
from those seams. Export a **factory** instead:

```ts
export const createApp = (base: ActorAppOptions) => defineActorApp(base).use(metrics());

/** Type-only binding, never started. */
export const { defineActor } = createApp({});
```

On Node and under Vite the module-scope form is fine.

## Next steps

- [Running a host on Node](/actors/docs/node) — `createAppHandler` and graceful shutdown.
- [Storage](/actors/docs/storage) — the `ActorStorage` seam and the shipped providers.
- [Clustering](/actors/docs/clustering) — the `cluster()` plugin.
- [Metrics](/actors/docs/metrics) — the first plugin most apps add.

---
url: https://sigx.dev/actors/docs/streams/
title: Streams
description: "The streams: factory — server-to-client async generators over NDJSON, why bodies are observers rather than turns, and when to prefer a live read"
---

# Streams

<p class="lede">Declare server-to-client streams in the `streams:` factory as async generators;
clients get them as an `AsyncIterable` over NDJSON.</p>

```ts
streams: (ctx) => ({
    async *watch() {
        yield* ctx.changes({ initial: true });
    },
})
```

A stream arrives as an `AsyncIterable`, so a component consumes it with an ordinary
`for await`:

```tsx
import { component, onMounted, signal } from 'sigx';

const CartView = component<{ id: string }>(({ props }) => {
    const cart = signal<CartState | null>(null);

    onMounted(async () => {
        for await (const next of actor(CartActor, props.id).watch()) cart.value = next;
    });

    return () => <p>{cart.value?.items.length ?? 0} items</p>;
});
```

## Bodies are observers, not turns

Stream bodies run **[outside the turn sequence](/actors/docs/turns)**. A stream that waited on
its own actor's next turn while occupying it would deadlock against itself.

The consequence is a rule: read `ctx.snapshot()` or `ctx.changes()`, and **never mutate live
state** from a stream body. Dev builds warn when a body reads live `ctx.state`.

`ctx.changes()` yields a detached snapshot after every mutating turn, through a bounded
buffer that drops oldest.

## Seed with `{ initial: true }`

```ts
async *watch() {
    yield* ctx.changes({ initial: true });   // ✓
}
```

Not this:

```ts
async *watch() {
    yield ctx.snapshot();        // ✗ subscribes late
    yield* ctx.changes();
}
```

The prologue subscribes only once the consumer resumes past that first yield, so every
mutation in between is lost — and the snapshot it yielded is already stale by then.
`{ initial: true }` queues the current snapshot in the same synchronous call that registers
the subscription, leaving no gap.

## Coalesce bursts with `throttleMs`

```ts
async *watch() {
    yield* ctx.changes({ initial: true, throttleMs: 100 });
}
```

At most one snapshot per window, **leading edge plus trailing edge**, and the trailing
snapshot is taken **fresh when the window closes** — so a throttled consumer never receives
state older than the window it waited out.

Reach for it when the consumer **redraws rather than accumulates**. A snapshot is a full
encode+revive of the whole state, and a boundary landing inside an open window builds none at
all. The case that makes this obvious is an actor whose state grows through a run — a
[job](/actors/docs/jobs) appending a step's output per turn and reporting progress as it goes
— which otherwise clones everything it has accumulated on every single step.

**The final state is never dropped.** A window still owing an emit when the actor deactivates
is flushed before the feed ends.

`throttleMs` must be a non-negative finite number; anything else throws rather than quietly
reading as unthrottled. Omitting it, or `0`, keeps one snapshot per mutating turn.

## The factory runs once per subscription

Each subscription gets its own context. That is what lets a disconnect close the feeds a body
opened: an async generator parked inside `ctx.changes()` is suspended at an internal `await`,
where the spec *queues* `return()` rather than running it, so the subscription has to be
closable from outside the body.

Nothing an author writes changes because of this — but it does mean the factory is a **table
constructor**, not a place for per-activation state. Two rules follow:

- Do not touch `ctx` while *constructing* the table; its method names are read at definition
  time. Inside generator bodies, anything goes.
- `computed` and `watch` setup belongs in `methods:`.

Closing the feed unwinds the body through its own `finally`, so cleanup works normally.

## Keep-alive at the byte layer

A stream that yields nothing sends nothing, and every intermediary with an idle timeout —
ingress at 60s, cloud load balancers at ~4 minutes, mobile NATs — closes it. The client then
sees a stream that "ended without a done/error terminator".

So the endpoint emits a `{"ping":1}` line after 30 seconds of silence, which the client's
reader skips.

```ts
handleActorRequest(request, { host, streamPingMs: 30_000 });   // 0 disables
```

An open stream also keeps the activation alive, so
[idle collection](/actors/docs/lifecycle) cannot pull it out from under a consumer.

## Prefer a live read for current state

> **Reading current state? Use
> [`useActorState(…, { live: true })`](/actors/docs/live-reads)** rather than a hand-written
> `streams:` body. It pushes the result of the read you already declared, multiplexes every
> live read on the page onto one connection, and reconnects on its own.

`streams:` is for a feed that is **not** a read of current state: a log tail, a progress
sequence, an event history where each item matters in its own right.

The `examples/chat` app in the actors repo is the worked case for the other side of that line:
its message list, topic and activity feed are all reads of current state, so it declares
`{ live: true }` on each and carries no `streams:` at all.

## Next steps

- [Live reads](/actors/docs/live-reads) — the multiplexed alternative.
- [Tasks](/actors/docs/tasks) — long work that reports progress.
- [Jobs](/actors/docs/jobs) — durable work with a `watch()` stream built in.

---
url: https://sigx.dev/core/api/components/
title: Components
description: SignalX components API reference
---

# Components API

Component creation and built-in components.

## component

Create a SignalX component.

```tsx
function component<TCombined, TRef, TSlots>(
    setup: (ctx: ComponentSetupContext) => ViewFn | Promise<ViewFn>,
    options?: ComponentOptions
): ComponentFactory<TCombined, TRef, TSlots>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `setup` | `(ctx) => ViewFn` | Setup function receiving context |
| `options.name` | `string` | Component name for DevTools |

### Returns

`ComponentFactory` - A function usable as a JSX element.

### Setup Context

| Property | Type | Description |
|----------|------|-------------|
| `signal` | `typeof signal` | Create reactive state |
| `props` | `PropsAccessor<TProps>` | Reactive props |
| `slots` | `SlotsObject<TSlots>` | Slot functions |
| `emit` | `EmitFn<TEvents>` | Emit custom events |
| `el` | `PlatformElement` | Root element (after mount) |
| `parent` | `any` | Parent component |
| `onMounted` | `(fn) => void` | Register mount callback |
| `onUnmounted` | `(fn) => void` | Register unmount callback |
| `onCreated` | `(fn) => void` | Register creation callback |
| `onUpdated` | `(fn) => void` | Register update callback |
| `expose` | `(api) => void` | Expose API to parent |
| `update` | `() => void` | Force re-render |

### Examples

```tsx
import { component, type Define } from 'sigx';

type CardProps = 
    & Define.Prop<'title', string, true>
    & Define.Event<'close'>
    & Define.Slot<'default'>
    & Define.Slot<'footer'>;

const Card = component<CardProps>(({ props, slots, emit }) => {
    return () => (
        <div class="card">
            <header>
                {props.title}
                <button onClick={() => emit('close')}>×</button>
            </header>
            <main>{slots.default?.()}</main>
            {slots.footer?.()}
        </div>
    );
}, { name: 'Card' });

// Usage
<Card 
    title="Welcome" 
    onClose={() => setOpen(false)}
    slots={{
        footer: () => <button>OK</button>
    }}
>
    <p>Card content</p>
</Card>
```

---

## Fragment

Render children without a wrapper element.

```tsx
const Fragment: Symbol;
```

### Usage

```tsx
import { Fragment } from 'sigx';

// Using Fragment component
<Fragment>
    <li>Item 1</li>
    <li>Item 2</li>
</Fragment>

// Using short syntax
<>
    <li>Item 1</li>
    <li>Item 2</li>
</>
```

---

## lazy

Create a lazy-loaded component.

```tsx
function lazy<T extends ComponentFactory>(
    loader: () => Promise<T | { default: T }>
): LazyComponentFactory<T>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `loader` | `() => Promise<Component>` | Dynamic import function |

### Returns

`LazyComponentFactory` with:
- `preload(): Promise<T>` - Start loading before render
- `isLoaded(): boolean` - Check if loaded

### Examples

```tsx
import { lazy, Defer } from 'sigx';

const HeavyChart = lazy(() => import('./HeavyChart'));

// Basic usage — Defer shows the fallback while the chunk loads
<Defer fallback={<Spinner />}>
    <HeavyChart />
</Defer>

// Preload on hover
<button onMouseEnter={() => HeavyChart.preload()}>
    Show Chart
</button>

// Check load status
if (HeavyChart.isLoaded()) {
    console.log('Ready');
}
```

---

## Defer

Show fallback content while lazy component chunks load. `<Defer>`'s fallback covers **chunk loading only** — a pending `useData` read renders through its own component's `match()`, never through a wrapper. On the server, the fallback streams with the shell and a single replacement arrives when everything pending beneath it (chunks and keyed data) resolves.

```tsx
const Defer: ComponentFactory<DeferProps>;
```

### Props

| Name | Type | Description |
|------|------|-------------|
| `fallback` | `JSXElement \| () => JSXElement` | Content while chunks below load |

### Examples

```tsx
import { lazy, Defer } from 'sigx';

const Dashboard = lazy(() => import('./Dashboard'));

// Static fallback
<Defer fallback={<div>Loading...</div>}>
    <Dashboard />
</Defer>

// Dynamic fallback
<Defer fallback={() => <Spinner size={size} />}>
    <Dashboard />
</Defer>

// Multiple lazy components — one fallback until all chunks resolve
<Defer fallback={<Loading />}>
    <LazyHeader />
    <LazyContent />
</Defer>
```

---

## Portal

Render children to a different DOM location.

```tsx
const Portal: ComponentFactory<PortalProps>;
```

### Props

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `string \| Element` | `document.body` | Target container |
| `disabled` | `boolean` | `false` | Render in-place instead |

### Examples

```tsx
import { Portal } from 'sigx';

// Render to body (default)
<Portal>
    <div class="modal">Modal content</div>
</Portal>

// Render to specific element
<Portal to="#modal-root">
    <div class="modal">Modal content</div>
</Portal>

// Render to element reference
<Portal to={containerElement}>
    <Tooltip />
</Portal>

// Conditional portal
<Portal disabled={inline}>
    <Dropdown />
</Portal>
```

---

## isLazyComponent

Check if a component is lazy-loaded.

```tsx
function isLazyComponent(component: any): component is LazyComponentFactory;
```

### Examples

```tsx
import { lazy, isLazyComponent } from 'sigx';

const LazyComp = lazy(() => import('./Comp'));
const RegularComp = component(() => () => <div />);

isLazyComponent(LazyComp);    // true
isLazyComponent(RegularComp); // false
```

---

## getCurrentInstance

Get the current component's setup context.

```tsx
function getCurrentInstance(): ComponentSetupContext | null;
```

### Returns

The current component context, or `null` if not in a component.

### Examples

```tsx
import { getCurrentInstance } from 'sigx';

function useCustomHook() {
    const ctx = getCurrentInstance();
    if (!ctx) {
        throw new Error('Must be called in component setup');
    }
    
    ctx.onMounted(() => {
        console.log('Component mounted');
    });
}
```

---

## Data Loading

### useData

The keyed async read. Every read has a key — the reactive trigger, the cache / SSR identity, and the fetcher's input. A static string key is SSR-transferable (runs on the server, serialized under the key into `window.__SIGX_ASYNC__`, restored on hydration, deduped per key). A reactive getter returning a string or tuple re-runs on change; a falsy result holds the read in `idle`. There is no unkeyed form.

```tsx
// Static key: SSR + hydration state transfer.
function useData<T>(
    key: string,
    fetcher: (arg: string, ctx: { signal: AbortSignal }) => Promise<T>,
    opts?: AsyncOptions,
): AsyncState<T>;
// Reactive key (string or tuple); falsy ⇒ 'idle'.
function useData<T, const K extends KeyValue>(
    key: () => K | Falsy,
    fetcher: (arg: K, ctx: { signal: AbortSignal }) => Promise<T>,
    opts?: AsyncOptions,
): AsyncState<T>;

interface AsyncOptions {
    server?: boolean; // default true; false ⇒ client-only keyed read
}
```

Render every state with `match()`; `refresh()` re-runs in place (stale-while-revalidate) and never rejects. See the [Data Loading](/core/docs/data-loading) guide.

### useAction

The async write — the manual counterpart to `useData`, triggered by `.run(input)`. `run` never rejects; it resolves a settled `RunResult<T>`. In-flight writes are never aborted.

```tsx
function useAction<T, In = void>(
    fn: (input: In, ctx: { signal: AbortSignal }) => Promise<T>,
    opts?: ActionOptions,
): AsyncAction<T, In>;
```

### all

Combine several `AsyncState`s into one all-or-nothing state — a single `match()` for a whole view. A pure derived view; no fetching.

```tsx
// Object form (named value/errors records).
function all<S extends Record<string, AsyncState<unknown>>>(sources: S): AllState<…>;
// Rest-tuple form (positional).
function all<S extends readonly AsyncState<unknown>[]>(...sources: S): AllState<…>;
```

`AllState<T, E>` extends `AsyncState<T>` with an `errors` collect-all counterpart to first-error-wins `.error`.

### useStream

Accumulate a streamed `AsyncIterable<string>` into a reactive string — progressive text (LLM-token-style), SSR-aware via the key.

```tsx
function useStream(
    key: string,
    source: () => AsyncIterable<string>
): { readonly value: string };
```

---

## Helper Functions

### mergeProps

Combine several prop sources into one object, without the key collisions a JSX
spread produces.

```tsx
type MergeSource =
    | Record<string, any>
    | (() => Record<string, any>)
    | null
    | undefined;

function mergeProps(...sources: MergeSource[]): Record<string, any>;
```

| Key | How it combines |
|---|---|
| `class` / `className` | Concatenated in source order, emitted as `class` |
| `style` | Merged into an object left-to-right; string sources are parsed |
| `on*` handlers | Chained in source order, grouped by resolved event name |
| `ref` | Chained into one ref feeding every source's ref |
| everything else | Exact spread semantics — last source with the key wins, including an explicit `undefined` |

Sources may be objects or zero-argument thunks; the result resolves on read, so
thunk sources stay reactive. Call it **once in setup** — the derived `ref` and
chained handlers are identity-cached, and a per-render call discards that cache.

```tsx
const merged = mergeProps(
    () => { const { variant: _v, ...rest } = ctx.props; return rest; },
    () => ({ class: 'btn', onClick: onActivate })
);
return () => <button {...merged}>{ctx.slots.default?.()}</button>;
```

See [Combining Prop Sources](/core/docs/components#combining-prop-sources) for
the guide.

### supportsMoveBefore

Check if browser supports state-preserving DOM moves.

```tsx
function supportsMoveBefore(): boolean;
```

### moveNode

Move a DOM node with state preservation when available.

```tsx
function moveNode(
    parent: Element,
    node: Node,
    anchor?: Node | null
): void;
```

---

## Types

### ComponentFactory

```tsx
type ComponentFactory<TCombined, TRef, TSlots> = 
    ((props: ComponentProps) => JSXElement) & {
        __setup: SetupFn;
        __name?: string;
        __props: TCombined;
        __ref: TRef;
        __slots: TSlots;
    };
```

### LazyComponentFactory

```tsx
type LazyComponentFactory<T> = T & {
    preload: () => Promise<T>;
    isLoaded: () => boolean;
    __lazy: true;
};
```

### DeferProps

```tsx
type DeferProps =
    & Define.Prop<'fallback', JSXElement | (() => JSXElement)>
    & Define.Slot<'default'>;
```

### PortalProps

```tsx
type PortalProps = 
    & Define.Prop<'to', string | Element>
    & Define.Prop<'disabled', boolean>;
```

### ViewFn

```tsx
type ViewFn = () => JSXElement | JSXElement[] | undefined;
```

### ComponentOptions

```tsx
interface ComponentOptions {
    name?: string;
}
```

### AsyncState

`AsyncState<T>` is a **discriminated union**, so a state check narrows `value` with
no cast:

```tsx
type AsyncState<T> =
    | AsyncIdle<T> | AsyncPending<T> | AsyncReady<T> | AsyncRefreshing<T> | AsyncErrored<T>;

// Every member carries these, narrowed per state:
//   state    'idle' | 'pending' | 'ready' | 'refreshing' | 'errored'
//   value    the best data the cell has — see below
//   hasValue presence — a resolved null IS a value
//   error    Error | null
//   loading  state === 'pending' ONLY (a refresh reads state === 'refreshing')

interface AsyncStateBase<T> {          // the shared methods
    match<R>(arms: MatchArms<T, R>): R | undefined;
    refresh(): Promise<void>;          // re-run in place; NEVER rejects (failures land on .error)
}

interface AsyncReady<T> extends AsyncStateBase<T> {
    readonly state: 'ready';
    readonly value: T;                 // narrowed — no cast
    readonly hasValue: true;
    readonly error: null;
    readonly loading: false;
}
```

```tsx
if (q.state === 'ready') q.value   // T — narrowed
if (q.hasValue) q.value            // T — narrowed
```

`value` is **the best data the cell has**, under one rule: kept across a same-key
`refresh()` *and across a failed fetch*, cleared on key change. So an errored cell
that once succeeded still holds its last-good value, and `'errored'` genuinely
splits on `hasValue`.

`value` is not a presence signal: a fetch that legitimately resolves `null` has a
value, and the cell stays `ready`. Read presence from `state` or from `hasValue`,
which is present on `useData` cells, `@sigx/cache` cells, `all()` and SSR-side
state. `AsyncStateName` is exported.

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>Two patterns break under the union.</strong> `q.error && !q.value` no
    longer means "errored" — an errored cell that once had data still holds it, so
    content beside an error banner stays on screen instead of blanking. That is the
    intended SWR posture; to blank deliberately, check `q.state === 'errored'`.
    And `interface X extends AsyncState<T>` no longer compiles — intersect instead:
    `type X<T> = AsyncState<T> & { … }`.
  </div>
</div>

### MatchArms

```tsx
interface MatchArms<T, R> {
    idle?: () => R;                                    // defaults to `pending`
    pending?: () => R;                                 // omitted ⇒ renders nothing
    error?: (e: Error, ctx: ErrorArmContext<T>) => R;  // omitted ⇒ bubbles to errorScope / app onError
    ready: (v: T) => R;                                // required — the only route to a present T
}

type ErrorArmContext<T> =
    & { retry: () => void }
    & ({ value: T; hasValue: true } | { value: null; hasValue: false });
```

The error arm's second parameter is a **context object**, not positional
arguments: `error: (e, { retry }) => …`. The last-good value is `ctx.value`,
guarded by `ctx.hasValue` — so a legitimately-`null` last-good finally reads as
present. `match` renders the error arm on every `'errored'` state; it never falls
back to `ready`.

### AsyncAction

```tsx
interface AsyncAction<T, In> {
    readonly state: 'idle' | 'pending' | 'ready' | 'errored';
    readonly value: T | null;      // last successful result
    readonly error: Error | null;
    readonly loading: boolean;      // state === 'pending' — the double-submit guard
    match<R>(arms: MatchArms<T, R>): R | undefined;
    run(input: In): Promise<RunResult<T>>; // never rejects; in-flight runs never aborted
    reset(): void;                  // back to 'idle'; clears value/error
}

type RunResult<T> = { ok: true; value: T } | { ok: false; error: Error };
```

A superseded run resolves `{ ok: false, error: SupersededError }` and never writes state.

---
url: https://sigx.dev/core/docs/lifecycle/
title: Lifecycle
description: Understanding component lifecycle in SignalX
---

# Component Lifecycle

SignalX components have a simple lifecycle that gives you control over initialization, mounting, updates, and cleanup.

## onCreated

The `onCreated` hook runs after the component's setup function completes, before it's mounted to the DOM:

```tsx
import { component, onCreated } from 'sigx';

const MyComponent = component(({ signal }) => {
    const state = signal({ initialized: false });
    
    onCreated(() => {
        console.log('Component created!');
        state.initialized = true;
    });
    
    return () => <div>Hello World</div>;
});
```

## onMounted

The `onMounted` hook runs after the component is first rendered and attached to the DOM. It receives a context object with the element:

```tsx
import { component, onMounted } from 'sigx';

const MyComponent = component(({ signal }) => {
    const state = signal({ mounted: false });
    
    onMounted((ctx) => {
        console.log('Component mounted!');
        console.log('Element:', ctx.el);  // The DOM element
        state.mounted = true;
    });
    
    return () => <div>Hello World</div>;
});
```

### Using Context Method

You can also use `onMounted` from the setup context:

```tsx
const MyComponent = component((ctx) => {
    ctx.onMounted(({ el }) => {
        console.log('Mounted to:', el);
    });
    
    return () => <div>Hello</div>;
});
```

## onUpdated

The `onUpdated` hook runs after the component re-renders due to reactive state changes:

```tsx
import { component, onUpdated } from 'sigx';

const Counter = component(({ signal }) => {
    const state = signal({ count: 0 });
    
    onUpdated(() => {
        console.log('Component updated! Count is now:', state.count);
    });
    
    return () => (
        <button onClick={() => state.count++}>
            Count: {state.count}
        </button>
    );
});
```

## onUnmounted

Use `onUnmounted` to run cleanup when a component is removed:

```tsx
import { component, onUnmounted } from 'sigx';

const Timer = component(({ signal }) => {
    const state = signal({ count: 0 });
    
    const intervalId = setInterval(() => {
        state.count++;
    }, 1000);
    
    // Cleanup when component unmounts
    onUnmounted(() => {
        clearInterval(intervalId);
    });
    
    return () => <div>Timer: {state.count}</div>;
});
```

### Using Context Method

```tsx
const Timer = component((ctx) => {
    const state = ctx.signal({ count: 0 });
    
    const intervalId = setInterval(() => {
        state.count++;
    }, 1000);
    
    ctx.onUnmounted(() => {
        clearInterval(intervalId);
    });
    
    return () => <div>Timer: {state.count}</div>;
});
```

## Full Lifecycle Example

```tsx
import { component, onCreated, onMounted, onUpdated, onUnmounted } from 'sigx';

const WebSocketComponent = component(({ signal, props }) => {
    const state = signal({ 
        messages: [] as string[],
        connected: false 
    });
    
    let ws: WebSocket | null = null;
    
    onCreated(() => {
        console.log('Component created, preparing to connect...');
    });
    
    onMounted(() => {
        // Connect when mounted
        ws = new WebSocket(props.url);
        
        ws.onopen = () => {
            state.connected = true;
        };
        
        ws.onmessage = (e) => {
            state.messages.push(e.data);
        };
    });
    
    onUpdated(() => {
        console.log('Messages updated:', state.messages.length);
    });
    
    onUnmounted(() => {
        // Disconnect when unmounted
        ws?.close();
    });
    
    return () => (
        <div>
            <p>Status: {state.connected ? 'Connected' : 'Disconnected'}</p>
            <ul>
                {state.messages.map(msg => <li>{msg}</li>)}
            </ul>
        </div>
    );
});
```

## Lifecycle Order

1. **Setup function runs** - Component is created, signals initialized
2. **`onCreated` callbacks run** - Setup complete, before render
3. **Render function runs** - JSX is evaluated
4. **DOM is created** - Elements inserted into document
5. **`onMounted` callbacks run** - Access to real DOM elements
6. *(Component lives, effects run on changes)*
7. **`onUpdated` callbacks run** - After each re-render
8. **`onUnmounted` callbacks run** - Component is being removed
9. **DOM is removed** - Elements removed from document

## Important Notes

- All lifecycle hooks must be called **synchronously** during setup
- Calling them outside a component setup will log a warning
- Effects automatically clean up when the component unmounts
- Multiple lifecycle hook calls are allowed - all callbacks will run
- `setup()`, `onCreated`, and `onMounted` run **untracked** — reactive reads in them don't become dependencies of any render effect. Use the render function, `watch`, or `computed` for reactivity (see [Components → setup runs untracked](/core/docs/components#defining-components)).

## Dev-Mode Runaway-Loop Guards

If a component's render writes reactive state that the same render reads — directly, or through a store action called mid-render — the synchronous flush would otherwise re-queue itself forever and freeze the page. **Development builds** turn this into an actionable error instead:

- The render scheduler bounds each flush, catching both ping-pong loops between existing components and loops that remount fresh components each iteration.
- The reactivity layer bounds each notification wave (`Runaway notification wave`) for runaway effect cascades outside the render queue.

These limits sit far above anything a legitimate update produces, and **all of them are compiled out of production builds** — they cost nothing in shipped apps. They surface real bugs (a render that mutates state it depends on) early, with a stack trace, rather than as a silent hang.

---
url: https://sigx.dev/core/api/reactivity/
title: Reactivity
description: SignalX reactivity API reference
---

# Reactivity API

Core reactive primitives for state management.

## signal

Create reactive state. Primitives are wrapped in `{ value }`, objects become reactive proxies.

```tsx
function signal<T extends Primitive>(target: T): PrimitiveSignal<T>;
function signal<T extends object>(target: T): Signal<T>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `target` | `T` | Initial value (primitive or object) |

### Returns

- **Primitives**: `{ value: T }` wrapper with reactive `value` property
- **Objects**: Reactive proxy with direct property access

### Examples

```tsx
import { signal } from 'sigx';

// Primitives - use .value
const count = signal(0);
count.value++;              // 1

const name = signal('World');
name.value = 'SignalX';

// Objects - direct access
const user = signal({ name: 'John', age: 30 });
user.name = 'Jane';         // Reactive
user.age++;                 // Reactive

// Arrays
const items = signal([1, 2, 3]);
items.push(4);              // Reactive
items[0] = 10;              // Reactive

// Collections
const map = signal(new Map());
map.set('key', 'value');    // Reactive

// Replace entire object
user.$set({ name: 'Bob', age: 25 });
```

### Key-set tracking

Enumerating an object proxy inside an effect or computed — `Object.keys()`,
`for…in`, spread, rest destructuring — also subscribes to its key set, so adding
or deleting a key re-runs the reader. `'x' in obj` subscribes to the same
dependency `obj.x` does. Arrays carry that dependency on `length`; Maps and Sets
track iteration and `.size`. See [Enumerating Reactive
Objects](/core/docs/advanced/reactivity#enumerating-reactive-objects).

---

## effect

Run a function when its reactive dependencies change.

```tsx
function effect(fn: EffectFn): EffectRunner;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `() => void` | Function to run reactively |

### Returns

`EffectRunner` - Callable function with a `stop()` method.

Called **directly in a component's setup body**, the effect is tied to that component and stops on unmount — the handle is there if you want it, not something you must keep. Created anywhere else (including inside `onMounted` or an async callback), stopping it is yours to do. See [Effect cleanup](/core/docs/effects#effect-cleanup).

### Examples

```tsx
import { signal, effect } from 'sigx';

const state = signal({ count: 0 });

// Effect runs immediately and on changes
const runner = effect(() => {
    console.log('Count:', state.count);
});

state.count = 5;  // Logs: "Count: 5"

// Stop the effect
runner.stop();
state.count = 10; // No log
```

---

## computed

Create a lazily-evaluated derived value.

```tsx
function computed<T>(getter: () => T): Computed<T>;
function computed<T>(options: { get: () => T; set: (v: T) => void }): WritableComputed<T>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `getter` | `() => T` | Function that computes the value |
| `options.get` | `() => T` | Getter for writable computed |
| `options.set` | `(v: T) => void` | Setter for writable computed |

### Returns

- **Read-only**: `Computed<T>` - Call to get value: `computed()`
- **Writable**: `WritableComputed<T>` - Has `set()` method

### Examples

```tsx
import { signal, computed } from 'sigx';

const state = signal({ count: 0 });

// Read-only computed
const doubled = computed(() => state.count * 2);
console.log(doubled());  // 0

state.count = 5;
console.log(doubled());  // 10

// Writable computed
const celsius = signal({ value: 0 });
const fahrenheit = computed({
    get: () => celsius.value * 9/5 + 32,
    set: (f) => celsius.value = (f - 32) * 5/9
});

fahrenheit.set(212);
console.log(celsius.value);  // 100
```

---

## watch

Watch reactive sources with a callback.

```tsx
function watch<T>(
    source: WatchSource<T>,
    callback: WatchCallback<T>,
    options?: WatchOptions
): WatchHandle;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `source` | `T \| () => T` | Value or getter to watch |
| `callback` | `(value, oldValue, onCleanup) => void` | Called on change |
| `options.immediate` | `boolean` | Run immediately (default: false) |
| `options.deep` | `boolean \| number` | Deep watch (default: false) |
| `options.once` | `boolean` | Run once then stop |

### Returns

`WatchHandle` - Object with `stop()`, `pause()`, `resume()` methods.

Like [`effect`](#effect), a `watch` created directly in a component's setup body stops automatically on unmount; `pause()`/`resume()` remain useful in the meantime. See [Effect cleanup](/core/docs/effects#effect-cleanup).

### Examples

```tsx
import { signal, watch } from 'sigx';

const state = signal({ count: 0 });

// Basic watch
const handle = watch(
    () => state.count,
    (newVal, oldVal) => {
        console.log(`Changed from ${oldVal} to ${newVal}`);
    }
);

state.count = 5;  // Logs: "Changed from 0 to 5"

// With cleanup
watch(
    () => state.count,
    (value, _, onCleanup) => {
        const timer = setInterval(() => console.log(value), 1000);
        onCleanup(() => clearInterval(timer));
    }
);

// Pause/resume
handle.pause();
state.count = 10;  // No log
handle.resume();   // Catches up if value changed

// Stop watching
handle.stop();
```

---

## batch

Group multiple updates into a single reactive flush.

```tsx
function batch(fn: () => void): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `() => void` | Function containing updates |

### Examples

```tsx
import { signal, effect, batch } from 'sigx';

const state = signal({ a: 0, b: 0, c: 0 });

effect(() => {
    console.log(state.a, state.b, state.c);
});

// Without batch: effect runs 3 times
state.a = 1;
state.b = 2;
state.c = 3;

// With batch: effect runs once
batch(() => {
    state.a = 1;
    state.b = 2;
    state.c = 3;
});
```

---

## untrack

Read values without creating dependencies.

```tsx
function untrack<T>(fn: () => T): T;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `() => T` | Function to execute |

### Returns

The return value of `fn`.

### Examples

```tsx
import { signal, effect, untrack } from 'sigx';

const state = signal({ count: 0, multiplier: 2 });

effect(() => {
    // Depends on count, NOT multiplier
    const mult = untrack(() => state.multiplier);
    console.log(state.count * mult);
});

state.count++;      // Effect runs
state.multiplier++; // Effect does NOT run
```

---

## toRaw

Get the underlying non-reactive object from a proxy.

```tsx
function toRaw<T>(observed: T): T;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `observed` | `T` | Reactive proxy or any value |

### Returns

The raw object, or the value itself if not reactive.

### Examples

```tsx
import { signal, toRaw } from 'sigx';

const state = signal({ name: 'John', items: [1, 2, 3] });

// Get raw for serialization
const raw = toRaw(state);
fetch('/api', { body: JSON.stringify(raw) });

// Check identity
const obj = { x: 1 };
const reactive = signal(obj);
toRaw(reactive) === obj;  // true
```

---

## isReactive

Check if a value is a reactive proxy.

```tsx
function isReactive(value: unknown): boolean;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `value` | `unknown` | Value to check |

### Returns

`true` if the value is a reactive proxy.

### Examples

```tsx
import { signal, isReactive } from 'sigx';

const state = signal({ count: 0 });
const plain = { count: 0 };

isReactive(state);  // true
isReactive(plain);  // false
```

---

## effectScope

Create a scope for grouping effects.

```tsx
function effectScope(detached?: boolean): EffectScope;
```

### Parameters

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `detached` | `boolean` | `false` | Independent of parent scope |

### Returns

`EffectScope` with:
- `run<T>(fn: () => T): T | undefined` - Execute within scope
- `stop(): void` - Stop all effects in scope

### Examples

```tsx
import { signal, effect, effectScope } from 'sigx';

const scope = effectScope();

scope.run(() => {
    const state = signal({ count: 0 });
    effect(() => console.log(state.count));
    effect(() => console.log(state.count * 2));
});

// Stop all effects at once
scope.stop();
```

---

## toSignal

Create a signal-shaped (`{ value }`) live view over **one** property of a reactive object. Unlike destructuring — which snapshots the value — the view reads and writes through to the source, so tracking and triggering are preserved.

```tsx
function toSignal<T extends object, K>(source: T, key: K): PropertySignal<T[K]>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `source` | `T` | A reactive object (e.g. from `signal({...})`) |
| `key` | `K` | The property to view (any string key except `$set`) |

### Examples

```tsx
import { signal, toSignal } from 'sigx';

const state = signal({ count: 0 });
const count = toSignal(state, 'count');

count.value++;             // triggers effects watching state.count
console.log(state.count);  // 1
```

---

## toSignals

Create signal-shaped views for **every** own enumerable property of a reactive object, so it can be destructured without losing reactivity.

```tsx
function toSignals<T extends object>(source: T): ToSignals<T>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `source` | `T` | A reactive object |

### Returns

A `ToSignals<T>` — one `PropertySignal` per own enumerable string key (`$set` excluded).

### Examples

```tsx
import { signal, toSignals } from 'sigx';

const state = signal({ count: 0, name: 'Ada' });
const { count, name } = toSignals(state);

count.value++;            // still reactive
name.value = 'Grace';     // writes through to state.name
```

---

## Types

### Signal\<T\>

```tsx
type Signal<T> = T & {
    $set: (newValue: T) => void;
};
```

### PrimitiveSignal\<T\>

```tsx
type PrimitiveSignal<T> = Signal<{ value: Widen<T> }>;
```

### EffectRunner

```tsx
interface EffectRunner<T = void> {
    (): T;
    stop: () => void;
}
```

### Computed\<T\>

```tsx
interface Computed<T> {
    (): T;
}
```

### WritableComputed\<T\>

```tsx
interface WritableComputed<T> {
    (): T;
    set(value: T): void;
}
```

### WatchHandle

```tsx
interface WatchHandle {
    (): void;          // Callable to stop
    stop: () => void;
    pause: () => void;
    resume: () => void;
}
```

### EffectScope

```tsx
type EffectScope = {
    run<T>(fn: () => T): T | undefined;
    stop(fromParent?: boolean): void;
}
```

---
url: https://sigx.dev/use/docs/use-online/
title: useOnline
description: Reactive navigator.onLine — the sugar form of the cross-platform connectivity contract
---

# useOnline

Reactive `navigator.onLine` via the `online`/`offline` events. Browser composable — import from `@sigx/use-web`.

```ts
import { effect } from 'sigx';
import { useOnline } from '@sigx/use-web';

const online = useOnline();
effect(() => { if (!online.value) showOfflineBanner(); });
```

This is the **sugar form** of the cross-platform connectivity contract — `useOnline()` is `useNetwork().isConnected` as a standalone [`ReadSignal<boolean>`](/use/docs/conventions#outputs-single-value--readsignalt). Reach for [`useNetwork`](/use/docs/use-network) when you also need `type` or the Network Information API extras.

## Signature

```ts
function useOnline(options?: ConfigurableWindow): ReadSignal<boolean>;
```

Pass `{ window }` to drive it from a mock — see [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides).

## SSR

On the server the signal reads `true`, then reflects `navigator.onLine` on mount.

## See also

- [`useNetwork`](/use/docs/use-network) — the full state (`type`, `effectiveType`, `downlink`, `saveData`).
- [`useDocumentVisibility`](/use/docs/use-document-visibility) — the other "is now a good time to do work" sensor.
- [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) — connectivity as a shared contract.

---
url: https://sigx.dev/store/docs/patterns/
title: Patterns
description: Multi-slice stores, composition, optimistic updates, request races, and undo
---

# Patterns

Recipes that fall out of the primitives — each one is plain store code, no extra API. Format: the problem, the solution, and the caveats that bite in practice.

## Multi-slice stores

**Problem:** one store has grown two unrelated groups of state — say UI preferences and a draft document — and you want to patch, watch, and persist them independently without splitting into two stores.

**Solution:** call `defineState` more than once. Each call is an independent slice with its own `state`, `patch`, and `events`; spread both `signals` into the return:

```ts
import { defineStore } from '@sigx/store';
import { persist } from '@sigx/store/persist';

const useEditorStore = defineStore('editor', (ctx) => {
    const ui = ctx.defineState({ sidebar: 'open', zoom: 1 });
    const doc = ctx.defineState({ text: '', savedAt: '' });

    // independent persistence per slice — explicit keys required:
    persist(ctx, ui, { key: 'sigx:editor:ui' });
    persist(ctx, doc, { key: 'sigx:editor:doc', debounce: 500 });

    const actions = ctx.defineActions({
        resetView() { ui.patch({ sidebar: 'open', zoom: 1 }); },   // slice-local patch
    });

    return { ...ui.signals, ...doc.signals, ...actions };
});
```

**Caveats:**

- The instance surface is still flat — `store.$patch({ zoom: 2, text: 'hi' })` works **across** slices (each key routes to its owning slice, in one atomic flush). Slices organize the *setup*, not the consumer.
- Returned key names must be unique across slices — a later spread silently shadows an earlier one.
- Each `persist` call needs an explicit `key`; the default `sigx:<storeName>` would collide. See [Persistence](/store/docs/persistence#multiple-slices).

## Store composition (stores using stores)

**Problem:** the cart store needs the session store's user id. You don't want components to glue them together on every use.

**Solution:** call the other store's use-function inside your setup — a factory call is valid anywhere, including another factory's setup:

```ts
const useSessionStore = defineStore('session', sessionSetup, 'singleton');

const useCartStore = defineStore('cart', ({ defineState, defineActions }) => {
    const session = useSessionStore();              // resolve the dependency

    const { state, signals } = defineState({ items: [] as Item[] });

    const actions = defineActions({
        async checkout() {
            await api.checkout(session.userId, state.items);
            state.items = [];
        },
    });

    return { ...signals, ...actions };
});
```

**Caveats — all about [lifetimes](/store/docs/lifetimes-and-di):**

- **The inner store resolves when the outer setup runs** — for a shared outer store, that's its *first creation*, and the result is captured for the outer's whole life. A `'scoped'` inner store resolves against whatever component tree (and `defineProvide` overrides) surrounded that first call — later overrides won't reach an already-created outer store.
- **Lifetime mismatch:** composing a long-lived outer (`'singleton'`) with a shorter-lived inner is the dangerous direction. Inner `'singleton'`/`'scoped'` deps from a shared outer are the safe, boring default.
- **A `'transient'` inner store is owned by whoever created it** — resolved during the outer setup inside a component, it disposes with that *component*, not with the outer store. If the outer store should own it, say so explicitly inside its setup:

```ts
const useOuterStore = defineStore('outer', (ctx) => {
    const inner = useScratchStore();                  // 'transient'
    ctx.onDeactivated(() => inner.$dispose());        // die together
    // ...
    return { /* ... */ };
});
```

## Optimistic update with rollback

**Problem:** toggling a todo should feel instant, but the server may reject it — the UI must snap back.

**Solution:** patch optimistically before the request; keep a snapshot; roll back from an `onFailure` subscriber ([error semantics](/store/docs/actions-and-async#error-semantics) guarantee it fires on rejection):

```ts
const useTodoStore = defineStore('todos', ({ defineState, defineActions }) => {
    const { state, signals, patch } = defineState({ todos: [] as Todo[] });

    let snapshot: Todo[] = [];

    const actions = defineActions({
        async toggle(id: number) {
            snapshot = state.todos.map(t => ({ ...t }));        // capture BEFORE the patch
            patch(s => {
                const todo = s.todos.find(t => t.id === id);
                if (todo) todo.done = !todo.done;               // optimistic
            });
            await api.toggle(id);                               // rejection → onFailure
        },
    });

    actions.toggle.onFailure.subscribe(() => {
        patch({ todos: snapshot });                             // rollback, one flush
    });

    return { ...signals, ...actions };
});
```

**Caveats:**

- One `snapshot` variable assumes **non-overlapping** invocations — a second `toggle` before the first settles overwrites the snapshot, and a late failure rolls back too much. Disable the control on `store.toggle.pending`, or keep a `Map<id, snapshot>` keyed per call.
- Snapshot *deeply* (note the `.map(t => ({ ...t }))`) — the optimistic patch mutates in place, and a shallow copy would share the mutated objects.
- The rollback patch is atomic — subscribers and renders see one flush, not a flicker through intermediate states.

## Request de-duplication and latest-wins

**Problem:** every component calling `store.load()` triggers its own fetch; and when calls *do* overlap with different arguments, a slow early response can overwrite a fast late one.

**Solution (de-dup):** share the in-flight promise in a private variable. Callers all await the same request; `pending` still drives the UI:

```ts
let inflight: Promise<void> | null = null;

const actions = defineActions({
    load() {
        inflight ??= api.fetchAll()
            .then(data => { state.items = data; })
            .finally(() => { inflight = null; });
        return inflight;
    },
});
```

**Solution (latest wins):** stamp each invocation with an id; only the latest may write:

```ts
let requestId = 0;

const actions = defineActions({
    async search(query: string) {
        const id = ++requestId;
        const results = await api.search(query);
        if (id !== requestId) return;        // superseded — drop silently
        state.results = results;
    },
});
```

**Caveats:**

- Don't check `store.load.pending` *inside* the action body for de-dup — the current invocation already counts, so it's always `true` there. `pending` is for callers; the private promise is the guard.
- In the de-dup form, a rejection still reaches every awaiting caller and fires `onFailure` once per `load()` call that joined the shared promise.
- The latest-wins drop is invisible to `onDispatched` — the superseded call still "succeeds" (it returns normally). If observers must distinguish applied from dropped, publish a [custom event](/store/docs/events-and-observability#custom-events-with-defineevents) on apply.

## Undo (a sketch)

**Problem:** cheap undo for a single piece of state, without a command architecture.

**Solution:** `$events` hands you `(value, prev)` for every change — record `prev`, and undo by writing it back. A flag keeps the undo write itself out of history:

```ts
const useDraftStore = defineStore('draft', ({ defineState, defineActions }) => {
    const { state, signals, events } = defineState({ text: '' });

    const history: string[] = [];
    let undoing = false;

    events.text.subscribe((value, prev) => {
        if (undoing || prev === undefined) return;
        history.push(prev);
        if (history.length > 100) history.shift();
    });

    const actions = defineActions({
        undo() {
            const prev = history.pop();
            if (prev === undefined) return;
            undoing = true;
            try { state.text = prev; }
            finally { undoing = false; }
        },
    });

    return { ...signals, ...actions };
});
```

**Caveats:**

- `history` is deliberately a plain (non-reactive) array — pushing to it doesn't trigger renders. If the UI needs a live `canUndo`, mirror the depth into a state key (`state.undoDepth = history.length`) inside the subscriber and the action.

- **This works as written for primitives and replaced references only.** For object/array keys mutated *in place* (`state.todos.push(...)`), the deep watcher reports the **same object** as both `value` and `prev` — there is no old copy to record. Either replace immutably (`state.todos = [...state.todos, item]`) or snapshot `value` yourself on every event and push the *previous snapshot*.
- State events flush per reactivity flush, not per assignment — a `patch` touching `text` produces one history entry, but several plain assignments in one synchronous block may too. Good enough for a sketch; group explicitly (wrap edits in `patch`) when granularity matters.
- Redo is the same machinery with a second stack — push the undone value onto it inside `undo()`, clear it on any organic change.

## Next steps

- [Actions & Async](/store/docs/actions-and-async) — `pending`, error semantics, and cancellation, which these recipes build on.
- [Lifetimes & DI](/store/docs/lifetimes-and-di) — the resolution rules behind the composition caveats.
- [Events & Observability](/store/docs/events-and-observability) — what `$events` delivers, exactly.
- [TypeScript](/store/docs/typescript) — keeping all of the above fully inferred.

---
url: https://sigx.dev/use/docs/use-scroll/
title: useScroll
description: Reactive scroll position with edge-arrival and direction detection — writing x/y scrolls the target
---

# useScroll

Reactive scroll position with edge-arrival and direction detection; writing `x`/`y` scrolls the target. Browser composable — import from `@sigx/use-web`.

```ts
import { effect } from 'sigx';
import { useScroll } from '@sigx/use-web';

const { y, arrivedState } = useScroll();      // defaults to the window
effect(() => { if (arrivedState.bottom) loadMore(); });
y.value = 0;                                   // scroll to top
```

The target defaults to the window, so there is deliberately **no separate `useWindowScroll`** — call `useScroll()` for the window, or pass an element/`Document` to scroll something else:

```ts
const el = signal<HTMLElement | null>(null);
const { x, y } = useScroll(el);
```

## Signature

```ts
function useScroll(target?: MaybeSignal<ScrollTarget>, options?: UseScrollOptions): UseScrollReturn;

type ScrollTarget = Element | Window | Document | null | undefined;
```

`target` is a [`MaybeSignal`](/use/docs/conventions#inputs-maybesignalt-and-tovalue); a reactive target re-attaches the listener. Listeners are passive and detach with the owning scope.

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `throttle` | `number` | `0` | Throttle scroll handling to at most once per `throttle` ms (`0` = off). |
| `idle` | `number` | `200` | ms of quiet before `isScrolling` flips back to `false`. |
| `offset` | `{ left?, right?, top?, bottom? }` | — | Edge tolerance (px) for `arrivedState`. |
| `behavior` | `ScrollBehavior` | `'auto'` | Scroll behavior for programmatic writes to `x`/`y`. |
| `onScroll` | `(event: Event) => void` | — | Called on each scroll event. |
| `onStop` | `(event: Event) => void` | — | Called when scrolling goes idle. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). See [`Configurable*`](/use/docs/conventions#ssr-safety-and-configurable-overrides). |

## Returns

| Field | Type | Description |
|---|---|---|
| `x` / `y` | `WritableComputed<number>` | Scroll position; **writing scrolls** the target with the configured `behavior`. |
| `isScrolling` | `ReadSignal<boolean>` | `true` while scrolling, back to `false` after `idle` ms of quiet. |
| `arrivedState` | `ReactiveView<{ left, right, top, bottom }>` | Which edges the position has arrived at (within `offset`). |
| `directions` | `ReactiveView<{ left, right, top, bottom }>` | Which directions the latest scroll moved in. |
| `stop` | `Stop` | Detach the listener/watcher and clear timers — for standalone, no-scope use. |

`arrivedState` and `directions` are [reactive views](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — read fields by property access.

## SSR

On the server `x`/`y` read as `0`, `arrivedState`/`directions` are all `false`, and **writes are a no-op** — nothing scrolls until the client takes over on mount.

## See also

- [`useWindowSize`](/use/docs/use-window-size) — the viewport dimensions to scroll within.
- [`useThrottledSignal`](/use/docs/use-throttled-signal) — derive a throttled value from `y` for expensive scroll work.
- [`useMediaQuery`](/use/docs/use-media-query) — react to viewport media instead of position.

---
url: https://sigx.dev/use/docs/use-toggle/
title: useToggle
description: A boolean signal with a toggler — flip with no argument, set with a boolean
---

# useToggle

A boolean signal paired with a **toggler**. Call the toggler with no argument to flip the value, or with a boolean to set it explicitly; it returns the new value. Cross-platform — import from `@sigx/use`.

```tsx
import { component, render } from 'sigx';
import { useToggle } from '@sigx/use';

const Switch = component(() => {
    const [dark, toggleDark] = useToggle(false);

    return () => (
        <div class="flex items-center gap-3">
            <button class="btn" onClick={() => toggleDark()}>
                {dark ? '🌙 Dark' : '☀️ Light'}
            </button>
            <button class="btn btn-ghost" onClick={() => toggleDark(false)}>force light</button>
        </div>
    );
});

render(<Switch />, "#app");
```

## Usage

```ts
import { useToggle } from '@sigx/use';

const [open, toggleOpen] = useToggle();      // starts false
toggleOpen();        // true  — flips
toggleOpen(false);   // false — explicit set
open.value;          // read the signal directly
```

Pass an **existing boolean signal** to get just a toggler bound to it — useful when the signal already lives somewhere (a store, a prop):

```ts
import { signal } from 'sigx';

const visible = signal(false);
const toggleVisible = useToggle(visible);
toggleVisible(); // visible.value === true
```

## Signatures

```ts
function useToggle(initial?: boolean): [PrimitiveSignal<boolean>, Toggler];
function useToggle(source: PrimitiveSignal<boolean>): Toggler;

type Toggler = (value?: boolean) => boolean;
```

| Call | Returns |
|---|---|
| `useToggle(initial?)` | `[signal, toggler]` — a new boolean signal (default `false`) and its toggler. |
| `useToggle(existingSignal)` | `toggler` — a toggler bound to the signal you passed. |

**Platform:** everywhere. No cleanup needed.

## See also

- [`useCounter`](/use/docs/use-counter) — the numeric equivalent, with clamped mutators.
- [`useCycleList`](/use/docs/use-cycle-list) — cycle through more than two states.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/actors/docs/client/
title: The client
description: configureActors, transports and routers — calling actors from a browser, a native app or another service
---

# The client

<p class="lede">`actor(Def, key)` is the same expression everywhere. On the server it
dispatches in-process; in a browser it goes through a transport. `@sigx/actors/client` is
where you configure the second one.</p>

## The default

Inside a SignalX app, install the plugin and you are done:

```ts
import { actorsPlugin } from '@sigx/actors/app';

app.use(actorsPlugin());
```

The build stamps each actor's endpoint onto its client ref, so an ordinary same-origin app
needs no configuration at all.

## Pointing somewhere else

```ts
import { configureActors } from '@sigx/actors/client';

configureActors({
    endpoint: 'https://api.example.com/_sigx/actor',
    headers: () => ({ authorization: token() }),
});
```

This is sugar for `fetchTransport(config)`. `headers` may be a function, so it is re-read per
call — which is what you want for a token that rotates.

Because `init.endpoint` carries the endpoint the build baked in, `configureActors({ headers })`
overrides headers alone without restating where the server is.

`configureActors` is independent of `configureServerFn`, so a native or remote client can
point actors at one origin and server functions at another.

## Supplying a whole transport

```ts
configureActors({
    name: 'batching',
    call: (symbol, args, init) => /* … */,
    stream: (symbol, args, init) => /* … */,
    live: () => /* optional push channel */,
    close: () => /* optional */,
});
```

`call` and `stream` are required; `live` and `close` are optional. Omit `live` and
[live reads](/actors/docs/live-reads) are driven over your `stream()` instead.

`close()` is **idempotent by contract**. A live channel resolved from a transport's own
`live()` is released through the transport that produced it, so either owner — the plugin or
the channel — may release first. (`ActorLiveChannel` deliberately has no `close()` of its
own.)

### The socket transport

[`@sigx/actors-ws`](/actors/packages/actors-ws/overview) is the ready-made one: every call and
every live subscription on the page over a single connection.

```ts
import { socketTransport } from '@sigx/actors-ws/client';

app.use(actorsPlugin({ transport: socketTransport({ url: 'wss://example.com/_sigx/socket' }) }));
```

It implements `live()`, so subscriptions change incrementally instead of reopening. Note that
it is **host-affine** — a per-call `endpoint` is ignored, because every call re-dispatches
through placement anyway — and that in-flight calls fail un-retried when a socket drops, while
subscriptions re-establish.

`fetchTransport()` stays the default; reach for the socket when the connection *shape* is the
problem, not when you want a faster call.

## Routing

`ActorTransport` decides *how* a call travels; `ActorRouter` decides *where* it goes. They
compose:

```ts
import {
    configureActors, fetchTransport, learningRouter, routedTransport,
} from '@sigx/actors/client';

configureActors(routedTransport(fetchTransport({ endpoint }), learningRouter()));
```

| Router | How it decides | Good for |
|---|---|---|
| *(none — the default)* | always the configured endpoint | one origin, browsers |
| `learningRouter()` | caches what redirects teach it | any caller that can reach hosts directly |
| `staticRouter(map)` | a fixed key → host mapping | tenancy or sharding you already own |
| `chainRouters(a, b)` | first answer wins | a static override in front of learning |

A learned endpoint is dropped as soon as it proves wrong — a connection failure or a 5xx — and
the caller falls back to the configured endpoint.

> **`learningRouter()` is not a browser feature.** It pays off for a service that can reach
> hosts directly. A browser talking to one public origin should stay on the default and get
> its locality from [the routing token](/actors/docs/locality-routing) instead.

## Refs are inspectable

A ref's `get` trap synthesizes a dispatcher for any unknown property — that is what lets
methods need no registration. A handful of names are answered **locally** instead, so
inspecting a ref never issues a call:

```ts
const ref = actor(CartActor, 'user-42');

String(ref);            // '[actor Cart#user-42]'
JSON.stringify(ref);    // undefined — no call
ref.constructor;        // undefined — no call
```

`toString` reads `[actor Type#key]`, so refs interpolate usefully into logs. Every other
`Object.prototype` name — plus `toJSON` and Node's legacy `inspect` — reads `undefined`,
exactly like symbols and `then`. This holds for every proxy: `actor()` in the browser and on
the server, `host.actor(…)` and `ctx.actor(…)`.

The cost is one naming rule: **an actor method named after an `Object.prototype` member**
(`toString`, `valueOf`, `hasOwnProperty`, `toJSON`, …) **is not reachable through a proxy.**
Pick another name.

## The request-context bag

Server-side callers can attach a small string-only bag of app data to a call — a request id, a
tenant hint, a feature flag — without adding an argument:

```ts
await actor(RoomActor, id).with({ bag: { tenant: 'acme' } }).post(text);
```

The method reads it as `ctx.bag`. Caps, propagation rules and the deliberately silent
drop-whole posture for a malformed bag arriving en route are covered under
[the request-context bag](/actors/docs/wire-protocol#the-request-context-bag). Identity does
**not** belong here — use [`ctx.principal`](/actors/docs/guards).

## Per-call options

```ts
actor(Cart, id).with({ get: false }).summary();      // force POST on a declared read
actor(Notifier, id).with({ oneWay: true }).ping();   // resolve at acceptance
actor(Cart, id).with({ signal }).checkout();         // abort
```

`with()` also accepts `headers`, `endpoint` and `route` for one call.

## Calling from outside a SignalX app

Nothing about the wire requires a SignalX client. It is the
[serverFn protocol](/actors/docs/wire-protocol) — a `POST` with a JSON body — so a script, a
mobile app or another service can call an actor with `fetch` and no SDK.

`@sigx/actors/client` is worth using anyway when you want the typed proxy, since it is
dependency-free and small: 5 kB budgeted for the whole entry, and 2.3 kB for a bundle that
pulls in no router.

## Next steps

- [Wire protocol](/actors/docs/wire-protocol) — the contract a transport implements.
- [Locality routing](/actors/docs/locality-routing) — redirects, `follow`, and the token.
- [Reads & writes in components](/actors/docs/in-components) — the ergonomic layer above this.

---
url: https://sigx.dev/actors/docs/errors/
title: Errors
description: The actor error kinds — deadlock, activation, state conflict, wrong host, unreachable, timeout — and what each one means you should do
---

# Errors

<p class="lede">Actor errors are branded and narrow on a `kind`, so you can tell "the caller
did something wrong" from "the cluster is having a moment" without string matching.</p>

```ts
import { isActorError } from '@sigx/actors';

try {
    await actor(CartActor, id).checkout();
} catch (err) {
    if (isActorError(err) && err.kind === 'state-conflict') {
        // retry — another activation won a race and this one is stale
    }
}
```

## The kinds

| Error | `kind` | What it means | What to do |
|---|---|---|---|
| `ActorDeadlockError` | `deadlock` | A call cycle re-entered a non-reentrant actor. Carries the full chain. | Fix the cycle, or widen with [`reentrant`](/actors/docs/reentrancy). Not retryable. |
| `ActorActivationError` | `activation` | `onActivate` or [`migrateState`](/actors/docs/state-and-persistence) threw. | A bug or corrupt state. The stored record is untouched. |
| `ActorStateConflictError` | `state-conflict` | An etag CAS lost — another activation wrote first. | The stale activation is faulted; the next call reloads. Usually retry once. |
| `ActorMethodNotFoundError` | `method-not-found` | No such **own key** in `methods:`/`streams:`. | Check the callable surface — a class instance is the usual cause. |
| `ActorCallTimeoutError` | `call-timeout` | The call exceeded `callTimeoutMs`. | See the precision note below. |
| `ActorWrongHostError` | `wrong-host` | The actor is placed on another host. | Normally handled for you by proxy or redirect. See [Locality routing](/actors/docs/locality-routing). |
| `ActorUnreachableError` | `unreachable` | The owning host could not be reached. | Transient — a peer is down, restarting or partitioned. Retryable. |
| `ActorStorageConflict` | — | Raised by an `ActorStorage` implementation on an etag mismatch. | Surfaces as `state-conflict`. `isStorageConflict()` narrows it. |
| `HostShutdownError` | `host-shutdown` | The host is draining. | Retry against the cluster, or let the client follow. |

`isActorError(err)` narrows to `ActorError`; `err.kind` is `ActorErrorKind`. On a
`wrong-host`, the error carries an `ActorOwnerHint`.

## Deadlocks are immediate, on purpose

```
ActorDeadlockError: Cart/user-42 → Pricing/eu → Cart/user-42
```

Every call carries its chain, so the cycle is detected at the moment it would block rather
than surfacing as a timeout later. The alternative — a hang that resolves into
`ActorCallTimeoutError` thirty seconds on — tells you almost nothing about the cause.

## Call deadlines fire coarsely

Deadlines **10 seconds or more** away, which includes the 30-second default, share a
one-second registry tick and may fire up to about **two seconds late**. They never fire early.
Short budgets keep exact per-call timers.

If you are setting a deadline to bound user-visible latency, this is the contract to design
against: a 30-second budget is "about 30 seconds", not a hard fence. Set `callTimeoutMs: 0` to
disable deadlines entirely.

## Errors on the wire

An actor endpoint is a synthesized server function, so error handling is core's: an
`ActorError` crossing the wire carries its `kind` and status, and production masking applies
exactly as it does for `ServerFnError`. A guard rejection answers with the status the guard
threw.

For [live subscriptions](/actors/docs/live-reads), failure is **per subscription** — a guard
rejecting one widget produces an error frame at that index and the rest of the feed keeps
streaming.

## Next steps

- [The actor model](/actors/docs/actor-model) — where deadlock detection comes from.
- [State & persistence](/actors/docs/state-and-persistence) — conflicts in context.
- [Metrics](/actors/docs/metrics) — `errors.byKind`, and why conflicts deserve an alert.

---
url: https://sigx.dev/actors/docs/topics/
title: Topics
description: Actor-to-actor pub/sub — declarative subscriptions, best-effort at-most-once delivery, and a settlement report the publisher can act on
---

# Topics

<p class="lede">An actor that changes something often needs to tell N interested actors without
knowing who they are. Declare the interest on the *subscriber* and publish from anywhere on
the server.</p>

```ts
import { topic } from '@sigx/actors';

export const chatMessages = topic<{ from: string; text: string }>('chat-messages');
// per-room: topic('chat-messages', roomId)
```

```ts
export const RoomFeed = defineActor({
    type: 'RoomFeed',
    authorize: requireAuthenticated,
    state: () => ({ recent: [] as { from: string; text: string }[] }),
    methods: (ctx) => ({
        async recent() { return ctx.snapshot().recent; },
    }),
    subscriptions: {
        // subscriber key = topic key, so RoomFeed/room-1 gets room-1's events
        'chat-messages': async (ctx, event) => {
            ctx.state.recent.push(event.payload);
            await ctx.save();
        },
    },
});
```

```ts
// from another actor's turn…
const report = await ctx.publish(topic('chat-messages', ctx.key), { from, text });
// …or from a serverFn / script via the running host:
await publishTopic(topic('chat-messages', roomId), { from, text });
```

## Subscriptions are implicit and declarative

The subscriber set is a pure function of the deploy: every registered type whose
`subscriptions:` names the topic. Nothing registers at runtime, nothing is stored, and there
is no subscribe/unsubscribe call to get out of sync.

A publish **activates idle subscribers**, exactly the way a reminder delivery does. Each
delivery is an ordinary dispatch of the reserved `$sigx:topic` method through placement, so a
subscriber owned by another host is reached over the internal transport — HMAC, deadlines,
branded errors, all of it — with no topic-specific wire machinery.

The cost model is **S dispatches per publish, where S is subscribing *types***, not
activations.

## Delivery is best-effort, at-most-once, and settled

`publish()` resolves when every subscriber's handler turn has settled, and reports what
happened:

```ts
const { subscribers, delivered, failures } = await ctx.publish(chatMessages, msg);
// failures: [{ type, key, message, kind? }]
```

**The publisher never throws for a subscriber.** A throwing handler, a dead host or a detected
deadlock all arrive as entries in `failures`.

Nothing is persisted and nothing is retried — a subscriber that was down missed the event. If
that is unacceptable, the event is not a topic; it is state a subscriber should read, or a
[job](/actors/docs/jobs).

Backpressure is intrinsic: the publisher awaits the turns, bounded by its call deadline. FIFO
holds per publisher→subscriber pair **only when the publisher awaits its publishes
sequentially**; concurrent publishes have no relative order.

## The details worth knowing

**Key mapping.** An entry may be `{ key: (topicKey) => subscriberKey, handle }`. `key: () =>
'aggregate'` makes one singleton receive every key's events. The default is identity — topic
key equals subscriber key.

**Cycles are deadlocks, not hangs.** `ctx.publish` carries the publishing turn's call chain,
so a subscription that dispatches back into a non-reentrant publisher fails *that delivery*
with `kind: 'deadlock'` in the report. The publisher is awaiting the fan-out, so an undetected
cycle could never complete. [`reentrant: true`](/actors/docs/reentrancy) delivers inline
instead; `reentrant: 'always'` delivers as a concurrent turn.

**Handlers are turns.** They mutate state and `ctx.save()` like any method. A throwing handler
fails only its own delivery and does not fault the activation. Handlers are not wire-callable
and never appear on the client.

**Pages observe topics through a projection.** A subscriber actor folds events into state, and
the page reads that:

```ts
useActorState(RoomFeed, roomId, 'recent', { live: true });
```

The existing [live channel](/actors/docs/live-reads) pushes after every handler turn. No new
wire, and no way for a browser to subscribe to a topic directly.

**Rolling deploys skew the subscriber set.** A host publishes to the subscribers *its* registry
declares, so a newly added subscribing type misses publishes from not-yet-rolled hosts until
the deploy completes. That is consistent with best-effort delivery, but worth planning a
two-phase rollout around if the subscriber is important.

**Hot topics pin subscribers active.** Every delivery is activity, so a busy topic resets its
subscribers' `idleAfterMs` clocks.

## Reserved names

Topic names may not start with `$` or `@`, and `:topic` is reserved by the runtime.

## Next steps

- [Live reads](/actors/docs/live-reads) — how a page sees the projection.
- [Reentrancy](/actors/docs/reentrancy) — what changes for cyclic delivery.
- [Jobs](/actors/docs/jobs) — when delivery must not be best-effort.

---
url: https://sigx.dev/core/api/lifecycle/
title: Lifecycle
description: SignalX component lifecycle hooks API reference
---

# Lifecycle API

Hooks for responding to component lifecycle events.

## onMounted

Register a callback to run after the component is mounted to the DOM.

```tsx
function onMounted(fn: (ctx: MountContext) => void): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `(ctx: MountContext) => void` | Callback receiving mount context |

### MountContext

| Property | Type | Description |
|----------|------|-------------|
| `el` | `PlatformElement` | The component's root DOM element |

### Examples

```tsx
import { component, onMounted } from 'sigx';

const MyComponent = component(({ signal }) => {
    const state = signal({ width: 0 });

    onMounted(({ el }) => {
        // Access DOM element
        state.width = el.offsetWidth;
        
        // Set up DOM-dependent logic
        const observer = new ResizeObserver(entries => {
            state.width = entries[0].contentRect.width;
        });
        observer.observe(el);
    });

    return () => <div>Width: {state.width}px</div>;
});
```

### Notes

- Called after the component's DOM is created and inserted
- Safe to access `el` and perform DOM measurements
- Can be called multiple times to register multiple callbacks
- Must be called during component setup (synchronously)

---

## onUnmounted

Register a callback to run before the component is removed from the DOM.

```tsx
function onUnmounted(fn: (ctx: MountContext) => void): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `(ctx: MountContext) => void` | Cleanup callback |

### Examples

```tsx
import { component, onMounted, onUnmounted } from 'sigx';

const Timer = component(({ signal }) => {
    const state = signal({ seconds: 0 });
    let intervalId: number;

    onMounted(() => {
        intervalId = setInterval(() => {
            state.seconds++;
        }, 1000);
    });

    onUnmounted(() => {
        // Clean up resources
        clearInterval(intervalId);
    });

    return () => <div>Elapsed: {state.seconds}s</div>;
});
```

### Common Cleanup Tasks

```tsx
onUnmounted(() => {
    // Clear timers
    clearInterval(timerId);
    clearTimeout(timeoutId);
    
    // Remove event listeners
    window.removeEventListener('resize', handleResize);
    
    // Close connections
    websocket.close();
    
    // Cancel subscriptions
    subscription.unsubscribe();
    
    // Disconnect observers
    resizeObserver.disconnect();
    intersectionObserver.disconnect();
});
```

---

## onCreated

Register a callback to run after the component instance is created.

```tsx
function onCreated(fn: () => void): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `() => void` | Callback to run |

### Examples

```tsx
import { component, onCreated } from 'sigx';

const MyComponent = component(({ signal }) => {
    const state = signal({ data: null });

    onCreated(() => {
        // Run initialization logic
        console.log('Component instance created');
        
        // Start data fetching
        fetchData().then(data => {
            state.data = data;
        });
    });

    return () => <div>{state.data}</div>;
});
```

### Notes

- Called synchronously after setup completes
- Before DOM mounting
- Useful for initialization that doesn't need DOM access

---

## onUpdated

Register a callback to run after the component re-renders.

```tsx
function onUpdated(fn: () => void): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `fn` | `() => void` | Callback to run after updates |

### Examples

```tsx
import { component, onUpdated } from 'sigx';

const Chart = component(({ props, signal }) => {
    let chartInstance: Chart | null = null;
    
    onMounted(({ el }) => {
        chartInstance = new Chart(el, props.data);
    });

    onUpdated(() => {
        // Sync external library with new data
        chartInstance?.update(props.data);
    });

    onUnmounted(() => {
        chartInstance?.destroy();
    });

    return () => <canvas />;
});
```

### Notes

- Called after reactive changes cause re-render
- DOM is already updated when callback runs
- Useful for syncing with external libraries

---

## Context Methods

These hooks are also available on the setup context:

```tsx
const MyComponent = component((ctx) => {
    // Equivalent to standalone hooks
    ctx.onMounted(({ el }) => { /* ... */ });
    ctx.onUnmounted(({ el }) => { /* ... */ });
    ctx.onCreated(() => { /* ... */ });
    ctx.onUpdated(() => { /* ... */ });

    return () => <div />;
});
```

---

## Lifecycle Order

```
1. Setup function runs
2. onCreated callbacks
3. First render
4. DOM mounting
5. onMounted callbacks
   │
   ├─── Reactive updates ─── onUpdated callbacks
   │
6. onUnmounted callbacks
7. DOM removal
```

---

## Async Setup

Components can have async setup functions. On the server, the setup is awaited. On the client, it runs synchronously for hydration.

```tsx
const AsyncComponent = component(async ({ signal }) => {
    const data = await fetchData();
    const state = signal({ data });

    onMounted(() => {
        console.log('Mounted with data');
    });

    return () => <div>{state.data}</div>;
});
```

---

## Types

### MountContext

```tsx
interface MountContext<TElement = PlatformElement> {
    el: TElement;
}
```

### PlatformElement

```tsx
// In browser (runtime-dom)
type PlatformElement = HTMLElement;

// Configurable per platform
type PlatformElement = PlatformTypes extends { element: infer E } ? E : any;
```

---
url: https://sigx.dev/core/docs/computed/
title: Computed Values
description: Derive reactive values from signals with computed
---

# Computed Values

Computed values automatically derive from other signals and update when their dependencies change. They are **lazy** (only compute when accessed) and **cached** (memoize results).

## Creating Computed Values

Access computed values using `.value`, just like primitive signals:

```tsx
import { signal, computed } from 'sigx';

const firstName = signal({ value: 'John' });
const lastName = signal({ value: 'Doe' });

// Access computed via .value
const fullName = computed(() => {
    return `${firstName.value} ${lastName.value}`;
});

console.log(fullName.value);  // "John Doe"

firstName.value = 'Jane';
console.log(fullName.value);  // "Jane Doe"
```

## Computed with Object Signals

When using object signals (the recommended pattern), access properties directly:

```tsx
import { signal, computed } from 'sigx';

const state = signal({
    firstName: 'John',
    lastName: 'Doe'
});

const fullName = computed(() => {
    return `${state.firstName} ${state.lastName}`;
});

console.log(fullName.value);  // "John Doe"
state.firstName = 'Jane';
console.log(fullName.value);  // "Jane Doe"
```

## Computed in Components

```tsx
import { component, computed, render } from 'sigx';

const ShoppingCart = component(({ signal }) => {
    const state = signal({
        items: [
            { name: 'Apple', price: 1.50, qty: 3 },
            { name: 'Banana', price: 0.75, qty: 5 },
        ]
    });
    
    // Computed values
    const total = computed(() => {
        return state.items.reduce(
            (sum, item) => sum + item.price * item.qty, 
            0
        );
    });
    
    const itemCount = computed(() => {
        return state.items.reduce((sum, item) => sum + item.qty, 0);
    });
    
    return () => (
        <div>
            <p>{itemCount.value} items</p>  {/* Access via .value */}
            <p>Total: ${total.value.toFixed(2)}</p>
        </div>
    );
});

render(<ShoppingCart />, "#sandbox");
```

## Writable Computed

Create computed values with custom setters. Set values using `.value =`:

```tsx
import { signal, computed } from 'sigx';

const state = signal({ firstName: 'John', lastName: 'Doe' });

const fullName = computed({
    get: () => `${state.firstName} ${state.lastName}`,
    set: (value: string) => {
        const [first, last] = value.split(' ');
        state.firstName = first;
        state.lastName = last || '';
    }
});

console.log(fullName.value);  // "John Doe"
fullName.value = 'Jane Smith';  // Set via .value
console.log(state.firstName);  // "Jane"
```

## Computed vs Effects

| Computed | Effect |
|----------|--------|
| Returns a value via `.value` | Runs side effects |
| Lazy - only runs when accessed | Eager - runs immediately |
| Cached - memoizes result | No caching |
| Pure - no side effects | Can have side effects |

```tsx
// ✅ Use computed for derived values
const doubled = computed(() => state.count * 2);
console.log(doubled.value);  // Access via .value

// ✅ Use effect for side effects
effect(() => {
    document.title = `Count: ${state.count}`;
});
```

## Chaining Computed Values

Computed values can depend on other computed values:

```tsx
import { signal, computed } from 'sigx';

const state = signal({ a: 1, b: 2 });

const sum = computed(() => state.a + state.b);
const doubled = computed(() => sum.value * 2);  // Access via .value

console.log(doubled.value);  // 6

state.a = 5;
console.log(doubled.value);  // 14
```

## Type Guard

Use `isComputed()` to check if a value is a computed signal:

```tsx
import { computed, isComputed } from 'sigx';

const doubled = computed(() => 42);

console.log(isComputed(doubled));       // true
console.log(isComputed({ value: 1 }));  // false
```

## Performance

Computed values offer significant performance benefits:
- **Lazy evaluation**: Only computes when the value is actually read
- **Dependency tracking**: Automatically knows which signals to watch
- **Caching**: Won't recompute if dependencies haven't changed
- **Minimal updates**: Only dependent effects/computeds update

Computed values are:
- **Lazy** - Only calculated when accessed
- **Cached** - Result is memoized until dependencies change
- **Efficient** - Fine-grained dependency tracking

## Next Steps

- [Effects](/core/docs/effects) - Run side effects reactively
- [Components](/core/docs/components) - Use computed in components

---
url: https://sigx.dev/actors/docs/guards/
title: Authorization
description: authorize, methodAuthorize and allowAnonymous — per-instance policies over ctx.principal, run outside the turn sequence on every transport
---

# Authorization

<p class="lede">A policy answers one question: may **this** caller run **this**
operation on **this** actor? Because an actor has an address, the answer can name
the instance — `op.resource.key` is the actor's key.</p>

## The app decides, most actors declare nothing

Authorization is app-wide by default. Point `sigxActors` at your
[server app](/server/packages/server/usage#the-app) and its policy covers every
actor you have not spoken about:

```ts
// vite.config.ts
sigxActors({ app: '/src/actors/app.ts', serverApp: '/src/server-app.ts' })
```

```ts
// src/server-app.ts
createServerApp({
    authenticate: (rq) => sessionFrom(rq.request),
    authorize: requireAuthenticated,   // every actor inherits this
    codec: principalCodec,             // required for cross-hop propagation
});
```

That is the whole setup for the common case. An actor declares a policy only when
it needs something *different* from the app default.

## Per-instance policies

A policy is core's `ServerPolicy` — `(principal, rq, op) => boolean`, **strict-`true`
to allow** — and `op.resource` carries the address:

```ts
type ActorResource = {
    kind: 'actor';
    type: string;      // 'Cart'
    key: string;       // 'u_123'
    method: string;    // 'checkout'
};
```

So the policy every real system wants is one line:

```ts
// src/policies.ts
export const ownsIt: ServerPolicy = (p, rq, op) =>
    p != null && op.resource.key === p.id;

export const CartActor = defineActor({
    type: 'Cart',
    authorize: ownsIt,
    methodAuthorize: {
        applyDiscount: requireStaff,   // this one method needs more
    },
    state: () => ({ items: [] as Item[] }),
    methods: (ctx) => ({ /* … */ }),
});
```

`methodAuthorize` **ANDs after** `authorize` — it does not replace it. A call to
`applyDiscount` above must satisfy `ownsIt` *and* `requireStaff`. Policies within an
array AND together too, so a chain is a conjunction at every level.

Declaring a deliberately open actor:

```ts
defineActor({ type: 'Counter', allowAnonymous: true, /* … */ });
```

`allowAnonymous` waives the **identity gate** only. Middleware and authentication
still run, and a policy declared alongside it still decides — against a nullable
principal. The two together are coherent, not contradictory.

`sigxActors({ requireAuthorization })` is the build gate, on by default. It asks
whether an actor has said anything about access; an app-wide default answers for
every actor at once.

## Three properties worth stating outright

**They run on every transport.** The wire endpoint and in-process `actor()` calls
both run the policy. You cannot bypass one by calling from the server. Where the
distinction matters, a policy reads **`op.fn.transport`** (`'wire'` or
`'in-process'`); `Type#method` identity stays the same on both.

**They run [outside the turn sequence](/actors/docs/turns).** A slow auth check
never occupies the actor, so a burst of unauthorized calls cannot queue behind
each other or block legitimate ones.

**Actor-to-actor calls do not re-run them.** `ctx.actor(Other, key).method()` is
intra-system: the decision was made at the edge where the request entered. Treat an
actor method as trusted once it is executing.

## ctx.principal

The authenticated identity is a first-class slot on the call envelope, and actors
read it as `ctx.principal`:

```ts
methods: (ctx) => ({
    async checkout() {
        audit(ctx.principal?.id, 'checkout', ctx.key);
    },
}),
```

It is decoded lazily and memoized, and it carries **unchanged** through
`ctx.actor` and `ctx.publish` hops and host-to-host — so a downstream actor sees
whoever entered the system, not the actor that called it.

<div class="alert alert-warning not-prose my-4">
  <div>
    Cross-hop propagation needs <strong><code>codec</code> on
    <code>createServerApp</code></strong>. Without one it propagates nothing and
    dev-warns exactly once — fail-closed at the reader, but easy to miss if you
    only ever test in one process.
  </div>
</div>

### Identity is not a bag key

`ctx.principal` and [`ctx.bag`](/actors/docs/wire-protocol) look similar and are
not interchangeable:

| | carries | can it be forged? |
|---|---|---|
| `ctx.principal` | the authenticated identity | **No** — it rides its own envelope slot, unreachable from `.with({ bag })` |
| `ctx.bag` | app data (a request id, a tenant hint, a feature flag) | it is caller-supplied by design |

Two failure modes follow. A bag key can be **forged** by any caller that can build
a request, and it can be **dropped** by an author forgetting to stamp it — and a
missing entry reads as "unauthenticated", which is the one thing an identity
channel must never be ambiguous about. Identity gets its own slot for exactly
those reasons; the bag stays for data.

## Jobs authorize at enqueue

A [job](/actors/docs/jobs) outlives the request that started it. A crash-resume
can happen on another host hours later with nobody waiting, so there is no live
request to authorize against.

So **`start` is the entry point that decides**, and the detached run body reads a
snapshot:

```ts
const run = await ctx.jobs.start(ImportJob, input);   // authorized HERE

// inside the job body:
job.principal        // the snapshot, persisted with the run
ctx.principal        // null — by design, there is no request behind a detached run
```

`ctx.principal` being null inside a detached run is exactly why `job.principal`
exists. Read the snapshot, not the ambient identity. (The same holds for a
[task](/actors/docs/tasks) body, for the same reason — no request is behind it.)

## Cacheable reads

A [cacheable read](/actors/docs/cacheable-reads) still authorizes on `GET`, and a
denial answers `Cache-Control: no-store`. But `public: true` is **refused at
definition time on an authorized read** — a shared cache would serve one caller's
copy to the next, and core's contract for a public cache entry is args-only.
Without `public`, a declared read is still cached per client with `Vary: Cookie`.

## Packaged actors

`sigxActors()` excludes `node_modules`, so it cannot see inside a
[packaged actor](/actors/docs/shipping-actors-in-packages) to enforce the gate.
Declaring `authorize` or `allowAnonymous` is the package author's responsibility;
with a server app configured, the app default covers a package that declares
nothing.

## Next steps

- [Wire protocol](/actors/docs/wire-protocol) — where authorization sits in a request, and the context bag.
- [Cacheable reads](/actors/docs/cacheable-reads) — the `public` restriction in context.
- [Server functions](/server/packages/server/usage#the-three-stages) — the pipeline actors inherit.

---
url: https://sigx.dev/i18n/docs/overview/
title: Overview
description: "@sigx/i18n — reactive localization for SignalX: namespaces, a master locale with automatic fallback, detection and SSR-safe state transfer"
---

# Internationalization

<p class="lede">Reactive localization for SignalX — namespaces, a master locale with automatic fallback, API-defined targets, locale detection, SSR-safe state transfer, and easy UI binding.</p>

<p class="mod-meta-row"> <span class="mmr-dot" /> ESM-only <span class="mmr-dot" /> MIT</p>

Translations are signals. Switch the locale and every component that read a message re-renders — no context plumbing, no re-mounting a provider tree, no manual subscription.

```tsx
import { createI18n, useTranslation } from '@sigx/i18n';

const app = defineApp(<Root />).use(createI18n({
    fallbackLocale: 'en',
    supported: ['en', 'sv'],
    load: (target, locale, ns) => import(`./locales/${target}/${locale}/${ns}.json`),
}));

const Greeting = component(() => {
    const t = useTranslation('home');
    return () => <p>{t('greeting', { name: 'Ada' })}</p>;
});
```

## It is renderer-neutral

`@sigx/i18n` depends on `@sigx/runtime-core` and `@sigx/reactivity`, **never on the `sigx` umbrella**. That is a deliberate constraint, and it is what makes the package usable outside the browser.

`sigx` is the DOM meta-package: its entry imports `@sigx/runtime-dom`, which declares `JSX.IntrinsicElements` globally. A single import of a package that reached for the umbrella would type **every** JSX element in the consuming app against the DOM intrinsics — so a lynx app would suddenly see `Property 'bindinput' does not exist on type 'InputHTMLAttributes<HTMLInputElement>'` on components that had nothing to do with i18n.

It was a runtime problem too, not only a typing one: pulling `sigx/jsx-runtime` would build `<T>` with the DOM JSX factory instead of the host renderer's, which fails silently rather than at the typecheck.

So the package takes no dependency on `sigx` at all — it is not even an optional peer — and a packaging test asserts the core entry's source graph contains no bare `sigx` specifier. Use it from web, lynx and terminal apps alike.

### `Intl` is optional too

Renderer-neutrality is a type-level claim; this is the runtime half of it. Some JavaScript
engines a sigx app runs on do not ship `Intl` at all — lynx's PrimJS is the one you are most
likely to meet.

The default `lightweightFormatter` does not need it: interpolation, plurals and selects are
resolved without `Intl.PluralRules` or `Intl.NumberFormat`. So a lynx or terminal app gets
working translations on an engine with no `Intl` object.

What `Intl` buys, where it exists, is locale-correct number, date and currency formatting. If
you need that, supply a `formatter` that uses it — and check the engines you ship to before you
do.

## The model

**A master locale defines the key set.** `fallbackLocale` is the source of truth for which keys exist; other locales supply translations for those keys, and anything missing falls through to it.

**Namespaces split catalogs.** A namespace is a unit of loading — list the ones your first paint needs in `namespaces` and leave section-specific ones out, so they load on use.

**Locale resolution walks a chain.** BCP-47 truncation (`sv-FI` → `sv` → the fallback) plus any explicit `localeFallbacks` you declare. A message is always formatted **in the locale it was found in**, which is what plural selection depends on.

## What's here

- [Installation](/i18n/docs/installation) — install, entry points and the Vite plugin.
- [Translating](/i18n/docs/usage) — `useTranslation`, `<T>`, namespaces, plurals and rich text.
- [Locales](/i18n/docs/locales) — detection, switching, persistence and the load-error surface.
- [Runtime catalogs](/i18n/docs/runtime-catalogs) — messages that come from a CMS or a database.
- [Server & SSR](/i18n/docs/server) — request locale, state transfer and `forLocale`.
- [API reference](/i18n/docs/api) — every export.

---
url: https://sigx.dev/lynx/docs/elements/
title: Native elements
description: The built-in Lynx elements — View, Text, Image, ScrollView and friends
---

# Native elements

<p class="lede">Instead of HTML tags, a Lynx component tree is built from a small fixed set of native elements. Each one maps to a real view on iOS and Android.</p>

On the web you write `div`, `span`, `img`. On Lynx there is no DOM — your JSX is built from a closed set of intrinsic elements that the renderer knows how to turn into native views. Importing `@sigx/lynx` globally augments JSX so these tags are typed; there is deliberately no catch-all, so a misspelled tag is a type error.

This page documents the low-level intrinsic tags directly. In day-to-day code you will more often reach for the capitalized layout primitives (`View`, `Text`, `Image`, `ScrollView`) that wrap them, but everything below is what those wrappers ultimately render.

## How an element becomes a native view

Every element exists twice. On the background thread, where your component runs, the renderer builds a lightweight tree of shadow nodes — there are no native APIs there, just enough structure for signals to walk parents and siblings. Each create, insert and prop change is pushed onto a compact op queue, serialized, and shipped to the main thread, where it is replayed against the real Lynx engine.

Most elements use a dedicated native creator so the engine can set up type-specific internals: `view` becomes a native View (with overflow clipping), `text` a native Text, `image` a native Image (with hardware-accelerated decode), `scroll-view` a native ScrollView, and `list` a native recycler. Elements without a dedicated creator — `input`, `textarea`, `svg`, `filter-image` — fall through to a generic create call. You never see any of this; it is the mechanism behind the tags.

## Attributes every element shares

All elements extend a common base, so these props are valid everywhere:

- `id`, `class`, `style`, `key`, `ref`
- `flatten` — controls whether the element collapses into its parent for rendering
- Accessibility: `accessibility-label`, `accessibility-role`, `accessibility-element`
- Gesture routing: `ignore-focus` (a tap here does not blur the focused input), `block-native-event` and `block-native-event-areas` (claim a touch back from an external native scroll/pan)
- The full touch event set (see [Events](#events))

```tsx
<view id="card" class="surface" style={{ padding: 16 }}>
    <text accessibility-label="Greeting">Hello</text>
</view>
```

## view

The base layout container — the flexbox box analogous to a `div`. It carries only the common attributes and children.

```tsx
<view style={{ flexDirection: 'row', gap: 8, padding: 12 }}>
    <view style={{ flex: 1, height: 40 }} />
    <view style={{ flex: 1, height: 40 }} />
</view>
```

## text

All text must live inside a `text` element — you cannot put a bare string in a `view`. Beyond the common attributes it supports truncation and native selection.

- `number-of-lines` — truncate after N lines
- `text-overflow` — `'clip'` or `'ellipsis'`
- `text-selection` — long-press to select with the system menu (requires `flatten={false}`)
- `custom-text-selection` / `custom-context-menu` — drive selection from your own UI / suppress the system menu
- Events: `bindselectionchange`, `bindlayout` (frame, baseline and line metrics)

```tsx
<text number-of-lines={2} text-overflow="ellipsis">
    A long paragraph that will be truncated to two lines with an ellipsis.
</text>
```

```tsx
<text flatten={false} text-selection bindselectionchange={onSelect}>
    Long-press to select me.
</text>
```

## image

A native image element.

- `src` — the image URI; `placeholder` — a URI shown while loading
- `mode` — resize/scale mode: `'cover'`, `'contain'`, `'stretch'`, `'center'`, `'repeat'`, `'aspectFit'`, `'aspectFill'`
- `alt`, `lazy-load`, `auto-size` (size the element to the image content)
- Events: `bindload` / `binderror` (aliases `onLoad` / `onError`)

```tsx
<image
    src="https://example.com/avatar.png"
    placeholder="https://example.com/blur.png"
    mode="aspectFill"
    style={{ width: 64, height: 64 }}
    bindload={onLoad}
    binderror={onError}
/>
```

## filter-image

An image with a native filter (blur, brightness, etc.) applied.

- `src`, `filter` (the filter type string), `mode` (`'cover'`, `'contain'`, `'stretch'`, `'center'`)
- Events: `bindload` / `binderror`

```tsx
<filter-image src="https://example.com/photo.jpg" filter="blur" style={{ width: 200, height: 120 }} />
```

## scroll-view

A plain scrolling container. It is not a recycler — every child is laid out, so use it for a bounded amount of content. For long, dynamic lists use [`list`](#list) instead.

- Direction: `scroll-orientation` (`'vertical'` | `'horizontal'`), or the legacy `scroll-x` / `scroll-y`
- `enable-scroll` — toggle scroll responsiveness at runtime (e.g. lock scrolling while a child gesture holds the touch)
- `scroll-left`, `scroll-top` — programmatic offset
- `upper-threshold` / `lower-threshold` — gate the edge events
- `bounces` (iOS), `show-scrollbar`, `paging-enabled`
- Events: `bindscroll`, `bindscrolltoupper`, `bindscrolltolower`

```tsx
<scroll-view
    scroll-orientation="vertical"
    lower-threshold={80}
    bindscrolltolower={loadMore}
    style={{ height: 400 }}
>
    <view style={{ height: 200 }} />
    <view style={{ height: 200 }} />
    <view style={{ height: 200 }} />
</scroll-view>
```

UI methods such as `scrollBy`, `scrollTo` and `autoScroll` are reachable through a main-thread ref handle — see [Main-thread refs](#main-thread-refs).

## list

A managed native recycler. It is fundamentally different from `scroll-view`: the engine recycles and reuses cell views as they scroll, so it stays efficient over thousands of items.

Two rules matter:

1. A `list` only accepts `list-item` children. Conditional and text anchors inside a `list` are skipped to avoid a native crash, so do not put bare text or fragments directly inside it.
2. Each `list-item` needs a stable `item-key`.

List props:

- `scroll-orientation` (`'vertical'` | `'horizontal'`)
- `span-count` — number of grid columns
- `list-type` — `'single'`, `'flow'` or `'waterfall'`
- `item-snap` — `'start'`, `'center'`, `'end'` or `'none'`
- `sticky-top` / `sticky-bottom`
- Events: `bindscroll`, `bindscrolltoupper`, `bindscrolltolower`

```tsx
<list scroll-orientation="vertical" span-count={2} list-type="flow" style={{ flex: 1 }}>
    <list-item item-key="a" item-type="row">
        <text>First</text>
    </list-item>
    <list-item item-key="b" item-type="row">
        <text>Second</text>
    </list-item>
</list>
```

### list-item

The only valid direct child of `list` — one recycler cell.

- `item-key` — the unique stable key the recycler diffs and reuses on; must be unique among siblings in the same `list`
- `item-type` — views with the same type share a recycling pool
- `full-span` — span all grid columns
- `sticky-top` / `sticky-bottom`

One sigx-specific note: unlike some React renderers that render cells on demand, the sigx renderer eagerly builds every `list-item` subtree up front, and the recycler pulls the already-built cell when it scrolls into view.

## input

A single-line native text field. It supports sigx two-way binding through `model`.

- `value`, `placeholder`
- `type` — `'text'`, `'number'`, `'password'`, `'digit'`, `'idcard'`
- `maxlength`, `disabled`, `focus` (auto-focus)
- `confirm-type` — the keyboard return key: `'send'`, `'search'`, `'next'`, `'go'`, `'done'`
- `model` — two-way binding; emits `onUpdate:modelValue`
- Events: `bindinput`, `bindblur`, `bindfocus`, `bindconfirm`

```tsx
<input
    model={() => state.name}
    placeholder="Your name"
    confirm-type="done"
    bindconfirm={submit}
/>
```

There is one important behavior to know: the native field treats `value` as initial-only once the user has typed into it. The renderer handles programmatic writes after mount for you (it issues a native set-value call), and it deliberately skips both the initial mount and the echo of the user's own typing so the cursor and IME composition are never disturbed. In practice: prefer `model` and let it manage the value.

## textarea

A multi-line native text field. Same `model` two-way binding and the same value-echo handling as `input`.

- `value`, `placeholder`, `maxlength`, `disabled`, `focus`
- `auto-height` — grow the height to fit the content
- Events: `bindinput`, `bindblur`, `bindfocus`

There is no `confirm-type` or `bindconfirm` — a multi-line field has no single confirm action.

```tsx
<textarea model={() => state.notes} auto-height placeholder="Notes…" style={{ minHeight: 80 }} />
```

## svg

A native SVG element. It does not accept JSX children — pass the markup as a string via `content`, or a URL via `src`.

- `content` — inline SVG XML (the engine parses it)
- `src` — a URL to an SVG
- `width`, `height`, `viewBox` (sizing via `style` is preferred; `viewBox` only matters when `content` is omitted)

```tsx
<svg
    content='<svg viewBox="0 0 24 24"><path d="…" fill="currentColor"/></svg>'
    style={{ width: 24, height: 24 }}
/>
```

## page

The page root. The real root view is created once for you; if you wrap your own content in a second `page`, it is treated as a transparent `view` (a second native page would throw on some hosts). You almost never write `page` yourself — use `view` for your layout root.

## Events

Event handlers attach with one of two prefixes:

- `bind*` — bubbling, non-capturing (e.g. `bindtap`)
- `catch*` — stops propagation (e.g. `catchtap`)

For convenience there are also `onX` aliases that map to the bubbling `bind` form: `onTap` is the same as `bindtap`. The common touch events available on every element are `tap`, `longpress`, `touchstart`, `touchmove`, `touchend`, `touchcancel` and `layoutchange`.

```tsx
<view bindtap={() => state.open = true}>
    <text>Open</text>
</view>

<view catchtap={onInner}>
    {/* a tap here will not reach an outer bindtap */}
    <text>Stop here</text>
</view>
```

Every handler has the signature `(event) => void`.

### Main-thread events

Plain `bind*` handlers run on the background thread, which means a touch round-trips across the thread boundary before your handler fires. For latency-sensitive interactions you can run a handler directly on the main thread with the `main-thread-bind*` / `main-thread-catch*` prefixes — these dispatch with zero thread crossing.

```tsx
<view main-thread-bindtap={onTapMT}>
    <text>Instant</text>
</view>
```

## Main-thread refs

`scroll-view` (and any element) can expose a synchronous handle to its native element on the main thread via `main-thread:ref`. From a main-thread handler you can read and write styles directly, run an animation, or call a native UI method with `invoke`.

```tsx
const ref = useMainThreadRef(null);

// later, inside a main-thread handler:
ref.current?.invoke('scrollTo', { offset: 0, smooth: true });
```

The handle calls the Lynx engine directly with no cross-thread round-trip. The set of `invoke` methods is defined by the native engine per element — for example `scrollBy` / `scrollTo` / `autoScroll` on `scroll-view`.

## A note on hybrid apps

If a single codebase imports both the web (`@sigx/runtime-dom`) and Lynx runtime types, the two `input` definitions collide and TypeScript reports a merge error. Pick one platform per app, or alias the imports. The Lynx element types ship inside the runtime package — there is no separate types package — and activate the moment you import `@sigx/lynx`.

## Next steps

- Learn the [styling model](/lynx/docs/styling) — how `style` numbers, flex shorthand and `class` map to native
- Review [reactivity](/lynx/docs/reactivity) — how signal changes patch exactly the views that read them
- Browse the [module catalog](/lynx/modules) for higher-level components

---
url: https://sigx.dev/lynx/docs/overview/
title: Overview
description: SignalX Lynx — write one component tree, render real native views on iOS and Android
---

# SignalX on Lynx

<p class="lede">Write one SignalX component tree, render it to real native views on iOS and Android — no webview, no diffing, the same signals you already use on the web.</p>

`@sigx/lynx` brings the SignalX component model to [Lynx](https://lynxjs.org), ByteDance's cross-platform native rendering engine. Your components run on a background thread; fine-grained signal updates stream to the main thread as a compact op queue, so only the native views that read a changed signal update.

## Why Lynx

- **Real native views** — components render to UIView / Android View, not DOM in a webview.
- **Fine-grained updates** — no virtual-DOM diff; a changed signal patches exactly the views that read it.
- **One toolchain** — the same CLI, Vite-style DX and devtools as SignalX on the web.
- **A module family** — 32 lockstep-versioned `@sigx/lynx-*` packages: navigation, gestures, motion, a DaisyUI component library and every native API you need.

## The package family

`@sigx/lynx` is a collection: the framework barrel plus sub-packages that each ship their own docs. Browse the [module catalog](/lynx/modules) or jump straight to a favorite — [Navigation](/lynx/modules/navigation/overview), [DaisyUI](/lynx/modules/daisyui/overview), [Gestures](/lynx/modules/gestures/overview), [Motion](/lynx/modules/motion/overview).

## Next steps

Head to [Installation](/lynx/docs/installation), then build [your first app](/lynx/docs/your-first-app).

---
url: https://sigx.dev/mermaid/docs/usage/
title: Usage
description: The <Mermaid> component, global configuration, theming and colour-scheme detection
---

# Usage

<p class="lede">Place a diagram with <code>&lt;Mermaid&gt;</code>, configure the palette once, and let it follow the page's theme.</p>

## The component

```tsx
import { Mermaid } from '@sigx/mermaid';

<Mermaid code="graph TD; A-->B;" title="Flow" />
<Mermaid code={source} eager />
```

| Prop | Type | Description |
| --- | --- | --- |
| `code` | `string` | **Required.** The diagram definition. |
| `title` | `string` | Rendered as a `<figcaption>` and used as the SVG's accessible name. |
| `options` | `MermaidOptions` | Per-instance overrides, merged over the global config. |
| `eager` | `boolean` | Render on mount instead of on scroll-into-view. Default `false`. |

Anything else lands on the `<figure>` — `id`, `class`, `style`, `data-*`, `aria-*`, DOM event handlers. `class` is **composed** with the component's own rather than replacing it:

```tsx
<Mermaid code={source} id="architecture" class="my-diagram" />
// → <figure class="sigx-mermaid my-diagram" id="architecture" …>
```

`title` is the exception: it is this component's caption, so it is *not* forwarded as the HTML tooltip attribute.

**The source is emitted as a `<pre>` and only hidden once the SVG lands.** So a diagram that has not rendered — no JavaScript yet, or a syntax error — still shows its definition instead of a blank frame.

## Configuration

Set global options once, wherever your app starts up:

```ts
import { configureMermaid } from '@sigx/mermaid';

configureMermaid({
    themes: { light: 'neutral', dark: 'dark' },
    config: { flowchart: { curve: 'basis' } },
});
```

Calls **merge**, so several modules can each contribute a slice, and any component can override with `options`.

| Option | Default | Description |
| --- | --- | --- |
| `themes` | `{ light: 'default', dark: 'dark' }` | Appearance per colour scheme. |
| `securityLevel` | `'strict'` | Passed to mermaid. Raising it lets diagrams emit raw HTML and click handlers. |
| `config` | `{}` | Merged into `mermaid.initialize()`. `themeVariables` merges rather than replaces. |
| `resolveColorScheme` | — | Override colour-scheme detection entirely. |

## Matching your palette

Each scheme takes a mermaid theme name or `{ theme, variables }`:

```ts
configureMermaid({
    themes: {
        light: { theme: 'base', variables: { primaryColor: '#f6f8fa', lineColor: '#d1d9e0' } },
        dark: { theme: 'base', variables: { primaryColor: '#161b22', lineColor: '#3d444d' } },
    },
});
```

Pair `variables` with **`theme: 'base'`** — `base` is the theme mermaid intends to be recoloured; the others largely ignore overrides.

`variables` may be a **function**, evaluated at render time rather than at config time. That is how diagrams track a daisyUI or Tailwind theme swap without restating the palette:

```ts
const cssVar = (n: string) => getComputedStyle(document.documentElement).getPropertyValue(n).trim();

const fromTokens = () => ({
    background: cssVar('--b1'),
    primaryColor: cssVar('--b2'),
    primaryTextColor: cssVar('--bc'),
    lineColor: cssVar('--bc'),
});

configureMermaid({
    themes: { light: { theme: 'base', variables: fromTokens }, dark: { theme: 'base', variables: fromTokens } },
});
```

Precedence, lowest first: package defaults → global `config` → per-call `options.config` → the active scheme's `variables`. `themeVariables` merges at each step, so overriding one colour keeps the rest.

### The one variable the package sets

| Variable | Default | Why |
| --- | --- | --- |
| `edgeLabelBackground` | the page background | mermaid hardcodes a light grey in every built-in theme, **including the dark ones**, so an edge label lands as a highlighter smear across a dark diagram. |

The page background rather than `transparent`, because the chip's job is to occlude the line running under it. Set it yourself to override — `'transparent'` included. When no background is painted the canvas is white, which is what mermaid's default already assumes, so nothing is applied.

## Theme detection

In order, first match wins:

1. an explicit `resolveColorScheme`
2. `data-theme` of exactly `light` / `dark` on `<html>`
3. the **computed** `color-scheme` — how named daisyUI themes like `night` or `cupcake` resolve
4. a `.dark` class on `<html>` (the Tailwind convention)
5. the page's actual background colour

Note what is **not** on that list: `prefers-color-scheme`. A page that has not opted into dark mode renders light no matter what the OS prefers, so keying off the OS puts a dark diagram on a white page.

Reading the background answers the question actually being asked — *is this diagram about to sit on something dark?* — and it works whether the site themes itself with `data-theme`, a class, or a bare `@media (prefers-color-scheme: dark)` block that declares no `color-scheme`. A page with no background at all is canvas white, so: light.

If your page is dark in a way none of these can see, say so directly:

```ts
configureMermaid({ resolveColorScheme: () => (myStore.dark ? 'dark' : 'light') });
```

### Re-rendering

When the resolved appearance changes, already-rendered diagrams re-render; ones that have not drawn yet pick up the new theme when they do.

"Changes" means the colour scheme, the theme name, **or** the resolved `variables` — all three, because with per-scheme variables both schemes usually name `base`, and a daisyUI swap between two light themes changes neither the scheme nor the name while changing every colour.

The watcher fires on `data-theme` / `class` / `style` mutations on `<html>` and on `prefers-color-scheme`. **A theme delivered purely by swapping a stylesheet is not observable** — call `renderDiagram` again, or toggle an attribute.

## Styling

`@sigx/mermaid/styles` is cosmetic. Everything functional is done in JS with the `hidden` attribute, so a site that skips the stylesheet still behaves correctly.

Override the custom properties on `.sigx-mermaid`: `--sigx-mermaid-gap`, `--sigx-mermaid-radius`, `--sigx-mermaid-padding`, `--sigx-mermaid-bg`, `--sigx-mermaid-border`, `--sigx-mermaid-muted`, `--sigx-mermaid-error`, `--sigx-mermaid-min-height`.

## Next steps

- [SSG integration](/mermaid/docs/ssg) — `mermaid` fences in MDX.

---
url: https://sigx.dev/router/docs/guards/
title: Route Guards
description: Protect routes with guards in @sigx/router
---

# Route Guards

Route guards allow you to control access to routes, redirect users, and load data before rendering.

## Basic Guard

Add a `guard` function to a route:

```tsx
const router = createRouter({
    routes: [
        {
            path: '/admin',
            component: AdminDashboard,
            guard: () => {
                if (!isAuthenticated()) {
                    return '/login'; // Redirect to login
                }
                return true; // Allow access
            },
        },
    ],
});
```

## Guard Return Values

Guards can return different values:

```tsx
guard: () => {
    // Allow navigation
    return true;
    
    // Block navigation (stays on current page)
    return false;
    
    // Redirect to path
    return '/login';
    
    // Redirect with options
    return { path: '/login', query: { redirect: '/admin' } };
}
```

## Async Guards

Guards can be asynchronous for data fetching or validation:

```tsx
{
    path: '/profile',
    component: Profile,
    guard: async () => {
        try {
            await fetchUserProfile();
            return true;
        } catch (error) {
            return '/login';
        }
    },
}
```

## Guard with Route Context

Guards receive the target route as context:

```tsx
{
    path: '/users/:id',
    component: UserProfile,
    guard: async (to) => {
        const userId = to.params.id;
        const hasAccess = await checkUserAccess(userId);
        return hasAccess ? true : '/unauthorized';
    },
}
```

## Nested Route Guards

Guards are executed from parent to child. If a parent guard fails, child guards are not executed:

```tsx
{
    path: '/admin',
    component: AdminLayout,
    guard: () => isAdmin(), // Checked first
    children: [
        {
            path: 'settings',
            component: AdminSettings,
            guard: () => hasSuperAdminRole(), // Checked second
        },
    ],
}
```

## Global Navigation Guards

Register global guards that run on every navigation:

```tsx
router.beforeEach((to, from) => {
    // Log all navigation
    console.log(`Navigating from ${from?.path ?? '(initial)'} to ${to.path}`);
    return true;
});

router.afterEach((to, from) => {
    // Track page views
    analytics.pageView(to.path);
});
```

## Guards run on the initial navigation

The full guard pipeline — `beforeEach`, per-route `beforeEnter`, `beforeResolve`, route-record `redirect`s, and `afterEach` — runs on the **initial** route resolution too, not only on later `navigate()` calls. A direct load or refresh of a guarded URL (server or client) goes through the same guards as any in-app navigation, kicked off by `app.use(router)` (or the first `router.isReady()` call). Two things to know:

- **`from` is `null` on the initial navigation.** There is no previous route on a fresh load, so always treat `from` as nullable in guards and `afterEach` hooks:

  ```tsx
  router.beforeEach((to, from) => {
      if (from === null) {
          // first resolution — direct load or refresh
      }
      return true;
  });
  ```

- **A guard returning `false` on the initial navigation keeps the matched route.** There is no previous route to stay on, so a bare `false` leaves the protected component showing. To actually protect content on a direct load, **redirect** (return a path or location) instead of returning `false`:

  ```tsx
  router.beforeEach((to, from) => {
      if (to.meta.requiresAuth && !isAuthenticated()) {
          return '/login';   // redirect — works on initial load and later navigations
      }
      return true;
  });
  ```

A redirect on the initial load lands with **replace** semantics (Back can't return to the guarded URL) and records the original location on `to.redirectedFrom` — which is what makes real server-side 30x redirects possible (see [SSR Routing](/router/docs/ssr#redirects-during-ssr)).

`router.isReady()` resolves once that initial navigation — guards included — has completed:

```tsx
const app = defineApp(<App />).use(router);
await router.isReady();   // initial route resolved, guards have run
```

## Guards run in the app's DI context

When the router is installed into an app (`defineApp(...).use(router)`), guards and `afterEach` hooks are invoked inside that app's DI context. A `defineFactory` / `defineInjectable` use-function called from a guard resolves the **same app-scoped instance your components receive** — so an auth guard that reads an injected auth store sees the same state the rest of the app sees:

```tsx
router.beforeEach((to) => {
    const auth = useAuthStore();        // resolves the app's instance, same as components
    return auth.isLoggedIn || to.path === '/login' ? true : '/login';
});
```

> **Async-guard caveat.** The app context covers only the **synchronous** portion of each guard — it does not survive an `await`. Resolve your injected dependencies at the **top** of the guard, before the first `await`:
>
> ```tsx
> router.beforeEach(async (to) => {
>     const auth = useAuthStore();      // ✓ resolve before awaiting
>     await auth.refresh();
>     // useOtherStore() here would resolve the realm fallback, not the app instance
>     return auth.isLoggedIn ? true : '/login';
> });
> ```
>
> When the router runs standalone (no app), guards are invoked directly, as they always are.

---
url: https://sigx.dev/router/docs/routes/
title: Defining Routes
description: Learn how to define routes in @sigx/router
---

# Defining Routes

Routes are defined as an array of route configuration objects when creating the router.

## Basic Route Configuration

Each route requires a `path` and `component`:

```tsx
import { createRouter } from '@sigx/router';

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

## Dynamic Parameters

Use `:param` syntax for dynamic segments:

```tsx
const router = createRouter({
    routes: [
        { path: '/users/:id', component: UserProfile },
        { path: '/posts/:category/:slug', component: BlogPost },
    ],
});
```

Access parameters in your component:

```tsx
import { component } from 'sigx';
import { useRoute } from '@sigx/router';

const UserProfile = component(() => {
    const route = useRoute();
    
    return () => (
        <div>
            <h1>User ID: {route.params.id}</h1>
        </div>
    );
});
```

## Nested Routes

Define child routes with the `children` property:

```tsx
const router = createRouter({
    routes: [
        {
            path: '/admin',
            component: AdminLayout,
            children: [
                { path: '', component: AdminDashboard }, // /admin
                { path: 'users', component: AdminUsers }, // /admin/users
                { path: 'settings', component: AdminSettings }, // /admin/settings
            ],
        },
    ],
});
```

Use nested `RouterView` in the parent layout:

```tsx
const AdminLayout = component(() => {
    return () => (
        <div class="admin-layout">
            <AdminSidebar />
            <main>
                <RouterView /> {/* Renders child routes */}
            </main>
        </div>
    );
});
```

## Lazy Loading

Lazy load routes for better performance:

```tsx
const router = createRouter({
    routes: [
        { 
            path: '/dashboard', 
            component: () => import('./pages/Dashboard'),
        },
    ],
});
```

## Catch-All Routes

Use `*` for catch-all/404 routes:

```tsx
const router = createRouter({
    routes: [
        { path: '/', component: Home },
        { path: '*', component: NotFound }, // Matches everything else
    ],
});
```

---
url: https://sigx.dev/use/docs/use-title/
title: useTitle
description: A two-way binding to document.title — a signal you write to set the tab title, for post-load dynamic titles
---

# useTitle

A two-way binding to `document.title`: write `.value` (or change a passed reactive source) and the tab title follows. Browser composable — import from `@sigx/use-web`.

```ts
import { signal } from 'sigx';
import { useTitle } from '@sigx/use-web';

const unread = signal(3);
const title = useTitle();
title.value = `(${unread.value}) Inbox`;   // sets document.title

// Or bind a reactive source directly:
const page = signal('Home');
useTitle(() => `${page.value} · sigx`);      // updates as page changes
```

## Signature

```ts
function useTitle(
    newTitle?: MaybeSignal<string | null | undefined>,
    options?: UseTitleOptions,
): PrimitiveSignal<string | null | undefined>;
```

Returns the backing `PrimitiveSignal`. Pass an initial title (plain string, signal, or getter) as the first argument, or omit it and write `.value` later.

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `observe` | `boolean` | `false` | Mirror external `document.title` changes back into the signal (via `MutationObserver`). |
| `restoreOnUnmount` | `false \| ((original, current) => string)` | `false` | Restore the title on scope disposal. |
| `document` | `Document` | `defaultDocument` | Override the document ([`ConfigurableDocument`](/use/docs/conventions#ssr-safety-and-configurable-overrides)). |

> `restoreOnUnmount` is **not a boolean**. Pass a function that computes the value to restore — `(original) => original` puts the title back the way it was — or leave it `false` to keep whatever title is current when the scope disposes.

## `useTitle` vs core's `useHead`

They own different moments:

- [`useHead`](/server/packages/server-renderer/rendering) is the **SSR-rendered, dedupe-aware** path — it owns first paint, so the correct title ships in the server HTML.
- `useTitle` is the **imperative, client-side** signal for **post-load dynamic** titles — unread counters, "Saving…", the active document name.

Reach for `useHead` for the title a page loads with; reach for `useTitle` to mutate it while the app runs.

## SSR

The signal works on the server, but the **DOM is untouched** — no `document.title` write happens until the client. Use `useHead` for the title that must be present in the server-rendered markup.

## See also

- [`useHead`](/server/packages/server-renderer/rendering) — the SSR-owning head/title path for first paint.
- [`useClipboard`](/use/docs/use-clipboard) — the other document-surface composable.
- [Conventions](/use/docs/conventions) — the shared input/output patterns.

---
url: https://sigx.dev/vite/docs/commands/
title: Commands
description: The sigx-types CLI — generate component type definitions for tag-named components
---

# Commands

`@sigx/vite` ships a `sigx-types` CLI that generates TypeScript definitions for
components declared with a tag name, so JSX gets intellisense for those tags. It's
exposed through the package's `bin` field, so `npx sigx-types` runs it from any
project that has `@sigx/vite` installed — no global install needed.

## sigx-types

Scans the project (the current working directory) for components declared with a
tag name — `component('my-button', ...)`, including the typed form
`component<...>('my-button', ...)` and `export default component('my-button', ...)`
— and writes two files into the output directory:

- `components.d.ts` — augments `@sigx/runtime-core`'s `CustomElementRegistry` so
  JSX gets intellisense for tag names like `<my-button>`.
- `components.ts` — nested global runtime objects (for example, `ui.button.primary`
  from the tag `ui-button-primary`).

Add the output directory to your tsconfig `include` so the editor picks it up.

### Usage

```bash
npx sigx-types [options]
```

### Flags

| Flag | Alias | Description |
|---|---|---|
| `--help` | `-h` | Show the help message and exit. |
| `--watch` | `-w` | Re-generate on file changes instead of running once. |
| `--out <dir>` | `-o` | Output directory. Default: `node_modules/.sigx`. |
| `--include <globs>` | — | Comma-separated globs to scan. Default: `**/*.tsx,**/*.ts,**/*.jsx`. |
| `--exclude <globs>` | — | Comma-separated globs to skip. Default: `node_modules/**,dist/**,**/*.d.ts`. |

### Examples

Generate once into the default output directory:

```bash
npx sigx-types
```

Watch for changes:

```bash
npx sigx-types --watch
```

Use a custom output directory:

```bash
npx sigx-types --out .sigx-types
```

Restrict the scan to specific globs:

```bash
npx sigx-types --include "src/**/*.tsx,components/**/*.tsx"
```

### Wiring the Output into TypeScript

After generating, add the output to your tsconfig `include` so the editor uses
the generated definitions:

```json
// tsconfig.json
{
    "include": ["src", "node_modules/.sigx/**/*.d.ts"]
}
```

## Go-to-definition into source

Every `@sigx/*` package ships its TypeScript `src/` alongside the compiled
`dist/`, and the `.d.ts` files carry declaration maps (`.d.ts.map`) — so "Go to
Definition" in your editor lands in the real source, not a `.d.ts` stub. No configuration is
needed; it works as soon as the package is installed.

## Next Steps

- [Installation](/vite/docs/installation) — peer deps and TypeScript wiring
- [API Reference](/vite/docs/api) — every export and option

---
url: https://sigx.dev/use/docs/use-mouse/
title: useMouse
description: Reactive pointer position as one { x, y, sourceType } object — per-key tracked, passive listeners, detaches with the owning scope
---

# useMouse

Reactive pointer position as **one** `{ x, y, sourceType }` object. Browser composable — import from `@sigx/use-web`.

It returns a [`ReactiveView`](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — read `mouse.x` / `mouse.y` by property access, each tracked per key, so an `x`-only consumer doesn't re-run on `y` changes. Listeners are **passive** and detach with the owning scope.

```tsx
import { component, render } from 'sigx';
import { useMouse } from '@sigx/use-web';

const Pointer = component(() => {
    const mouse = useMouse();
    return () => (
        <p class="font-mono text-sm">
            x: {mouse.x} · y: {mouse.y} · {mouse.sourceType ?? 'none'}
        </p>
    );
});

render(<Pointer />, "#app");
```

By default it tracks both mouse and touch moves on `window`, in **page** coordinates. Switch coordinate systems with `type`, bind to a specific element with `target`, or seed the pre-move value with `initialValue`.

To pull the fields out without snapshotting them, use core's [`toSignals()`](/core/docs/signals):

```ts
import { toSignals } from 'sigx';
const { x, y } = toSignals(useMouse()); // each a live signal
```

> Every caller that mounts `useMouse` adds its own `mousemove` listener. To share **one** listener app-wide, wrap it: `createSharedComposable(useMouse)`.

## Signature

```ts
function useMouse(options?: UseMouseOptions): ReactiveView<MouseState>;

interface MouseState {
    x: number;
    y: number;
    sourceType: 'mouse' | 'touch' | null;
}
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `type` | `'page' \| 'client' \| 'screen'` | `'page'` | Coordinate system: page, client (viewport), or screen. |
| `touch` | `boolean` | `true` | Also track touch moves. |
| `target` | `MaybeSignal<EventTarget \| null \| undefined>` | `window` | Listen on a specific target instead of `window`. |
| `initialValue` | `{ x: number; y: number }` | — | Position before the first move. |
| `window` | `Window` | `defaultWindow` | Override the window (SSR/testing). |

## SSR

Frozen at `initialValue`, with `sourceType: null` — no listeners are attached until mount.

## See also

- [`useScroll`](/use/docs/use-scroll) — reactive scroll position, another passive-listener sensor.
- [`createSharedComposable`](/use/docs/create-shared-composable) — share one listener across many components.
- [Conventions → Multiple fields](/use/docs/conventions#outputs-multiple-fields--one-reactiveviewt) — the `ReactiveView` return and `toSignals()`.

---
url: https://sigx.dev/actors/docs/tasks/
title: Tasks
description: "The tasks: factory — long-running work that runs outside the turn sequence, ctx.turn() for safe state writes, and built-in crash resume"
---

# Tasks

<p class="lede">A method call occupies the actor until it settles — fine for milliseconds, wrong
for a sync job or an AI workflow run. A task runs detached, so ordinary reads, streams and
watches keep answering while it works.</p>

```ts
const Sync = defineActor({
    type: 'Sync',
    allowAnonymous: true,
    state: () => ({ done: 0, total: 0, phase: 'idle' as string }),
    methods: (ctx) => ({
        begin: (total: number) => ctx.tasks.start('run', total),
        status: () => ctx.snapshot(),
        stop: () => ctx.tasks.cancel('run'),
    }),
    tasks: (ctx) => ({
        async run(total: number) {
            await ctx.turn((c) => { c.state.phase = 'running'; c.state.total = total; });
            for (let i = 0; i < total; i++) {
                ctx.abortSignal.throwIfAborted();
                await syncOne(i, { signal: ctx.abortSignal });
                await ctx.turn((c) => { c.state.done = i + 1; });
            }
            await ctx.turn(async (c) => { c.state.phase = 'done'; await c.save(); });
        },
    }),
});
```

## The rules

**State only through `ctx.turn(fn)`.** A task body is detached, so it gets no `state` or
`save()`. `turn()` enqueues `fn` as one ordinary serialized turn with the full
context, so every mutation stays race-free and everything downstream — change feeds, watches,
write-behind — works unmodified. Reads in the body use `ctx.snapshot()` or `ctx.changes()`.

**`ctx.abortSignal` in a task is the *run's* signal.** It fires on `ctx.tasks.cancel(name)`
with reason `'cancelled'`, and on deactivation for any reason with the `DeactivationReason` —
*before* in-flight turns drain. Deactivation then gives signalled tasks a bounded grace
(`taskGraceMs`, default 10s) with the actor still accepting turns, so a winding-down task can
run one final `turn()` checkpoint.

**`cancel` is a request, not a join.** It aborts and returns; the run leaves
`ctx.tasks.list()` when its body settles. Awaiting settlement from a method turn would
deadlock against the task's own wind-down `turn()`.

**A running task keeps the actor alive** — the idle sweeper skips it, like an open stream.

**`start` is single-flight per name** and resolves when the body is *launched*, not finished.
A task that throws is terminal: no automatic retry, because that policy belongs to the layer
above.

**No wire surface.** Start, cancel and status go through your own methods, so your
[policy](/actors/docs/guards) governs them like any other call.

## Crash resume is built in

`start()` resolves only after the run is durably recorded — a ledger entry in the reserved
`$sigx:tasks` storage record, plus a liveness reminder armed under the same name.

- A run **interrupted by deactivation** (any reason but cancel) keeps its entry. The next
  activation restarts it with `TaskInfo.restarts` bumped and the original `input` replayed
  through the state codec. Completion, a throw and `cancel` all remove the entry — a thrown
  task is terminal, because a crash is not a throw. An empty ledger disarms the reminder.
- **The reminder is the crash driver.** When a host dies, its reminder shards are re-owned by
  surviving hosts, the next tick delivers through placement, and the actor — tasks and all —
  re-activates wherever the cluster puts it, within roughly 60–90 seconds. No client call
  needed.
- **The contract is at-least-once.** The runtime resumes the *function*; your code resumes the
  *work* from its own checkpointed state — the `ctx.turn()` + `save()` pattern above, reading
  how far the last checkpoint got. A run that completes in the same instant its host stops may
  restart once more, so make the last step idempotent or gate it on state.

> **On Cloudflare Durable Objects this degrades gracefully.** The ledger lives in the DO's own
> storage and the liveness reminder maps onto its alarm, but a fiber does not survive
> eviction — so a task there is checkpoint-and-resume with short gaps rather than one
> continuous run. Same at-least-once contract; checkpoint aggressively.

## Tasks or jobs?

Tasks are the primitive. [`defineJob`](/actors/docs/jobs) is the packaged experience on top —
a state machine, progress, checkpoints, attempts and a client surface already decided.

Reach for a task when the work is an internal detail of an actor that has other
responsibilities. Reach for a job when the run *is* the thing, and something outside needs to
ask how it is going.

## Next steps

- [Jobs](/actors/docs/jobs) — the packaged layer.
- [Timers & reminders](/actors/docs/timers-and-reminders) — the crash driver.
- [Lifecycle](/actors/docs/lifecycle) — keep-alive and the grace window.

---
url: https://sigx.dev/actors/docs/turns/
title: Turns & concurrency
description: What a turn is, the two lanes an activation runs them in, and why an await blocks the serial one — the single idea the rest of the actor model rests on
---

# Turns & concurrency

<p class="lede">Actor state is race-free because of one mechanism, and it is worth understanding
before anything else here: an activation runs its work in <strong>turns</strong>, and by default
only one turn runs at a time.</p>

## What a turn is

A **turn** is one execution of one method against one activation. It begins when the runtime
dispatches the call and ends when the method's promise **settles** — not when the method stops
running.

That distinction is the whole thing:

```ts
async checkout() {
    const quote = await fetch('https://slow.example/quote');  // the turn is still open
    ctx.state.total = await quote.json();
    await ctx.save();
}                                                            // now the turn ends
```

Between two `await`s nothing else touches this actor's state. That is why
`ctx.state.items.push(item)` is safe with no lock, no transaction and no compare-and-set loop.

## Turns chain, they do not queue

Each new turn attaches to the tail of a promise chain with `.then()`. Nothing is stored between
them, so the ordering you get is the ordering of arrival and nothing else.

That has a practical consequence worth knowing before you go looking: the `queued` number in
[`host.activations()`](/actors/docs/lifecycle) and the
[ops endpoint](/actors/docs/ops-endpoint) is a **counter**, not the length of a structure you
can inspect. There is no priority lane to configure, no bounded-queue policy to tune, and no
way to drop or reorder pending work.

If your design needs any of those, put them in your own code in front of the actor — a queue
you own, with the policy you want, calling the actor as its consumer.

## Two lanes

An activation runs turns in one of two ways, and which one a call takes is a property of the
actor or the method, not of the caller.

**The serial lane** is the default. Each turn waits for the previous one to settle. This is
what makes plain mutation safe.

**The interleaved lane** does not wait and is not waited for. A call takes it when the actor
declares [`reentrant: 'always'`](/actors/docs/reentrancy), or when the method is named in
`methodReentrancy`.

```mermaid
sequenceDiagram
    participant A as Caller A
    participant B as Caller B
    participant R as Reader
    participant C as Cart/user-42
    A->>C: checkout
    activate C
    Note over C: serial turn 1
    B->>C: addItem
    Note right of B: waits for turn 1
    R->>C: stats
    Note right of R: interleaved, runs now
    C-->>R: result
    C-->>A: done
    deactivate C
    activate C
    Note over C: serial turn 2
    C-->>B: done
    deactivate C
```

The consequence is the trade you are making when you reach for the interleaved lane: a turn
there can observe state changing across every `await`, so it must re-read rather than cache
anything another turn may have moved.

## Why `await` blocks the serial lane

Because a turn ends when the promise settles, an awaited call inside a method keeps the serial
lane occupied for its whole duration:

```ts
async checkout() {
    await fetch('https://slow.example/quote');   // every queued turn for THIS actor waits
}
```

Nothing else is affected — other actors are other activations — but this one is blocked. Dev
builds warn when a turn exceeds `slowTurnMs` (default 5s), and a persistently non-zero `queued`
count is the same symptom seen from outside.

This is a deliberate trade: **state safety over concurrency within one actor.** The runtime
could have released the lane at each `await` and given you neither.

When it hurts, the three ways out, in order of preference:

1. **Move the I/O out of the turn** — do the slow call in the caller and pass the result in.
2. **Move it to a [task](/actors/docs/tasks)**, which runs outside the turn sequence entirely
   and re-enters through `ctx.turn()` only to touch state.
3. **Let that one method interleave** with
   [`methodReentrancy`](/actors/docs/reentrancy) — the usual fit for a read that must not queue
   behind slow writes.

## What runs outside the turn sequence

Not everything an actor does is a turn, and the exceptions are deliberate:

| Runs outside | Why |
|---|---|
| [Authorization](/actors/docs/guards) | a slow auth check must not occupy the actor |
| [Stream bodies](/actors/docs/streams) | a stream awaiting its own actor's next turn would deadlock against itself |
| [Task bodies](/actors/docs/tasks) | long work must not block ordinary calls |

Each of those reads state through a snapshot rather than touching it live.

## Two schedulers, different jobs

The runtime has two things called a scheduler, and conflating them will confuse a debugging
session:

| | Decides |
|---|---|
| **Turn scheduling** | in what **order** and with what **overlap** an activation's turns run. No clock involved. |
| **`ActorScheduler`** | **when in wall-clock time** something fires — timers, reminder ticks, idle sweeps, write-behind flushes. Swappable via `CreateHostOptions.scheduler`; `manualScheduler()` makes time deterministic in tests. |

If your question is "why did these two calls overlap?", it is the first. If it is "why did this
fire late?", it is the second — see
[Timers & reminders](/actors/docs/timers-and-reminders) and the coarse-deadline note in
[Errors](/actors/docs/errors).

## Next steps

- [The actor model](/actors/docs/actor-model) — identity, activation and deactivation.
- [Reentrancy & interleaving](/actors/docs/reentrancy) — opting into the second lane.
- [Tasks](/actors/docs/tasks) — work that outlives a turn.

---
url: https://sigx.dev/core/docs/effects/
title: Effects
description: React to changes with effects in SignalX
---

# Effects

Effects let you run side effects in response to signal changes. They're essential for data fetching, DOM manipulation, and synchronization.

## Basic Effects

```tsx
import { signal, effect } from 'sigx';

const state = signal({ count: 0 });

// This runs immediately, then re-runs when count changes
effect(() => {
    console.log('Count is:', state.count);
});

state.count = 5;  // Logs: "Count is: 5"
```

## Effects in Components

```tsx
import { component, effect } from 'sigx';

type UserProfileProps = Define.Prop<'userId', number, true>;

const UserProfile = component<UserProfileProps>(({ signal, props }) => {
    const state = signal({ user: null as any });
    
    // Fetch user when userId changes
    effect(() => {
        fetch(`/api/users/${props.userId}`)
            .then(r => r.json())
            .then(data => state.user = data);
    });
    
    return () => (
        <div>
            {state.user ? (
                <h1>{state.user.name}</h1>
            ) : (
                <p>Loading...</p>
            )}
        </div>
    );
});
```

## Effect Cleanup

### In a component: disposal is automatic

`effect()`, `watch()` and non-detached `effectScope()` created **directly in a component's setup body** are tied to that component's lifetime. They stop when it unmounts — and are re-created on HMR reload — so there is no handle to hold and nothing to call in `onUnmounted`:

```tsx
const Search = component(() => {
    const query = signal('');

    // Stopped automatically when <Search /> unmounts.
    watch(() => query.value, (q) => runSearch(q));

    return () => <input onInput={(e) => (query.value = e.target.value)} />;
});
```

**Only the setup body is scoped.** A reaction created inside `onMounted`, `onCreated`, a `setTimeout`, or any async callback runs after setup has finished collecting, so it is *not* captured — dispose those yourself:

```tsx
const Feed = component(() => {
    onMounted(() => {
        const runner = effect(() => console.log(count.value));
        onUnmounted(() => runner.stop());   // ← still your job
    });

    return () => <div />;
});
```

`computed()` is lazy and holds no subscription of its own, so it never needs disposal.

### Outside a component: stop it yourself

With no component setup to attach to — module scope, a plugin's `install()`, an event handler — the returned `EffectRunner` is the only thing that can stop the effect:

```tsx
const runner = effect(() => {
    const timer = setInterval(() => {
        console.log('Tick');
    }, 1000);
});

// Later: stop the effect
runner.stop();
```

## Watch API

For more control over when callbacks fire, use `watch`:

```tsx
import { signal, watch } from 'sigx';

const state = signal({ count: 0 });

// Watch a specific value
const stop = watch(
    () => state.count,
    (newValue, oldValue, onCleanup) => {
        console.log(`Changed from ${oldValue} to ${newValue}`);
        
        // Optional cleanup
        onCleanup(() => {
            console.log('Cleaning up...');
        });
    },
    { immediate: true }  // Run immediately with current value
);

// Control the watcher
stop.pause();   // Pause watching
stop.resume();  // Resume watching
stop.stop();    // Stop completely
```

### Watch Options

```tsx
watch(source, callback, {
    immediate: true,  // Run callback immediately
    deep: true,       // Deep watch nested objects
    once: true        // Only trigger once
});
```

## Batching Updates

Use `batch` to group multiple updates:

```tsx
import { signal, batch, effect } from 'sigx';

const state = signal({ a: 1, b: 2 });

effect(() => {
    console.log('Sum:', state.a + state.b);
});

// Without batch: logs twice
state.a = 10;  // Logs
state.b = 20;  // Logs

// With batch: logs once
batch(() => {
    state.a = 100;
    state.b = 200;
});
// Logs once: "Sum: 300"
```

## Effect Scope

Group and manage multiple effects:

```tsx
import { effectScope, effect } from 'sigx';

const scope = effectScope();

scope.run(() => {
    effect(() => { /* tracked */ });
    effect(() => { /* tracked */ });
});

// Dispose all effects at once
scope.stop();
```

A scope created in a component's setup body is itself scoped to that component, so it stops on unmount along with everything inside it. Pass `effectScope(true)` to detach it — a detached scope opts out of that capture and is yours to stop.

## When to Use Effects

**Good use cases:**
- Data fetching
- DOM manipulation
- Event listeners
- Timers and intervals
- Syncing with external systems

**Avoid:**
- Computing derived values (use `computed` instead)
- Modifying other signals (can cause infinite loops)
- Modifying signals within the same effect (can cause loops)

## Next Steps

- [Computed](/core/docs/computed) - Derive values reactively
- [Lifecycle](/core/docs/lifecycle) - Component mount/unmount hooks

---
url: https://sigx.dev/core/docs/signals/
title: Signals
description: Learn how to use signals for reactive state management in SignalX
---

# Signals

Signals are the foundation of SignalX's reactivity system. They create **reactive proxies** that automatically track access and notify subscribers when values change.

## Creating Signals

SignalX signals work differently depending on the value type:

```tsx
import { signal } from 'sigx';

// Primitives are wrapped in { value: T }
const count = signal(0);        // { value: 0 }
const name = signal('World');   // { value: 'World' }

console.log(count.value);       // 0
console.log(name.value);        // "World"

// Objects become reactive proxies - access properties directly
const user = signal({ id: 1, name: 'John' });
const items = signal([1, 2, 3]);

console.log(user.name);         // "John"
console.log(items[0]);          // 1
```

## Reading and Writing

### Primitives (wrapped in `{ value }`)

Primitives (`string`, `number`, `boolean`, etc.) are wrapped in `{ value: T }`. Use `.value` to read and write:

```tsx
import { signal } from 'sigx';

const count = signal(0);
console.log(count.value);  // 0

count.value = 5;
console.log(count.value);  // 5

count.value++;
console.log(count.value);  // 6
```

### Objects (direct property access)

```tsx
import { signal } from 'sigx';

// Objects use direct property access - no .value needed!
const user = signal({ id: 1, name: 'John' });
console.log(user.name);    // "John"

user.name = 'Jane';        // Reactive update
console.log(user.name);    // "Jane"

// Arrays work the same way
const items = signal([1, 2, 3]);
items.push(4);             // Reactive
console.log(items.length); // 4

items[0] = 10;             // Reactive
console.log(items[0]);     // 10
```

## Replacing Entire Objects and Arrays

Use `$set()` to replace the entire object or array. **Note:** `$set()` is only available on object/array signals, not primitive signals (use `.value` for primitives).

### Replacing Objects

```tsx
import { signal } from 'sigx';

const user = signal({ name: 'John', age: 25 });
console.log(user.name, user.age);  // "John" 25

user.$set({ name: 'Jane', age: 30 });  // Replace entirely
console.log(user.name, user.age);  // "Jane" 30
```

### Replacing Arrays

```tsx
import { signal } from 'sigx';

const items = signal([1, 2, 3]);
console.log([...items]);  // [1, 2, 3]

items.$set([4, 5]);       // Replace entire array
console.log([...items]);  // [4, 5]
console.log(items.length); // 2 (automatically updated)
```

### Array Mutation Methods

Array methods like `push`, `pop`, `splice`, `shift`, `unshift`, `sort`, and `reverse` are automatically batched for optimal performance:

```tsx
import { signal } from 'sigx';

const items = signal([1, 2, 3]);

items.push(4, 5);          // Batched - single reactive update
console.log([...items]);   // [1, 2, 3, 4, 5]

items.splice(1, 2);        // Remove 2 items starting at index 1
console.log([...items]);   // [1, 4, 5]
```

## Signals in Components

In components, you get `signal` from the setup context:

```tsx
import { component, render } from 'sigx';

const Counter = component(({ signal }) => {
    const state = signal({ count: 0 });
    
    return () => (
        <div>
            <span>Count: {state.count}</span>
            <button onClick={() => state.count++}>+</button>
        </div>
    );
});

render(<Counter />, "#sandbox");
```

### Object State Pattern (Recommended)

Group related state in a single signal object:

```tsx
import { component, render } from 'sigx';

const MyComponent = component(({ signal }) => {
    const state = signal({
        count: 0,
        name: 'World',
        items: ['Apple', 'Banana']
    });
    
    return () => (
        <div>
            <p>Hello, {state.name}!</p>
            <p>Count: {state.count}</p>
            <button onClick={() => state.count++}>Increment</button>
            <ul>
                {state.items.map(item => <li>{item}</li>)}
            </ul>
        </div>
    );
});

render(<MyComponent />, "#sandbox");
```

## Why Signals?

Signals provide:

1. **Fine-grained updates** - Only the specific DOM node that uses the signal updates
2. **No re-renders** - The component function doesn't re-run
3. **Referential stability** - The signal reference never changes
4. **Synchronous updates** - Changes are applied immediately
5. **Deep reactivity** - Nested properties are automatically reactive

## Signal API

| API | Description |
|-----|-------------|
| `signal(primitive)` | Returns `{ value: T }` wrapper for primitives |
| `signal(object)` | Returns reactive proxy with direct property access |
| `obj.$set(newObj)` | Replace entire object/array (not available on primitives) |
| `toRaw(proxy)` | Get the raw, non-reactive object |
| `isReactive(value)` | Check if a value is a reactive proxy |
| `untrack(() => ...)` | Read values without creating subscriptions |
| `batch(() => ...)` | Batch multiple updates together |

## Collection Support

SignalX supports reactive `Map`, `Set`, `WeakMap`, and `WeakSet`:

```tsx
import { signal } from 'sigx';

const map = signal(new Map());
map.set('key', 'value');  // Reactive
console.log(map.get('key'));  // "value"

const set = signal(new Set());
set.add('item');          // Reactive
console.log(set.has('item'));  // true
```

## Destructuring Without Losing Reactivity

Destructuring a reactive object snapshots its values — `const { count } = state` leaves you with a plain number that no longer tracks. Use `toSignal` (one property) or `toSignals` (every property) to get `{ value }` views that read **and** write through to the source:

```tsx
import { signal, toSignal, toSignals } from 'sigx';

const state = signal({ count: 0, name: 'Ada' });

// A live view over a single property
const count = toSignal(state, 'count');
count.value++;
console.log(state.count);  // 1 — write went through to the source

// Views for every property — destructure freely
const { name } = toSignals(state);
name.value = 'Grace';
console.log(state.name);   // "Grace"
```

`toSignals` creates a view for every own enumerable string key (except `$set`). Both keep reads tracked and writes flowing back to the original signal.

## Next Steps

- [Computed](/core/docs/computed) - Derive values from signals
- [Effects](/core/docs/effects) - React to signal changes
- [Components](/core/docs/components) - Use signals in components

---
url: https://sigx.dev/core/api/advanced/
title: Advanced
description: SignalX advanced utilities API reference
---

# Advanced API

Factories, messaging, and other advanced utilities.

## defineFactory

Create an injectable factory with managed subscriptions, disposal, and a real instance lifetime.

```tsx
function defineFactory<T>(
    setup: (ctx: SetupFactoryContext, ...args: any[]) => T,
    lifetime: Lifetime,
    typeIdentifier?: guid
): InjectableFunction<T & { dispose: () => void }>;
// Parameterized setups return a FactoryFunction creator instead
// (overloads up to 5 parameters).
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `setup` | `(ctx, ...args) => T` | Factory setup function. Must return an object or function (primitives throw) |
| `lifetime` | `Lifetime` | `'singleton'`, `'scoped'`, or `'transient'` — see [Lifetime](#lifetime) |
| `typeIdentifier` | `guid` | Optional unique identifier |

A parameterless factory returns an `InjectableFunction` (usable like `defineInjectable` tokens); a parameterized factory returns a `FactoryFunction` creator. Both carry the provide metadata, so either can be passed to `defineProvide` / `app.defineProvide` (they satisfy `Providable<T>`).

Every instance gets a **non-enumerable, idempotent `dispose()`** attached (a `dispose` returned by the setup is delegated to). Parameterized non-transient factories honor arguments at **first creation only** — later calls resolve the existing shared instance.

### SetupFactoryContext

| Property | Type | Description |
|----------|------|-------------|
| `onDeactivated` | `(fn: () => void) => void` | Register cleanup callback |
| `subscriptions` | `SubscriptionHandler` | Subscription manager |
| `overrideDispose` | `(fn) => void` | Custom disposal logic |

### Examples

```tsx
import { defineFactory } from 'sigx';

// Singleton service — one instance per app, disposed on app.unmount()
const useApi = defineFactory((ctx) => {
    const cache = new Map();

    ctx.onDeactivated(() => {
        cache.clear();
    });

    return {
        fetch: async (url: string) => {
            if (cache.has(url)) return cache.get(url);
            const data = await fetch(url).then(r => r.json());
            cache.set(url, data);
            return data;
        },
        invalidate: (url: string) => cache.delete(url)
    };
}, 'singleton');

// Factory with parameters — new instance per call (transient)
const useRepository = defineFactory((ctx, entityName: string) => {
    return {
        getAll: () => fetch(`/api/${entityName}`),
        getById: (id: number) => fetch(`/api/${entityName}/${id}`)
    };
}, 'transient');

// Usage
const api = useApi();
const usersRepo = useRepository('users');
```

---

## Lifetime

String-literal union for factory instance lifetimes. The lifetime you pass is **enforced** — it controls how many instances exist and when each is disposed.

```tsx
type Lifetime = 'singleton' | 'scoped' | 'transient';
```

| Value | Semantics |
|-------|-----------|
| `'singleton'` | One instance per `AppContext`, created on first resolution and disposed on `app.unmount()`. Outside any app context, one instance per JS realm |
| `'scoped'` | The nearest instance provided via `defineProvide` in the component tree; falls back to the app-context instance, and outside any app/component context to the per-realm instance |
| `'transient'` | A new instance per call, disposed with the calling component (or manually via `dispose()`) |

### Examples

```tsx
import { defineFactory } from 'sigx';

// New instance every call
const useTransient = defineFactory(setup, 'transient');

// Nearest defineProvide provider, falling back to the app instance
const useScoped = defineFactory(setup, 'scoped');

// One instance per app
const useSingleton = defineFactory(setup, 'singleton');
```

---

## SubscriptionHandler

Helper class for managing cleanup subscriptions.

```tsx
class SubscriptionHandler {
    add(unsub: () => void): void;
    unsubscribe(): void;
}
```

### Examples

```tsx
const useWebSocket = defineFactory((ctx) => {
    let ws: WebSocket;

    return {
        connect: (url: string) => {
            ws = new WebSocket(url);

            // Auto-cleanup on factory disposal
            ctx.subscriptions.add(() => ws.close());

            return ws;
        }
    };
}, 'singleton');
```

---

## createTopic

Create a pub/sub topic for messaging.

```tsx
function createTopic<T>(options?: CreateTopicOptions): Topic<T>;

interface CreateTopicOptions {
    namespace?: string;
    name?: string;
    onActivate?(): void;
    onDeactivate?(): void;
}
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `options.namespace` | `string` | Tooling metadata; topics **with** a namespace register in the [inspection registry](#inspection-sigxruntime-coreinspect) |
| `options.name` | `string` | Tooling metadata |
| `options.onActivate` | `() => void` | Called when `subscriberCount` transitions 0 → 1 (refCount pattern) |
| `options.onDeactivate` | `() => void` | Called when `subscriberCount` transitions back to 0 (last unsubscribe or destroy) |

### Returns

`Topic<T>` — see the [Topic interface](#topic-interface).

Behavior contract:
- `publish` **isolates subscriber errors** — a throwing handler is logged via `console.error` and neither skips later subscribers nor propagates to the publisher. Publishing to a destroyed topic is a no-op.
- `subscribe` **throws on a destroyed topic**. Called inside a component it auto-unsubscribes on unmount.
- `onActivate` / `onDeactivate` hook errors are isolated too.
- `destroy()` is idempotent and unregisters the topic from the inspection registry.

### Examples

```tsx
import { createTopic } from 'sigx';

// Create typed topic
const userEvents = createTopic<{
    type: 'login' | 'logout';
    userId: number;
}>({
    namespace: 'auth', name: 'userEvents',   // tooling metadata
    onActivate: () => startPolling(),         // first subscriber arrived
    onDeactivate: () => stopPolling()         // last subscriber left
});

// Subscribe
const sub = userEvents.subscribe((event) => {
    console.log(`User ${event.userId} ${event.type}`);
});

// Publish (skip work when nobody is listening)
if (userEvents.hasSubscribers) {
    userEvents.publish({ type: 'login', userId: 123 });
}

// Unsubscribe
sub.unsubscribe();

// Or destroy all
userEvents.destroy();
```

---

## createTopicGroup

Create a typed group of topics keyed by an event map — mitt-level DX on the `Topic` primitive. Topics are created lazily per key on first access and are namespaced/registered like any other topic.

```tsx
function createTopicGroup<EventMap extends Record<string, any>>(options?: {
    namespace?: string;
}): {
    topics: { [K in keyof EventMap]: Topic<EventMap[K]> };
    destroy(): void;
};
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `options.namespace` | `string` | Applied to every created topic |

### Returns

`{ topics, destroy }` — `destroy()` destroys all created topics; accessing a key on a destroyed group throws.

### Examples

```tsx
import { createTopicGroup } from 'sigx';

const group = createTopicGroup<{
    loggedIn: { userId: number };
    loggedOut: void;
}>({ namespace: 'auth' });

group.topics.loggedIn.subscribe(({ userId }) => console.log(userId));
group.topics.loggedIn.publish({ userId: 123 });  // payload type-checked

group.destroy();
```

---

## toSubscriber

Create a read-only subscriber from a topic.

```tsx
function toSubscriber<T>(topic: Topic<T>): {
    subscribe: (handler: (data: T) => void) => Subscription;
};
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `topic` | `Topic<T>` | Full topic to wrap |

### Returns

Object with only `subscribe` method (no `publish` or `destroy`).

### Examples

```tsx
import { createTopic, toSubscriber } from 'sigx';

// Internal: full control
const _notifications = createTopic<{ message: string }>();

// External: read-only
export const notifications = toSubscriber(_notifications);

// Can subscribe
notifications.subscribe(({ message }) => alert(message));

// Cannot publish (type error)
notifications.publish({ message: 'Hello' }); // Error!
```

---

## Topic Interface

```tsx
interface Topic<T> {
    /** Tooling metadata (set via createTopic options). */
    readonly namespace?: string;
    readonly name?: string;
    readonly subscriberCount: number;
    readonly hasSubscribers: boolean;
    readonly disposed: boolean;
    publish(data: T): void;
    subscribe(handler: (data: T) => void): Subscription;
    destroy(): void;
}
```

---

## Subscription Interface

```tsx
interface Subscription {
    unsubscribe(): void;
}
```

---

## Inspection (@sigx/runtime-core/inspect)

A separate `@sigx/runtime-core/inspect` entry exposes the **inspection-only** topic registry for tooling (devtools, diagnostics). The DX contract: **typed application code holds `Topic<T>` references; strings are tooling metadata.** The registry is deliberately `Topic<unknown>`-typed and realm-global — do not use it as an app-level lookup mechanism; share typed topic references instead.

Only topics created with a `namespace` register; `destroy()` unregisters. Patterns use `*` wildcards matched over `${namespace}.${name}` (e.g. `'todos#1.*'`, `'*.actions.*'`).

```tsx
import { getTopic, listTopics, subscribeTopics, onTopicCreated } from '@sigx/runtime-core/inspect';

// Exact lookup by namespace and name
function getTopic(namespace: string, name: string): Topic<unknown> | undefined;

// List live registered topics, optionally filtered by a wildcard pattern
function listTopics(pattern?: string): Topic<unknown>[];

// Subscribe to every matching topic — existing AND created later;
// one Subscription tears everything down
function subscribeTopics(
    pattern: string,
    handler: (data: unknown, meta: { namespace: string; name: string }) => void
): Subscription;

// Handler for every topic that registers from now on
function onTopicCreated(handler: (topic: Topic<unknown>) => void): Subscription;
```

`subscribeTopics` and `onTopicCreated` auto-unsubscribe on component unmount when called inside a setup.

---

## guid

Generate a unique identifier.

```tsx
function guid(): string;
type guid = string;
```

### Examples

```tsx
import { guid } from 'sigx';

const id = guid();
// "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

---

## Patterns

### Event Bus

```tsx
import { createTopicGroup } from 'sigx';

// Centralized, typed event bus
export const eventBus = createTopicGroup<{
    userLogin: { userId: number };
    userLogout: void;
    notification: { message: string; type: 'info' | 'error' };
    themeChange: 'light' | 'dark';
}>({ namespace: 'app' });

// Usage
eventBus.topics.userLogin.publish({ userId: 123 });
eventBus.topics.notification.subscribe(({ message }) => toast(message));
```

### Service Layer

```tsx
import { defineFactory, createTopic, toSubscriber, signal } from 'sigx';

const useCartService = defineFactory((ctx) => {
    const state = signal({ items: [] as CartItem[] });
    const cartUpdated = createTopic<{ itemCount: number }>();

    ctx.onDeactivated(() => {
        cartUpdated.destroy();
    });

    return {
        get items() { return state.items; },
        get count() { return state.items.length; },

        onUpdate: toSubscriber(cartUpdated),

        add: (item: CartItem) => {
            state.items = [...state.items, item];
            cartUpdated.publish({ itemCount: state.items.length });
        },

        remove: (id: string) => {
            state.items = state.items.filter(i => i.id !== id);
            cartUpdated.publish({ itemCount: state.items.length });
        },

        clear: () => {
            state.items = [];
            cartUpdated.publish({ itemCount: 0 });
        }
    };
}, 'singleton');
```

### Async Operations

```tsx
const useAsyncOperation = defineFactory((ctx) => {
    const state = signal({
        loading: false,
        error: null as Error | null,
        data: null as any
    });

    const execute = async <T>(operation: () => Promise<T>): Promise<T | null> => {
        state.loading = true;
        state.error = null;

        try {
            const result = await operation();
            state.data = result;
            return result;
        } catch (err) {
            state.error = err instanceof Error ? err : new Error(String(err));
            return null;
        } finally {
            state.loading = false;
        }
    };

    return {
        get loading() { return state.loading; },
        get error() { return state.error; },
        get data() { return state.data; },
        execute
    };
}, 'transient');
```

---
url: https://sigx.dev/cli/docs/commands/
title: Commands
description: Every sigx CLI command with its usage, flags, and behavior
---

# Commands

The CLI has two core commands shipped in `@sigx/cli` (`create` and `info`) plus a set of commands contributed by plugins at runtime. Run any command through your package runner:

```bash
npx sigx <command>
```

## Core commands

### sigx create

Scaffolds a new SignalX project by copying a bundled template into `./<name>` and substituting the `{{projectName}}` placeholder.

```bash
sigx create [name] [--type <basic|ssr|ssg|lynx>] [--styling <none|tailwind|daisyui>] [--yes|-y]
```

By default it runs an interactive prompt-kit flow on `@sigx/terminal`: an intro, a **name** text prompt, then **type** and **styling** select prompts, a scaffolding spinner, and a "next steps" note. It falls back to **headless, flag-driven mode** when any of the following is true:

- standard output / input is not a TTY (for example, in CI or when piped),
- `--yes` / `-y` is passed,
- both `--type` and a positional `name` are provided.

**Flags & arguments**

| Argument | Values | Default | Description |
| --- | --- | --- | --- |
| `name` (positional) | any directory name | `my-sigx-app` | Target directory created under the current folder. |
| `--type` | `basic`, `ssr`, `ssg`, `lynx` | `basic` | Project template to copy. |
| `--styling` | `none`, `tailwind`, `daisyui` | `none` | Styling preset. `daisyui` is also offered for `lynx` (maps to `@sigx/lynx-daisyui`). |
| `--yes` / `-y` | — | — | Skip the prompts and run headlessly with defaults/flags. |

**Examples**

```bash
sigx create my-app --type basic
sigx create my-app --type ssr --styling tailwind
sigx create my-app --type ssg --styling daisyui
sigx create my-app --type lynx --styling tailwind
```

Interactive prompts:

```bash
npx sigx create
```

**Exit codes**

- `1` — target directory already exists, or the requested template was not found.
- `2` — invalid `--type` or `--styling` value.

**Notes**

- If the target directory is inside a pnpm workspace (a `pnpm-workspace.yaml` is found by walking up the tree), `@sigx/*` dependencies in the generated `package.json` are rewritten to `workspace:*`.
- Templates ship a `gitignore` file that is renamed to `.gitignore` on copy (npm strips `.gitignore` from published tarballs).
- Text files have their `{{projectName}}` placeholders substituted on copy; binary assets (PNG icons in the `lynx` template) are copied byte-for-byte.
- The terminal prompt kit (`@sigx/terminal`) is lazy-loaded, so it is only pulled in when you actually run `create` interactively.

**Templates & pinned versions**

Templates pin a **matched set** of `sigx` / `@sigx/*` versions — never `latest` — so a freshly scaffolded project's peer graph resolves with a single copy of `@sigx/reactivity` under strict peer deps. Each template pins the set it was authored against rather than the newest core line, and the `ssg` and `lynx` templates pin the matched set their plugin (`@sigx/ssg` / `@sigx/lynx-cli`) is built against. Third-party deps (`vite`, `express`, `tailwindcss`, …) keep their own caret ranges. To start from the current core, bump the scaffolded `package.json` to `sigx`  and its matching `@sigx/*` set after creating the project.

The **SSR templates** (`ssr`, `ssr-tailwind`, `ssr-daisyui`) scaffold a server built on the document render API:

- an Express 5 **`server.js`** — Vite middleware in dev (`ssrLoadModule` for `entry-server`), static client assets + the built server bundle in prod;
- an **`index.html`** with the standard `<!--ssr-outlet-->` marker;
- an **`entry-server.tsx`** `render()` that serves crawlers and AI agents a blocking [`renderDocument`](/server/packages/server-renderer) (complete inline HTML, no client work) and everyone else a streaming `renderDocumentToNodeStream` (the `shell` promise settles before the first byte, so a failed render can still become a proper 500);
- an **`entry-client.tsx`** that gates hydration on the server's completion signal (`window.__SIGX_STREAMING_COMPLETE__` / the `sigx:ready` event), emitted in both modes, so hydration always runs against finished server HTML.

`npm run dev` / `start` / `preview` run `node server.js`; `build` runs `vite build` plus a `vite build --ssr` of `entry-server`.

### sigx info

Prints environment and project diagnostics. No flags.

```bash
sigx info
```

It reports:

- platform / architecture and Node.js version,
- the pnpm or npm version,
- the project `name` and `version` from `package.json`,
- detected `@sigx/*` dependencies (and `sigx`),
- detected config files: `sigx.lynx.config.ts/js`, `lynx.config.ts/js`, `ssg.config.ts`, `vite.config.ts`.

When a Lynx config is detected it additionally probes the Lynx toolchain: rspeedy version, `ANDROID_HOME` / `ANDROID_SDK_ROOT`, JDK version, ADB version and connected devices, and on macOS Xcode and CocoaPods.

## Plugin-provided commands

The following commands are **not** part of `@sigx/cli` — they are discovered at runtime from installed plugin packages whose `detect(cwd)` returns true for your project. See [Installation](/cli/docs/installation) for which package provides each one, and [Authoring Plugins](/cli/docs/plugins) to write your own.

### sigx dev

Starts the dev server. Provided by `@sigx/vite` for web projects and `@sigx/lynx-cli` for Lynx.

```bash
sigx dev
```

### sigx build

Runs a production build. Provided by `@sigx/vite` (web) and `@sigx/lynx-cli` (Lynx).

```bash
sigx build
```

### sigx preview

Serves a built SSG site. Provided by `@sigx/ssg`.

```bash
sigx preview
```

### sigx prebuild

Generates native iOS/Android project files. Provided by `@sigx/lynx-cli`.

```bash
sigx prebuild
```

### sigx run:android

Builds and launches the app on an Android device or emulator. Provided by `@sigx/lynx-cli`.

```bash
sigx run:android
```

### sigx run:ios

Builds and launches the app on iOS. Provided by `@sigx/lynx-cli`.

```bash
sigx run:ios
```

### sigx doctor

Verifies the Lynx toolchain (rspeedy, ADB, Xcode, JDK). Provided by `@sigx/lynx-cli`.

```bash
sigx doctor
```

## Command resolution & conflicts

The CLI builds its command list by starting with the core `info` and `create` commands, then registering each discovered plugin command. On a name collision the **last plugin wins**, and a warning is logged:

```text
[sigx] WARN Plugin "X" overrides command "Y"
```

---
url: https://sigx.dev/i18n/docs/locales/
title: Locales
description: Detecting, switching and persisting the locale — plus the load-error surface
---

# Locales

<p class="lede">Pick a starting locale from the request or the device, let the user change it, and keep the choice.</p>

## Switching

```tsx
import { useLocale } from '@sigx/i18n';

const LocalePicker = component(() => {
    const { locale, locales, setLocale } = useLocale();

    return () => (
        <select value={locale.value} onChange={(e) => setLocale(e.target.value)}>
            {locales.map((l) => <option value={l}>{l}</option>)}
        </select>
    );
});
```

`setLocale` is typed to the known locales when the [Vite plugin](/i18n/docs/installation#the-vite-plugin) has generated your schema. It returns a promise that settles once the new catalogs have loaded.

`whenReady` resolves when the initial catalogs and any device hydration have settled — useful for holding a splash screen rather than flashing untranslated keys.

## Detection

`detectLocale` runs an ordered list of detectors and returns the first supported match:

```ts
import { createDetectors, detectLocale } from '@sigx/i18n';

const detectors = createDetectors(['url', 'cookie', 'settings', 'browser']);
const locale = detectLocale(detectors, { supported: ['en', 'sv'] });
```

The built-ins are `urlDetector`, `cookieDetector`, `settingsDetector` and `browserDetector`; `parseAcceptLanguage` and `parseCookie` are exported for building your own.

On the server, `resolveRequestLocale(request, options)` does the whole job from a `Request` — see [Server & SSR](/i18n/docs/server).

`Detector.detect` is **synchronous**. A native locale that can only be read asynchronously — a lynx settings module, say — goes through `initialLocale` or `await setLocale()` instead.

## Persistence

`localeCookie` and `localeSwitchUrl` build the cookie and the URL for a locale switch that survives a reload. On the client, `@sigx/i18n` hands persistence to [`@sigx/store`](/store/docs/persistence)'s `persist` rather than touching storage itself.

Two things follow from that, and both matter off the web:

- **An async backend is supported.** `StorageLike`'s `getItem` / `setItem` / `removeItem` may each return a promise, so `@sigx/lynx-storage` works as-is. Hydration is awaited and applied as one atomic patch.
- **With no Web-Storage-shaped global present, persistence silently no-ops.** The locale does not survive a restart and nothing is logged. If you need it on a non-DOM renderer, pass a backend explicitly.

`@sigx/i18n` selects **no backend of its own** — omitting `persistence.storage` defers to whatever `@sigx/store` resolves.

## When a catalog fails to load

A bundled `import()` failing is a broken build. A `fetch` failing is Tuesday. So a load failure is surfaced rather than only logged:

```tsx
const { error, retry } = useLocale();

return () => error.value
    ? <button onClick={() => retry()}>Translations unavailable — retry</button>
    : <App />;
```

`error` is reactive and holds the most recent failure (`{ error, locale, namespace }`); `retry()` re-attempts every load that failed. `onLoadError` in the config replaces the default console logging if you would rather route it to telemetry.

## Next steps

- [Runtime catalogs](/i18n/docs/runtime-catalogs) — messages from a CMS or database.
- [Server & SSR](/i18n/docs/server) — request locale and state transfer.

---
url: https://sigx.dev/devtools/docs/api/
title: API Reference
description: "@sigx/devtools — inspect signals and the reactive graph at runtime — API reference"
---

# API Reference

Everything exported from `@sigx/devtools`. Import from the single package entry:

```ts
import {
    devtools,
    createPostMessageTransport,
    createWebSocketTransport,
    PROTOCOL_VERSION,
} from '@sigx/devtools';
import type {
    DevtoolsOptions,
    WebSocketTransportOptions,
    Transport,
    PageEvent,
    PanelRequest,
    PanelRequestInput,
    PanelResponse,
    ComponentNode,
    ReactivePrimitive,
    ReactivePrimitiveKind,
    StoreActionEvent,
    StoreMutationEvent,
    StoreCustomEvent,
    RouterNavEvent,
    SerializedValue,
    AppId,
    ComponentId,
    ValueRef,
} from '@sigx/devtools';
```

## Functions

### devtools

```ts
export function devtools(options: DevtoolsOptions = {}): Plugin<void>;
```

The page-side plugin factory. Install it with `app.use(devtools())`. It returns a
SignalX `Plugin` (name `'sigx-devtools'`) whose `install()`:

- resolves a `Transport` — defaults to `createPostMessageTransport()` in the browser,
  and a no-op in SSR/Node so it never crashes;
- attaches to the shared global devtools hook from `@sigx/reactivity` via
  `ensureDevtoolsHook()`;
- bridges component lifecycle events (from runtime-core: `app:init`/`app:unmount`,
  `component:created`/`mounted`/`updated`/`unmounted`/`error`) and reactivity primitives
  (signal/computed/effect create/update/dispose) to the panel;
- wires panel request handling (`get:apps`, `get:tree`, `get:value`,
  `get:reactive-value`, `get:reactives`, `highlight`, `unhighlight`);
- discovers and observes `@sigx/store` instances through the core inspection registry
  (`@sigx/runtime-core/inspect`) unless `includeStores: false`, and attaches the router
  observer when `router` is supplied;
- emits a `hello` event with `PROTOCOL_VERSION` and the agent version (`'0.0.3'`) once
  the wire is up.

**Parameters**

- `options` — a `DevtoolsOptions` bag (all fields optional). An empty object gives the
  postMessage transport, `appName` `'sigx-app'`, reactivity on, and `throttleMs` 16.

**Returns** — a SignalX `Plugin<void>` to pass to `app.use()`.

### createPostMessageTransport

```ts
export function createPostMessageTransport(target: Window = window): Transport;
```

The default browser transport. Communicates via `window.postMessage` using the envelope
`{ __sigx: 'SIGX_DEVTOOLS', dir: 'to-panel' | 'to-page', msg }`. `send()` posts
`to-panel` envelopes to `target` (with `targetOrigin` `'*'`); it listens for `to-page`
envelopes and forwards their `msg` (a `PanelRequest`) to registered listeners. `close()`
removes the message listener and clears listeners.

Designed so a Chrome MV3 content script can ferry messages between the page world and
`chrome.runtime`; an in-page panel can listen on the same window.

**Parameters**

- `target` — the window to post to. Defaults to the global `window`.

**Returns** — a `Transport`.

### createWebSocketTransport

```ts
export function createWebSocketTransport(options: WebSocketTransportOptions = {}): Transport;
```

WebSocket page-side transport for non-browser hosts (native renderers, terminals).
Connects to a `ws://` URL (default `ws://localhost:8098/page`). Queues outgoing messages
up to `maxQueue` (default 1000, dropping the oldest on overflow) while disconnected and
flushes on (re)connect. Auto-reconnects with exponential backoff (`250ms * 2^n`) capped
at `maxBackoffMs` (default 30000). Wraps messages in the same
`{ __sigx: 'SIGX_DEVTOOLS' }` envelope. If no `WebSocket` constructor is available it
returns a no-op stub.

Pair it with `sigx-devtools-inspector` (a localhost relay) or a custom WS server.

**Parameters**

- `options` — a `WebSocketTransportOptions` bag (all fields optional).

**Returns** — a `Transport`.

## Constants

### PROTOCOL_VERSION

```ts
export const PROTOCOL_VERSION = 1;
```

The wire protocol version. Sent in the `hello` event payload. Bump when message shapes
change incompatibly.

## Configuration interfaces

### DevtoolsOptions

```ts
export interface DevtoolsOptions {
    /** Custom transport. Defaults to createPostMessageTransport() in the browser; otherwise the plugin is a no-op so SSR doesn't crash. */
    transport?: Transport;
    /** App name shown in the panel. Defaults to 'sigx-app'. */
    appName?: string;
    /** Whether to discover and observe @sigx/store instances through the core inspection registry. Default true. */
    includeStores?: boolean;
    /** Router instance to observe for navigation events. */
    router?: DevtoolsObservableRouter;
    /** Whether to subscribe to reactivity (signal/effect/computed) events at all. Default true. */
    includeReactivity?: boolean;
    /** Coalesce reactive:updated events per-id within this millisecond window. Default 16ms (~one frame). Set 0 to disable. */
    throttleMs?: number;
}
```

The options bag for `devtools()`. All fields are optional.

`includeStores` (default `true`) controls store observation: stores register their
state/action/event topics in the core inspection registry
(`@sigx/runtime-core/inspect`), so existing **and** future store instances are picked
up automatically — there is no per-store wiring (the former `stores` array is gone).
Observation activates the stores' refCount state watchers — state tracing is
pay-when-observed.

The `router` element type (`DevtoolsObservableRouter`) is a private internal interface
and is not exported, but it defines the runtime shape your value must satisfy: a
reactive `currentRoute` getter with `{ path; params?; query? }`. Any `@sigx/router`
instance already satisfies it.

### WebSocketTransportOptions

```ts
export interface WebSocketTransportOptions {
    /** Full ws:// or wss:// URL to connect to. Defaults to ws://localhost:8098/page. */
    url?: string;
    /** Max queued outgoing messages while disconnected. Oldest are dropped past this. Default 1000. */
    maxQueue?: number;
    /** Max reconnect backoff in milliseconds. Default 30 seconds. */
    maxBackoffMs?: number;
    /** Override the WebSocket constructor — useful for tests. Defaults to the global WebSocket. */
    WebSocketImpl?: typeof WebSocket;
}
```

Configuration for `createWebSocketTransport`. All fields are optional.

## Transport interface

### Transport

```ts
export interface Transport {
    /** Send a message to the panel side. */
    send(msg: OutgoingMessage): void;
    /** Subscribe to messages from the panel. Returns an unsubscribe. */
    onMessage(listener: (msg: IncomingMessage) => void): () => void;
    /** Best-effort teardown. */
    close(): void;
}
```

The transport-agnostic interface the plugin talks through. Implement it for custom
channels (for example `BroadcastChannel`). `OutgoingMessage` is `PageEvent | PanelResponse`
and `IncomingMessage` is `PanelRequest`; those two aliases are internal and not exported
from the package — only `Transport` itself is public.

## Protocol types

### PageEvent

```ts
export type PageEvent =
    | { t: 'hello';              payload: { protocol: number; agentVersion: string } }
    | { t: 'app:init';           payload: { appId: AppId; name: string } }
    | { t: 'app:unmount';        payload: { appId: AppId } }
    | { t: 'component:mounted';  payload: ComponentNode }
    | { t: 'component:updated';  payload: { id: ComponentId; propsRef: ValueRef | null } }
    | { t: 'component:unmounted'; payload: { id: ComponentId } }
    | { t: 'component:error';    payload: { id: ComponentId | null; message: string; stack?: string; info: string } }
    | { t: 'reactive:created';   payload: ReactivePrimitive }
    | { t: 'reactive:updated';   payload: { id: number; lastUpdatedAt: number; updateCount: number } }
    | { t: 'reactive:disposed';  payload: { id: number } }
    | { t: 'store:action';       payload: StoreActionEvent }
    | { t: 'store:mutation';     payload: StoreMutationEvent }
    | { t: 'store:event';        payload: StoreCustomEvent }
    | { t: 'router:nav';         payload: RouterNavEvent }
    | { t: 'value:resolved';     payload: { ref: ValueRef; value: SerializedValue } };
```

Discriminated union (on `t`) of all page-to-panel events the plugin emits. Every variant
is JSON-serializable with no DOM or runtime references on the wire.

### PanelRequest

```ts
export type PanelRequest =
    | { t: 'get:apps';            id: number }
    | { t: 'get:tree';            id: number; payload: { appId: AppId } }
    | { t: 'get:value';           id: number; payload: { ref: ValueRef } }
    | { t: 'get:reactive-value';  id: number; payload: { reactiveId: number } }
    | { t: 'get:reactives';       id: number; payload: { componentId: ComponentId } }
    | { t: 'highlight';           id: number; payload: { componentId: ComponentId } }
    | { t: 'unhighlight';         id: number; payload: {} };
```

Panel-to-page requests. Each carries a numeric `id` for response correlation. The plugin
handles: `get:apps` (list apps), `get:tree` (component nodes for an app id), `get:value`
(resolve a `ValueRef`), `get:reactive-value` (serialize a reactive's raw value via
`toRaw`), `get:reactives` (primitives owned by a component), and `highlight`/`unhighlight`
(currently respond `{ ok: true }` — no DOM highlight implementation on the page side).

### PanelRequestInput

```ts
export type PanelRequestInput =
    | { t: 'get:apps' }
    | { t: 'get:tree';            payload: { appId: AppId } }
    | { t: 'get:value';           payload: { ref: ValueRef } }
    | { t: 'get:reactive-value';  payload: { reactiveId: number } }
    | { t: 'get:reactives';       payload: { componentId: ComponentId } }
    | { t: 'highlight';           payload: { componentId: ComponentId } }
    | { t: 'unhighlight';         payload: {} };
```

`PanelRequest` minus the `id` field — what a caller passes into a connection's request
helper on the panel/inspector side; the `id` is added by the caller. It is kept as an
explicit union (not `Omit`) so discriminant narrowing on `t` survives at call sites.

### PanelResponse

```ts
export type PanelResponse =
    | { t: 'response'; id: number; payload: unknown }
    | { t: 'error';    id: number; message: string };
```

Page-to-panel reply to a `PanelRequest`, correlated by the echoed `id`. Either a
successful `response` with a payload or an `error` with a message string.

### ComponentNode

```ts
export interface ComponentNode {
    id: ComponentId;
    parentId: ComponentId | null;
    appId: AppId;
    name: string;
    /** ValueRef to the props record. Null when the component has no props. */
    propsRef: ValueRef | null;
}
```

Snapshot of a component for the tree view. Component ids share the same id space as
reactivity ids (minted via the hook), which lets the panel join a component to the
signals it owns. `name` defaults to `'(anonymous)'`.

### ReactivePrimitive

```ts
export interface ReactivePrimitive {
    id: number;
    kind: ReactivePrimitiveKind;
    /** Component id this was created under, or null for module-level primitives. */
    ownerComponentId: ComponentId | null;
    /** Most recent update wall-clock time (ms since epoch). null if never updated. */
    lastUpdatedAt: number | null;
    /** Number of updates observed since creation. For effects, the number of times the effect body has run. */
    updateCount: number;
}
```

A reactive primitive (signal/computed/effect) tracked by the plugin. Sent in
`reactive:created` and returned by `get:reactives`.

### ReactivePrimitiveKind

```ts
export type ReactivePrimitiveKind = 'signal' | 'computed' | 'effect';
```

Discriminant for the kind of reactive primitive — drives the panel's icon and grouping.

### StoreActionEvent

```ts
export interface StoreActionEvent {
    /** Monotonic id linking the three phases of a single dispatch. */
    actionId: number;
    storeName: string;
    actionName: string;
    phase: 'dispatching' | 'dispatched' | 'failed';
    /** Serialized args. Present on every phase. */
    args: SerializedValue;
    /** Serialized result. Present on `dispatched` (or undefined). */
    result?: SerializedValue;
    /** Serialized error reason. Present on `failed`. */
    error?: SerializedValue;
    /** Milliseconds from dispatching to dispatched/failed. Set on later phases. */
    durationMs?: number;
    /** Wall-clock ms since epoch when this phase fired. */
    at: number;
}
```

Wire shape for a store action dispatch, emitted in three phases (`dispatching` →
`dispatched` | `failed`) that all share one `actionId`. Produced by the store observer.

### StoreMutationEvent

```ts
export interface StoreMutationEvent {
    storeName: string;
    key: string;
    /** Serialized new value. Inline because mutations are usually small. */
    value: SerializedValue;
    at: number;
}
```

Wire shape for a store state mutation. The store publishes per-key change topics in
its `${storeId}.state` namespace (topic name = state key, payload `{ value, prev }`);
the observer forwards the key and the serialized new value inline. `storeName` carries
the store's instance id (e.g. `'todos#1'`).

### StoreCustomEvent

```ts
export interface StoreCustomEvent {
    storeName: string;
    /** Event key as declared in the store's event map. */
    event: string;
    /** Serialized event payload. */
    data: SerializedValue;
    at: number;
}
```

Wire shape for store custom events (`defineEvents` topics, published in the store's
`${storeId}.events` namespace). Additive over protocol v1 — panels that don't know
`store:event` ignore it.

### RouterNavEvent

```ts
export interface RouterNavEvent {
    fromPath: string | null;
    toPath: string;
    params: SerializedValue;
    query: SerializedValue;
    at: number;
}
```

Wire shape for a router navigation. Emitted by the router observer (which wraps
`router.currentRoute` in an effect). The initial route at mount is skipped — only
subsequent navigations fire.

### SerializedValue

```ts
export type SerializedValue =
    | { kind: 'primitive'; value: string | number | boolean | null }
    | { kind: 'undefined' }
    | { kind: 'bigint';    value: string }
    | { kind: 'symbol';    description: string }
    | { kind: 'function';  name: string }
    | { kind: 'array';     length: number; entries: Array<[number, SerializedValue]> }
    | { kind: 'object';    typeName: string; entries: Array<[string, SerializedValue]> }
    | { kind: 'circular' }
    | { kind: 'truncated'; reason: 'depth' | 'size' };
```

Wire format for any inspected value. Reactive proxies are unwrapped first; cycles become
`{ kind: 'circular' }`; functions become `{ kind: 'function', name }`; recursion is
bounded by an internal max depth of 4 (emitting `{ kind: 'truncated', reason: 'depth' }`),
and object/array entries are capped at 100 — extra entries past the cap are silently
omitted with no `truncated` marker (an array's `length` still reports its true length).
Object `typeName` uses the constructor name. Only own
enumerable string keys are included; symbol keys (framework internals) are skipped.

### AppId

```ts
export type AppId = number;
```

Stable per-app id minted by the plugin (sequential, starting at 1).

### ComponentId

```ts
export type ComponentId = number;
```

Stable component instance id. Comes from the event's `instanceId`, minted by runtime-core
via the hook — the same id space as reactivity ids.

### ValueRef

```ts
export type ValueRef = number;
```

Indirection handle for a value the panel may inspect on demand. The plugin keeps a value
reference table (object values held via `WeakRef` so unmounted components can be
garbage-collected; primitives and functions held strongly) and resolves a ref on
`get:value`. Large or reactive values are never sent inline.

## Behavior constants (not exported)

These govern the serializer's bounds. They are defined in the package but not re-exported
from the entry point — treat them as behavior, not public API.

- **Max serialization depth: 4** — recursion past this emits `{ kind: 'truncated', reason: 'depth' }`.
- **Max entries per object/array: 100** — entries past the cap are silently omitted; no marker is emitted. (The `reason: 'size'` variant is declared in the protocol type but is currently unused.)

---
url: https://sigx.dev/lynx/docs/styling/
title: Styling & layout
description: Flexbox layout and the styling model on Lynx
---

# Styling & layout

<p class="lede">Every element lays out with flexbox; styles are typed objects or stylesheet classes. SignalX's runtime smooths over Lynx's CSS quirks, and @sigx/lynx-zero / @sigx/lynx-daisyui add a token-based theming layer on top.</p>

## The mental model

On Lynx there is no DOM and no browser CSS engine. Native host elements — `view`, `text`, `image`, `scroll-view` and friends — take two styling props:

- `style` — an inline object of camelCase CSS properties.
- `class` — a string that resolves against rules in an imported stylesheet (Lynx uses `class`, not React's `className`).

Both flow to the main thread as ops over SignalX's background-to-main bridge, not as HTML attributes. The runtime normalizes what you write so that the values Lynx's CSS engine actually receives are well-formed. Understanding that normalization is most of what you need to style confidently.

## Style objects

Write properties as camelCase JS keys. Numeric values are auto-suffixed with `px` by the runtime, so you rarely write units by hand:

```tsx
import { component } from 'sigx';
// view/text are global JSX intrinsics — importing @sigx/lynx augments JSX
// so the lowercase tags are typed; there are no View/Text components to import.

export const Card = component(() => {
    return () => (
        <view style={{ flexDirection: 'row', gap: 12, padding: 16, borderRadius: 12 }}>
            <text style={{ fontSize: 16, color: '#e7e9f1' }}>Styled natively</text>
        </view>
    );
});
```

A handful of properties are dimensionless and are passed through without a unit: `flex`, `flexGrow`, `flexShrink`, `order`, `opacity`, `zIndex`, `aspectRatio`, `fontWeight` and `lineClamp`. A literal `0` is also never suffixed. Everything else numeric becomes `px`. If you need a non-px unit, pass a string — for example `width: '100%'`.

## Flexbox by default

Lynx's layout engine speaks flexbox natively. `flexDirection`, `gap`, `alignItems` and `justifyContent` behave like the web, so a column layout is just:

```tsx
<view style={{ flexDirection: 'column', gap: 8, padding: 16 }}>
    <text>First</text>
    <text>Second</text>
</view>
```

### The flex shorthand trap

Lynx's native inline-style path does NOT expand CSS shorthands. A raw `flex: 1` would reach the engine as an unknown property and silently apply no sizing. SignalX's runtime works around this on the inline path by expanding `flex: n` to its longhand form (`flexGrow` / `flexShrink` / `flexBasis`) before it crosses the bridge, so this just works:

```tsx
<view style={{ flexDirection: 'column' }}>
    <text>Header</text>
    <view style={{ flex: 1 }}>{/* fills remaining space */}</view>
    <text>Footer</text>
</view>
```

On the stylesheet / Tailwind path the runtime can't rewrite your CSS, so there you must use the `.flex-fill` utility instead of `flex-1` — see [Tailwind preset](#tailwind-preset) below.

## Stylesheets and classes

For shared rules, import a stylesheet once at your app entry and reference it by `class`. The DaisyUI package ships a complete stylesheet (a base reset, theme tokens and per-component CSS):

```tsx
// app entry, e.g. src/main.tsx
import '@sigx/lynx-daisyui/styles';
```

Then any element can use those classes. Multi-class strings are applied verbatim, space-separated:

```tsx
<view class="card">
    <text class="card-title">Hello</text>
</view>
```

The component CSS is plain CSS that references custom properties like `var(--color-primary)`, `var(--size-field)` and `var(--radius-box)` — the structural token contract described under [Theming](#theming). Note that the imported base reset zeroes the border on every Lynx host element (`view`, `text`, `image`, `scroll-view`, `input` and so on), so borders are opt-in.

You can combine `style` and `class` on the same element. Classes set the baseline; inline style overrides per instance.

## Tailwind preset

If you use Tailwind, both `@sigx/lynx-zero` and `@sigx/lynx-daisyui` ship a preset that re-points the color and font-size utilities at the active theme's custom properties and adds the Lynx-correct layout utility. Add it to your Tailwind config:

```ts
// tailwind.config.ts
import { daisyuiPreset } from '@sigx/lynx-daisyui/preset';

export default {
    presets: [daisyuiPreset],
    content: ['./src/**/*.{ts,tsx}'],
};
```

With the preset installed, semantic utilities resolve against whichever theme is active:

```tsx
<view class="bg-base-200 p-4 rounded-box">
    <text class="text-primary text-lg">Themed via Tailwind</text>
</view>
```

`bg-primary`, `text-base-content`, `text-lg` and the rest map onto `var(--color-*)` and the `var(--text-*)` ramp through the preset's `contractColors` and `contractFontSizes` maps.

If you don't use a design system, `@sigx/lynx-zero`'s `zeroPreset` is the same composition without the DaisyUI-specific layer — import it from `@sigx/lynx-zero/preset`. (`daisyuiPreset` currently just spreads `zeroPreset`.)

### Use `.flex-fill`, not `flex-1`

The preset adds a `.flex-fill` utility for "fill the remaining main-axis space." Reach for it instead of `flex-1`:

```tsx
<view class="flex-fill">{/* grows to fill its flex parent */}</view>
```

`flex-1` expands to the `flex: 1 1 auto` shorthand, which on Lynx sizes the box to its content and collapses the layout chain. `.flex-fill` sets the correct longhands (`flexGrow: 1`, `flexShrink: 1`, `flexBasis: 0`, `minHeight: 0`) plus `display: flex`.

## Layout primitives

Rather than hand-writing flex objects, `@sigx/lynx-zero` exports design-system-neutral primitives — `Row`, `Col`, `Center` and `Spacer` — that build a Lynx-correct inline style for you and accept a `class` passthrough. They understand the box-model props (`gap`, `padding`, `margin`, `width`, `height`, `flex`, `background`, `borderRadius`) and resolve spacing and the flex shorthand the safe way:

```tsx
import { Row, Spacer } from '@sigx/lynx-zero';
// text is a global JSX intrinsic — no import needed.

export const Toolbar = () => (
    <Row gap={12} padding={{ x: 16, y: 8 }} background="base-200" borderRadius={12}>
        <text>Title</text>
        <Spacer />
        <text>Action</text>
    </Row>
);
```

The `background` prop is token-aware: pass a semantic token like `base-200` or `primary` and it resolves through the active theme, or pass any raw CSS color (`#fff`, `rgb(...)`). `padding` and `margin` accept a single number (all sides), per-axis `{ x, y }`, or per-side `{ top, right, bottom, left }` overrides.

## Theming

Themes on Lynx are sets of CSS custom properties — colors (`--color-<token>`), roundness (`--radius-*`), sizing (`--size-*`) and the text ramp (`--text-*`). Components and utilities read those variables, so switching a theme recolors everything that references them.

### How themes are applied

As of 0.19, `ThemeProvider` wraps children in a host `view` and declares the active theme's tokens as **inline CSS custom properties** on it. Because Lynx layout defaults enable CSS inheritance, the variables flow to every descendant — and because they are set inline they paint on the **first frame**, with no post-mount swap and no per-theme CSS class to generate. Inline custom properties require **Lynx ≥ 3.9** on native hosts (the CLI templates pin 3.9.0; an existing app runs `sigx prebuild --clean` once to adopt it).

Two authoring constraints remain — they concern the CSS engine's colour handling, not variable inheritance:

- Theme colors must be engine-safe strings — hex or `rgb()`, never `oklch()`, and avoid `calc(var() * n)`.
- Structural sizes ship as literal `px`; the provider re-derives any scaled values in JS.

### Mounting a provider

Mount one root provider near the top of your app and pick a starting theme:

```tsx
import { component } from 'sigx';
import { ThemeProvider } from '@sigx/lynx-daisyui';

export const App = component(() => {
    return () => (
        <ThemeProvider initial="daisy-light">
            {/* your screens */}
        </ThemeProvider>
    );
});
```

`@sigx/lynx-daisyui` registers six built-in themes on import — `daisy-light`, `daisy-dark`, `daisy-cupcake`, `daisy-synthwave`, `daisy-emerald` and `daisy-dracula` — each paired light/dark so they can toggle.

### Switching themes

Read and drive the active theme with the `useTheme` hook, which returns a reactive controller:

```tsx
import { component } from 'sigx';
import { Pressable } from '@sigx/lynx-gestures';
import { useTheme } from '@sigx/lynx-daisyui';
// text is a global JSX intrinsic — no import needed.

export const ThemeToggle = component(() => {
    const theme = useTheme();
    return () => (
        <Pressable onPress={() => theme.toggle()}>
            <text>Theme: {theme.name}</text>
        </Pressable>
    );
});
```

`set('daisy-dark')` pins a theme, `toggle()` flips to the paired light/dark theme, and `followSystem()` resumes following the OS color scheme. Reading `theme.name` inside render makes the subtree reactive to theme switches.

You can also drive the theme without a hook — from a store, a service or app boot — through the module-level `themeController`. A mounted root provider binds this singleton, so headless mutations still render:

```ts
import { themeController } from '@sigx/lynx-daisyui';

themeController.set('daisy-dark');
```

### Font scaling

Font scale is orthogonal to theme — it multiplies the `--text-*` ramp app-wide and persists across theme switches:

```ts
import { themeController } from '@sigx/lynx-daisyui';

themeController.setFontScale(1.25);
```

### Scoped sub-themes

Nesting a `ThemeProvider` creates a content-only sub-scope: its descendants recolor, while the OS status / navigation bars keep following the global root theme. This is handy for a single screen or panel on a different palette:

```tsx
<ThemeProvider initial="daisy-light">
    <MainContent />
    <ThemeProvider initial="daisy-dark">
        <SidePanel />
    </ThemeProvider>
</ThemeProvider>
```

### Custom themes

Register a theme before mounting the provider. The easiest path is `extendTheme`, which derives a full theme from a registered base and recomputes any soft tints you didn't override:

```ts
import { registerTheme, extendTheme } from '@sigx/lynx-daisyui';

registerTheme(
    extendTheme('daisy-dark', {
        name: 'acme-dark',
        colors: { primary: '#fb7185' },
    }),
);
```

Then use `initial="acme-dark"` on your provider. To build a theme from scratch, pass a `ThemeInput` to `registerTheme` directly — provide the core color tokens (the `*-soft` tints are computed for you) as hex or `rgb()` strings.

### Concrete colors for native consumers

Some native surfaces — text inputs, rich-text, SVG fills — can't read CSS variables. `useThemeColors` resolves the active palette to concrete hex values for those cases:

```tsx
import { component } from 'sigx';
import { useThemeColors } from '@sigx/lynx-zero';
// text is a global JSX intrinsic — no import needed.

export const Hint = component(() => {
    const colors = useThemeColors();
    return () => (
        <text style={{ color: colors.colorOf('base-content', 0.45) }}>Subtle hint</text>
    );
});
```

`colorOf(token, alpha?)` returns `#RRGGBB` or `#RRGGBBAA` and is reactive to theme switches.

## Component library

For a themed, ready-made component set built on this model, see [DaisyUI for Lynx](/lynx/modules/daisyui/overview). Each component composes its own classes (for example `color="primary"` becomes `btn-primary`) and exposes a `class` escape hatch so you can append your own. For the elements that take these styles, see the [native elements](/lynx/docs/elements) guide.

---
url: https://sigx.dev/ssg/docs/commands/
title: Commands
description: Every sigx ssg command with its usage, flags, and behavior
---

# Commands

`@sigx/ssg` adds a `sigx ssg` command group to the `sigx` CLI, with three subcommands — `dev`, `build`, and `preview` (each run as `sigx ssg <command>`). They are available when `@sigx/cli` (>= 0.4.0) is installed and an `ssg.config.{ts,js,mjs}` file exists in your project root (the plugin's `detect` step activates on that file).

Run any of them through your package runner:

```bash
npx sigx ssg <command>
```

Each subcommand maps directly to a programmatic function (`dev()`, `build()`, `preview()`), so you can also call those from a Node script — see the [API Reference](/ssg/docs/api).

## sigx ssg dev

Starts the SSG development server (Vite). If a `vite.config` exists it is used; otherwise the command runs zero-config, auto-loading `@sigx/vite`, optionally `@tailwindcss/vite`, and the SSG plugins with the `oxc` automatic JSX transform (import source `sigx`). The default port is 5173.

```bash
npx sigx ssg dev [--config <path>] [--port <n>] [--host] [--open] [--verbose]
```

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--config <path>` | string | Path to `ssg.config.ts`. |
| `--port <n>` | number | Port for the dev server (default 5173). |
| `--host` | boolean | Expose the server to the network. |
| `--open` | boolean | Open the browser on start. |
| `--verbose` | boolean | Verbose logging. |

## sigx ssg build

Builds the static site for production. It loads the config, scans routes, builds the client and SSR bundles with Vite, renders every path (including paths expanded from `getStaticPaths`) to static HTML in `outDir`, and writes `sitemap.xml` and `robots.txt`.

```bash
npx sigx ssg build [--config <path>] [--verbose] [--drafts] [--concurrency <n>]
```

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--config <path>` | string | Path to `ssg.config.ts`. |
| `--verbose` | boolean | Verbose logging. |
| `--drafts` | boolean | Include pages with `draft: true` frontmatter (excluded from production builds by default). |
| `--concurrency <n>` | number | Pages to render in parallel (default 20). |

Each rendered page is written to `<outDir>/<path>/index.html` (a `404` page becomes a root `404.html`). Per-page head tags (title, description, canonical, Open Graph, Twitter) are injected at the page's head marker. A failed page render fails the build with a non-zero exit. The build works zero-config too — without a `vite.config`, the same plugin set the dev server assembles is injected automatically.

## sigx ssg preview

Previews the production build locally through the Vite preview server. The default port is 4173.

```bash
npx sigx ssg preview [--config <path>] [--port <n>] [--host] [--open]
```

**Flags**

| Flag | Type | Description |
| --- | --- | --- |
| `--config <path>` | string | Path to `ssg.config.ts`. |
| `--port <n>` | number | Port for the preview server (default 4173). |
| `--host` | boolean | Expose the server to the network. |
| `--open` | boolean | Open the browser on start. |

## A typical workflow

```bash
npx sigx ssg dev
npx sigx ssg build
npx sigx ssg preview
```

## Next steps

- [Configuration & Content](/ssg/docs/configuration) — routing, layouts, collections, MDX, and the full config.
- [API Reference](/ssg/docs/api) — the programmatic `dev`, `build`, and `preview` functions and the rest of the public API.

---
url: https://sigx.dev/terminal/docs/api/
title: API Reference
description: "@sigx/terminal — build TUIs with TSX — API reference"
---

# API Reference

The terminal-specific exports of `@sigx/terminal`, grouped by kind. Import all of these from the `@sigx/terminal` entry.

`@sigx/terminal` is an umbrella that re-exports the `@sigx/reactivity` and `@sigx/runtime-core` surfaces (`signal`, `computed`, `effect`, `component`, `defineApp`, `onMounted`, `onUnmounted`, `Define`, `VNode`, etc.) — those belong to their own units and are documented there — plus the renderer (`@sigx/runtime-terminal`), the headless foundation (`@sigx/terminal-zero`) and the themed components (`@sigx/terminal-ui`). The component library is documented page-by-page under [Components](/terminal/docs/components); this page covers the renderer, focus/input, theming and intrinsics. `@sigx/reactivity` and `@sigx/runtime-core` are **peer dependencies** (see [Installation](/terminal/docs/installation)).

## Render & mount

### render

```ts
// const { render } = createRenderer<TerminalNode, TerminalNode>(nodeOps)
render(vnode: JSXElement, container: TerminalNode, appContext?: AppContext): void
```

Low-level renderer bound to the terminal node-ops. Renders or patches a tree into a `TerminalNode` container. Normally you use `terminalMount` / `renderTerminal` instead of calling this directly. Destructured from `createRenderer`. Its type is `@sigx/runtime-core`'s `RootRenderFunction`; pass `null` to unmount.

- **vnode** — the element tree to render, or `null` to unmount.
- **container** — the `TerminalNode` to render into.
- **appContext** — optional app context.

### renderTerminal

```ts
function renderTerminal(
    app: any,
    options?: RenderTerminalOptions,
): { unmount: () => void }
```

Standalone mount entry. Sets stdin to raw mode, hides the cursor, optionally clears the console, renders the app VNode into a fresh root node, and wires keyboard input. Use it directly in simple scripts.

- **app** — the app VNode (e.g. `<App />`).
- **options** — `RenderTerminalOptions`; defaults to `{}`.
- **Returns** — an object with `unmount()` that tears down stdin handling and restores the cursor.

```ts
const { unmount } = renderTerminal(<App />, { clearConsole: true });
```

### terminalMount

```ts
const terminalMount: (
    component: any,
    options: RenderTerminalOptions,
    appContext?: any,
) => (() => void)
```

The platform mount function passed to `defineApp().mount()`. Same setup as `renderTerminal` (raw mode, hide cursor, optional `clearConsole`, stdin wiring) but accepts an app context and returns the unmount function directly. It is registered as the platform default via `setDefaultMount(terminalMount)`, so `defineApp(<App />).mount({ clearConsole: true })` works without explicitly passing it.

- **component** — the app to mount.
- **options** — `RenderTerminalOptions`.
- **appContext** — optional app context.
- **Returns** — the `unmount` function.

### mountTerminal

```ts
function mountTerminal(options?: RenderTerminalOptions): {
    mount: typeof terminalMount;
    options: RenderTerminalOptions;
    onMount: (unmount: () => void) => void;
}
```

Helper that returns a mount target object suitable for `defineApp(MyApp).mount(mountTerminal())`. Captures the unmount callback into a module-level variable so `exitTerminal()` can later tear it down.

- **options** — `RenderTerminalOptions`; defaults to `{ clearConsole: true }`.
- **Returns** — a mount target with `mount`, `options` and `onMount`.

### exitTerminal

```ts
function exitTerminal(): void
```

Cleanly exits the terminal app: invokes the unmount function captured by `mountTerminal()`, shows the cursor, and clears the screen. Use it to quit a TUI app gracefully.

### renderNodeToLines

```ts
function renderNodeToLines(node: TerminalNode): string[]
```

The core cell/line renderer. Recursively walks a `TerminalNode` tree into an array of ANSI-styled output lines, handling text nodes, `<br>` line breaks, inline vs block layout (a `box`, or any node containing a `box` child, is treated as block), color codes, and box border drawing. Exported but primarily internal.

- **node** — the root `TerminalNode` to render.
- **Returns** — an array of output line strings.

## Input & focus

### onKey

```ts
type KeyLayer = 'overlay' | 'control' | 'view' | 'global';
type KeyHandler = (key: string) => boolean | void;

function onKey(handler: KeyHandler, opts?: { layer?: KeyLayer }): () => void
```

Subscribes a handler to raw keyboard input. Each keypress arrives as a string (for example `'\r'` for Enter, or `'\x1B[A'` for the up arrow). Handlers run in layers — **overlay → control → view → global** (default `control`) — and within a layer in registration order; returning strictly `true` **consumes** the key and stops dispatch. The built-in Tab / Shift+Tab focus cycling is the first `global` handler, so higher layers can consume Tab first. See [layered key dispatch](/terminal/docs/input-and-components).

- **handler** — called with each raw key string; return `true` to consume.
- **opts.layer** — dispatch layer; default `'control'`.
- **Returns** — an unsubscribe function.

### dispatchKey

```ts
function dispatchKey(key: string): void
```

Injects a key as if it arrived on stdin — runs the exact input path (Ctrl+C policy, Tab focus cycling, `onKey` fan-out). For tests, embedders and automation driving an app without a TTY.

### getTerminalSize

```ts
function getTerminalSize(): { columns: number; rows: number }
```

The terminal dimensions as a **reactive** read: a component that calls this in its render function re-renders when the terminal is resized (SIGWINCH). Prefer it over `getOutputTarget().columns/rows`, which are live but not reactive.

### writeStatic / printStatic

```ts
function writeStatic(text: string): void
const printStatic = writeStatic
```

Emit a permanent line above the live region (inline) or into the alt-screen transcript (fullscreen), composed atomically with the next frame so it never tears through the repaint. `console.*` is routed here automatically while an inline TTY app is mounted (`patchConsole`).

### focusState

```ts
const focusState: Signal<{ activeId: string | null }>
```

Reactive signal holding the currently focused element id. Created with the object overload of `signal`, so it is a deeply reactive proxy: components read `focusState.activeId` (property access, not a call) to know if they are focused, and the value updates reactively, driving a re-render.

### registerFocusable

```ts
function registerFocusable(id: string): void
```

Registers an id as focusable. If nothing is focused yet, the first registered id becomes active. Called by interactive components in `onMounted`.

### unregisterFocusable

```ts
function unregisterFocusable(id: string): void
```

Removes an id from the focusable set; if it was active, focus moves to another remaining focusable (or `null`). Called in `onUnmounted`.

### focus

```ts
function focus(id: string): void
```

Programmatically focuses the given id if it is registered as focusable. Used internally by components with the `autofocus` prop.

### focusNext

```ts
function focusNext(): void
```

Moves focus to the next registered focusable (wraps around). Bound to Tab by the input handler.

### focusPrev

```ts
function focusPrev(): void
```

Moves focus to the previous registered focusable (wraps around). Bound to Shift+Tab.

## Theme engine

The token-to-color pipeline (`@sigx/terminal-zero`, re-exported). Full guide: [Theming](/terminal/docs/theming).

### resolveColor

```ts
function resolveColor(token: string | undefined): string
```

Resolves a theme token (or raw `#hex`) to a concrete color for the renderer, **reactively** — it reads the active theme and the detected color depth, degrading to a 16-color ANSI name on limited terminals. A component that resolves a token during render re-renders on `setTheme()`.

### setTheme / getTheme / listThemes / registerTheme

```ts
function setTheme(id: string): void            // switch the active theme (throws on unknown id)
function getTheme(): string                    // active theme id (reactive)
function getActiveTheme(): Theme               // active theme object (reactive)
function hasTheme(id: string): boolean
function listThemes(): string[]
function registerTheme(id: string, theme: Theme): void   // first registered becomes active
```

The built-in themes (`obsidian` default, `nord`, `gum`, `classic`, `paper`) are also exported as the `THEMES` record. `applyThemeCanvas()` / `disableThemeCanvas()` bind or clear the renderer's themed screen canvas.

## Frame arithmetic

The renderer's layout is single-pass and content-driven: a `<box>` sizes itself to its widest line, there is no `width`/`height` prop, and nothing clips. So a component that wants to fill a known area has to know what its own chrome costs and pad its content to the remainder.

These two are that calculation, done once. Before them, every component that needed it hardcoded the answer — `- 4` for "rounded border (2) + padX (2)", `rows - 12` — and each copy silently went wrong when the box it described changed shape.

### boxChrome

```ts
function boxChrome(opts?: BoxChromeOptions): { rows: number; cols: number }

interface BoxChromeOptions {
    border?: boolean | 'single' | 'double' | 'rounded' | 'thick' | 'none';
    padX?: number;
    dropShadow?: boolean;
}
```

The rows and columns a `<box>` spends on chrome, so a caller can subtract them from the space it has. It mirrors `drawBox` exactly: a border adds one row top and bottom and one column each side; `padX` widens every content line symmetrically; a drop shadow appends one column to every row below the top border and pushes one extra row underneath.

```ts
const chrome = boxChrome({ border: true, padX: 1, dropShadow: true });
const inner = getTerminalSize().columns - chrome.cols;   // 5 columns of chrome
```

**A borderless box costs nothing** — `padX` and `dropShadow` included. `drawBox` runs only when a border is drawn, so on a bare `<box>` (what `Col` and friends render) those two props are silently inert. `border="none"` is the same case, which is why the border term takes the prop itself rather than a boolean you have to derive.

### fitLines

```ts
function fitLines(lines: string[], box: { width: number; height: number }, align?: CellAlign): string[]
```

Fit `lines` to exactly `box.height` lines of exactly `box.width` display cells — the convention that makes a component occupy the area it was given rather than hugging its content.

Both axes are enforced: each line is truncated (marked with `…`) or padded to `width`, and the list is padded with blank lines or clipped to `height`. **Clipping keeps the first `height` lines**, so a component that wants a different window — a log tailing the end — slices before calling.

## Components

The themed component library (`@sigx/terminal-ui`) is documented page-by-page under [Components](/terminal/docs/components): forms (`Input`, `TextArea`, `Checkbox`, `Confirm`, `Select`, `Radio`, `MultiSelect`), feedback (`ProgressBar`, `Spinner`, `Badge`), navigation (`Tabs`, `StatusBar`, `KeyHints`, `SuggestionList`), layout (`Card`, `Shell`, plus the `Box` / `Row` / `Col` / `Spacer` / `Divider` primitives), data (`Table`, `DataTable`, `Sparkline`, `BarChart`, `Meter`, `Trend`, `DetailList`, `StatusGrid`, `QRCode`), effects (`Gradient`, `Shimmer`, `Banner`, `PixelArt`) and tasks (`TaskList`, `LogView`, `LogPanel`). Typography (`Text`, `Heading`) is covered in [Typography](/terminal/docs/typography); the imperative prompt functions in [Prompts](/terminal/docs/prompts).

## Types & interfaces

### SelectOption

```ts
interface SelectOption<T = string> {
    label: string;
    value: T;
    description?: string;
}
```

The option shape consumed by the `Select` component's `options` prop.

### TerminalNode

```ts
interface TerminalNode {
    type: 'root' | 'element' | 'text' | 'comment';
    tag?: string;
    text?: string;
    props: Record<string, any>;
    children: TerminalNode[];
    parentNode?: TerminalNode | null;
}
```

The host node type for the terminal renderer — the equivalent of a DOM element. Created and mutated by the node-ops, and consumed by `renderNodeToLines`. It also augments `@sigx/runtime-core`'s `PlatformTypes` so `element` resolves to `TerminalNode`.

### RenderTerminalOptions

```ts
interface RenderTerminalOptions {
    mode?: 'inline' | 'fullscreen';   // how the app paints; default 'inline'
    fullscreen?: boolean;             // alias for mode: 'fullscreen'
    clearConsole?: boolean;           // start from a clean viewport
    patchConsole?: boolean;           // route console.* to writeStatic (default: on for inline TTY)
    canvas?: boolean;                 // themed screen canvas (default: on fullscreen, off inline)
    persistOnExit?: boolean;          // keep the final inline frame in scrollback (default true)
    exitOnCtrlC?: boolean;            // Ctrl+C tears down + exits 130 (default true)
}
```

Options accepted by `renderTerminal`, `terminalMount` and `mountTerminal`. See [Render modes](/terminal/docs/render-modes) for what each one does and how the renderer degrades on a non-TTY.

## JSX intrinsic elements

The terminal runtime declares the host elements. `box`, `text` and `br` share the `TerminalAttributes` shape; `row` is a horizontal layout element with its own attributes:

```ts
namespace JSX {
    interface IntrinsicElements {
        box: TerminalAttributes;
        text: TerminalAttributes;
        br: TerminalAttributes;
        row: RowAttributes;
    }

    interface TerminalAttributes {
        color?: string;            // foreground (named color or #hex)
        backgroundColor?: string;
        border?: 'single' | 'double' | 'rounded' | 'thick' | 'none';
        borderColor?: string;
        dropShadow?: boolean;
        shadowColor?: string;
        padX?: number;             // horizontal padding inside a box
        label?: string;            // centered caption in the top border
        labelColor?: string;
        // Text-style attributes (rendered on <text>; inert on <box>):
        bold?: boolean;
        faint?: boolean;
        italic?: boolean;
        underline?: boolean;
        inverse?: boolean;
        lineThrough?: boolean;
        children?: any;
    }

    interface RowAttributes {
        gap?: number;                                       // columns between cells (default 2)
        align?: 'start' | 'center' | 'end' | 'top' | 'bottom';
        children?: any;
    }
}
```

`color`, `backgroundColor`, `borderColor` and the text-style attributes accept a named ANSI color, a `#hex`, or a theme token resolved via [`resolveColor`](/terminal/docs/theming). On a 16-color terminal, hex and tokens degrade to the nearest ANSI name. For typed, themed text prefer the [`Text` and `Heading`](/terminal/docs/typography) components over the raw `<text>` intrinsic.

## Re-exports

`@sigx/terminal` re-exports the surfaces it sits on:

- **`@sigx/reactivity`** — `signal`, `computed`, `effect`, `untrack`, and the rest of the reactivity primitives. (A peer dependency — see [Installation](/terminal/docs/installation).)
- **`@sigx/runtime-core`** — `component`, `defineApp`, `onMounted`, `onUnmounted`, `Define`, `VNode`, and the rest of the core runtime. (Also a peer.)
- **`@sigx/runtime-terminal`** — the renderer and input APIs documented above.
- **`@sigx/terminal-zero`** — the theme engine, layout primitives and prompt engine.
- **`@sigx/terminal-ui`** — the themed [components](/terminal/docs/components) and [prompts](/terminal/docs/prompts).

The reactivity and runtime-core exports belong to their own units and are documented there. `@sigx/args` and `@sigx/terminal-dev` are separate installs — see [Command-line args](/terminal/packages/args/overview/) and [Dev mode](/terminal/packages/terminal-dev/overview/).

---
url: https://sigx.dev/use/docs/to-value/
title: toValue
description: Resolve a MaybeSignal to its current value — call getters, unwrap { value } handles, pass everything else through
---

# toValue

Resolve a [`MaybeSignal<T>`](/use/docs/conventions#inputs-maybesignalt-and-tovalue) to its current value: call getters, unwrap signal-shaped `{ value }` handles (primitive signals, computeds, `toSignal`/`toSignals` views), pass everything else through. Cross-platform — import from `@sigx/use`.

```ts
import { signal, computed } from 'sigx';
import { toValue } from '@sigx/use';

toValue(42);                 // 42
toValue(signal(42));         // 42
toValue(computed(() => 42)); // 42
toValue(() => 42);           // 42
```

This is the resolver behind every composable's `MaybeSignal` argument — reach for it when you build your own. Reading inside a reactive context tracks as usual — `toValue` adds no `untrack`, so a reactive source makes the surrounding effect/computed react to it.

> A plain (non-signal) object that happens to have a `value` property is passed through **as-is**, not unwrapped. If you mean it as a value, hand it over as a getter: `() => obj`.

## Signature

```ts
function toValue<T>(source: MaybeSignal<T>): T;
```

**Platform:** everywhere.

## See also

- [Conventions → Inputs](/use/docs/conventions#inputs-maybesignalt-and-tovalue) — the `MaybeSignal` contract this resolves.
- [`usePrevious`](/use/docs/use-previous) — a composable that takes a `MaybeSignal` source.
- [`unrefElement`](/use/docs/unref-element) — the element-target equivalent for the DOM.

---
url: https://sigx.dev/use/docs/overview/
title: Overview
description: "@sigx/use — tree-shakable, reactive composables built on signals"
---

# @sigx/use

`@sigx/use` is a collection of small, **tree-shakable composables** built directly on the SignalX reactive core. Toggles and counters, debounced and throttled signals, timers, element sensors, storage, clipboard, media queries: each is an ordinary function you call from a component's setup, and each returns plain signals you read as values.

Here's the shape of it — a clamped counter in three lines:

```tsx
import { component, render } from 'sigx';
import { useCounter } from '@sigx/use';

const Counter = component(() => {
    const { count, inc, dec, reset } = useCounter(0, { min: 0, max: 10 });

    return () => (
        <div class="flex items-center gap-3">
            <button class="btn" onClick={() => dec()}>-</button>
            <span class="text-xl font-bold w-12 text-center">{count}</span>
            <button class="btn" onClick={() => inc()}>+</button>
            <button class="btn btn-ghost" onClick={() => reset()}>reset</button>
        </div>
    );
});

render(<Counter />, "#app");
```

No `.value` at the call site inside JSX, no manual subscriptions — `count` is a signal, and reading it in the render function re-renders the component. That's the whole ergonomic.

## Two packages, one import for apps

`@sigx/use` ships as **two packages** so the same composables work on every SignalX target without dragging the DOM into places that don't have one:

| Package | Runs on | Contains |
|---|---|---|
| **`@sigx/use`** | web, Lynx, SSR, terminal — statically **DOM-free** | The cross-platform composables (state, timing, debounce/throttle, shared state, utilities). |
| **`@sigx/use-web`** | the browser (but **SSR-safe**) | The DOM/BOM sensors (elements, viewport, storage, clipboard, …) **plus a re-export of all of `@sigx/use`**. |

Because `@sigx/use-web` re-exports the core package, a **web app installs one package and imports everything from it**:

```bash
npm install @sigx/use-web
```

```ts
// a web app: both cross-platform and browser composables from one entry
import { useCounter, useStorage, useMouse } from '@sigx/use-web';
```

A **library** or a **non-web platform** (Lynx, terminal) that only needs the DOM-free composables installs the core package directly:

```bash
npm install @sigx/use
```

Throughout these docs, cross-platform composables show `from '@sigx/use'` and browser composables show `from '@sigx/use-web'` — but in a web app you can import both from `@sigx/use-web`.

> **Peers.** Both packages peer-depend on `@sigx/reactivity` and `@sigx/runtime-core` `^0.14.0` (the `sigx` umbrella your app already runs on provides these). `@sigx/use-web` additionally peers `@sigx/use`. They never bundle their own copy of the core — a composable always shares the *same* reactive runtime as your components.

## The cleanup model

Every composable that starts ongoing work — a timer, an event listener, an observer — cleans up on its own when the **owning scope** disposes. "Owning scope" means the component you called it in, or the innermost [`effectScope()`](/core/docs/effects#effect-scope) if you're outside a component. Call `useIntervalFn` in a component and the interval clears on unmount; you write nothing.

For **standalone** use — outside any component or scope, in a script or a test — there's no scope to hook, so every such composable also returns an **explicit handle**: a `stop()` function, or a [`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop) (`pause`/`resume`/`isActive`). Hold it and call `stop()` yourself.

```ts
import { useIntervalFn } from '@sigx/use';

// in a component: auto-clears on unmount
const { pause, resume } = useIntervalFn(() => tick(), 1000);

// standalone: you own teardown
const timer = useIntervalFn(() => tick(), 1000);
// ... later
timer.pause();
```

This is the same [`tryOnScopeDispose`](/use/docs/conventions#lifecycle-helpers) mechanism the composables use internally, and one you can reuse in your own.

## What's deliberately *not* here

`@sigx/use` stays focused on device, UI, and reactivity utilities. A few neighbours own their space, and these docs point you at them rather than duplicating:

- **Async data / server state** → core's [`useData` / `useAction`](/core/docs/data-loading). `createGlobalState` here is for device/UI state, not per-user data.
- **URL query params** → the router's [`useQuery`](/router/docs/getting-started).
- **Per-user, structured app state** → [`@sigx/store`](/store).

## Building a platform pack

`@sigx/use-web` is the reference **platform pack**: it implements the web side of the shared contracts (`StorageLike`, `NetworkState`, `ColorScheme`, …) and re-exports the core package. `@sigx/use-lynx` and third-party packs follow the same recipe — implement the platform contracts, re-export the seam, peer-depend on `@sigx/use`, and pull shared helpers from the `@sigx/use/internals` subpath. See [Conventions → Cross-platform contracts](/use/docs/conventions#cross-platform-contracts) for the type surface a pack fulfils.

## Next steps

- [Conventions](/use/docs/conventions) — `MaybeSignal`, `toValue`, `ReadSignal`, reactive-view returns, element targets, and the cross-platform contracts. **Read this next** — it explains patterns every composable shares.
- [`useToggle`](/use/docs/use-toggle), [`useCounter`](/use/docs/use-counter) — start with the state composables.
- [`useStorage`](/use/docs/use-storage) — the flagship: a deep-reactive object that auto-persists.

---
url: https://sigx.dev/actors/docs/jobs/
title: Jobs
description: defineJob — one durable long-running operation per actor, with the state machine, progress, checkpoints and client surface already decided
---

# Jobs

<p class="lede">`defineJob` is the packaged experience on top of [tasks](/actors/docs/tasks).
Start a job from a request handler and return immediately; check on it from anywhere in the
cluster.</p>

```ts
import { defineJob } from '@sigx/actors/job';

export const SecuritySync = defineJob({
    type: 'SecuritySync',
    authorize: requireStaff,
    maxAttempts: 3,          // crash-resume attempts before 'failed'
    retainMs: 86_400_000,    // keep the terminal record a day, then forget
    run: async (job, input: { providerId: string }) => {
        const users = await loadUsers(input.providerId, { signal: job.signal });
        const from = (job.resumedFrom as { cursor: number } | undefined)?.cursor ?? 0;
        for (let i = from; i < users.length; i++) {
            job.signal.throwIfAborted();
            await syncOne(users[i]);
            await job.progress({ done: i + 1, total: users.length });
            if (i % 100 === 0) await job.checkpoint({ cursor: i + 1 });
        }
        return { synced: users.length };
    },
});
```

```ts
// A request handler — returns immediately, the job runs on the cluster:
const runId = crypto.randomUUID();
await actor(SecuritySync, runId).start({ providerId });

// Later, from anywhere:
await actor(SecuritySync, runId).status();   // JobInfo: status/progress/attempts
await actor(SecuritySync, runId).cancel();
await actor(SecuritySync, runId).result();   // the return value, once completed
```

`watch()` is a stream of `JobInfo`, so a progress bar is a component that consumes it:

```tsx
import { component, onMounted, signal } from 'sigx';

const JobProgress = component<{ runId: string }>(({ props }) => {
    const info = signal<JobInfo | null>(null);

    onMounted(async () => {
        for await (const next of actor(SecuritySync, props.runId).watch()) info.value = next;
    });

    return () => (
        <progress value={info.value?.progress?.done ?? 0} max={info.value?.progress?.total ?? 1} />
    );
});
```

## What the layer decides for you

**The state machine.** `status()` and `watch()` return `JobInfo` — never the checkpoint, which
is private, and never the result, which is fetched once via `result()`.

```mermaid
stateDiagram-v2
    [*] --> pending: start(input)
    pending --> running
    running --> paused: job.pause(cp)
    paused --> running: resume(data)
    running --> running: crash-resume
    running --> completed: run() returns
    running --> failed: past maxAttempts
    running --> cancelled: cancel()
    paused --> cancelled: cancel()
    completed --> [*]: retainMs
    failed --> [*]: retainMs
    cancelled --> [*]: retainMs
```

**One actor per run**, keyed by your run id. The directory's single-activation guarantee *is*
the "exactly one runner" guarantee — there is no separate lock.

**`start` is idempotent under retry.** A non-pending job returns its current info and never
restarts. Safe to call from a handler that a client may retry.

**Crash-resume counts; pause-resume is free.** A crash-resumed run arrives with `job.attempt`
bumped and `job.resumedFrom` set to the last checkpoint. Past `maxAttempts` the job is marked
`failed`. `resume(data)` on a paused job re-runs with `job.resumeData` and costs no attempt.

**`pause` parks durably.** `return job.pause(checkpoint)` writes the checkpoint, marks
`paused` and releases the task — the actor idles at zero cost until `resume()`. For a timeout,
arm `job.reminders` before pausing and handle it in `onReminder(control, name)`;
`control.resume()` and `control.cancel()` are internal, so there is no self-dispatch deadlock.

**Progress rides the change feed, not storage.** `job.progress()` — and `job.update()` for
your own `state:` extra fields — mutate state in a turn so `watch()` pushes them live, but
nothing is persisted per tick. After a crash, progress honestly **regresses to the last
checkpoint** rather than claiming ground the work did not keep.

**`retainMs`** keeps the terminal record around for late `result()` readers, then a one-shot
reminder clears the state and deactivates. `discard()` does it on demand.

## Checkpoints are the contract

`progress()` is for humans; `checkpoint()` is for the runtime. Only a checkpoint survives a
crash, so how often you call it is how much work you are willing to redo.

The resume contract is **at-least-once**: the runtime resumes the function, and your code
resumes the work by reading `job.resumedFrom`. Make the step after a checkpoint idempotent.

## Projecting status outside the job

`onSettled` fires on **every** terminal transition, which is what makes it safe to keep a
projection — a status row in your own database, a metric, a notification — in step with the
job:

```ts
export const ImportJob = defineJob({
    type: 'Import',
    async run(job) { /* … */ },
    async onSettled(control, info) {
        await db.imports.update(info.key, { status: info.status });
    },
});
```

Two of those transitions cannot be observed from inside `run()` at all, which is the reason
the hook exists:

- **The `maxAttempts` give-up.** The body is re-entered, sees `attempts > maxAttempts`, and
  finishes as failed without ever calling your `run` — so there is no body turn to write from.
- **`cancel()` on a paused job.** A paused job holds no task, so nothing in the body is around
  to notice.

Without the hook, a projection written only from `run()` asserts "still running" forever after
either one.

The contract:

- **It runs after the save.** The transition is already durable and `info` is the final state.
  A handler that throws is caught, logged in dev, and swallowed — it cannot unwind the settle.
- **It fires for `completed` too**, not only the runtime-driven cases, so handlers should be
  **idempotent**.
- **No self-dispatch**, the same rule as `onReminder`: it receives a `JobControl`, not a
  client.
- **Awaiting slow I/O holds the actor's turn.** Hand long work to a
  [task](/actors/docs/tasks) rather than blocking the settle.

## `migrateState` is not supported

> **`defineJob` does not accept `migrateState`.** `JobOptions` has no such option and the
> underlying `defineActor` config forwards nothing.
>
> The reasoning is worth a sentence: a job's stored record **is** the job envelope —
> `status`, `progress`, `checkpoint` and the rest, with your own state under `extra`. A hook
> over that would hand you a runtime shape you do not own. Migrating the `extra` half wants
> its own option, and is not part of this.

See [State & persistence](/actors/docs/state-and-persistence) for migration on ordinary
actors.

## Recipes, not API

A singleton queue-worker with strict ordering and bounded concurrency, a cron-on-reminders
scheduler, and the Cloudflare Durable Object posture are all **patterns** rather than
features. They are written up in `docs/job-recipes.md` in the actors repo, deliberately left
out of the API so the job layer stays one thing done well.

## Next steps

- [Tasks](/actors/docs/tasks) — the primitive underneath, and the crash-resume machinery.
- [Timers & reminders](/actors/docs/timers-and-reminders) — pausing with a timeout.
- [Clustering](/actors/docs/clustering) — where a resumed job comes back.

---
url: https://sigx.dev/actors/docs/node/
title: Running a host on Node
description: createAppHandler, the production entry, and the graceful-shutdown recipe that retires keep-alive sockets properly
---

# Running a host on Node

<p class="lede">One handler serves the public actor endpoint and every plugin-contributed
route. The composition stays visible in your entry file — the sigx idiom.</p>

```ts
import { createServer } from 'node:http';
import { createAppHandler, attachSignalHandlers } from '@sigx/actors/node';
import { app } from './src/actors.app.ts';
import { Counter } from './src/counter.actor.ts';

// THE SAME app module the dev server runs: storage, defaults and every plugin
// shared, declared once. Only the registry differs — Vite hands the plugin's
// over, this entry names its actors.
const host = await app.withActors([Counter]).start();

const actorHandler = createAppHandler(app);

const server = createServer((req, res) => {
    void actorHandler(req, res, async () => {
        // your static / SSR fallthrough
    });
});

attachSignalHandlers(host, { server });
server.listen(5199);
```

`createAppHandler(app)` is a connect-style handler: it answers actor requests and any route a
plugin contributed, and calls `next()` for everything else. That last part is what lets it sit
in front of your existing app rather than beside it.

## Graceful shutdown

Stopping the actors is only half of it. The other half is retiring keep-alive sockets, and
getting it wrong shows up as occasional connection resets during every deploy:

```ts
// Once shutdown starts, every response says `connection: close` so keep-alive
// clients retire their pooled socket after the response they are already
// receiving — rather than reusing it right up to the moment it is destroyed.
let stopping = false;
const server = createServer((req, res) => {
    if (stopping) res.setHeader('connection', 'close');
    void actorHandler(req, res, staticFallthrough);
});

// Pass the server AND onStopBegin: `server` alone closes the listener at the
// end, without giving pools a chance to retire their sockets first.
attachSignalHandlers(host, { server, onStopBegin: () => (stopping = true) });
```

`attachSignalHandlers` wires `SIGINT`/`SIGTERM` to `host.stop()`, which drains in-flight
turns, flushes pending write-behind saves and runs `onDeactivate` for every activation. See
[Lifecycle](/actors/docs/lifecycle).

In a cluster, a graceful stop announces `leaving` before handing off — which is why liveness
and readiness [are allowed to disagree](/actors/docs/health-and-readiness) during a drain.

## The lower-level entry

`createHost` remains available when you want no app layer at all:

```ts
import { createHost } from '@sigx/actors/host';
import { handleActorRequest, matchesActorRequest } from '@sigx/actors/server';
import { actors } from './dist/server/sigx-actors.js'; // build-emitted registry

const host = createHost({ actors, storage });
await host.start();

export default {
    async fetch(request: Request): Promise<Response> {
        if (matchesActorRequest(request)) return handleActorRequest(request, { host });
        if (matchesServerFn(request))     return handleServerFnRequest(request, { resolve });
        return documentHandler(request);
    },
};
```

This is the WinterCG shape, and it is what the
[Cloudflare](/actors/docs/cloudflare-workers) and other platform entries build on.
`createFetchHandler` from `@sigx/actors/server` packages the same composition.

Prefer [`defineActorApp`](/actors/docs/the-app) unless you have a reason not to — `createHost`
takes exactly one `placement` and one `storage`, which is what makes plugins impossible.

## Other runtimes

`createFetchHandler(app)` turns an app into a single WinterCG `fetch` handler, which is all
Deno, Bun and edge runtimes need:

```ts
import { createFetchHandler } from '@sigx/actors/server';

await app.start();

Deno.serve(createFetchHandler(app));                 // Deno
export default { fetch: createFetchHandler(app) };   // Bun, Workers
```

<div class="alert alert-warning not-prose my-4">
  <div>
    <strong>On Node, keep <code>createAppHandler</code>.</strong> It is not a legacy shim —
    it keeps core's connect adapter for the public endpoint, which pumps request bodies with
    backpressure. The portable handler is what runtimes without <code>node:http</code> need,
    not a better version of the Node mount.
  </div>
</div>

If you want to place the mounts yourself, `app.routes` is the list — each entry a
`{ name, match(request), handle(request, host) }` triple you can hang off whatever server you
already have. Reading it **seals the app**, so register every plugin first.

`handleHostRequest` and `matchesHostRequest` from `@sigx/actors/cluster` cover the internal
host-to-host mount, the same way `handleActorRequest` and `matchesActorRequest` cover the
public one.

## Host defaults

```ts
defineActorApp({
    defaults: {
        idleAfterMs: 20 * 60_000,   // deactivate after 20 minutes idle
        callTimeoutMs: 30_000,      // 0 disables
        sweepIntervalMs: 60_000,    // 0 disables
        maxActivations: 0,          // 0 = unlimited
        reminderTickMs: 30_000,
        slowTurnMs: 5_000,          // __DEV__ warning threshold
        taskGraceMs: 10_000,
        devSerializeChecks: false,
    },
});
```

Note that `callTimeoutMs` deadlines
[fire coarsely](/actors/docs/errors#call-deadlines-fire-coarsely) at 10 seconds or more.

## Next steps

- [Storage](/actors/docs/storage) — what to run in production.
- [Clustering](/actors/docs/clustering) — more than one of these.
- [Health & readiness](/actors/docs/health-and-readiness) — probes and draining.
- [Kubernetes](/actors/docs/kubernetes) — the deployment shape.

---
url: https://sigx.dev/cli/docs/plugins/
title: Authoring Plugins
description: Extend the sigx CLI with your own commands using the plugin API
---

# Authoring Plugins

The `sigx` CLI is extensible: any package installed in a project can contribute commands. Commands like `dev`, `build`, and `preview` are themselves provided by plugins (`@sigx/vite`, `@sigx/ssg`, `@sigx/lynx-cli`). This guide shows how to write your own.

## How discovery works

When the CLI runs, it scans the current project's `package.json` `dependencies` and `devDependencies`. For each dependency it reads `node_modules/<dep>/package.json` and looks for a top-level `sigx-cli` field that points at a plugin module:

```json
{
    "name": "my-sigx-plugin",
    "sigx-cli": {
        "plugin": "./dist/plugin.js",
        "requires": ">=0.4.0"
    }
}
```

- **`plugin`** is a path, relative to the dependency's package root, to a module that **default-exports** a `SigxPlugin`. The CLI dynamically imports that module, takes its default export, calls `detect(cwd)`, and registers the plugin's commands only if `detect` returns `true`.
- **`requires`** (optional) is the semver range of `@sigx/cli` your plugin's contract needs — `^x.y.z`, `>=x.y.z`, or an exact version. If the running `sigx` binary is older than your range, the plugin still loads (best effort) but the CLI prints a prominent warning telling the user to update. Declare `"requires": ">=0.4.0"` for any plugin written against the `@sigx/args` arg contract described below — that is the floor where it landed.

Discovery inspects the current working directory's `package.json` and `node_modules`. All discovery failures are swallowed silently, so a broken plugin never crashes the CLI.

## Defining a plugin

Use `definePlugin` for type-safe authoring. It is an identity function — it returns the plugin unchanged but gives you full type checking against the `SigxPlugin` contract. Import it from `@sigx/cli/plugin` (it is also re-exported from `@sigx/cli`); the same module re-exports `a`, the `@sigx/args` builder you declare arguments with, so plugins keep a single import surface:

```ts
import { definePlugin } from '@sigx/cli/plugin';

export default definePlugin({
    name: 'my-plugin',
    detect: (cwd) => true,
    commands: {
        hello: {
            description: 'Say hello',
            async run({ cwd, args, logger }) {
                logger.log(`hello from ${cwd}`);
            },
        },
    },
});
```

If you prefer, you can use the `satisfies` operator instead of `definePlugin` for the same type safety:

```ts
import type { SigxPlugin } from '@sigx/cli/plugin';

export default {
    name: 'my-plugin',
    detect: (cwd) => true,
    commands: {
        hello: {
            description: 'Say hello',
            async run({ cwd, args, logger }) {
                logger.log(`hello from ${cwd}`);
            },
        },
    },
} satisfies SigxPlugin;
```

The `Logger` passed to `run` has only `log`, `warn`, and `error` methods — there is no `info`. Messages are prefixed with `[sigx]` and `warn` / `error` are uppercased.

## Gating activation with detect

`detect(cwd)` decides whether your plugin is relevant to the current project. Return `true` to register your commands, `false` to stay out of the way. A common pattern is to look for a config file or a marker dependency:

```ts
import { existsSync } from 'node:fs';
import { join } from 'node:path';
import { definePlugin } from '@sigx/cli/plugin';

export default definePlugin({
    name: 'my-plugin',
    detect: (cwd) => existsSync(join(cwd, 'my-plugin.config.ts')),
    commands: {
        // ...
    },
});
```

## Declaring command arguments

Commands declare their arguments through the `args` map, using the fluent [`@sigx/args`](/terminal/packages/args/overview/) builders exposed as `a` (re-exported from `@sigx/cli/plugin`). Each entry is a builder you chain to describe its type, aliases, default, and help — and the chain drives the type your handler receives in `ctx.args`:

```ts
import { definePlugin, a } from '@sigx/cli/plugin';

export default definePlugin({
    name: 'deployer',
    detect: () => true,
    commands: {
        deploy: {
            description: 'Deploy the built site',
            args: {
                target: a.enum(['staging', 'production']).default('staging').describe('Deploy target'),
                port: a.number().alias('p').default(8788).describe('Port to listen on'),
                force: a.boolean().describe('Skip confirmation'),
                files: a.rest().describe('Files to deploy'),
            },
            async run({ args, logger }) {
                logger.log(`Deploying to ${args.target} on :${args.port}`);
                if (args.force) logger.warn('Forcing deploy without confirmation');
            },
        },
    },
});
```

The common builders:

| Builder | Parses | Inferred type |
| --- | --- | --- |
| `a.string()` | `--name value`, `--name=value` | `string` |
| `a.number()` | finite numbers (incl. negative) | `number` |
| `a.boolean()` | `--flag`, `--no-flag`, `--flag=false` | `boolean` |
| `a.enum(['a', 'b'])` | exact member | `'a' \| 'b'` |
| `a.positional()` | non-flag tokens, in declaration order | `string` |
| `a.rest()` | the remaining positional tokens | `string[]` |

Chain refiners to shape them: `.alias('p', …)` (single characters become short flags like `-p`), `.default(v)`, `.required()`, `.multiple()` (repeatable → array), `.describe(text)`. Builders are immutable — each refiner returns a new builder. For the full builder/refiner reference see the [`@sigx/args` guide](/terminal/packages/args/overview/).

**Parsing behavior** flows straight from `@sigx/args`, so plugin commands inherit it:

- **Unknown flags are an error.** An undeclared `--flag` fails with a clear message rather than being silently accepted.
- **Positionals bind only to declared builders.** Bare positional tokens fill your `a.positional()` / `a.rest()` args in order; there is no loose positional bag.
- **`--` is a strict separator.** Everything after a bare `--` lands verbatim in `ctx.args._` (a `string[]`) and is never parsed as flags.
- **Booleans negate** with `--no-<flag>`, and kebab/camel spellings both resolve (`--dry-run` ↔ `dryRun`).
- **`--help` is generated** from the `@sigx/args` help catalog — don't hand-write usage text. `sigx <your-command> --help` lists every declared arg, its type, default, and description automatically.

A malformed `args` schema (e.g. an alias collision) throws a `DefinitionError` at registration. The CLI catches it, logs a warning, and skips just that command — one bad schema never takes down the whole CLI.

## Command options

Beyond `description`, `args`, and `run`, a command can set three optional fields:

```ts
commands: {
    deploy: {
        description: 'Deploy the built site',
        aliases: ['ship', 'push'],   // also answers to `sigx ship` / `sigx push`
        hidden: false,               // set true to keep it out of `sigx --help`
        allowUnknownFlags: true,     // collect undeclared flags into ctx.unknownFlags instead of erroring
        args: { /* … */ },
        async run(ctx) {
            // forward extras verbatim to an underlying tool
            await runRsync([...ctx.args._, ...(ctx.unknownFlags ?? [])]);
        },
    },
},
```

- **`aliases`** — extra names the command also answers to. If an alias collides with another command, the CLI warns and a **direct command name always beats an alias**, so a plugin can't shadow a built-in by aliasing over it.
- **`hidden`** — omit the command from `sigx --help` while keeping it fully dispatchable (handy for internal or experimental commands).
- **`allowUnknownFlags`** — instead of erroring on an undeclared flag, collect the raw tokens into `ctx.unknownFlags` (an optional `string[]`, populated only when this is set — hence the `ctx.unknownFlags ?? []` above). The command decides whether and how to forward them; nothing is passed through automatically. Use it for wrapper commands that hand flags to an underlying tool. Without it, unknown flags remain an error (the default).

Nested subcommands within a plugin command are not yet supported.

## Standalone commands with defineCommand

Inside a `definePlugin` literal every command already infers its `ctx.args` per key. When you factor a command **out** of the literal — into its own module or variable — wrap it in `defineCommand` so it keeps that inference instead of widening to the legacy `Record`:

```ts
import { defineCommand, definePlugin, a } from '@sigx/cli/plugin';

export const deploy = defineCommand({
    description: 'Deploy the built site',
    args: { target: a.enum(['staging', 'production']).default('staging') },
    async run({ args, logger }) {
        logger.log(`Deploying to ${args.target}`); // args.target: 'staging' | 'production'
    },
});

export default definePlugin({
    name: 'deployer',
    detect: () => true,
    commands: { deploy },
});
```

`defineCommand` is an identity helper (like `definePlugin`) — it returns the command unchanged and only drives typing. The new command options and the typed context landed in `@sigx/cli` 0.5, so declare `"requires": ">=0.5.0"` in your `sigx-cli` field if you rely on `aliases` / `hidden` / `allowUnknownFlags`.

## The command context

Every command's `run` handler receives a single context object:

```ts
async run(ctx) {
    ctx.cwd;          // process.cwd()
    ctx.args;         // parsed args, INFERRED from your `args` builders; ctx.args._ = post-`--` tokens
    ctx.logger;       // prefixed Logger with log/warn/error
    ctx.plugins;      // every plugin discovered for this project (for runShell)
    ctx.cliVersion;   // the running `sigx` binary's version, for feature detection
    ctx.unknownFlags; // undeclared flags — only when the command sets allowUnknownFlags
}
```

`ctx.args` is fully typed from the `args` builders you declared — no casts. Inside `definePlugin`, each command's args shape infers per key, so `args.port` above is a `number`, `args.target` is `'staging' | 'production'`, and so on. The context is a `TypedCommandContext<S>` — an intersection over the plain `CommandContext`, so it stays assignable to `CommandContext` and any helper you've typed against the base still accepts it. A command with no `args` (or a hand-annotated `CommandContext`) falls back to the legacy `args: Record<string, unknown>`.

`ctx.plugins` and `ctx.cliVersion` exist so a shell-hosting command (for example a long-running `dev`) can merge peer plugins' TUI contributions and adapt to the CLI version. See [The shell runtime](/cli/docs/shell).

## Contributing to the shell (TUI)

Beyond plain commands, a plugin can ship a **TUI contribution** — tabs, slash commands, single-key shortcuts, and status-line items that get merged into whichever plugin hosts the [shell runtime](/cli/docs/shell). Add a `tui` field to your plugin:

```ts
import { definePlugin } from '@sigx/cli/plugin';

export default definePlugin({
    name: 'my-plugin',
    detect: () => true,
    commands: { /* … */ },
    tui: {
        tabs: [{ id: 'routes', label: 'Routes', render: () => myRoutesView() }],
        commands: [{ name: '/reload', description: 'reload config', run: (shell) => shell.say('reloaded') }],
        shortcuts: [{ key: 'r', label: 'reload', run: (shell) => shell.say('reloaded') }],
        status: () => [{ label: 'mode', value: 'dev', tone: 'success' }],
        setup(shell) {
            const server = startWatcher();
            // Returned teardown runs before the process exits (also on Ctrl+C / SIGTERM).
            return () => server.close();
        },
    },
});
```

The host plugin's command merges these by passing `ctx.plugins` to `runShell({ plugins })`; host entries win conflicts (a duplicate tab `id`, command `name`, or shortcut `key` from a contributor is skipped). The `setup(shell)` lifecycle runs once when the shell comes up — start servers and watchers there, and return a function (or call `shell.onExit`) to tear them down cleanly. See [The shell runtime](/cli/docs/shell) for the host side, the `ShellHandle` API, and the non-TTY fallback.

## Packaging checklist

To ship a plugin:

1. Build a module that **default-exports** a `SigxPlugin` (via `definePlugin` or `satisfies SigxPlugin`).
2. Point your package's `package.json` `sigx-cli.plugin` field at that built module, and set `"requires": ">=0.4.0"` (or higher) so the CLI can warn users on too-old a binary.
3. Publish the package and add it to a project's dependencies.

Once installed, run `npx sigx <your-command>` in a project where your `detect` returns `true`.

## Command name conflicts

If two plugins register a command with the same name, the last one discovered wins, and the CLI logs a warning via `logger.warn`:

```text
[sigx] WARN Plugin "X" overrides command "Y"
```

## See also

- [API Reference](/cli/docs/api) — the full `SigxPlugin`, `PluginCommand`, `CommandContext`, `TuiContribution`, and `Logger` types.
- [The shell runtime](/cli/docs/shell) — `runShell`, the `ShellHandle` API, and the TUI contribution model.
- [`@sigx/args` guide](/terminal/packages/args/overview/) — the fluent arg builders behind `PluginCommand.args`.
- [Commands](/cli/docs/commands) — the built-in and plugin-provided commands.

---
url: https://sigx.dev/core/docs/portal/
title: Portal
description: Render content outside the component tree in SignalX
---

# Portal

The `Portal` component renders its children to a different location in the DOM, outside of the normal component tree. This is essential for modals, tooltips, dropdowns, and other overlay UI.

## Basic Usage

```tsx
import { Portal, component, render } from 'sigx';

const App = component(() => {
    return () => (
        <div>
            <p>Content inside the component tree</p>
            <Portal>
                <div style={{
                    position: 'fixed',
                    bottom: '20px',
                    right: '20px',
                    padding: '16px',
                    background: '#3b82f6',
                    color: 'white',
                    borderRadius: '8px',
                    boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
                    zIndex: 10000
                }}>
                    This is portaled to document.body!
                </div>
            </Portal>
        </div>
    );
});

render(<App />, "#sandbox");
```

By default, `Portal` renders to `document.body`.

## Specifying a Target

Use the `to` prop to render to a specific container:

```tsx
import { Portal, component, render } from 'sigx';

const App = component(() => {
    return () => (
        <div>
            {/* Create a custom target container */}
            <div 
                id="custom-portal-target" 
                style={{ 
                    padding: '16px', 
                    border: '2px dashed #3b82f6',
                    borderRadius: '8px',
                    minHeight: '60px',
                    marginBottom: '16px'
                }}
            >
                <strong>Custom Target Container:</strong>
            </div>
            
            {/* Portal to the custom container using CSS selector */}
            <Portal to="#custom-portal-target">
                <span style={{ 
                    background: '#10b981', 
                    color: 'white', 
                    padding: '4px 8px', 
                    borderRadius: '4px',
                    marginLeft: '8px'
                }}>
                    Portaled here!
                </span>
            </Portal>
            
            <p style={{ color: '#666' }}>The green badge was portaled into the dashed container above.</p>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Conditional Portals

Use the `disabled` prop to render in-place instead of portaling:

```tsx
import { component, Portal, render } from 'sigx';

const App = component(({ signal }) => {
    const state = signal({ disabled: false });

    const boxStyle = {
        padding: '12px 16px',
        background: '#8b5cf6',
        color: 'white',
        borderRadius: '6px',
        marginTop: '8px'
    };

    return () => (
        <div>
            <button 
                onClick={() => state.disabled = !state.disabled}
                style={{ padding: '8px 16px', cursor: 'pointer' }}
            >
                Toggle: {state.disabled ? 'Disabled (in-place)' : 'Enabled (portaled)'}
            </button>
            
            <div style={{ 
                marginTop: '16px', 
                padding: '16px', 
                border: '2px solid #e5e7eb',
                borderRadius: '8px' 
            }}>
                <p>This is the component tree.</p>
                
                <Portal disabled={state.disabled}>
                    <div style={boxStyle}>
                        {state.disabled 
                            ? '📍 Rendered in-place (inside the border)' 
                            : '🚀 Portaled to body (outside the border)'}
                    </div>
                </Portal>
            </div>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Modal Example

A complete modal implementation using Portal:

```tsx
import { component, Portal, render, type Define } from 'sigx';

type ModalProps = Define.Prop<'open', boolean, true> & Define.Event<'close'>;

const Modal = component<ModalProps>(({ props, slots, emit }) => {
    const handleBackdropClick = (e: MouseEvent) => {
        if (e.target === e.currentTarget) emit('close');
    };

    return () => {
        if (!props.open) return null;

        return (
            <Portal>
                <div 
                    onClick={handleBackdropClick}
                    style={{
                        position: 'fixed',
                        inset: 0,
                        background: 'rgba(0,0,0,0.5)',
                        display: 'flex',
                        alignItems: 'center',
                        justifyContent: 'center',
                        zIndex: 1000
                    }}
                >
                    <div 
                        role="dialog" 
                        aria-modal="true"
                        style={{
                            background: 'white',
                            borderRadius: '12px',
                            padding: '24px',
                            minWidth: '300px',
                            boxShadow: '0 20px 40px rgba(0,0,0,0.2)'
                        }}
                    >
                        <div style={{ 
                            display: 'flex', 
                            justifyContent: 'space-between', 
                            alignItems: 'center',
                            marginBottom: '16px'
                        }}>
                            <h3 style={{ margin: 0 }}>Modal Title</h3>
                            <button 
                                onClick={() => emit('close')} 
                                aria-label="Close"
                                style={{ 
                                    border: 'none', 
                                    background: 'none', 
                                    fontSize: '24px', 
                                    cursor: 'pointer' 
                                }}
                            >
                                ×
                            </button>
                        </div>
                        <div style={{ marginBottom: '16px' }}>
                            {slots.default?.()}
                        </div>
                        <div style={{ textAlign: 'right' }}>
                            <button 
                                onClick={() => emit('close')}
                                style={{ 
                                    padding: '8px 16px', 
                                    cursor: 'pointer',
                                    borderRadius: '6px'
                                }}
                            >
                                Close
                            </button>
                        </div>
                    </div>
                </div>
            </Portal>
        );
    };
});

const App = component(({ signal }) => {
    const state = signal({ showModal: false });

    return () => (
        <div>
            <button 
                onClick={() => state.showModal = true}
                style={{ padding: '10px 20px', cursor: 'pointer' }}
            >
                Open Modal
            </button>

            <Modal 
                open={state.showModal} 
                onClose={() => state.showModal = false}
            >
                <p>This modal is rendered via Portal to document.body!</p>
                <p>Click the backdrop or close button to dismiss.</p>
            </Modal>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Dropdown Example

A dropdown menu using Portal for proper stacking:

```tsx
import { component, Portal, render } from 'sigx';

const App = component(({ signal }) => {
    const state = signal({ open: false });
    let buttonRef: HTMLButtonElement | null = null;

    const getPosition = () => {
        if (!buttonRef) return { top: 0, left: 0 };
        const rect = buttonRef.getBoundingClientRect();
        return {
            top: rect.bottom + window.scrollY + 4,
            left: rect.left + window.scrollX
        };
    };

    return () => {
        const pos = getPosition();
        
        return (
            <div>
                <button 
                    ref={(el) => buttonRef = el}
                    onClick={() => state.open = !state.open}
                    style={{ padding: '10px 20px', cursor: 'pointer' }}
                >
                    {state.open ? 'Close' : 'Open'} Dropdown
                </button>

                {state.open && (
                    <Portal>
                        <div style={{
                            position: 'absolute',
                            top: `${pos.top}px`,
                            left: `${pos.left}px`,
                            background: 'white',
                            border: '1px solid #e5e7eb',
                            borderRadius: '8px',
                            boxShadow: '0 10px 25px rgba(0,0,0,0.1)',
                            padding: '8px 0',
                            minWidth: '150px',
                            zIndex: 1000
                        }}>
                            <div style={{ padding: '8px 16px', cursor: 'pointer' }}>Option 1</div>
                            <div style={{ padding: '8px 16px', cursor: 'pointer' }}>Option 2</div>
                            <div style={{ padding: '8px 16px', cursor: 'pointer' }}>Option 3</div>
                        </div>
                    </Portal>
                )}
            </div>
        );
    };
});

render(<App />, "#sandbox");
```

## State Preservation

Portal uses the `moveBefore` API (Chrome 133+) when available for state-preserving DOM moves. This means:

- **iframes** maintain their loaded content
- **videos** continue playing without interruption
- **form inputs** keep focus and selection
- **CSS animations** continue smoothly

On older browsers, Portal falls back to `insertBefore` which may reset some state.

## API Reference

### `Portal`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `string \| Element` | `document.body` | Target container (element or CSS selector) |
| `disabled` | `boolean` | `false` | When true, renders children in-place |

### Helper Functions

```tsx
import { supportsMoveBefore, component, render } from 'sigx';

const App = component(() => {
    const supported = supportsMoveBefore();
    
    return () => (
        <div style={{
            padding: '16px',
            borderRadius: '8px',
            background: supported ? '#d1fae5' : '#fef3c7',
            border: `1px solid ${supported ? '#10b981' : '#f59e0b'}`
        }}>
            <strong>moveBefore API:</strong> {supported ? '✅ Supported' : '⚠️ Not supported'}
            <p style={{ margin: '8px 0 0', fontSize: '14px', color: '#666' }}>
                {supported 
                    ? 'State-preserving DOM moves are available!' 
                    : 'Falls back to insertBefore (may reset iframe/video state)'}
            </p>
        </div>
    );
});

render(<App />, "#sandbox");
```

## Best Practices

### Accessibility & Focus Management

Ensure portaled content is accessible with proper ARIA attributes and focus management:

```tsx
import { component, Portal, render, onMounted, type Define } from 'sigx';

type ModalProps = Define.Prop<'open', boolean, true> & Define.Event<'close'>;

const AccessibleModal = component<ModalProps>(({ props, slots, emit }) => {
    let dialogRef: HTMLDivElement | null = null;

    onMounted(() => {
        // Auto-focus the first button when modal opens
        dialogRef?.querySelector('button')?.focus();
    });

    return () => {
        if (!props.open) return null;

        return (
            <Portal>
                <div 
                    onClick={(e) => e.target === e.currentTarget && emit('close')}
                    style={{
                        position: 'fixed',
                        inset: 0,
                        background: 'rgba(0,0,0,0.5)',
                        display: 'flex',
                        alignItems: 'center',
                        justifyContent: 'center',
                        zIndex: 1000
                    }}
                >
                    <div 
                        ref={(el) => dialogRef = el}
                        role="dialog" 
                        aria-modal="true"
                        aria-labelledby="modal-title"
                        style={{
                            background: 'white',
                            borderRadius: '12px',
                            padding: '24px',
                            minWidth: '300px'
                        }}
                    >
                        <h3 id="modal-title" style={{ marginTop: 0 }}>Accessible Modal</h3>
                        <p>This modal has:</p>
                        <ul style={{ fontSize: '14px' }}>
                            <li><code>role="dialog"</code></li>
                            <li><code>aria-modal="true"</code></li>
                            <li><code>aria-labelledby</code> linking to title</li>
                            <li>Auto-focus on open</li>
                        </ul>
                        <button 
                            onClick={() => emit('close')}
                            style={{ padding: '8px 16px', cursor: 'pointer' }}
                        >
                            Close (focused automatically)
                        </button>
                    </div>
                </div>
            </Portal>
        );
    };
});

const App = component(({ signal }) => {
    const state = signal({ open: false });
    
    return () => (
        <div>
            <button 
                onClick={() => state.open = true}
                style={{ padding: '10px 20px', cursor: 'pointer' }}
            >
                Open Accessible Modal
            </button>
            <AccessibleModal open={state.open} onClose={() => state.open = false} />
        </div>
    );
});

render(<App />, "#sandbox");
```

### Portal Roots & Cleanup

Create dedicated mount points for different overlay types. Portal automatically cleans up when unmounted:

```tsx
import { component, Portal, render } from 'sigx';

const App = component(({ signal }) => {
    const state = signal({ showModal: false, showTooltip: false });

    return () => (
        <div>
            {/* Create dedicated portal targets */}
            <div id="modal-root" />
            <div id="tooltip-root" />
            
            <div style={{ display: 'flex', gap: '8px', marginBottom: '16px' }}>
                <button 
                    onClick={() => state.showModal = !state.showModal}
                    style={{ padding: '8px 16px', cursor: 'pointer' }}
                >
                    Toggle Modal
                </button>
                <button 
                    onClick={() => state.showTooltip = !state.showTooltip}
                    style={{ padding: '8px 16px', cursor: 'pointer' }}
                >
                    Toggle Tooltip
                </button>
            </div>
            
            {state.showModal && (
                <Portal to="#modal-root">
                    <div style={{
                        padding: '16px',
                        background: '#3b82f6',
                        color: 'white',
                        borderRadius: '8px',
                        marginBottom: '8px'
                    }}>
                        📦 Modal content (in #modal-root)
                    </div>
                </Portal>
            )}
            
            {state.showTooltip && (
                <Portal to="#tooltip-root">
                    <div style={{
                        padding: '12px',
                        background: '#10b981',
                        color: 'white',
                        borderRadius: '6px'
                    }}>
                        💡 Tooltip content (in #tooltip-root)
                    </div>
                </Portal>
            )}
        </div>
    );
});

render(<App />, "#sandbox");
```

## Next Steps

- [Components](/core/docs/components) - Component patterns and composition
- [Lifecycle](/core/docs/lifecycle) - Mount and cleanup hooks
- [Lazy Loading](/core/docs/lazy-loading) - Code splitting with Defer

---
url: https://sigx.dev/mermaid/docs/api/
title: API reference
description: Every export of @sigx/mermaid, grouped by entry point
---

# API reference

<p class="lede">Exports of `@sigx/mermaid` .</p>

`mermaid` and `sigx` are **peer dependencies**; the package has no runtime dependencies of its own.

## `@sigx/mermaid`

| Export | Kind | Purpose |
|---|---|---|
| `Mermaid` | component | The diagram component. Props: `code` (required), `title`, `options`, `eager`, plus anything else forwarded to the `<figure>`. |
| `MermaidProps` | type | Its prop type. |
| `configureMermaid(options)` | function | Set global options. Calls **merge**. |
| `getMermaidConfig()` | function | Read the resolved global config. |
| `resetMermaidConfig()` | function | Clear it — useful between tests. |
| `mergeMermaidConfig(a, b)` | function | The merge used internally, exposed. |
| `loadMermaid()` | function | Load the mermaid module on demand. |
| `renderDiagram(…)` | function | Render one diagram imperatively; returns a `RenderResult`. |
| `resolveColorScheme()` | function | The detected scheme (`'light' \| 'dark'`). |
| `resolveTheme()` / `resolveSchemeTheme(scheme)` | function | The resolved theme for the active or a given scheme. |
| `defaultThemeVariables()` | function | The variables the package supplies. |
| `pageBackgroundColor()` | function | The detected page background — the input to scheme detection's last step. |
| `watchTheme(cb)` | function | Subscribe to appearance changes. |
| `resetMermaidLoader()` | function | Drop the cached module, for tests. |

### Option types

`MermaidOptions`, `MermaidSchemeTheme`, `MermaidThemeName`, `MermaidThemes`, `MermaidThemeVariables`, `RenderResult`.

`MermaidOptions` carries `themes`, `securityLevel`, `config` and `resolveColorScheme` — see [Configuration](/mermaid/docs/usage#configuration).

## `@sigx/mermaid/client`

Installs on import.

| Export | Purpose |
|---|---|
| `installMermaid(options?)` | Install explicitly; returns a disposer. Safe to call repeatedly. |
| `uninstallMermaid()` | Tear down whatever is installed. A no-op if nothing is. |
| `MermaidClientOptions` | `{ root?, rootMargin? }`. |

`configureMermaid` and `getMermaidConfig` are re-exported here, so a client-only entry needs one import.

## `@sigx/mermaid/ssg`

| Export | Purpose |
|---|---|
| `remarkMermaid(options?)` | The remark plugin — claims the fence on the markdown tree. **Prefer this one.** |
| `rehypeMermaid(options?)` | The rehype plugin — claims the fence on the HTML tree. Also the default export. |
| `RemarkMermaidOptions` | `{ language?, className? }`. |
| `RehypeMermaidOptions` | `{ language?, className? }`. |
| `mermaidThemeContribution` | Drop-in `ThemeConfig` slice for an `@sigx/ssg` theme — contributes `markdown.remarkPlugins` and `css`. |

Both plugins emit the same `<figure>` shell and neither renders an SVG. `remarkMermaid` runs before HTML conversion, so it never contends with the syntax highlighter; `rehypeMermaid` does, and needs `markdown.shiki.skipLanguages: ['mermaid']` alongside it.

See [SSG integration](/mermaid/docs/ssg).

## `@sigx/mermaid/styles`

The cosmetic stylesheet. Everything functional is done in JS with the `hidden` attribute, so a site that skips it still behaves correctly. Override the custom properties on `.sigx-mermaid` — see [Styling](/mermaid/docs/usage#styling).

---
url: https://sigx.dev/i18n/docs/server/
title: Server & SSR
description: Resolving the request locale, translating outside a component, and rendering into a locale other than the active one
---

# Server & SSR

<p class="lede">Translating on the server is a different shape from translating in a component: there is no active locale to read, because a server process handles every locale at once.</p>

So a locale is **bound**, not ambient.

## Per request

`createRequestT` builds once and binds per request — the shape a server function wants:

```ts
import { createRequestT } from '@sigx/i18n/server';
import catalogs from 'virtual:sigx-i18n/server-catalogs';

const requestT = createRequestT({ catalogs, fallbackLocale: 'en', supported: ['en', 'sv'] });

export const greet = serverFn({
    allowAnonymous: true,
    handler: async (rq) => requestT(rq.request).forNamespace('mail').greeting({ name: 'Ada' }),
});
```

It runs the detection chain against the request and hands back a translator bound to the negotiated locale.

`@sigx/server` is deliberately **not** imported here. You pass `rq.request`, so the same function works from a plain fetch handler in a platform entry, with no dependency in either direction.

## Standing catalogs

`createServerT` is the lower-level form, over an in-memory catalog tree:

```ts
import { createServerT } from '@sigx/i18n/server';

const t = createServerT({ catalogs, fallbackLocale: 'en', defaultNamespace: 'mail' });

const m = t.forLocale('sv').forNamespace('mail');
m.subject();                  // typed against the generated Schema
m.welcome({ name: 'Åsa' });
```

`t.t(key, params, { locale })` and `t.exists(key, { locale })` are the one-off forms; `forLocale(locale)` binds and everything else hangs off the result.

## Translating into a locale that isn't the active one

On the **client**, the active locale is ambient — that is the whole point of `useTranslation`. But some things are not "the current user's language":

- a preview pane showing how a page reads in another locale
- a list whose rows each carry their own locale
- an email or notification rendered for a *recipient's* stored preference

For those, pass the locale explicitly. It is available on every reader:

```tsx
const tSv = useTranslation('cart', { locale: 'sv' });      // pinned translator
const content = useDynamicTranslation('content', { locale: row.locale });

<T k="cart.title" locale={row.locale} />                    // per-element
```

The bound locale still walks its **own** fallback chain, so a message missing from `sv-FI` resolves through `sv` and then the master locale exactly as the active locale would.

The primitive underneath is `store.translateKey(key, params, { locale })`, and `store.forLocale(locale)` is the client-side mirror of the server's binder.

> **`locale` is typed `string`, not `KnownLocale`, on purpose.** The narrowed spellings are the ones you write as a literal next to `setLocale('sv')`. This one also carries *data* locales — a ticket's `row.locale`, a recipient's stored preference — which are `string` at the type level however carefully they were produced. Narrowing here would put a cast on the per-row case that is half the reason the option exists.

## SSR state transfer

The store is created lazily on the first `useTranslation()` **during render**, so under SSR it is constructed inside the request render and its state registration attaches to the correct per-request context. The catalogs the server resolved transfer to the client automatically — no second fetch on hydration.

The idiomatic preload is `initialMessages`: load the request's catalogs, pass them in, and the render stays synchronous while the state still transfers.

```ts
createI18n({
    fallbackLocale: 'en',
    initialMessages: await loadForRequest(locale),   // messages[locale][namespace]
});
```

`installPersistSSR` wires the persistence half for a server-rendered app.

## Resolving the locale from a request

```ts
import { resolveRequestLocale, localeCookie, localeSwitchUrl } from '@sigx/i18n';

const locale = resolveRequestLocale(request, { supported: ['en', 'sv'] });
```

`detectionContextFromRequest`, `parseAcceptLanguage` and `parseCookie` are the pieces if you need to assemble it yourself. `localeCookie` and `localeSwitchUrl` build the response side of a locale switch.

## Next steps

- [API reference](/i18n/docs/api) — every export.

---
url: https://sigx.dev/deploy/docs/deno/
title: Deno & Deno Deploy
description: Deploying to Deno — the inline SigxAdapter (no package), the bundled build, and the serveDir static tier
---

# Deno & Deno Deploy

<p class="lede">Deno needs no adapter package — a `SigxAdapter` is a plain object, and hand-rolling it in your Vite config *is* the documentation. The build goes bundled because Deno cannot select custom export conditions at runtime.</p>

## The config

```ts
// vite.config.deno.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [
        sigx({
            ssr: {
                entry: 'src/entry-server.tsx',
                clientOutDir: 'dist-deno/client',
                serverOutDir: 'dist-deno/server',
                adapter: {
                    name: 'deno',
                    serverBuild: 'bundled',
                    conditions: ['deno'],
                    // jsr: specifiers stay runtime imports — Deno fetches
                    // and caches them itself.
                    runtimeExternal: [/^jsr:/],
                    entry: 'src/entry.deno.ts'
                }
            }
        })
    ]
});
```

`serverBuild: 'bundled'` bakes the production dists in at build time (no
`--conditions` flag exists in Deno), and `runtimeExternal: [/^jsr:/]` leaves
`jsr:` imports for Deno to resolve natively.

## The entry

```ts
// src/entry.deno.ts — static → server functions → document render
import { serveDir } from 'jsr:@std/http@^1.0.0/file-server';
import { createFetchHandler } from '@sigx/server-renderer/server';
import { template, assets } from 'virtual:sigx-app';
import { createApp } from './entry-server';

const handler = createFetchHandler({
    template,
    app: (url) => createApp(url),
    document: { assets }
});

Deno.serve({ port: 8000 }, async (request: Request): Promise<Response> => {
    // Static tier is GET/HEAD-only: serveDir answers other methods with
    // 405 (not 404), which would swallow server-fn POSTs. showIndex: false
    // keeps the raw outlet template off '/', and the explicit /index.html
    // guard keeps the template file itself unreachable — documents belong
    // to the render.
    const { pathname } = new URL(request.url);
    if ((request.method === 'GET' || request.method === 'HEAD') && pathname !== '/index.html') {
        const res = await serveDir(request, {
            fsRoot: 'dist-deno/client',
            quiet: true,
            showIndex: false
        });
        if (res.status !== 404) return res;
    }
    return handler(request);
});
```

Statics ride the standard library's `serveDir` — the runtime's own file server
(a hand-rolled sigx one is a deliberate refusal: traversal, ranges and caching
are security surface the platform already owns). Using server functions? Mount
`matchesServerFn`/`handleServerFnRequest` between the static tier and the
render, exactly as in the
[entry contract](/deploy/docs/overview/#the-entry-contract).

## Build, run, deploy

```bash
vite build --app -c vite.config.deno.ts
deno run --allow-net --allow-read --allow-env dist-deno/server/entry.deno.js
deno deploy   # ship it to Deno Deploy
```

The reference wiring — `vite.config.deno.ts` + the committed
`src/entry.deno.ts` — lives at `examples/resume` in the
[SignalX core repo](https://github.com/signalxjs/core), exercised by CI.

---
url: https://sigx.dev/use/docs/use-now/
title: useNow
description: The current time as a reactive Date, updated on an interval — optionally with pause/resume controls
---

# useNow

The current time as a reactive `Date`, updated every `interval` ms (default `1000`). Cross-platform — import from `@sigx/use`.

```ts
import { computed } from 'sigx';
import { useNow } from '@sigx/use';

const now = useNow();
const clock = computed(() => now.value.toLocaleTimeString());
```

> The `Date` is held by reference and replaced wholesale on each tick — `Date` is an exotic built-in sigx deliberately never proxies. Read `now.value` to get the current instant; don't mutate it in place.

The timer clears with the owning scope (component setup or the innermost `effectScope()`).

## Controls form

Pass `{ controls: true }` to also get [`Pausable`](/use/docs/conventions#control-handles-pausable-and-stop) controls alongside the time. The return shape then becomes `{ now, pause, resume, isActive }`:

```ts
import { useNow } from '@sigx/use';

const { now, pause, resume, isActive } = useNow({ controls: true, interval: 1000 });
pause(); // freeze the clock
```

## Signature

```ts
function useNow(): ReadSignal<Date>;
function useNow(options: UseNowOptions<true>): { now: ReadSignal<Date> } & Pausable;
function useNow(options: UseNowOptions<false>): ReadSignal<Date>;
```

## Options

| Option | Type | Default | Description |
|---|---|---|---|
| `interval` | `number` | `1000` | Update period in ms. |
| `controls` | `boolean` | `false` | Also return `pause`/`resume`/`isActive` controls. |

## Returns

| Call | Returns |
|---|---|
| `useNow()` | `ReadSignal<Date>` — the current time, bare. |
| `useNow({ controls: true })` | `{ now: ReadSignal<Date> } & Pausable` — the time plus `pause`/`resume`/`isActive`. |

**Platform:** everywhere (`setInterval`).

## See also

- [`useIntervalFn`](/use/docs/use-interval-fn) — the timer `useNow` is built on.
- [`useTimeoutFn`](/use/docs/use-timeout-fn) — a restartable one-shot timer.
- [Conventions → Control handles](/use/docs/conventions#control-handles-pausable-and-stop) — the `Pausable` contract the controls form returns.

---
url: https://sigx.dev/mermaid/docs/ssg/
title: SSG integration
description: Rendering mermaid fences in an @sigx/ssg site — remarkMermaid, the client enhancer and the theme contribution
---

# SSG integration

<p class="lede">Write a <code>```mermaid</code> fence in MDX and get a diagram. Two lines of
<a href="/ssg/docs/getting-started">@sigx/ssg</a> config, and nothing to keep in sync with the
highlighter.</p>

## Setup

```ts
// ssg.config.ts
import { defineSSGConfig } from '@sigx/ssg';
import { remarkMermaid } from '@sigx/mermaid/ssg';

export default defineSSGConfig({
    markdown: {
        remarkPlugins: [remarkMermaid],
    },
    clientImports: ['@sigx/mermaid/styles', '@sigx/mermaid/client'],
});
```

Two pieces:

1. **`remarkMermaid`** claims the fence on the **markdown** tree (mdast), before HTML
   conversion. Nothing downstream ever sees a mermaid fence — including the syntax
   highlighter — so there is no `skipLanguages` to configure and nothing to keep in step.
2. **`clientImports`** adds the styles and the enhancer that renders the diagrams in the
   browser.

Then write a fence:

````mdx
```mermaid title="Request flow"
sequenceDiagram
  Browser->>Server: GET /
  Server-->>Browser: HTML
```
````

`title` on the fence becomes the `<figcaption>`.

<div class="alert alert-info not-prose my-4">
  <div>
    <strong>Neither plugin renders anything.</strong> They emit a
    <code>&lt;figure data-sigx-mermaid&gt;</code> shell that the client enhancer upgrades to an
    SVG. Rendering at build time needs real text metrics (<code>getBBox</code>), which means a
    headless browser.
  </div>
</div>

## Where in the pipeline

Both plugins emit the same shell. They differ only in which stage hands them the tree, and that
difference decides whether the highlighter is a problem:

| | stage | tree | interacts with the highlighter? |
|---|---|---|---|
| `remarkMermaid` | markdown | mdast | **No** — it claims the fence before HTML conversion |
| `rehypeMermaid` | HTML | hast | **Yes** — it claims whatever `<pre><code class="language-mermaid">` is still in the tree when it runs, so anything ordered before it can take the fence first |

Prefer `remarkMermaid`. Reach for `rehypeMermaid` only when the fence has to survive into the
HTML tree for something else to see first — and then order it deliberately and add
`markdown.shiki.skipLanguages: ['mermaid']`, or the highlighter gets there first and there is
nothing left to claim.

The plugins are **optional** either way: `@sigx/mermaid/client` also claims a bare
`pre > code.language-mermaid`. What the shell buys is a stable class hook, a `<figcaption>`
from the fence's `title=`, and a reserved box so the page does not jump when the SVG lands.

## Plugin options

Usable bare (`remarkPlugins: [remarkMermaid]`) or configured
(`remarkPlugins: [[remarkMermaid, { language: 'mmd' }]]`). Both plugins take the same two:

| Option | Default | Description |
| --- | --- | --- |
| `language` | `'mermaid'` | The fence language this plugin claims. |
| `className` | `'sigx-mermaid'` | Class on the emitted `<figure>`. |

For `rehypeMermaid` the language is matched as `language-<language>` on the `<code>`, which
must still be present when the plugin runs.

## The client enhancer

Importing `@sigx/mermaid/client` installs it. For control over where and when it looks:

```ts
import { installMermaid } from '@sigx/mermaid/client';

installMermaid({ rootMargin: '400px' });
```

| Option | Default | Description |
| --- | --- | --- |
| `root` | the document | Where to look — for the initial scan **and** the observer that catches diagrams added later. Diagrams outside it are left alone. With the default, the observer narrows to `#app`, falling back to `<body>`. |
| `rootMargin` | `'200px'` | How far outside the viewport to start rendering. |

`installMermaid` is safe to call repeatedly — only the first call does anything — and returns a
disposer. `uninstallMermaid()` tears down whatever is installed, whether it came from an
explicit call or from importing the module.

**Failures degrade visibly.** A diagram that fails to parse leaves its source on the page with
`data-mermaid-state="error"`, never a blank box.

## Contributing it from a theme

An `@sigx/ssg` theme can carry the integration so every site using it gets diagrams:

```ts
import { mermaidThemeContribution } from '@sigx/mermaid/ssg';

export const myTheme = {
    ...mermaidThemeContribution,
};
```

`applyThemeConfig` merges `markdown.remarkPlugins` and prepends the `css` entries to
`clientImports`. Because the contribution is remark-stage, a site adopting the theme adds
**nothing** — there is no `skipLanguages` line for it to own.

## Next steps

- [API reference](/mermaid/docs/api) — every export.

---
url: https://sigx.dev/deploy/docs/bun/
title: Bun
description: Deploying to Bun — the shared external build, Bun.serve({ fetch }) and Bun.file statics
---

# Bun

<p class="lede">Bun consumes the **same external build as Node** — it resolves `node_modules` and honors export conditions — so there is nothing platform-specific to build. One `server.bun.ts` with `Bun.serve` is the whole deployment.</p>

## The build

No separate config: run the standard build.

```bash
vite build --app
```

Bun runs the externalized `dist/` directly — dependencies resolve from
`node_modules` at startup, same as Node.

## The server

```ts
// server.bun.ts — static → server functions → document render
import { createFetchHandler } from '@sigx/server-renderer/server';
import { template, assets } from './dist/server/sigx-app.js';
import { createApp } from './dist/server/entry-server.js';
import { join, resolve, sep } from 'node:path';

const clientDir = resolve('dist/client');

const handler = createFetchHandler({
    template,
    app: (url: string) => createApp(url),
    document: { assets }
});

Bun.serve({
    port: Number(process.env.PORT) || 3000,
    async fetch(request: Request): Promise<Response> {
        const { pathname } = new URL(request.url);

        // Static tier: GET/HEAD-only, exact file paths only, and the raw
        // outlet template (index.html) is explicitly unreachable — it must
        // never shadow the document render.
        if (
            (request.method === 'GET' || request.method === 'HEAD') &&
            pathname !== '/' && !pathname.endsWith('/') &&
            pathname !== '/index.html'
        ) {
            const filePath = resolve(join(clientDir, decodeURIComponent(pathname)));
            if (filePath.startsWith(clientDir + sep)) {    // guards ../ traversal
                const file = Bun.file(filePath);
                if (await file.exists()) return new Response(file);
            }
        }

        return handler(request);
    }
});
```

Statics are served with `Bun.file` — the runtime's own file responses
(content-type, streaming); the resolved-prefix check guards path traversal.
Using server functions? Mount `matchesServerFn`/`handleServerFnRequest` between
the static tier and the render, as in the
[entry contract](/deploy/docs/overview/#the-entry-contract).

## Run

```bash
bun --conditions=production server.bun.ts
```

`--conditions=production` selects the production dists, mirroring the Node
server's flag. The reference `server.bun.ts` (including the server-fn mount and
the hardened static tier) lives at `examples/resume` in the
[SignalX core repo](https://github.com/signalxjs/core), exercised by CI.

---
url: https://sigx.dev/deploy/docs/node/
title: Node
description: The default deployment — nodeAdapter(), the externalized build, server.mjs and one sigx-app.js import
---

# Node

<p class="lede">Node is the default: no adapter to install, an externalized server build, and a `server.mjs` you own. One import — `dist/server/sigx-app.js` — replaces four `readFile`s.</p>

## The build

`sigx({ ssr: { entry } })` without an adapter **is** the Node deployment —
`nodeAdapter()` (`serverBuild: 'external'`) produces today's output,
byte-identical to pre-adapter builds: dependencies resolve from `node_modules`
at runtime, so the bundle stays small and the runtime keeps one DI-token
identity.

```bash
vite build --app
```

## The server

The [full SSR app guide](/server/packages/server-renderer/full-app) builds this
up step by step; the deployment shape is:

```js
// server.mjs (prod branch) — static → server functions → document render
import express from 'express';
import { createRequestHandler } from '@sigx/server-renderer/node';
import { createServerFnHandler } from '@sigx/server/node';

// ONE import replaces four readFiles: the build materializes
// template/assets/manifests as dist/server/sigx-app.js.
const { template, assets } = await import('./dist/server/sigx-app.js');
const { createApp } = await import('./dist/server/entry-server.js');
const { serverFns } = await import('./dist/server/sigx-server-fns.js');

const app = express();
// The raw outlet template must never be served: index: false keeps it off
// '/', and the explicit guard keeps /index.html itself unreachable.
app.get('/index.html', (_req, res) => res.redirect(301, '/'));
app.use(express.static('dist/client', { index: false }));
app.use(createServerFnHandler({ resolve: (s) => serverFns[s]?.() ?? null }));
app.use(createRequestHandler({ template, app: (url) => createApp(url), document: { assets } }));

app.listen(process.env.PORT ?? 3000);
```

`index: false` keeps the raw outlet template off `/` — the
[static-tier rule](/deploy/docs/overview/#the-static-tier-rules) every platform
shares.

### The AsyncLocalStorage cost

On Node, the request scope backing in-process calls resolves an
`AsyncLocalStorage` through a dynamic `import('node:async_hooks')`. **Only the
first scope entry is asynchronous**; every one after it enters synchronously, so
the per-request cost is a synchronous store entry rather than an awaited promise.

The observable consequence is a widened return type: entering the scope yields
`T | Promise<T>` rather than `Promise<T>`. Awaiting it is unaffected — what breaks
is treating the result as a thenable *without* awaiting, such as
`runInScope(rq, fn).then(…)` or passing it to something that requires a real
`Promise`. Wrap it in `Promise.resolve(…)`, or just `await` it.

`runWithServerFnContext` imports `node:async_hooks` dynamically, so merely loading
`@sigx/server/node` does not pull it on a runtime that lacks it — only calling the
function does. Where ALS is unavailable (workerd without `nodejs_compat`), there
is no scope to share, so a per-request value is computed per invocation;
`.with({ context })` behaves identically and needs no ALS.

## Run

```bash
node --conditions production server.mjs
```

`--conditions production` selects the `NODE_ENV`-stripped production dists (the
server works without it too). Use your process manager of choice — the server
is a plain Node HTTP app.

## Prefer the fetch shape?

`createFetchHandler` runs on Node too (Node 18+ has WinterCG primitives) — but
`createRequestHandler` from `@sigx/server-renderer/node` is the
Node-native `(req, res)` handler and drops into Express/Connect/Polka
middleware chains, so it stays the recommended shape here. The reference server
lives at `examples/resume/server.mjs` in the
[SignalX core repo](https://github.com/signalxjs/core).

---
url: https://sigx.dev/i18n/docs/usage/
title: Translating
description: useTranslation, the <T> component, namespaces, plurals and rich text
---

# Translating

<p class="lede">Read a message with <code>useTranslation</code>, or place one declaratively with <code>&lt;T&gt;</code>. Both are reactive — switch the locale and everything re-renders.</p>

## `useTranslation`

```tsx
import { component } from 'sigx';
import { useTranslation } from '@sigx/i18n';

const Cart = component(() => {
    const t = useTranslation('cart');

    return () => (
        <div>
            <h1>{t('title')}</h1>
            <p>{t('items', { count: items.value.length })}</p>
        </div>
    );
});
```

The namespace is checked against the generated schema, and so are the keys. Call it without one and you get `defaultNamespace` (`'translation'` unless you changed it).

Pin a call to a locale that is not the active one — a preview pane, a row that carries its own locale — with the `locale` option:

```tsx
const tSv = useTranslation('cart', { locale: 'sv' });
```

## `<T>`

The declarative form, for placing a message in markup:

```tsx
<T k="cart.items" params={{ count }} />
<T ns="content" k={block.labelKey} default={block.label} />
<T k="cart.title" locale={row.locale} />
```

It is renderer-agnostic — on lynx it goes inside a `<text>` element exactly as any other string would:

```tsx
<text><T k="cart.title" /></text>
```

## Rich text

A message that needs markup in the middle of a sentence cannot be split without breaking translation — word order differs per language. Pass `components` and the tags in the message are mapped to nodes:

```tsx
<T k="legal.terms" components={{ a: (c) => <a href="/terms">{c}</a> }} />
```

```json
{ "legal": { "terms": "Please read our <a>terms of service</a> before continuing." } }
```

The splitting is non-nested, and an unknown tag stays literal. **You supply the nodes**, which is what keeps this renderer-agnostic — the library only positions them, so a lynx app passes lynx elements and the same message works.

`renderRich(text, components)` is the underlying function if you need it directly.

## Namespaces

A namespace is a **unit of loading**. List the ones your first paint needs:

```ts
createI18n({
    fallbackLocale: 'en',
    namespaces: ['common', 'nav'],     // loaded up front
    load: (target, locale, ns) => import(`./locales/${target}/${locale}/${ns}.json`),
});
```

Leave section-specific namespaces out and they load on first use, so a settings page's catalog does not sit in the initial payload.

## Fallback

`fallbackLocale` is the **master** locale — the source of truth for which keys exist. A key missing from the active locale falls through to it; `onMissing` decides what happens when it is missing from both.

Resolution walks a chain: BCP-47 truncation (`sv-FI` → `sv` → the fallback), plus any explicit `localeFallbacks` you declare.

A message is always formatted **in the locale it was found in**. That matters for plurals: a Swedish string found in the Swedish catalog selects its plural form by Swedish rules, even if the request asked for `sv-FI`.

## Layers

`layers` turns on per-**key** layering, for the case where a tenant or a brand overrides a handful of messages and everything else should keep falling through:

```ts
createI18n({
    fallbackLocale: 'en',
    layers: ['base', 'tenant'],        // lowest priority first
    loaders: { base: loadBase, tenant: loadTenant },
});
```

An override layer supplies a few keys; every other key falls through to the layer below, **including keys the base gains in a later version** — so a tenant override does not freeze that tenant's catalog at the version it forked from.

Layers compose *within* one locale and the locale chain is walked after. A `base` message in the requested locale therefore beats a `tenant` override that exists only in a fallback locale — which keeps the message formatted in the locale it was found in.

Omit `layers` entirely for single-source behaviour: nothing is composed and nothing is allocated.

## Next steps

- [Locales](/i18n/docs/locales) — detection, switching and persistence.
- [Runtime catalogs](/i18n/docs/runtime-catalogs) — keys that are not known at build time.

---
url: https://sigx.dev/router/docs/ssr/
title: SSR Routing
description: Configure @sigx/router for server-side rendering with memory history and client hydration
---

# SSR Routing

On the server there is no browser `History` API, so the router needs a different
history backend. `@sigx/router` ships two history implementations:

| History | Environment | Purpose |
|---|---|---|
| `createWebHistory()` | Browser | Uses the browser History API for SPA navigation |
| `createHashHistory()` | Browser (static hosts) | Uses `/#/path` URLs — no server-side SPA fallback needed (GitHub Pages, S3, Electron) |
| `createMemoryHistory()` | Server / Tests | Keeps navigation state in memory — no DOM required |

The core idea is simple: **create the router per-request on the server** with
`createMemoryHistory`, and **once on the client** with `createWebHistory`.

## Setup — Router Factory

Define your routes once and export two factory functions — one for each
environment:

```ts
// src/router.ts
import {
    createRouter,
    createWebHistory,
    createMemoryHistory,
    type RouteRecordRaw,
} from '@sigx/router';
import { Home } from './pages/Home';
import { About } from './pages/About';
import { BlogIndex } from './pages/BlogIndex';
import { BlogPost } from './pages/BlogPost';

export const routes: RouteRecordRaw[] = [
    { path: '/', name: 'home', component: Home },
    { path: '/about', name: 'about', component: About },
    { path: '/blog', name: 'blog', component: BlogIndex },
    { path: '/blog/:slug', name: 'blog-post', component: BlogPost },
];

/** Browser — uses the History API */
export function createClientRouter() {
    return createRouter({
        history: createWebHistory(),
        routes,
    });
}

/** Server — receives the request URL and resolves the route in memory */
export function createServerRouter(url: string) {
    return createRouter({
        history: createMemoryHistory({ initialLocation: url }),
        routes,
    });
}
```

> **Why a factory?** Each incoming HTTP request must get its own router instance.
> Sharing a single router across requests would leak state between users.

## Server-Side Rendering

The server entry creates a fresh app + router for every request and renders it
to HTML with `@sigx/server-renderer`.

```tsx
// src/entry-server.tsx
import { defineApp } from 'sigx';
import { createSSR } from '@sigx/server-renderer';
import { App } from './App';
import { createServerRouter } from './router';

const ssr = createSSR();

export async function render(url: string) {
    const router = createServerRouter(url);
    const app = defineApp(<App />).use(router);
    return await ssr.render(app);
}
```

Then wire it into your HTTP server (Express shown here, but any Node framework
works):

```ts
// server.ts
import express from 'express';
import { render } from './entry-server';

const app = express();

app.use(express.static('dist/client'));

app.get('*', async (req, res) => {
    try {
        const html = await render(req.url);
        res.status(200).set({ 'Content-Type': 'text/html' }).send(`
            <!DOCTYPE html>
            <html>
            <head><title>My App</title></head>
            <body>
                <div id="root">${html}</div>
                <script type="module" src="/entry-client.js"></script>
            </body>
            </html>
        `);
    } catch (err) {
        console.error(err);
        res.status(500).send('Internal Server Error');
    }
});

app.listen(3000);
```

### Streaming

For large pages you can stream HTML to the client instead of buffering the
full string. `createSSR()` supports several streaming modes:

```ts
// ReadableStream (Web Streams API)
const stream = ssr.renderStream(app);

// Node.js Readable stream
const nodeStream = ssr.renderNodeStream(app);

// Callback-based streaming for fine-grained control
await ssr.renderStreamWithCallbacks(app, {
    onShellReady(html) { /* send the initial shell */ },
    onAsyncChunk(chunk) { /* stream async component updates */ },
    onComplete() { /* finalize the response */ },
    onError(err) { /* handle errors */ },
});
```

## Client Hydration

On the client, create the router with `createWebHistory()` and **hydrate**
instead of mounting:

```tsx
// src/entry-client.tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';
import { createClientRouter } from './router';

const router = createClientRouter();

function startHydration() {
    defineApp(<App />)
        .use(router)
        .use(ssrClientPlugin)
        .hydrate('#root');
}

// Wait for streaming to finish before hydrating
if (window.__SIGX_STREAMING_COMPLETE__) {
    startHydration();
} else {
    window.addEventListener('sigx:ready', startHydration, { once: true });
}
```

The client reuses the same `routes` array, so route matching is identical on
both sides. Once hydrated, navigation is handled entirely in the browser via
`createWebHistory()`.

## Common Patterns

### Route-Based Data Loading

Load data on the server before rendering with a keyed [`useData`](/core/docs/data-loading)
read inside component setup. A keyed read runs during SSR, serializes its value
into the page, and restores on hydration without refetching — key it off the route
param so it re-fetches on client navigation.

```tsx
import { component, useData } from 'sigx';
import { useParams } from '@sigx/router';

export const BlogPost = component(() => {
    const params = useParams();

    // Keyed on the slug: runs on the server, restores on hydration,
    // re-fetches whenever the route param changes.
    const post = useData(() => `post:${params.slug}`, async (key, { signal }) => {
        const res = await fetch(`/api/posts/${params.slug}`, { signal });
        return res.json() as Promise<Post>;
    });

    return () => (
        <article>
            {post.match({
                pending: () => <p>Loading…</p>,
                error: (e, retry) => <p>Failed: {e.message} <button onClick={retry}>Retry</button></p>,
                ready: (p) => <><h1>{p.title}</h1><div>{p.body}</div></>,
            })}
        </article>
    );
});
```

### Redirects During SSR

Guards and route-record `redirect`s run on the **initial** route resolution, so a
guarded or redirected URL is resolved in memory on the server before any HTML is
produced. Wait for that to finish with `await router.isReady()`, then read the
resolved route to emit a real 30x — don't just send the rendered HTML under the
requested URL.

```ts
// router.ts — a route-record redirect, or any guard that returns a location
export const routes: RouteRecordRaw[] = [
    { path: '/old-page', redirect: '/new-page' },
    // ...other routes
];
```

When a guard or `redirect` sends the navigation elsewhere, the resolved route carries
the original location on `currentRoute.redirectedFrom`. The server handler checks for
it (and, as a fallback, compares the resolved path to the requested one) and replies
with a 302:

```ts
// Imports and `const ssr = createSSR()` as in the entry-server example above.
export async function render(url: string) {
    const router = createServerRouter(url);
    const app = defineApp(<App />).use(router);

    // Let the initial navigation — including guards and redirects — settle.
    await router.isReady();

    const resolved = router.currentRoute;
    const redirect =
        resolved.redirectedFrom != null || resolved.fullPath !== url
            ? resolved.fullPath
            : null;

    if (redirect) return { html: null, redirect };

    const html = await ssr.render(app);
    return { html, redirect: null };
}

// server.ts
app.get('*', async (req, res) => {
    const { html, redirect } = await render(req.url);
    if (redirect) {
        return res.redirect(302, redirect);
    }
    res.status(200).send(/* ... */);
});
```

> An initial redirect uses **replace** semantics, so the redirected-away URL never
> enters the client's history — Back won't return to it after hydration.

## Next Steps

- [Getting Started](/router/docs/getting-started) — Basic router setup
- [Navigation](/router/docs/navigation) — Programmatic navigation
- [Route Guards](/router/docs/guards) — Protect routes with guards

---
url: https://sigx.dev/monaco/docs/api/
title: API Reference
description: "@sigx/monaco-editor — pluggable Monaco editor wrapper with prebundled assets and a Vite plugin — API reference"
---

# API Reference

Unless noted, everything below is exported from the main entry `@sigx/monaco-editor`. The Vite plugin lives at `@sigx/monaco-editor/vite`, the Shiki integration at `@sigx/monaco-editor/shiki`, and individual language packs at `@sigx/monaco-editor/languages/*`.

## Loader

### loadMonaco

```ts
export async function loadMonaco(): Promise<typeof Monaco>
```

Lazy-loads Monaco using the configured strategy (`prebundled` or `cdn`). Idempotent: returns the cached instance after the first call and dedupes concurrent calls via an in-flight promise. On first load it applies all pending setup (languages, themes, extraLibs) registered via `configureMonaco()`. Returns the Monaco namespace.

### isMonacoLoaded

```ts
export function isMonacoLoaded(): boolean
```

Returns `true` once Monaco is loaded into memory (that is, once `loadMonaco()` has resolved at least once).

### getMonaco

```ts
export function getMonaco(): typeof Monaco
```

Synchronous accessor for the loaded Monaco namespace. Throws `[@sigx/monaco-editor] Monaco not loaded. Call loadMonaco() first.` if Monaco has not been loaded yet.

### configureMonacoLoader

```ts
export function configureMonacoLoader(config: Partial<MonacoLoaderConfig>): void
```

Overrides the load strategy, `basePath`, `cdnUrl`, or `version`. Merges onto the current config. Must be called before `loadMonaco()`; warns to the console if called after Monaco is already loaded (the change won't take effect until reload).

- `config` — partial loader configuration to merge.

### configureMonaco

```ts
export function configureMonaco(setup: MonacoSetup): void
```

Registers language packs, themes, and extra `.d.ts` libs to apply when Monaco loads. Accumulates across calls. If Monaco is already loaded, the new setup is applied immediately to the live instance (the call itself returns `void`).

- `setup` — the languages, themes, and extraLibs to register.

### getLoaderConfig

```ts
export function getLoaderConfig(): MonacoLoaderConfig
```

Returns a shallow copy of the current loader config (`strategy`, `basePath`, `cdnUrl`, `version`).

## Editor

### createEditor

```ts
export async function createEditor(options: CreateEditorOptions): Promise<MonacoEditorInstance>
```

Imperative low-level editor creation. Awaits `loadMonaco()`, creates a uniquely-named `file:///playground-<n><ext>` model, runs the TSX/JSX extension dance (creates the model as `typescript`/`javascript` so the TS worker treats it correctly, then swaps the model language to `tsx`/`jsx` for highlighting), merges shorthand options into Monaco defaults, wires `onChange` via `onDidChangeModelContent`, and returns the standalone code editor.

Defaults: `theme` `'vs-dark'`, `readOnly` `false`, minimap off, `lineNumbers` `'on'`, `fontSize` `14`, `automaticLayout` `true`, `tabSize` `2`, `wordWrap` `'on'`, `fixedOverflowWidgets` `true`. `language` defaults to `'typescript'`.

- `options` — see [CreateEditorOptions](#createeditoroptions).
- Returns a live `IStandaloneCodeEditor`.

### MonacoEditor

```ts
export const MonacoEditor: (props: MonacoEditorProps) => /* sigx component */
```

SignalX component wrapper (created via `component<MonacoEditorProps>()`). On mount it lazy-loads Monaco and calls `createEditor()` with the props; disposes the editor on unmount. Reactively mirrors prop changes onto the live editor:

- `model` — two-way bound content. When supplied it is the source of truth and takes precedence over `value`; editor edits are written back through `props.model.value`. See [Two-way model binding](/monaco/docs/getting-started#two-way-model-binding).
- `value` — one-way content (pair with `onChange`); applied to the model (guards against echo loops from `onChange`).
- `language` — applied via `monaco.editor.setModelLanguage`.
- `theme` — applied via `monaco.editor.setTheme` (global; affects all editors).
- `readOnly` — applied via `editor.updateOptions`.

Renders a single `<div>` with `class` (default `'sigx-monaco-editor'`) and `style` (default `'width: 100%; height: 100%;'`). Calls `onReady` once with the live editor instance.

## Language packs

### typescriptLanguagePack

```ts
export function typescriptLanguagePack(options?: TypescriptPackOptions): LanguagePack
```

Builds a `LanguagePack` registering four language ids: `typescript`, `javascript`, `tsx`, `jsx`. Its `setup()` configures Monaco's TS/JS compiler and diagnostics defaults (ESNext target/module, ReactJSX, `jsxImportSource` default `'react'`, `allowNonTsExtensions`, `allowJs`, `strict` `false`, `noEmit`, `esModuleInterop`, NodeJs resolution) and registers completion and hover providers for the tsx/jsx ids so IntelliSense keeps working when Shiki provides highlighting. `workerLabel`: `'typescript'`. Supports Monaco 0.55 (`monaco.typescript`) and older (`monaco.languages.typescript`).

Entry: `@sigx/monaco-editor/languages/typescript` or the main barrel.

- `options` — see [TypescriptPackOptions](#typescriptpackoptions).

### htmlLanguagePack

```ts
export function htmlLanguagePack(): LanguagePack
```

Builds a `LanguagePack` for HTML. id `'html'`, extensions `['.html', '.htm']`, `workerLabel` `'html'`. No `setup` (Monaco ships the HTML language; handlebars/razor reuse the same worker). Entry: `@sigx/monaco-editor/languages/html` or the main barrel.

### cssLanguagePack

```ts
export function cssLanguagePack(): LanguagePack
```

Builds a `LanguagePack` for CSS/SCSS/LESS (one CSS worker handles all three). id `'css'`, extensions `['.css']`, `workerLabel` `'css'`. No `setup`. Entry: `@sigx/monaco-editor/languages/css` or the main barrel.

### jsonLanguagePack

```ts
export function jsonLanguagePack(options?: JsonPackOptions): LanguagePack
```

Builds a `LanguagePack` for JSON. id `'json'`, extensions `['.json']`, `workerLabel` `'json'`. `setup()` calls `jsonDefaults.setDiagnosticsOptions` with `validate` (default `true`), `enableSchemaRequest` (default `true`), and `schemas` (default `[]`). Supports `monaco.json` and `monaco.languages.json`. Entry: `@sigx/monaco-editor/languages/json` or the main barrel.

- `options` — see [JsonPackOptions](#jsonpackoptions).

## Shiki

### applyShikiThemes

```ts
export async function applyShikiThemes(monaco: MonacoNamespace, options: ApplyShikiOptions): Promise<ApplyShikiResult>
```

Optional Shiki integration (subpath `@sigx/monaco-editor/shiki`). Dynamically imports `shiki/core`, `shiki/engine/javascript`, and `@shikijs/monaco` (optional peer deps), creates a `HighlighterCore` with the JS regex engine using the passed-in themes and langs, optionally registers `monacoLanguages` first, then calls `shikiToMonaco` to wire TextMate grammars and themes into the Monaco instance. Returns `{ highlighter }` so the consumer can reuse it for non-Monaco code.

- `monaco` — the loaded Monaco namespace (from `loadMonaco()` / `getMonaco()`).
- `options` — see [ApplyShikiOptions](#applyshikioptions).

## Vite plugin

### monacoPrebundledPlugin

```ts
export function monacoPrebundledPlugin(options?: MonacoPrebundledPluginOptions): Plugin
```

Vite plugin (subpath `@sigx/monaco-editor/vite`; also the default export of that module). `enforce: 'pre'`. Intercepts every `monaco-editor` import (resolve alias + `resolveId` + regex transform of static, dynamic, and type-only imports), replacing it with a virtual stub that throws at runtime, and excludes `monaco-editor` from `optimizeDeps` so the bundler never touches Monaco.

- For `prebundled` (default): serves `public/monaco-bundle/*` via a dev middleware (with a path-traversal guard and immutable cache headers) and emits the bundle files (read from `manifest.json`) into the production build.
- For `cdn`: marks `monaco-editor` as a Rollup external.

In both modes it injects a `<script>` setting `window.__MONACO_LOADER_CONFIG__` into the `index.html` head so the runtime loader picks up the strategy/basePath (or cdn version/url).

- `options` — see [MonacoPrebundledPluginOptions](#monacoprebundledpluginoptions).

### default export

```ts
export default monacoPrebundledPlugin
```

The vite-plugin module's default export is the same `monacoPrebundledPlugin` function.

## Types

### MonacoLoaderConfig

```ts
export interface MonacoLoaderConfig {
    strategy: 'prebundled' | 'cdn';
    basePath?: string;
    cdnUrl?: string;
    version?: string;
}
```

Loader configuration. `basePath`: base URL where the prebundled `monaco.min.js`/workers/CSS live. `cdnUrl`: optional CDN override (default unpkg). `version`: Monaco version to fetch from the CDN.

### MonacoSetup

```ts
export interface MonacoSetup {
    languages?: LanguagePack[];
    themes?: ThemePack[];
    extraLibs?: ExtraLib[];
}
```

Argument to `configureMonaco()`: language packs to register, themes to define, and extra `.d.ts` content to inject into the TS service.

### CreateEditorOptions

```ts
export interface CreateEditorOptions {
    container: HTMLElement;
    value: string;
    language?: string;
    theme?: string;
    readOnly?: boolean;
    minimap?: boolean;
    lineNumbers?: 'on' | 'off' | 'relative';
    fontSize?: number;
    monacoOptions?: MonacoEditorConstructionOptions;
    onChange?: (value: string) => void;
}
```

Options for `createEditor()`. `language` may be a generic id (`'typescript'`) or a JSX/TSX flavor. `monacoOptions` are merged on top of the derived defaults. `onChange` fires on every content change.

### MonacoEditorProps

```ts
export interface MonacoEditorProps extends Define.Model<string> {
    value?: string;
    language?: string;
    theme?: string;
    readOnly?: boolean;
    minimap?: boolean;
    lineNumbers?: 'on' | 'off' | 'relative';
    fontSize?: number;
    class?: string;
    style?: string | Record<string, string | number>;
    monacoOptions?: MonacoEditorConstructionOptions;
    onChange?: (value: string) => void;
    onReady?: (editor: MonacoEditorInstance) => void;
}
```

Props for the `<MonacoEditor />` component. Extends [`Define.Model<string>`](/core/api/types#definemodel), adding a `model` prop for [two-way binding](/monaco/docs/getting-started#two-way-model-binding) — when supplied it takes precedence over `value`. Use `value` (paired with `onChange`) for one-way binding. `value`/`language`/`theme`/`readOnly` are reactive. `class`/`style` control the container. `onReady` fires once with the live editor instance after creation.

### TypescriptPackOptions

```ts
export interface TypescriptPackOptions {
    jsxImportSource?: string;
    compilerOptions?: Record<string, unknown>;
    diagnosticsOptions?: { noSemanticValidation?: boolean; noSyntaxValidation?: boolean };
    skipJsxProviders?: boolean;
}
```

Options for `typescriptLanguagePack()`. `jsxImportSource` defaults to `'react'` (pass `'sigx'` for SignalX apps). `compilerOptions`/`diagnosticsOptions` merge over the pack defaults. `skipJsxProviders` (default `false`) skips the tsx/jsx completion and hover providers.

### JsonPackOptions

```ts
export interface JsonPackOptions {
    schemas?: Array<{ uri: string; fileMatch?: string[]; schema?: unknown }>;
    validate?: boolean;
    enableSchemaRequest?: boolean;
}
```

Options for `jsonLanguagePack()`. `schemas` are registered with Monaco's JSON service; `validate` (default `true`), `enableSchemaRequest` (default `true`).

### ApplyShikiOptions

```ts
export interface ApplyShikiOptions {
    themes: Array<Promise<unknown> | unknown>;
    langs: Array<Promise<unknown> | unknown>;
    monacoLanguages?: Array<{ id: string; extensions?: string[]; aliases?: string[] }>;
}
```

Options for `applyShikiThemes()`. `themes`/`langs` entries can be Promises from `import('@shikijs/themes/<name>')` / `import('@shikijs/langs/<name>')` or resolved objects. `monacoLanguages` are registered with Monaco before Shiki wires grammars (omit if already registered).

### ApplyShikiResult

```ts
export interface ApplyShikiResult {
    highlighter: unknown;
}
```

Return of `applyShikiThemes()`: the created `HighlighterCore`, reusable for highlighting static code outside Monaco.

### MonacoPrebundledPluginOptions

```ts
export interface MonacoPrebundledPluginOptions {
    strategy?: 'prebundled' | 'cdn';
    publicPath?: string;
    cdnUrl?: string;
    version?: string;
    languages?: string[];
}
```

Options for `monacoPrebundledPlugin()`. `strategy` default `'prebundled'`. `publicPath` default `'/monaco-bundle'`. `cdnUrl`/`version` are used only for `'cdn'` (version default `'0.55.1'`). `languages` is currently informational (the prebundled bundle ships a fixed worker set).

### LanguagePack

```ts
export interface LanguagePack {
    id: string;
    extensions?: string[];
    aliases?: string[];
    workerLabel?: string;
    workerUrl?: string;
    setup?: (monaco: MonacoNamespace) => void | Promise<void>;
}
```

A pluggable language registration. `id` is the language id; `workerLabel` + `workerUrl` together map a Monaco worker label to a URL in the prebundled loader; `setup` runs once after Monaco loads (register completions, compiler options, etc.). Re-exported from the main entry.

### ThemePack

```ts
export interface ThemePack {
    name: string;
    data: Monaco.editor.IStandaloneThemeData;
}
```

A theme to define against the Monaco instance via `monaco.editor.defineTheme`.

### ExtraLib

```ts
export interface ExtraLib {
    content: string;
    filePath: string;
}
```

Extra `.d.ts` content injected into Monaco's TS service via `typescriptDefaults.addExtraLib(content, filePath)`.

### MonacoNamespace

```ts
export type MonacoNamespace = typeof Monaco;
```

The full `monaco-editor` module namespace type (`typeof import('monaco-editor')`).

### MonacoEditorInstance

```ts
export type MonacoEditorInstance = Monaco.editor.IStandaloneCodeEditor;
```

A live standalone code editor instance. Declared in `types.ts` as `MonacoEditor`; re-exported from the main entry under the alias `MonacoEditorInstance` to avoid clashing with the `MonacoEditor` component.

### MonacoEditorConstructionOptions

```ts
export type MonacoEditorConstructionOptions = Monaco.editor.IStandaloneEditorConstructionOptions;
```

Raw Monaco editor construction options, accepted via the `monacoOptions` field on `CreateEditorOptions` / `MonacoEditorProps`.

## Entry points

```ts
// Main barrel: loader + createEditor + MonacoEditor component + types + all 4 language packs
import { /* ... */ } from '@sigx/monaco-editor';

// Vite plugin (also the default export of this module)
import { monacoPrebundledPlugin } from '@sigx/monaco-editor/vite';

// Optional Shiki integration
import { applyShikiThemes } from '@sigx/monaco-editor/shiki';

// Individual language packs
import { typescriptLanguagePack } from '@sigx/monaco-editor/languages/typescript';
import { htmlLanguagePack } from '@sigx/monaco-editor/languages/html';
import { cssLanguagePack } from '@sigx/monaco-editor/languages/css';
import { jsonLanguagePack } from '@sigx/monaco-editor/languages/json';
```

Raw prebundled assets are also exposed under `./monaco-bundle/*` (mapped to `./public/monaco-bundle/*`), but runtime serving is normally handled by the Vite plugin rather than this export.

---
url: https://sigx.dev/ssg/docs/themes/
title: Themes
description: Author and consume @sigx/ssg themes, and the prebuilt @sigx/ssg-theme-daisyui
---

# Themes

A theme is an npm package that bundles layouts, components, and configuration so a site can adopt a polished look without hand-rolling its shell. Reference one through the config `theme` field:

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    theme: '@sigx/ssg-theme-daisyui',
});
```

The build and dev server load the theme automatically and merge its contributions; your own config always wins.

## Consuming a theme

A theme package exports three things, all optional:

- **`layouts`** — a `Record<string, Layout>` keyed by name. A page selects one via frontmatter `layout:`, the collection config, or the config `defaultLayout`. The theme's `config.defaultLayout` is used only when your config doesn't set one.
- **`components`** — a `Record<string, Component>` the theme's layouts use (header, sidebar, table of contents, …). You can import and reuse these in your own layouts.
- **`config`** — a `ThemeConfig` of build-time contributions, merged so your site's config wins.

Layouts receive the whole site config as `props.site`, so a theme renders *your* branding — `site.title`, `site.nav`, `site.logo`, `site.repo`, `site.announcement`, `site.editBase`, and the `site.search` flag — instead of hardcoding its own. Set those fields and the theme reflects them.

## Authoring a theme

Export `layouts`, `components`, and `config` from the package entry. The shapes are `ThemeModule` and `ThemeConfig`:

```ts
import type { ThemeConfig } from '@sigx/ssg';
import DefaultLayout from './layouts/default.js';
import DocsLayout from './layouts/docs.js';

export const layouts = {
    default: DefaultLayout,
    docs: DocsLayout,
};

export const components = {
    /* Header, Sidebar, TOC, … */
};

export const config: ThemeConfig = {
    defaultLayout: 'default',
    css: ['@my/theme/styles.css'],
    head: [{ tag: 'script', children: '/* no-FOUC theme init */' }],
    markdown: { rehypePlugins: [/* … */] },
    hooks: { /* transformHtml, onPageRendered, postBuild */ },
};

export default { layouts, components, config };
```

How each `config` field merges (the site's own config always wins):

- **`defaultLayout`** — used only when the site doesn't set its own.
- **`css`** — import specifiers, prepended to the site's `clientImports` (so the theme ships its own stylesheet without the site adding it manually).
- **`head`** — `HeadTag[]` prepended to `site.head` (the slot for a no-FOUC theme-init script, font preloads, …).
- **`markdown`** — `remarkPlugins` / `rehypePlugins` that run *before* the site's own markdown plugins.
- **`hooks`** — build hooks composed with the site's: the theme's run first, then the site's (`transformHtml` chains the output through both).

A theme layout is an ordinary `@sigx/ssg` layout — a component that renders `slots.default?.()` and reads `props.meta`, `props.path`, and `props.site`. See [Configuration → Layouts](/ssg/docs/configuration#layouts).

**Call the slot optionally.** A layout whose default fill is missing renders nothing there rather than throwing, so one page without body content cannot take the build down. `slots.default?.()` is also what type-checks under core 0.15, which checks a slot fill against the slot it declares and makes the accessor optional at the call site.

## @sigx/ssg-theme-daisyui

`@sigx/ssg-theme-daisyui` is the recommended prebuilt theme — a drop-in docs/blog shell built on [daisyUI](https://daisyui.com/) and Tailwind. The SignalX docs site you are reading keeps its own custom layouts, so this is presented as an option, not a requirement.

### Install

```bash
npm install @sigx/ssg-theme-daisyui daisyui tailwindcss
```

It declares `@sigx/ssg`, `@sigx/router`, `sigx`, `daisyui@>=5.0.0`, and `tailwindcss@>=4.0.0` as peer dependencies. With daisyUI v5 and Tailwind v4, the theme's styling is wired through the `@plugin` directive in your own CSS file rather than a CSS export, so add daisyUI to your Tailwind setup as usual.

### Use it

```ts
import { defineSSGConfig } from '@sigx/ssg';

export default defineSSGConfig({
    theme: '@sigx/ssg-theme-daisyui',
    search: true, // emit the index the command palette searches
    site: {
        title: 'My Docs',
        repo: 'https://github.com/me/my-docs',
        editBase: 'https://github.com/me/my-docs/edit/main/',
        announcement: { text: 'v1 is out!', href: '/blog/v1', id: 'v1' },
        search: true, // show the ⌘K palette
    },
});
```

### Layouts

The package exports three layouts:

- **`default`** — a header + content + footer shell for general pages.
- **`docs`** — a documentation layout with an announcement bar, header (with the search palette), a collapsible sidebar, breadcrumbs, a table of contents, previous/next links, and a page footer with edit-this-page and last-updated.
- **`blog`** — a layout for long-form posts.

Select one per page via frontmatter `layout:`, or per collection via the collection config; `default` is the theme's default layout.

### Components

The theme also exports the components its layouts compose, so you can reuse them in your own layouts:

- **`Header`** — site branding, nav, theme toggle, and (when `site.search` is set) the ⌘K search trigger.
- **`Sidebar`** — auto-generated from `virtual:ssg-navigation` (or explicit `items` / `sections`), collapsible, with a `collection` override.
- **`TOC`** — a table of contents built from the rendered headings; honors per-page `meta.toc` min/max levels (falling back to its `minLevel` / `maxLevel` props, defaults 2–3).
- **`CommandPalette`** — the ⌘K / Ctrl+K palette over the built-in search index.
- **`PrevNext`** — previous / next links within the collection.
- **`Breadcrumbs`**, **`AnnouncementBar`**, **`PageFooter`** — the page-chrome pieces (`PageFooter` renders edit-this-page and last-updated from `site.editBase` + `meta.sourceFile` and `meta.lastmod` / frontmatter `updated`).

### Light/dark and theming

The theme contributes a no-FOUC init script (via `config.head`) that applies the persisted or OS color scheme before first paint; the `Header` toggle reads and writes the same storage key. Every daisyUI theme is available — configure them through your Tailwind/daisyUI setup as usual.

## Next steps

- [Configuration & Content](/ssg/docs/configuration) — layouts, collections, and the `theme` / `site` config.
- [Client Runtime](/ssg/docs/client-runtime) — the search and switcher behaviors a theme wires for you.
- [API Reference](/ssg/docs/api) — `ThemeModule`, `ThemeConfig`, `LayoutProps`, and theme-loading helpers.

---
url: https://sigx.dev/core/docs/keys/
title: Keys
description: Learn how to use keys for efficient list rendering and component identity
---

# Keys

Keys help SignalX identify which items in a list have changed, been added, or removed. They are essential for efficient updates and preserving component state during re-renders.

## Why Keys Matter

When rendering lists, SignalX needs to understand which elements correspond between renders. Without keys, SignalX uses element position and type to match elements, which can lead to:

- **Incorrect state preservation** - Component state may be applied to the wrong element
- **Unnecessary DOM operations** - Elements may be destroyed and recreated instead of reused
- **Animation issues** - Transitions may not work correctly when items move

## Using Keys

Add the `key` prop to elements in a list:

```tsx
import { component } from 'sigx';

const TodoList = component(({ signal }) => {
    const todos = signal([
        { id: 1, text: 'Learn SignalX' },
        { id: 2, text: 'Build an app' },
        { id: 3, text: 'Deploy to production' }
    ]);

    return () => (
        <ul>
            {todos.map(todo => (
                <li key={todo.id}>{todo.text}</li>
            ))}
        </ul>
    );
});
```

## Key Requirements

### Keys Must Be Unique Among Siblings

Keys only need to be unique within the same parent, not globally:

```tsx
// ✅ Good - keys unique within each list
<ul>
    {categories.map(category => (
        <li key={category.id}>
            <h3>{category.name}</h3>
            <ul>
                {category.items.map(item => (
                    <li key={item.id}>{item.name}</li>
                ))}
            </ul>
        </li>
    ))}
</ul>
```

### Keys Should Be Stable

Use IDs from your data, not array indices:

```tsx
// ❌ Bad - using index as key
{todos.map((todo, index) => (
    <TodoItem key={index} todo={todo} />
))}

// ✅ Good - using stable ID
{todos.map(todo => (
    <TodoItem key={todo.id} todo={todo} />
))}
```

Using indices as keys causes issues when items are reordered, added, or removed because the key no longer corresponds to the same data.

### Keys Should Be Consistent

The same item should always have the same key:

```tsx
// ❌ Bad - random keys change on every render
{todos.map(todo => (
    <TodoItem key={Math.random()} todo={todo} />
))}

// ✅ Good - stable, predictable keys
{todos.map(todo => (
    <TodoItem key={todo.id} todo={todo} />
))}
```

## Key Types

Keys can be strings or numbers:

```tsx
// String key
<li key="header">Header</li>

// Number key
<li key={1}>First</li>

// ID from data
<li key={item.id}>{item.name}</li>
```

> **Note:** Keys are converted to strings internally, so `key={1}` and `key="1"` are treated as the same key.

## Forcing Component Remount

Changing a component's key forces it to unmount and remount with fresh state:

```tsx
import { component } from 'sigx';

const FormWizard = component(({ signal }) => {
    const step = signal(1);
    
    return () => (
        <div>
            {/* Changing key resets the form state */}
            <StepForm key={step()} step={step()} />
            
            <button onClick={() => step.v++}>Next Step</button>
        </div>
    );
});

const StepForm = component(({ props, signal }) => {
    // This state resets when the key changes
    const formData = signal({});
    
    return () => (
        <form>
            {/* Form fields for step {props.step} */}
        </form>
    );
});
```

This pattern is useful for:
- Resetting form state when switching between items
- Forcing animations to restart
- Clearing component caches

## Development Warnings

SignalX provides helpful warnings in development mode for actual bugs:

### Duplicate Key Warning

```tsx
// ⚠️ Warning: Duplicate key "1" detected
<ul>
    <li key="1">First</li>
    <li key="1">Also First?</li>  {/* Duplicate! */}
</ul>
```

> **Note:** SignalX does not warn about missing keys. Our double-ended diffing algorithm efficiently handles lists without keys by matching on type and position. Keys are still recommended for optimal performance and correct state preservation in dynamic lists, but you won't be nagged about them.

## Best Practices

### 1. Always Key Dynamic Lists

Any list that can change (items added, removed, or reordered) should use keys:

```tsx
// Dynamic list - needs keys
{users.map(user => <UserCard key={user.id} user={user} />)}

// Static list - keys are optional but still recommended
{['Home', 'About', 'Contact'].map(page => (
    <NavLink key={page} to={`/${page.toLowerCase()}`}>{page}</NavLink>
))}
```

### 2. Use Meaningful IDs

If your data doesn't have IDs, generate them when the data is created, not during rendering:

```tsx
// ✅ Good - generate IDs when creating data
function addTodo(text) {
    todos.push({
        id: crypto.randomUUID(),  // or use a counter
        text
    });
}
```

### 3. Composite Keys

For items that don't have a single unique ID, combine multiple fields:

```tsx
{events.map(event => (
    <EventCard 
        key={`${event.date}-${event.venue}-${event.time}`} 
        event={event} 
    />
))}
```

### 4. Keys on Components

Keys work the same way on custom components:

```tsx
{products.map(product => (
    <ProductCard 
        key={product.sku}
        product={product}
        onAddToCart={() => addToCart(product)}
    />
))}
```

## How Keys Work Internally

SignalX uses a double-ended diffing algorithm that:

1. Compares elements from the start of both old and new lists
2. Compares elements from the end of both lists
3. Detects moves (old start → new end, old end → new start)
4. Uses a key-to-index map for O(1) lookup of remaining items
5. Mounts new items and unmounts removed items

This algorithm is O(n) and efficiently handles common list operations like:
- Appending items
- Prepending items
- Removing items
- Reordering items
- Complete list replacement

## Summary

- **Use keys** for all dynamic lists to help SignalX track element identity
- **Keys must be unique** among siblings
- **Keys should be stable** - use data IDs, not array indices
- **Changing a key** forces remount with fresh state
- **Development warnings** help catch common mistakes

---
url: https://sigx.dev/core/api/types/
title: Types
description: SignalX TypeScript type helpers reference
---

# Types API

TypeScript type helpers for defining component contracts.

## Define.Prop

Define a single component prop with type and required status.

```tsx
type Define.Prop<
    TName extends string,
    TType,
    Required extends boolean = false
> = Required extends false
    ? { [K in TName]?: TType }
    : { [K in TName]: TType };
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `TName` | `string` | Prop name |
| `TType` | `any` | Prop type |
| `Required` | `boolean` | Is required (default: false) |

### Examples

```tsx
import { component, type Define } from 'sigx';

// Required prop
type NameProp = Define.Prop<'name', string, true>;

// Optional prop
type CountProp = Define.Prop<'count', number>;

// With default in component
type ColorProp = Define.Prop<'color', 'red' | 'blue'>;

// Combined props
type ButtonProps = 
    & Define.Prop<'label', string, true>
    & Define.Prop<'variant', 'primary' | 'secondary'>
    & Define.Prop<'disabled', boolean>;

const Button = component<ButtonProps>(({ props }) => {
    // props.label is string (required)
    // props.variant is 'primary' | 'secondary' | undefined
    // props.disabled is boolean | undefined
    
    return () => (
        <button 
            class={props.variant || 'primary'}
            disabled={props.disabled}
        >
            {props.label}
        </button>
    );
});
```

---

## Define.Event

Define a custom event with its detail type.

```tsx
type Define.Event<TName extends string, TDetail = void> = {
    [K in TName]?: EventDefinition<TDetail>;
};
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `TName` | `string` | Event name |
| `TDetail` | `any` | Event payload type (default: void) |

### Examples

```tsx
import { component, type Define } from 'sigx';

// Event without payload
type CloseEvent = Define.Event<'close'>;

// Event with payload
type ChangeEvent = Define.Event<'change', { value: string }>;

// Combined
type InputProps = 
    & Define.Event<'change', string>
    & Define.Event<'blur'>
    & Define.Event<'submit', { data: FormData }>;

const Input = component<InputProps>(({ emit }) => {
    return () => (
        <input
            onInput={(e) => emit('change', e.target.value)}
            onBlur={() => emit('blur')}
        />
    );
});

// Usage - events become onEventName props
<Input 
    onChange={(value) => console.log(value)}
    onBlur={() => console.log('blurred')}
    onSubmit={({ data }) => console.log(data)}
/>
```

---

## Define.Slot

Define a named slot with optional scoped props.

```tsx
type Define.Slot<TName extends string, TProps = void> = {
    __slots?: {
        [K in TName]: TProps extends void
            ? () => JSXElement | JSXElement[] | null
            : (props: TProps) => JSXElement | JSXElement[] | null
    }
};
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `TName` | `string` | Slot name |
| `TProps` | `any` | Scoped slot props (default: void) |

### Examples

```tsx
import { component, type Define } from 'sigx';

// Simple slots
type CardProps = 
    & Define.Slot<'default'>
    & Define.Slot<'header'>
    & Define.Slot<'footer'>;

const Card = component<CardProps>(({ slots }) => {
    return () => (
        <div class="card">
            {slots.header?.()}
            <div class="body">{slots.default?.()}</div>
            {slots.footer?.()}
        </div>
    );
});

// Scoped slots
type ListProps<T> = 
    & Define.Prop<'items', T[], true>
    & Define.Slot<'item', { item: T; index: number }>
    & Define.Slot<'empty'>;

const List = component<ListProps<any>>(({ props, slots }) => {
    return () => (
        <ul>
            {props.items.length === 0 
                ? slots.empty?.()
                : props.items.map((item, index) => (
                    <li>{slots.item?.({ item, index })}</li>
                ))
            }
        </ul>
    );
});

// Usage
<List 
    items={users}
    slots={{
        item: ({ item, index }) => (
            <span>{index + 1}. {item.name}</span>
        ),
        empty: () => <span>No users found</span>
    }}
/>
```

> **Slot presence.** A slot accessor on `slots` is callable **only when the parent
> provided that slot**, and is `undefined` otherwise. Check presence with plain
> truthiness (`slots.x`), render with an optional call (`slots.x?.()`), and supply
> a fallback with `slots.x?.() ?? fallback`. Always call optionally — invoking an
> unprovided slot throws. Presence is reactive (a slot appearing/disappearing
> re-renders the consumer) and resolves identically under SSR and hydration.

---

## Define.Model

Define a two-way bound prop (modelValue + update event + model caller prop).

```tsx
type Define.Model<TNameOrType, TType = void> = TType extends void
    ? Define.Prop<"modelValue", TNameOrType> 
        & Define.Event<"update:modelValue", TNameOrType>
        & { model?: () => TNameOrType }
    : TNameOrType extends string
        ? Define.Prop<TNameOrType, TType> 
            & Define.Event<`update:${TNameOrType}`, TType>
            & { [K in `model:${TNameOrType}`]?: () => TType }
        : never;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `TNameOrType` | `string \| type` | Prop name or type for 'modelValue' |
| `TType` | `any` | Prop type (when TNameOrType is name) |

### What It Creates

For `Define.Model<string>`:
- `modelValue?: string` — the value prop (component reads this)
- `update:modelValue` event — component emits this to update
- `model?: () => string` — caller uses this for two-way binding

For `Define.Model<'min', number>`:
- `min?: number` — the named prop
- `update:min` event — component emits this
- `model:min?: () => number` — caller uses this for binding

### Examples

```tsx
import { component, type Define } from 'sigx';

// Default 'modelValue' prop
type InputProps = Define.Model<string>;

// Named model prop
type RangeProps = 
    & Define.Model<'min', number>
    & Define.Model<'max', number>;
// Creates: { min?: number, max?: number, ... }

const TextInput = component<Define.Model<string>>(({ props, emit }) => {
    return () => (
        <input
            value={props.modelValue || ''}
            onInput={(e) => emit('update:modelValue', e.target.value)}
        />
    );
});

// Usage with model binding
const Form = component(({ signal }) => {
    const state = signal({ name: '' });
    
    return () => (
        <TextInput model={() => state.name} />
    );
});
```

---

## Define.Expose

Define the API exposed by a component via ref.

```tsx
type Define.Expose<T> = {
    __exposed?: { __type: T };
};
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `T` | `object` | Shape of exposed API |

### Examples

```tsx
import { component, type Define } from 'sigx';

type FormApi = {
    submit: () => void;
    reset: () => void;
    validate: () => boolean;
};

type FormProps = Define.Expose<FormApi>;

const Form = component<FormProps>(({ expose, signal }) => {
    const state = signal({ data: {} });
    
    expose({
        submit: () => console.log('Submit:', state.data),
        reset: () => state.data = {},
        validate: () => Object.keys(state.data).length > 0
    });
    
    return () => <form>...</form>;
});

// Usage with typed ref
let formApi: FormApi;
<Form ref={(api) => formApi = api!} />

formApi.validate();
formApi.submit();
```

---

## Define.Attrs

Opt a component into accepting host attributes.

```tsx
type Define.Attrs = ComponentAttributes;
```

`ComponentAttributes` is empty in `@sigx/runtime-core` and filled by the
platform. On the web (`@sigx/runtime-dom`) it declares the universal HTML
attributes — `id`, `class`, `className`, `style`, `title`, `role`, `tabIndex`,
`hidden`, `inert`, `popover`, `dir`, `lang`, `slot`, `part`, `draggable`,
`spellCheck`, `translate`, `autoFocus`, `accessKey`, `contentEditable`,
`enterKeyHint`, `inputMode` — the `data-*` and `aria-*` patterns, and the DOM
event handlers in camelCase.

Declare it only on a component that forwards its leftover props to an element;
the type is a promise the component has to keep.

### Examples

```tsx
import { component, mergeProps, type Define } from 'sigx';

type ButtonProps =
    & Define.Prop<'variant', 'primary' | 'secondary'>
    & Define.Slot<'default'>
    & Define.Attrs;

const Button = component<ButtonProps>((ctx) => {
    const merged = mergeProps(
        () => { const { variant: _v, ...rest } = ctx.props; return rest; },
        () => ({ class: 'btn' })
    );
    return () => <button {...merged}>{ctx.slots.default?.()}</button>;
});

<Button variant="primary" id="save" aria-label="Save" onClick={save} />
```

There is no index signature and no `on${string}` catch-all, so a typo in an
attribute or handler name is still an error on an opted-in component.

---

## Define.WithAttrs

`Define.Attrs` for a component that declares a prop of its own with the same
name as a host attribute. The component's declaration wins.

```tsx
type Define.WithAttrs<TOwn> = TOwn & Omit<ComponentAttributes, keyof TOwn>;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `TOwn` | `object` | The component's own definition types |

### Examples

```tsx
// `title` here is a heading, not the HTML tooltip attribute.
type DialogProps = Define.WithAttrs<
    & Define.Prop<'title', string, true>
    & Define.Slot<'default'>
>;
```

---

## ComponentRef

Extract the ref type from a component for typed refs.

```tsx
type ComponentRef<T extends { __ref: any }> = Ref<T["__ref"]>;
```

### Examples

```tsx
import { component, ComponentRef, type Define } from 'sigx';

const Counter = component<Define.Expose<{ increment: () => void }>>(
    ({ expose, signal }) => {
        const state = signal({ count: 0 });
        expose({ increment: () => state.count++ });
        return () => <div>{state.count}</div>;
    }
);

// Type the ref variable
const counterRef: ComponentRef<typeof Counter> = { current: null };

<Counter ref={counterRef} />

// Type-safe access
counterRef.current?.increment();
```

---

## Exposed

Extract the exposed type from a component.

```tsx
type Exposed<T extends { __ref: any }> = T["__ref"];
```

### Examples

```tsx
import { component, Exposed, type Define } from 'sigx';

const Modal = component<Define.Expose<{ open: () => void; close: () => void }>>(
    ({ expose }) => {
        expose({ open: () => {}, close: () => {} });
        return () => <div />;
    }
);

// Extract exposed type
type ModalApi = Exposed<typeof Modal>;
// { open: () => void; close: () => void }

let modalApi: ModalApi;
<Modal ref={(api) => modalApi = api!} />
```

---

## Ref

Ref type accepting both object and callback refs.

```tsx
type Ref<T> = { current: T | null } | ((instance: T | null) => void);
```

### Examples

```tsx
// Object ref
const myRef = { current: null };
<Component ref={myRef} />
myRef.current?.method();

// Callback ref
let api: MyApi;
<Component ref={(instance) => api = instance!} />
```

---

## Combining Types

```tsx
import { 
    component, 
    type Define,
} from 'sigx';

// Full component type definition
type DataTableProps<T> = 
    // Props
    & Define.Prop<'data', T[], true>
    & Define.Prop<'columns', Column[], true>
    & Define.Prop<'loading', boolean>
    & Define.Prop<'selectable', boolean>
    // Events
    & Define.Event<'select', T>
    & Define.Event<'sort', { column: string; direction: 'asc' | 'desc' }>
    // Slots
    & Define.Slot<'empty'>
    & Define.Slot<'row', { item: T; index: number }>
    & Define.Slot<'footer'>
    // Two-way binding
    & Define.Model<'selected', T[]>
    // Exposed API
    & Define.Expose<{
        refresh: () => Promise<void>;
        clearSelection: () => void;
    }>;

const DataTable = component<DataTableProps<any>>(({ 
    props, emit, slots, expose, signal 
}) => {
    const state = signal({ internalSelected: [] as any[] });
    
    expose({
        refresh: async () => { /* ... */ },
        clearSelection: () => {
            state.internalSelected = [];
            emit('update:selected', []);
        }
    });
    
    return () => (
        <table>
            {/* ... */}
        </table>
    );
});
```

---
url: https://sigx.dev/cli/docs/shell/
title: The Shell Runtime
description: Host a persistent TUI dashboard from a plugin command with runShell
---

# The Shell Runtime

Some plugin commands run for a long time — a dev server, a watcher, a device bridge. For these, `@sigx/cli/shell` provides a **persistent terminal-UI runtime**: a live dashboard with tabs, a command palette, single-key shortcuts, and a status line, all assembled from the contributions of every plugin in the project. A command starts it with `runShell` and gets back a `ShellHandle` to drive it.

```ts
import { runShell } from '@sigx/cli/shell';
```

The shell is built on [`@sigx/terminal`](/terminal/docs/getting-started); tabs are authored as terminal-UI components. It degrades gracefully: in a non-TTY environment (CI, a pipe) nothing mounts, and the same `ShellHandle` shape streams plain lines instead — so a host command keeps a single code path.

## Hosting a shell from a command

A command calls `runShell(config)` and awaits the handle. Pass `ctx.plugins` so peer plugins' [TUI contributions](#tui-contributions) get merged in:

```ts
import { definePlugin } from '@sigx/cli/plugin';
import { runShell } from '@sigx/cli/shell';

export default definePlugin({
    name: 'my-dev',
    detect: () => true,
    commands: {
        dev: {
            description: 'Start the dev server',
            args: {},
            async run(ctx) {
                const shell = await runShell({
                    title: 'my-dev',
                    version: ctx.cliVersion,
                    tabs: [
                        { id: 'logs', label: 'Logs', render: () => logsView() },
                        { id: 'routes', label: 'Routes', render: () => routesView() },
                    ],
                    plugins: ctx.plugins, // merge peer plugins' tui contributions
                    onReady(shell) {
                        shell.say('dev server ready');
                    },
                    onExit() {
                        // runs before the process exits, on quit / Ctrl+C / SIGTERM
                        stopServer();
                    },
                });

                shell.setStatus([{ label: 'mode', value: 'dev', tone: 'success' }]);
            },
        },
    },
});
```

## Two layouts

`ShellConfig.mode` picks the frame:

- **`'inline'`** (default) — a transcript shape. The header prints once into scrollback, `say()` appends permanent transcript lines, and a `/`-command input sits anchored at the bottom. The conversation *is* the terminal scrollback.
- **`'fullscreen'`** — an alt-screen dashboard: a bordered title bar, a segmented tab strip, a full-height tab body, and a pinned status/hints line. `/` summons a command-palette overlay with intellisense. `say()` streams live into the log store and also queues into the normal terminal buffer, so quitting leaves a post-mortem trail in real scrollback.

Both layouts support plugin-contributed tabs, slash commands, shortcuts, and status items; `1`–`9` switch tabs, `Esc` pops a pushed view, and `Ctrl+C` runs teardown *before* exiting.

## ShellConfig

```ts
export interface ShellConfig {
    mode?: 'inline' | 'fullscreen';
    theme?: string;          // design theme (themed canvas in fullscreen); default 'obsidian'
    title: string;           // shown in the header
    version?: string;        // dim version next to the title
    logo?: { rows: string[]; palette: Record<string, string> };
    tabs: ShellTab[];
    commands?: SlashCommand[];
    shortcuts?: Shortcut[];
    status?: () => StatusItem[];
    plugins?: SigxPlugin[];  // peer plugins whose `tui` contributions are merged in
    onReady?: (shell: ShellHandle) => void | Promise<void>;
    onExit?: () => void | Promise<void>;
}
```

`onReady` fires once the shell is live (or immediately in the non-TTY fallback). `onExit` runs on `shell.exit()`, `Ctrl+C`/`q`, and external `SIGTERM`/`SIGHUP`/`SIGINT` — *before* the process exits. Do cleanup there.

## The ShellHandle

`runShell` resolves to a `ShellHandle` — the live control surface, also passed to slash commands, shortcuts, and `setup`/`onReady`:

```ts
export interface ShellHandle {
    isInteractive: boolean;                  // false in non-TTY fallback
    say: (text?: string) => void;            // print a permanent transcript line
    store: ShellLogStore;                    // streaming log store (feeds a Logs tab)
    setStatus: (items: StatusItem[]) => void;
    readonly activeTab: string;              // id of the tab currently on screen
    switchTab: (id: string) => void;
    pushView: (id: string) => void;          // push a focused sub-view
    popView: () => void;                     // pop it (also via Esc)
    onExit: (cb: () => void | Promise<void>) => () => void; // register teardown; returns unsubscribe
    exit: (code?: number) => void;
}
```

`activeTab` is the id of the tab on screen — `''` when there are no tabs, and in the non-TTY fallback. Read it rather than tracking your own copy: the shell's built-in <kbd>1</kbd>–<kbd>9</kbd> keys switch tabs without going through `switchTab`, so a plugin-held copy silently drifts. It is what a shortcut that acts on "the visible tab" should branch on.

`onExit` subscribers run *after* the host's `ShellConfig.onExit`, most-recently-registered first; each returns an unsubscribe. Register servers, watchers, and locks here so they tear down on every exit path. In the non-TTY fallback `isInteractive` is `false`, `say` writes plain lines, the store streams through, and the navigation methods are no-ops.

## TUI contributions

A plugin doesn't have to host a shell to appear in one. By adding a `tui` field, any installed plugin contributes tabs, slash commands, shortcuts, and status items to whichever plugin *does* host the shell — see [Contributing to the shell](/cli/docs/plugins#contributing-to-the-shell-tui) in the plugin guide.

```ts
export interface TuiContribution {
    tabs?: ShellTab[];
    commands?: SlashCommand[];
    shortcuts?: Shortcut[];
    status?: () => StatusItem[];
    setup?: (shell: ShellHandle) => void
        | (() => void | Promise<void>)
        | Promise<void | (() => void | Promise<void>)>;
}
```

The host's command passes `ctx.plugins` to `runShell({ plugins })`; the runtime merges every plugin's `tui` in discovery order. **Host entries win conflicts** — a duplicate tab `id`, command `name`, or shortcut `key` from a contributor is skipped. `status` providers concatenate. The `setup(shell)` lifecycle runs once when the shell comes up (interactive or plain); start servers/watchers there, and an optionally returned function is registered as teardown (equivalent to `shell.onExit(fn)`).

### Tabs, slash commands, shortcuts, status

```ts
/** The area a tab's body has to render into — the terminal minus the
 *  shell's own chrome. A budget, not a reservation: fit content to it. */
export interface ShellPane {
    width: number;
    height: number;
}

export interface ShellTab {
    id: string;
    label: string;
    render: (pane: ShellPane) => ShellNode;   // a @sigx/terminal component
}

export interface SlashCommand {
    name: string;              // includes the leading slash, e.g. '/reload'
    description: string;
    run: (shell: ShellHandle) => void | Promise<void>;
}

export interface Shortcut {
    key: string;               // single key, active only while the command input is empty
    label: string;
    run: (shell: ShellHandle) => void | Promise<void>;
}

export interface StatusItem {
    label: string;
    value: string;
    tone?: string;             // theme token: 'success' | 'warn' | 'danger' | 'dim' | 'accent'
}
```

Tab `render(pane)` returns a `ShellNode` — an opaque renderable you author with `@sigx/terminal` JSX (set `"jsxImportSource": "@sigx/terminal"` in your `tsconfig.json`). The runtime passes it straight to the renderer.

`pane` is the area left after the shell drew its own chrome — the terminal size minus the title bar, tab strip and status line. It exists because those are the shell's private layout details: without it a tab has to guess (`rows - 12`), and the guess breaks the moment the chrome changes.

It is a **budget, not a reservation.** The renderer's layout is content-driven, so the shell cannot hold the box on a tab's behalf. A body that emits more rows pushes the status line off the bottom. Fit content to it — [`fitLines(lines, pane)`](/terminal/docs/api#fitlines) does exactly that in one call:

```tsx
render: (pane) => (
    <DataTable width={pane.width} height={pane.height} columns={COLS} rows={rows} />
)
```

Ignoring the argument is fine for a tab whose content is naturally small.

## Helpers

`@sigx/cli/shell` also exports:

- **`createShellLogger(shell)`** — wraps a `ShellHandle` as a `Logger` (`log`/`warn`/`error`), so existing `Logger`-based code paths route into the shell transcript.
- **`collectTuiContributions(plugins)`** / **`mergeShellConfig(config, contributions, logger?)`** — the lower-level merge primitives `runShell` uses internally, exported for hosts that want to merge contributions themselves.

## See also

- [Authoring Plugins](/cli/docs/plugins) — declaring commands, args, and the `tui` contribution field.
- [API Reference](/cli/docs/api) — the plugin and shell types.
- [`@sigx/terminal`](/terminal/docs/getting-started) — the terminal-UI toolkit tabs are built with.

---
url: https://sigx.dev/i18n/docs/api/
title: API reference
description: Every export of @sigx/i18n, grouped by entry point
---

# API reference

<p class="lede">Exports of `@sigx/i18n` , grouped by entry point.</p>

## `@sigx/i18n`

### Setup

| Export | Kind | Purpose |
|---|---|---|
| `createI18n(options)` | plugin | `app.use(createI18n({ … }))`. The store is created lazily on first use during render. |
| `provideI18nConfig(options)` | function | Client-only config for the no-app case (`@sigx/resume` boundaries). A no-op on the server. |
| `I18nOptions` | type | The resolved runtime config. |

Key `I18nOptions` fields:

| Field | Notes |
|---|---|
| `fallbackLocale` | **Required.** The master locale — the source of truth for which keys exist. |
| `initialLocale` | Locale to start on before detection. Defaults to `fallbackLocale`. |
| `supported` | Negotiation target set; empty accepts any locale. |
| `localeFallbacks` | Explicit fallbacks layered on BCP-47 truncation. |
| `namespaces` | Loaded up front. Leave section-specific ones out so they load on use. |
| `defaultNamespace` | Used when `useTranslation()` is called without one. Default `'translation'`. |
| `load` | The catalog loader. Without it, catalogs come from `addMessages`. |
| `layers` / `defaultLayer` / `loaders` / `layerMessages` | Per-key override layering — see [Layers](/i18n/docs/usage#layers). |
| `initialMessages` | Catalogs seeded synchronously at creation, marked loaded. The idiomatic SSR preload. |
| `formatter` | Defaults to `lightweightFormatter` — interpolation, plurals and selects with **no `Intl` dependency**, so it runs on engines that lack it. Supply your own to opt into `Intl`-backed number/date formatting. |
| `onMissing` | Missing-key handler. |
| `onLoadError` | Replaces the default console logging for a failed catalog load. |

### Reading

| Export | Kind | Purpose |
|---|---|---|
| `useTranslation(ns?, options?)` | hook | The typed translator. Namespace **and** keys checked. |
| `useDynamicTranslation(ns?, options?)` | hook | Namespace checked, keys open — for [runtime catalogs](/i18n/docs/runtime-catalogs). |
| `useLocale()` | hook | `{ locale, locales, setLocale, error, retry, whenReady }`. |
| `useI18n()` / `useI18nConfig()` | hook | The store itself, and the resolved config. |
| `T` | component | Declarative translation — `k`, `params`, `ns`, `locale`, `default`, `components`. |
| `renderRich(text, components)` | function | The tag-splitting behind `<T components>`. |

Both readers take `{ locale }` to pin a call to a locale other than the active one — see [Translating into a locale that isn't the active one](/i18n/docs/server#translating-into-a-locale-that-isnt-the-active-one).

### Store actions

`useI18n()` returns the store. Beyond the reactive `locale` / `locales` / `messages` signals:

| Action | Purpose |
|---|---|
| `setLocale(locale)` | Switch; resolves once catalogs have loaded. |
| `loadNamespace(locale, ns)` | Load one namespace explicitly. |
| `addMessages(locale, ns, catalog, { layer? })` | Seed a catalog directly. |
| `setLayer(layer, tree)` | Replace a whole override layer. |
| `invalidate(locale?, ns?, layer?)` | Drop and reload. Narrows from the left; omit an argument to cover every value of it. |
| `forLocale(locale)` | A translator bound to one locale. |
| `translateKey(key, params?, { locale? })` | The primitive under the readers. |

### Detection

`detectLocale`, `createDetectors`, `findSupported`, `parseAcceptLanguage`, `parseCookie`, `settingsDetector`, `browserDetector`, `cookieDetector`, `urlDetector`, `detectionContextFromRequest`, `resolveRequestLocale`, `localeCookie`, `localeSwitchUrl`, `LOCALE_COOKIE`.

`Detector.detect` is **synchronous** — an async native locale goes through `initialLocale` or `await setLocale()`.

### Lower-level

`translate`, `translateWith`, `lookup`, `getMessage`, `localeChain`, `matchLocale`, `lightweightFormatter`, `isPluralForms`, `composeCatalogs`, `composeAt`, `layerFor`, `flatten`, `createTranslator`, `createDynamicTranslator`, `bindLocale`, `installPersistSSR`.

## `@sigx/i18n/server`

| Export | Purpose |
|---|---|
| `createRequestT(options)` | Build once, bind per request. Returns `(request) => LocaleTranslator`. |
| `createServerT(options)` | A translator over an in-memory catalog tree; `forLocale(locale)` binds. |
| `LocaleTranslator` | `forNamespace(ns)`, `withLayers(trees)`, and the bound translation calls. |

`@sigx/i18n/server/node` is the Node flavour of the same surface.

## `@sigx/i18n/vite`

| Export | Purpose |
|---|---|
| `i18n(options)` | The build plugin — scans catalogs, generates types, runs the consistency check. |
| `runI18nCheck` / `checkCatalogs` / `formatReport` | The check, for wiring into CI without a build. |
| `writeI18nTypes` / `generateDts` | Type generation on its own. |
| `buildManifest` / `scanDir` | The catalog scan. |

`runtimeNamespaces` declares namespaces whose keys are not knowable at build time — see [Runtime catalogs](/i18n/docs/runtime-catalogs).

## `@sigx/i18n/virtual`

Types for the generated virtual module (`virtual:sigx-i18n/server-catalogs` and friends).

---
url: https://sigx.dev/store/docs/api/
title: API Reference
description: "@sigx/store — centralized state on signals — API reference"
---

# API Reference

The package ships two entry points:

```ts
import { defineStore, storeToSignals, onStoreCreated } from '@sigx/store';
import { persist } from '@sigx/store/persist';
```

## Functions

### defineStore

Defines a store factory. Returns a factory function; calling it creates (or resolves, per the lifetime) a store instance.

```ts
function defineStore<TReturn extends object, TArgs extends unknown[] = []>(
    name: string,
    setup: (ctx: SetupStoreContext, ...args: TArgs) => TReturn,
    lifetime?: Lifetime
): (...args: TArgs) => UnwrapStore<TReturn>;
```

**Parameters**

- `name` — the logical store name. Instance ids are `${name}#${n}` (e.g. `'todos#1'`); the name is also the default persistence key suffix and the prefix of the store's topic namespaces.
- `setup` — builds the store via the provided `SetupStoreContext` and **must return an object**. Extra setup parameters are tuple-typed with full inference (any arity) and are forwarded when the returned factory is called.
- `lifetime` — `'singleton' | 'scoped' | 'transient'` (from `@sigx/runtime-core`, honored since core `0.5.0`). Defaults to `'scoped'`.

**Returns**

A factory function (commonly assigned to a `useXxxStore` const). Calling it yields an `UnwrapStore<TReturn>` — the flat store surface: returned key signals read/write as plain values, returned computeds read as plain read-only values, actions and everything else pass through, and `$`-meta (`$id`, `$patch`, `$events`, `$dispose`) rides on the side. Instances created inside a component dispose with it per the lifetime rules. There is no `useStore` export — the factory is named by you.

Assigning to a `$`-prefixed key on the instance throws, as does assigning to a computed key. Spread and `Object.keys` over the instance see only your returned keys, never `$`-meta.

### storeToSignals

Destructuring-safe views of a store: key signals for state keys, read-only signal views for computeds. Functions and `$`-meta are skipped.

```ts
function storeToSignals<TReturn extends object>(store: UnwrapStore<TReturn>): {
    /* state keys */    K: KeySignal<V>;
    /* computed keys */ K: { readonly value: V };
};
```

- `store` — a store instance created by `defineStore` (anything else throws).
- Returns an object of `{ value }` views you can destructure without losing reactivity.

```ts
const { todos, remaining } = storeToSignals(store);
todos.value.push(item);   // still reactive
remaining.value;          // read-only
```

### onStoreCreated

Register a global plugin that runs for every store instance, synchronously after its setup returns. Plugins run in registration order; a throwing plugin is isolated (logged via `console.error`) and cannot break store creation.

```ts
function onStoreCreated(plugin: (ctx: StorePluginContext) => void): Subscription;
```

- `plugin` — receives a `StorePluginContext` per instance.
- Returns a `Subscription` whose `unsubscribe()` stops future invocations.

```ts
onStoreCreated(({ name, instanceId, instance, onDeactivated }) => {
    const sub = wireUpLogging(instanceId, instance);
    onDeactivated(() => sub.unsubscribe());
});
```

## Interfaces

### SetupStoreContext

The context object passed to the `defineStore` setup function. Extends runtime-core's `SetupFactoryContext`.

```ts
interface SetupStoreContext extends SetupFactoryContext {
    /** The logical store name passed to defineStore (e.g. 'todos'). */
    readonly storeName: string;
    /** The friendly instance id (e.g. 'todos#1'). */
    readonly instanceId: string;
    defineState<TState extends object>(state: TState): {
        /** The deep reactive proxy — mutate freely inside the setup/actions. */
        state: TState;
        /** Spreadable per-key signals; the ones you return become public state. */
        signals: { [K in keyof TState]-?: KeySignal<TState[K]> };
        /** Per-key change events (lazy: watchers run only while subscribed). */
        events: { [K in keyof TState]-?: StateKeyEvent<TState[K]> };
        /** Atomic multi-key update; flushes reactivity once. Errors propagate. */
        patch: Patch<TState>;
    };
    defineActions<TActions extends Record<string, (...args: any[]) => any>>(
        actions: TActions
    ): StoreActions<TActions>;
    /** Typed custom events; namespaced `${id}.events`, destroyed with the store. */
    defineEvents<EventMap extends Record<string, any>>(): { [K in keyof EventMap]: Topic<EventMap[K]> };
}
```

- `storeName` / `instanceId` — the logical name and the friendly per-instance id; composables use them for defaults (e.g. `persist`'s `sigx:<storeName>` key).
- `defineState(state)` — creates deep reactive, signal-backed state and returns `{ state, signals, events, patch }`. Can be called multiple times for independent slices.
- `defineActions(actions)` — wraps action functions with `pending` and dispatch lifecycle events; see `StoreAction`.
- `defineEvents<EventMap>()` — a typed topic group (core `createTopicGroup`) keyed by your event map. Topics are created lazily per key on first access, namespaced `${instanceId}.events`, and destroyed with the store.
- Inherited from `SetupFactoryContext`: `onDeactivated(fn)`, `subscriptions`, `overrideDispose(fn)`.

### StoreMeta

The `$`-meta every store instance carries. `$patch` and `$events` are typed from the **returned** key signals only (`PublicState<TReturn>`).

```ts
type StoreMeta<TReturn extends object> = {
    /** Friendly instance id, e.g. 'todos#1'. */
    readonly $id: string;
    /** Atomic update across the store's public state keys. */
    $patch: Patch<PublicState<TReturn>>;
    /** Per-key change events for the public state keys. */
    $events: { [K in keyof PublicState<TReturn>]: StateKeyEvent<PublicState<TReturn>[K]> };
    $dispose(): void;
};
```

`$patch` throws on a state key that is not part of the public surface. `$events` watchers are refCounted — they run only while subscribed and never fire immediately on subscribe. The full `$`-meta surface per instance: **`$id`** (readonly string), **`$patch`** (object or mutator form, one flush), **`$events`** (per-public-key `StateKeyEvent`s), **`$dispose()`** (stop state watchers, destroy every topic). Assigning to any `$`-prefixed key throws; spread and `Object.keys` over the instance never see `$`-meta.

### StorePluginContext

What an `onStoreCreated` plugin receives per store instance.

```ts
type StorePluginContext = {
    /** The logical store name passed to defineStore. */
    name: string;
    /** The instance id, e.g. 'todos#1'. */
    instanceId: string;
    /** The raw setup return (any shape — duck-type as needed). */
    instance: object;
    /** Tie plugin resources to the store instance's lifetime. */
    onDeactivated(fn: () => void): void;
};
```

## Types

### UnwrapStore

The flat store surface a factory call returns. Key signals unwrap to mutable plain values, computeds unwrap to read-only plain values, everything else passes through, intersected with `StoreMeta`.

```ts
type UnwrapStore<TReturn extends object> =
    { /* key signals  */ [K]: V }            // read/write
  & { /* computeds    */ readonly [K]: V }   // read-only
  & { /* the rest     */ [K]: TReturn[K] }   // actions, topics, helpers…
  & StoreMeta<TReturn>;
```

### PublicState

The keys of the setup return that are key signals — the store's public state. Drives the typing of `$patch` and `$events`.

```ts
type PublicState<TReturn> = {
    [K in keyof TReturn as TReturn[K] extends KeySignal<any> ? K : never]:
        TReturn[K] extends KeySignal<infer V> ? V : never;
};
```

### KeySignal

A signal-shaped, spreadable view over one state key (branded; produced by `defineState`'s `signals`). Spread these into your setup return to make keys public.

```ts
type KeySignal<T> = {
    value: T;
};
```

### StateKeyEvent

A per-key change event. Callbacks receive the new and previous values.

```ts
type StateKeyEvent<T> = {
    subscribe(fn: (value: T, prev: T | undefined) => void): Subscription;
};
```

### Patch

The atomic update function returned by `defineState` (over the full slice) and exposed as `$patch` (over the public state). Both forms flush reactivity once.

```ts
type Patch<TState extends object> = {
    (partial: Partial<TState>): void;
    (mutator: (state: TState) => void): void;
};
```

### StoreAction

A wrapped store action: callable with the exact original signature, plus a reactive in-flight flag and per-action lifecycle event subscribers.

```ts
type StoreAction<F extends (...args: any[]) => any> = F & {
    /** Reactive: true while any invocation of this action is in flight. */
    readonly pending: boolean;
    onDispatching: { subscribe(fn: (...args: Parameters<F>) => void): Subscription };
    onDispatched: { subscribe(fn: (result: Awaited<ReturnType<F>>, ...args: Parameters<F>) => void): Subscription };
    onFailure: { subscribe(fn: (error: unknown, ...args: Parameters<F>) => void): Subscription };
};
```

Semantics:

- `onDispatching` fires before the action body, with the original args.
- `onDispatched` fires after the action with `(result, ...args)`; for async actions, after the promise resolves, with the **resolved value**.
- `onFailure` fires on a sync throw or an async rejection, with `(error, ...args)`.
- Sync errors **re-throw** to the caller; async actions return the **original promise** (rejections are observable by the caller, while fire-and-forget calls produce no unhandled-rejection noise).
- `pending` is count-based across overlapping invocations.

> Write actions as single-signature functions (union parameters instead of overloads) so these derived types stay exact.

### StoreActions

The return type of `defineActions` — each function wrapped as a `StoreAction`.

```ts
type StoreActions<T extends Record<string, (...args: any[]) => any>> = {
    [K in keyof T]: StoreAction<T[K]>;
};
```

## Supporting types

These come from `@sigx/runtime-core` and appear in the signatures above.

### Lifetime

The `lifetime` argument to `defineStore`. Defaults to `'scoped'`. (Replaces the old `InstanceLifetimes` enum.)

```ts
type Lifetime = 'singleton' | 'scoped' | 'transient';
```

### Topic and Subscription

Event primitives from `@sigx/runtime-core` (Topic v2 — see the [runtime-core API](/core/packages/runtime-core/api#messaging)). Every `subscribe()` returns a `Subscription`.

```ts
interface Subscription {
    unsubscribe(): void;
}

interface Topic<T> {
    readonly namespace?: string;
    readonly name?: string;
    readonly subscriberCount: number;
    readonly hasSubscribers: boolean;
    readonly disposed: boolean;
    publish(data: T): void;
    subscribe(handler: (data: T) => void): Subscription;
    destroy(): void;
}
```

### SetupFactoryContext

The base of `SetupStoreContext` (from `@sigx/runtime-core`).

```ts
interface SetupFactoryContext {
    onDeactivated(fn: () => void): void;
    subscriptions: SubscriptionHandler;
    overrideDispose(onDispose: (fn: () => void) => void): void;
}
```

## @sigx/store/persist

The persistence subpath entry. See the [Persistence guide](/store/docs/persistence) for behavior and examples.

### persist

Persist a state slice to storage and rehydrate it on store creation. Call inside a store setup.

```ts
function persist<TState extends object>(
    ctx: SetupStoreContext,
    slice: { state: TState; patch: Patch<TState> },
    options?: PersistOptions<TState>
): PersistHandle;
```

- `ctx` — the setup context (used for the default key and disposal wiring).
- `slice` — the `{ state, patch }` pair from `defineState`.
- `options` — a `PersistOptions<TState>` bag (all fields optional).
- Returns a `PersistHandle`.

Hydration is one atomic `patch()`; saving is a deep watch over the picked keys, debounced, and paused until hydration completes; storage failures are logged and never crash the store; everything is cleaned up on store disposal. With no storage available (SSR), persist is a no-op and `hydrated` is immediately `true`.

### StorageLike

Minimal storage contract — satisfied by `localStorage`, `sessionStorage`, and async stores like React Native's AsyncStorage (Promise-returning methods).

```ts
interface StorageLike {
    getItem(key: string): string | null | Promise<string | null>;
    setItem(key: string, value: string): void | Promise<void>;
    removeItem?(key: string): void | Promise<void>;
}
```

### PersistOptions

```ts
interface PersistOptions<TState extends object> {
    /** Storage key. Defaults to `sigx:<storeName>` — pass one explicitly when persisting multiple slices. */
    key?: string;
    /** Defaults to globalThis.localStorage. Absent storage (SSR) → no-op. */
    storage?: StorageLike;
    /** Persist (and hydrate) only these keys. Default: all slice keys. */
    pick?: (keyof TState)[];
    serialize?(snapshot: Partial<TState>): string;
    deserialize?(raw: string): unknown;
    /** Schema version stored alongside the data. */
    version?: number;
    /** Convert data persisted under an older version. Receives the raw deserialized payload. */
    migrate?(persisted: unknown, fromVersion: number): Partial<TState>;
    /** Debounce for writes, in ms. Default 0 (write on every change flush). */
    debounce?: number;
}
```

### PersistHandle

```ts
interface PersistHandle {
    /** Plain readonly view: true once hydration has completed. */
    hydrated: { readonly value: boolean };
    /** Resolves when hydration has completed (immediately for sync/no storage). */
    whenHydrated: Promise<void>;
    /** Remove the persisted entry from storage. */
    clear(): Promise<void>;
}
```

## Errors

Everything the package throws is prefixed `[@sigx/store]` and includes the instance id where one exists. The catalog:

| Thrown message | When |
|---|---|
| `[@sigx/store] <id>: the store setup must return an object.` | The `defineStore` setup returned `null` or a non-object. |
| `[@sigx/store] <id>: "<key>" is store meta and cannot be assigned.` | Assignment to any `$`-prefixed key on the instance (`store.$id = …`). |
| `[@sigx/store] <id>: "<key>" is a computed value and is read-only.` | Assignment to a returned computed (`store.total = 0`). |
| `[@sigx/store] <id>: $patch received unknown state key "<key>".` | Object-form `$patch` with a key that is not public state. |
| `[@sigx/store] <id>: $patch draft has no state key "<key>".` | Mutator-form `$patch` reading or writing a non-public key on the draft. |
| `[@sigx/store] storeToSignals expects a store instance created by defineStore.` | `storeToSignals` called with anything that isn't a store instance. |

Beyond these, errors thrown by *your* code propagate per the documented semantics: action errors re-throw (sync) or reject the returned promise (async), and errors inside a `patch`/`$patch` mutator propagate to the caller.

The following failures are **logged via `console.error`, never thrown** — they are isolation points where third-party or environmental failures must not break the store:

| Logged message | When |
|---|---|
| `[@sigx/store] <id>: error in onStoreCreated plugin: …` | A registered plugin threw; store creation continues. |
| `[@sigx/store] <id>: error settling action "<name>": …` | A subscriber/effect threw inside the internal async settle handlers. |
| `[@sigx/store] persist("<key>"): hydration failed, continuing with defaults: …` | Corrupted entry, throwing `deserialize`/`migrate`/`patch` during hydration. |
| `[@sigx/store] persist("<key>"): storage read failed, continuing with defaults: …` | `getItem` threw synchronously. |
| `[@sigx/store] persist("<key>"): hydration failed: …` | Async `getItem` rejected. |
| `[@sigx/store] persist("<key>"): write failed: …` | `setItem` threw or rejected (quota, privacy mode, broken backend). |

## See also

- [Getting Started](/store/docs/getting-started)
- [Defining a Store](/store/docs/defining-a-store) — the conceptual hub
- [Actions & Async](/store/docs/actions-and-async) · [Events & Observability](/store/docs/events-and-observability) · [Lifetimes & DI](/store/docs/lifetimes-and-di)
- [Using Stores in Components](/store/docs/using-in-components) · [Persistence](/store/docs/persistence)
- [Composables & Plugins](/store/docs/composables-and-plugins) · [TypeScript](/store/docs/typescript) · [Patterns](/store/docs/patterns)

---
url: https://sigx.dev/vite/docs/api/
title: API Reference
description: "@sigx/vite — Vite plugin with HMR for SignalX components — API reference"
---

# API Reference

Every public export of `@sigx/vite`, grouped by entry point and kind.

## Plugin (from `@sigx/vite`)

### sigxPlugin

```ts
export function sigxPlugin(options: SigxPluginOptions = {}): Plugin;
```

The main Vite plugin. Returns a Vite `Plugin` object with `name: 'sigx'` and
`enforce: 'pre'`.

- In dev (`command === 'serve'`) it aliases the SignalX runtime packages —
  `sigx`, `sigx/internals`, `sigx/jsx-runtime`, `sigx/jsx-dev-runtime`,
  `@sigx/reactivity`, `@sigx/runtime-core`, `@sigx/runtime-dom`,
  `@sigx/server-renderer`, plus their `/internals` subpaths — to their `src`
  entry files so a single reactivity instance is shared. It excludes **all**
  `@sigx/*` packages from `optimizeDeps` pre-bundling — the core tier plus every
  `@sigx/*` dependency declared in the project's `package.json` — and sets
  `ssr.noExternal: ['sigx', /^@sigx\//]`. In middleware mode, if you have not
  pinned an HMR port, it assigns a free one so concurrent dev servers don't clash
  on Vite's default `24678`.
- In build (`command === 'build'`) it dedupes the runtime tier, sets the same
  `ssr.noExternal`, and forces those packages into a single `sigx` manual chunk to
  preserve singleton reactivity.
- Its `transform` hook injects the HMR runtime registration into any
  `.ts`/`.tsx`/`.jsx` source file (outside `node_modules` and `/dist/`) that
  contains a `component<` or `component(` usage, when `hmr` is `true` and in
  serve mode.
- All of the above merges with (never replaces) your own `optimizeDeps.exclude`,
  `ssr.noExternal`, and `server.hmr` config.

**Parameters**

- `options` — `SigxPluginOptions`. Optional; defaults to `{}`.

**Returns** — a Vite `Plugin`.

### default

```ts
export default sigxPlugin;
```

The default export, an alias for `sigxPlugin`. Idiomatic usage:

```ts
import sigx from '@sigx/vite';

export default {
    plugins: [sigx()],
};
```

### installHMRPlugin

```ts
export function installHMRPlugin(): Promise<void>;
```

Re-exported from `@sigx/vite/hmr` through the main entry. Installs the
browser-side SignalX HMR component plugin exactly once (guarded by an internal
`installed` flag). It lazily imports `registerComponentPlugin` from
`sigx/internals` to avoid a circular-init dependency, then registers an
`onDefine` hook that assigns each component a stable `__hmrId`, re-binds live
instances to the new setup/render function on reload, and tracks and cleans up
instances. Auto-invoked when the HMR module loads, so manual calls are rarely
needed.

**Returns** — `Promise<void>`.

### registerHMRModule

```ts
export function registerHMRModule(moduleId: string): void;
```

Re-exported from `@sigx/vite/hmr` through the main entry. Injected at the top of
each HMR-transformed module; it sets the current module id and resets that
module's component index to `0` so component ids (`moduleId:index`) stay stable
across re-executions. Normally injected automatically by the plugin's
`transform` hook, not called by hand.

**Parameters**

- `moduleId` — `string`. The id of the module being registered.

**Returns** — `void`.

## Library Builds (from `@sigx/vite/lib`)

### defineLibConfig

```ts
export function defineLibConfig(options: LibBuildOptions): UserConfigFnObject;
```

Produces a Vite 8 / Rolldown library-build config function for `@sigx/*` packages.
It normalizes the entry (`string` | record | `LibEntry[]`) into a Rolldown lib
config (ES format only, file name `${entryName}.js`), resolves alias paths
against `root` (accepts a `file://` URL or directory), and **always** prepends
the SignalX runtime externals — `sigx`, `@sigx/reactivity`,
`@sigx/runtime-core`, `@sigx/runtime-dom`, `@sigx/server-renderer`, and their
subpaths — to the caller's `external` list (deduped) to preserve singleton
reactivity.

It builds ES output only (file name `${entryName}.js`), sets `sourcemap` (default
`true`), minifies in place via Oxc (`minify: 'oxc'`, or `false`), an optional
`output.banner`, a node target (`node18`) when `platform === 'node'`, and Oxc
automatic JSX with import source `importSource` (default `sigx`) when `jsx` is
`true`. The result is a
config **function** (wrapped in Vite's `defineConfig`) that branches on
`--mode prod-dist`:

- **Default build** (`vite build`) emits the development dist with `emptyOutDir`
  on.
- **`vite build --mode prod-dist`** emits a parallel **production** dist into the
  same `outDir` (without emptying it): `process.env.NODE_ENV` is defined away to
  `'production'` so dev warnings and devtools plumbing are stripped, and every
  output file gets a `.prod.js` suffix for the package's `production` export
  condition. Run it as a second pass after the default build.

**Parameters**

- `options` — `LibBuildOptions`. Required.

**Returns** — a Vite `UserConfigFnObject` (a config function `({ mode }) =>
UserConfig`), so the `prod-dist` mode branch resolves at build time.

### defineConfig

```ts
export { defineConfig };
```

A direct re-export of Vite's own `defineConfig` from the `@sigx/vite/lib`
subpath, for convenience when composing custom configs alongside
`defineLibConfig`.

## Assets (from `@sigx/vite/assets`)

### collectAssets

```ts
function collectAssets(
    manifest: ViteManifest,
    entries: string[],
    base?: string     // public base path, default '/'
): CollectedAssets;   // { modulepreload: string[]; stylesheets: string[] }
```

Turns the Vite client manifest into `DocumentOptions.assets` — the
`<link rel="modulepreload">` and stylesheet set for the given client entries.
`entries` are manifest keys (source-relative ids such as
`'src/entry-client.tsx'`); one that isn't in the manifest is skipped with a
warning. URLs are deduped and prefixed with `base`.

```ts
import { collectAssets } from '@sigx/vite/assets';

const assets = collectAssets(manifest, ['src/entry-client.tsx']);
```

The `assets` entry imports nothing — no `node:` builtins, no `process` — so it
is importable from a workerd, Deno or Bun entry. `@sigx/vite/ssr` re-exports it,
but that module also carries `createDevRequestHandler` and so imports `node:fs/promises`
and `node:path` at its top level; reach for `/ssr` in dev and `/assets`
everywhere else.

## Types

### SigxPluginOptions

```ts
interface SigxPluginOptions {
    /**
     * Enable HMR support
     * @default true
     */
    hmr?: boolean;

    /**
     * Port for Vite's HMR websocket. Only relevant in middleware mode (the
     * standard SSR setup), where Vite's default 24678 collides when two dev
     * servers run on one machine. Unset: the plugin picks a free port
     * automatically. Explicit `server.hmr` settings always take precedence.
     */
    hmrPort?: number;
}
```

Options for `sigxPlugin`:

- **hmr** — toggles HMR injection. Default `true`.
- **hmrPort** — pins the HMR websocket port in middleware mode. When unset the
  plugin assigns a free port automatically; an explicit `server.hmr.port` (or
  `server.hmr: false`) in your Vite config wins.

> **Note.** This interface is declared but not exported from the package — pass
> the options inline: `sigx({ hmr: false })` or `sigx({ hmrPort: 24700 })`.

### LibBuildOptions

```ts
export interface LibBuildOptions {
    /** Single entry point or multiple entry points */
    entry: string | Record<string, string> | LibEntry[];
    /** Output directory @default 'dist' */
    outDir?: string;
    /** Enable sourcemaps @default true */
    sourcemap?: boolean;
    /** External dependencies (will not be bundled) @default [/@sigx\/.*/] */
    external?: (string | RegExp)[];
    /** Path aliases for bundling sibling packages. Keys are import paths, values are file paths relative to project root */
    alias?: Record<string, string>;
    /** Minify output in place via Oxc @default true */
    minify?: boolean;
    /** Banner to prepend to output (e.g., shebang for CLI tools) */
    banner?: string;
    /** Enable JSX transform for sigx @default false */
    jsx?: boolean;
    /** The module the automatic JSX runtime imports from. Read only when `jsx` is enabled. @default 'sigx' */
    importSource?: string;
    /** Platform target @default 'browser' */
    platform?: 'browser' | 'node' | 'neutral';
    /** The directory containing package.json (used to resolve aliases). Pass import.meta.url from your vite.config.ts */
    root?: string;
}
```

Options for `defineLibConfig`. Only `entry` is required; the rest use the
documented defaults.

### LibEntry

```ts
export interface LibEntry {
    /** Entry name (becomes output filename without extension) */
    name: string;
    /** Entry file path relative to project root */
    entry: string;
}
```

A single named entry in the array form of `LibBuildOptions.entry`.

## CLI

### sigx-types

```bash
npx sigx-types [options]
```

Generates `components.d.ts` and `components.ts` for tag-named components. Exposed
through the package's `bin` field, so `npx sigx-types` runs from any project with
`@sigx/vite` installed. See the [Commands](/vite/docs/commands) guide for usage and flags.

## See Also

- [Getting Started](/vite/docs/getting-started)
- [HMR for Components](/vite/docs/hmr)
- [Library Builds](/vite/docs/library-builds)
- [Commands](/vite/docs/commands)

---
url: https://sigx.dev/vite/docs/hmr/
title: HMR for Components
description: How @sigx/vite hot-reloads SignalX components while preserving per-instance signal state
---

# HMR for Components

Hot Module Replacement (HMR) lets you edit a component and see the change in the
browser without a full page reload. With `@sigx/vite`, component HMR preserves
each live instance's signal state — so editing a counter does not reset its
value.

You do not write any HMR code yourself. The plugin injects everything during
the dev server's transform step.

## Enabling HMR

HMR is on by default. Simply having the plugin in your config is enough:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [sigx()],
});
```

To turn it off, pass `hmr: false`:

```ts
import sigx from '@sigx/vite';

export default defineConfig({
    plugins: [sigx({ hmr: false })],
});
```

## The HMR websocket port

In a **middleware-mode** dev server — the standard SignalX SSR setup, where Vite
runs inside your own HTTP server — the HMR websocket cannot piggyback on the HTTP
server and Vite falls back to a fixed default port (`24678`). Run two dev servers
on one machine and they collide: the browser connects to the *other* server's
websocket, gets a 400 token mismatch, and HMR silently breaks.

`@sigx/vite` fixes this automatically. When you do **not** pin a port, the plugin
asks the OS for a free port and uses it for the HMR websocket — so concurrent dev
servers never clash. To pin one explicitly, pass `hmrPort`:

```ts
import sigx from '@sigx/vite';

export default defineConfig({
    server: { middlewareMode: true },
    plugins: [sigx({ hmrPort: 24700 })],
});
```

Any explicit `server.hmr` settings in your Vite config always take precedence —
the plugin only steps in when you haven't pinned a port yourself, and only in
middleware mode (when the websocket shares the HTTP server's port there is nothing
to fix).

## When the Transform Fires

The HMR transform only runs when **all** of these are true:

- The dev server is running (`vite` / `command === 'serve'`) — never during a
  production build.
- The plugin's `hmr` option is `true` (the default).
- The file is a first-party `.ts`, `.tsx`, or `.jsx` file — files in
  `node_modules` and `/dist/` are skipped.
- The file's source text contains a component declaration, matched by the
  pattern `component<` or `component(`.

If a file has no `component(` or `component<` usage, it is left untouched.

## What Gets Injected

For each matching module, the plugin prepends a module registration and appends
Vite's hot-accept call. Conceptually, your file is wrapped like this:

```ts
// --- injected at the top ---
import { registerHMRModule } from '@sigx/vite/hmr';
registerHMRModule('<module-id>');

// --- your original source ---
import { component, signal } from 'sigx';

export const Counter = component(() => {
    const count = signal(0);
    return () => <button onClick={() => count.value++}>{count.value}</button>;
});

// --- injected at the bottom ---
if (import.meta.hot) {
    import.meta.hot.accept();
}
```

You never write these lines — they are added automatically. The
`registerHMRModule` and `installHMRPlugin` functions are re-exported from
`@sigx/vite` only so the injected code can reference them; you rarely call them
by hand.

## How State Survives a Reload

Each component gets a stable id of the form `moduleId:definitionIndex`.
`registerHMRModule` resets the per-module component index to `0` at the top of
every re-execution, so the first `component(...)` in a file always keeps the
same id even after edits.

When a module reloads, the browser-side HMR plugin (installed once via
`installHMRPlugin`) re-binds each live instance to the new setup/render
function: it replaces `ctx.renderFn` and calls `ctx.update()` against the
existing context. Because the existing context is reused, signals created in
`setup` keep their current values across the reload. Instances are tracked on
define and cleaned up on `ctx.onUnmounted`.

## When a Full Reload Happens

If an HMR update throws, the runtime logs:

```text
[sigx] HMR failed for <name>
```

and falls back to a full page reload — the clean recovery path. This typically
happens when an edit changes the shape of a component in a way that cannot be
patched in place.

## Why This Matters

The deeper guarantee behind HMR is a **single physical copy** of
`@sigx/reactivity`. In dev the plugin aliases the SignalX runtime packages to
their `src` entries and excludes **all** `@sigx/*` packages from `optimizeDeps`
pre-bundling — the core tier plus every `@sigx/*` dependency declared in your
`package.json` (store, router, daisyui, …) — so no pre-bundled chunk can carry a
second reactivity copy. It also sets `ssr.noExternal: ['sigx', /^@sigx\//]` so the
whole family stays in the SSR module graph instead of splitting between Vite's
module runner and Node's resolver. In build it dedupes the runtime tier and forces
it into a single `sigx` chunk. Without that single copy, signal mutations from
`onMounted`, observers, `setTimeout`, or event handlers would silently fail to
re-render after hydration. Your own `optimizeDeps.exclude` / `ssr.noExternal`
entries are merged with the plugin's, never replaced.

## Next Steps

- [Library Builds](/vite/docs/library-builds) — build `@sigx/*` packages
- [API Reference](/vite/docs/api) — `installHMRPlugin`, `registerHMRModule`, and options

---
url: https://sigx.dev/vite/docs/ssr/
title: SSR mode
description: Build a server-rendered SignalX app with @sigx/vite — one vite build for both client and server, the islands transform, and the dev request handler
---

# SSR mode

<p class="lede">The <code>@sigx/vite</code> plugin has an SSR mode that produces both halves of a server-rendered app — the client bundle and the server bundle — from a single <code>vite build</code>, and a dev-server handler that shares one module graph with your app.</p>

This is the build-and-dev side of SSR; the runtime APIs it feeds live in [`@sigx/server-renderer`](/server/packages/server-renderer/overview).

## Turning on SSR

Pass an `ssr` block to the plugin, pointing at your server entry:

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { sigx } from '@sigx/vite';

export default defineConfig({
    plugins: [
        sigx({
            ssr: { entry: 'src/entry-server.tsx' },
        }),
    ],
});
```

| Option | Default | Meaning |
|---|---|---|
| `entry` | — (required) | Your server entry module. |
| `clientOutDir` | `'dist/client'` | Where the browser bundle + manifest are written. |
| `serverOutDir` | `'dist/server'` | Where the server bundle is written. |
| `adapter` | `nodeAdapter()` | The [deployment adapter](/vite/docs/deploy-adapters) shaping the server build — externalized Node output by default; Cloudflare/Vercel/Netlify adapters produce bundled platform builds. |

One `vite build` now runs both environments (via Vite's builder API): the client build emits `.vite/manifest.json` alongside the browser assets, and the server build emits `entry-server.js`.

With the default adapter the server bundle **externalizes its dependencies** rather than bundling a second copy of the runtime. That matters for correctness, not just size: a bundled runtime carries its own DI token identities and would never see the app's provides. (In practice the spa-ssr server bundle drops from ~97 kB to ~25 kB.) Edge platforms can't resolve `node_modules` at runtime, which is why their [deploy adapters](/vite/docs/deploy-adapters) switch to a **total** bundle — everything in one module graph preserves the same DI invariant from the other direction.

## The islands transform

If you use islands, add `sigxIslands()` from the `@sigx/vite/islands` entry:

```ts
import { sigx } from '@sigx/vite';
import { sigxIslands } from '@sigx/vite/islands';

export default defineConfig({
    plugins: [
        sigx({ ssr: { entry: 'src/entry-server.tsx' } }),
        sigxIslands(),
    ],
});
```

```ts
interface SigxIslandsOptions {
    include?: string | string[];   // default: *.island.ts(x), islands/**/*.ts(x)
    exclude?: string | string[];   // default: node_modules, dist
}
```

It does four things:

1. Stamps `__islandId` onto each island's named component export.
2. Rewrites signal declarations so island state gets a stable key (see [automatic state keys](/server/packages/ssr-islands/plugin-setup#automatic-state-keys)).
3. Serves `virtual:sigx-islands`, which registers a lazy `import()` per island.
4. Emits a `sigx-islands-manifest.json` on the client build (under `clientOutDir`, at `.vite/sigx-islands-manifest.json`), mapping island names → `{ chunkUrl, exportName }`. Feed that to `islandsPlugin({ manifest })`.

An island is a **named export** that is a component factory, in a file the `include` globs match. Names must be **unique across island files** — that name is the key.

## The dev-server handler

For `vite dev`, `@sigx/vite/ssr` gives you a request handler that renders through Vite's module runner — so the renderer, your app, and `islandsPlugin()` all share one module graph and one set of DI token identities:

```ts
import { createServer } from 'vite';
import { createDevRequestHandler } from '@sigx/vite/ssr';

const vite = await createServer({ server: { middlewareMode: true } });
const handler = await createDevRequestHandler(vite, {
    entry: '/src/entry-server.tsx',   // Vite-root-relative
    entryExport: 'createApp',         // default
});

app.use(vite.middlewares);
app.use(handler);
```

It fails fast at startup if `@sigx/server-renderer` isn't installed, and applies `ssrFixStacktrace` so errors point at your source.

### Styles in dev

The dev handler inlines the SSR module graph's CSS into the document `<head>`. There is nothing to configure.

This matters because of how Vite serves CSS in dev: a stylesheet reached through a JS import (`import './styles.css'` — so any app with Tailwind, daisyUI, CSS modules, or plain imported CSS) is served as a **JS module that injects a `<style>` at runtime**. Without inlining, dev SSR streamed a fully rendered document with no styles in the head, and the browser painted the entire page unstyled until the client entry executed.

The styles are emitted as `<style data-vite-dev-id="…">` — the shape Vite's client adopts on boot and HMR-replaces in place, so there are no duplicated rules and CSS HMR is untouched.

```ts
const handler = await createDevRequestHandler(vite, {
    entry: '/src/entry-server.tsx',
    devStyles: false,   // default: true
});
```

Set `devStyles: false` only when your template already ships a stylesheet link of its own.

This is **dev-only**. Production has always emitted the built manifest's real `<link>` tags via [`collectAssets`](/vite/docs/api), so it was never affected.

For **production**, the counterpart is `createRequestHandler` from `@sigx/server-renderer/node`, fed your built `entry-server.js` and manifest — see [Building a full SSR app](/server/packages/server-renderer/full-app).

## Where to go next

- [Deploy adapters](/vite/docs/deploy-adapters) — `ssr.adapter`, the `SigxAdapter` contract and `virtual:sigx-app`
- [The boundary model](/server/packages/server-renderer/boundaries) — what the transform's output feeds
- [Request lifecycle](/server/packages/server-renderer/request-lifecycle) — `createRequestHandler`, `useResponse`, the error seam
- [Islands plugin setup](/server/packages/ssr-islands/plugin-setup) — consuming the islands manifest

---
url: https://sigx.dev/cli/docs/api/
title: API Reference
description: "@sigx/cli — project scaffolding, plugin discovery and platform commands — API reference"
---

# API Reference

`@sigx/cli` exposes four entry points:

- `@sigx/cli` — `definePlugin`, `a` (the `@sigx/args` builder), and the plugin types.
- `@sigx/cli/plugin` — the same plugin API surface (preferred for plugin authors).
- `@sigx/cli/create` — `runCreate`, the `create` command entry point.
- `@sigx/cli/shell` — `runShell` and the TUI shell runtime (documented in [The shell runtime](/cli/docs/shell)).

For the command-line surface (`sigx create`, `sigx info`, and plugin-provided commands), see [Commands](/cli/docs/commands).

## Functions

### definePlugin

```ts
export function definePlugin(plugin: SigxPlugin): SigxPlugin;
```

Identity helper for authoring a sigx CLI plugin with type safety. It returns the plugin object unchanged, but checks it against the `SigxPlugin` contract. Import it from `@sigx/cli/plugin` (also re-exported from `@sigx/cli`).

- **`plugin`** — the plugin definition to validate and return.
- **Returns** — the same `SigxPlugin` object, unchanged.

As an alternative, you can use the `satisfies SigxPlugin` pattern instead of calling `definePlugin`.

### defineCommand

```ts
export function defineCommand<S extends ArgsShape = ArgsShape>(
    cmd: PluginCommand<S>,
): PluginCommand<S>;
```

Identity helper for authoring a single command **outside** a `definePlugin` literal — factoring a command into its own module or variable — while keeping `run`'s `ctx.args` inferred from the command's `args` builders. Inside a `definePlugin` literal each command already infers per key, so `defineCommand` is only needed when a command is defined on its own. Import it from `@sigx/cli/plugin` (also re-exported from `@sigx/cli`).

### a

```ts
export const a; // the @sigx/args builder factory
```

Re-exported from `@sigx/args`. Use it to declare a command's arguments — `a.string()`, `a.number()`, `a.boolean()`, `a.enum([...])`, `a.positional()`, `a.rest()`, refined with `.alias()`, `.default()`, `.required()`, `.multiple()`, `.describe()`. See [Authoring Plugins](/cli/docs/plugins#declaring-command-arguments) and the [`@sigx/args` guide](/terminal/packages/args/overview/). The companion types `AnyArg`, `ArgsShape`, and `InferArgs` are exported alongside it.

### runCreate

```ts
export function runCreate(opts?: CreateOptions): Promise<void>;
```

Entry point of the `create` command, exported from `@sigx/cli/create`. The `sigx` binary calls it with the options it already parsed via `@sigx/args`; the bare `@sigx/create` shim (`npm create @sigx@latest`) calls it with no argument, in which case it parses `process.argv` itself. In a TTY it runs the interactive `@sigx/terminal` prompts; in non-interactive mode — no TTY, `yes: true`, or both `type` and a positional `name` — it scaffolds headlessly and calls `process.exit()` with the result code.

- **`opts`** — optional pre-parsed `CreateOptions` (`name?`, `type?`, `styling?`, `yes?`). Omitted, it reads `process.argv`.
- **Returns** — `Promise<void>` (the function exits the process when it finishes).

When the bare `@sigx/create` shim parses `process.argv` itself, it is lenient: **unknown flags are tolerated** (ignored rather than erroring), so a future `sigx create` flag never breaks an older shim. The one hard error is a **trailing value-expecting flag with no value** (e.g. a dangling `--type`), which exits with code `2`.

## Interfaces

### SigxPlugin

```ts
export interface SigxPlugin {
    /** Unique plugin name (e.g. 'ssg', 'lynx') */
    name: string;
    /** Return true if this plugin handles the current project */
    detect: (cwd: string) => boolean;
    /** Commands this plugin provides */
    commands: Record<string, PluginCommand>;
    /** Optional TUI contributions merged into any plugin-hosted shell. */
    tui?: TuiContribution;
}
```

The plugin contract. A plugin package default-exports one of these (created via `definePlugin` or `satisfies SigxPlugin`).

- **`name`** — unique plugin name.
- **`detect`** — called during discovery with the current working directory; its commands are registered only when it returns `true`.
- **`commands`** — a map of command name to `PluginCommand`.
- **`tui`** — optional [TUI contribution](/cli/docs/shell) (tabs, slash commands, shortcuts, status items) merged into whichever plugin hosts the shell.

### PluginCommand

```ts
export interface PluginCommand<S = ArgsShape> {
    description: string;
    /** Fluent @sigx/args builders, e.g. `{ port: a.number().default(8788) }`. */
    args?: S;
    /** Alternate command names. Collisions warn; direct names beat aliases. */
    aliases?: string[];
    /** Hide from `sigx --help` (still dispatchable). */
    hidden?: boolean;
    /** Collect unknown flags into ctx.unknownFlags instead of erroring. */
    allowUnknownFlags?: boolean;
    run: (ctx: TypedCommandContext<S>) => Promise<void>;
}
```

Describes a single CLI command contributed by a plugin. It is generic over its `args` shape `S`, so `run`'s `ctx.args` is inferred from the builders you declare — no cast.

- **`description`** — help text for the command.
- **`args`** — optional map of argument names to `@sigx/args` builders (`a.*`). See [Declaring command arguments](/cli/docs/plugins#declaring-command-arguments). Defaults to `ArgsShape` (`Record<string, AnyArg>`).
- **`aliases`** — alternate names the command also answers to. A collision with another command warns; a direct command name always beats an alias.
- **`hidden`** — omit the command from `sigx --help` while keeping it dispatchable.
- **`allowUnknownFlags`** — collect undeclared flags into `ctx.unknownFlags` instead of erroring on them.
- **`run`** — async handler receiving a [`TypedCommandContext<S>`](#typedcommandcontext); resolves when the command finishes.

### CommandContext

```ts
export interface CommandContext {
    cwd: string;
    args: Record<string, unknown>;
    logger: Logger;
    plugins?: SigxPlugin[];
    cliVersion?: string;
    /** Unknown flag tokens — only when the command sets allowUnknownFlags. */
    unknownFlags?: string[];
}
```

The base context passed to a `PluginCommand.run` handler (see [`TypedCommandContext`](#typedcommandcontext) for the args-narrowed form your handler actually receives).

- **`cwd`** — `process.cwd()`.
- **`args`** — the parsed arguments. `args._` holds the verbatim tokens after a bare `--`.
- **`logger`** — a prefixed `Logger`.
- **`plugins`** — every plugin discovered for this project, so a shell-hosting command can merge peer plugins' TUI contributions via `runShell({ plugins })`.
- **`cliVersion`** — the running `sigx` binary's version, for plugin feature detection.
- **`unknownFlags`** — undeclared flag tokens, present only when the command sets `allowUnknownFlags`.

### TypedCommandContext

```ts
export type TypedCommandContext<S = ArgsShape> = Omit<CommandContext, 'args'> & {
    args: PluginArgs<S>;
};

export type PluginArgs<S> =
    ArgsShape extends S ? Record<string, unknown>
    : S extends ArgsShape ? InferArgs<S>
    : Record<string, unknown>;
```

`CommandContext` with `args` narrowed to the command's inferred shape. It's an intersection (not a generic member) so it stays assignable to `CommandContext` — a helper typed against `CommandContext` still accepts a `TypedCommandContext`. `PluginArgs<S>` resolves to the exact `InferArgs<S>` when `S` is a builders shape, and falls back to the legacy `Record<string, unknown>` for arg-less commands or hand-annotated contexts.

### Logger

```ts
export interface Logger {
    log: (msg: string) => void;
    warn: (msg: string) => void;
    error: (msg: string) => void;
}
```

Minimal logging interface available on `CommandContext.logger`. The core implementation prefixes messages with `[sigx]` and uppercases `WARN` / `ERROR` output.

- **`log`** — print an informational message.
- **`warn`** — print a warning.
- **`error`** — print an error.

Only `log`, `warn`, and `error` exist — there is no `info` method.

## Shell runtime

The `@sigx/cli/shell` entry point exports `runShell`, `createShellLogger`, `collectTuiContributions`, and `mergeShellConfig`, along with the `ShellConfig`, `ShellHandle`, `TuiContribution`, `ShellTab`, `SlashCommand`, `Shortcut`, and `StatusItem` types. These are documented in full in [The shell runtime](/cli/docs/shell).

---
url: https://sigx.dev/core/api/di/
title: Dependency Injection
description: SignalX dependency injection API reference
---

# Dependency Injection API

Provide and inject dependencies throughout the component tree.

## provide

Provide a value to all descendant components.

```tsx
function provide<T>(token: any, value: T): void;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `token` | `any` | Unique key (Symbol recommended) |
| `value` | `T` | Value to provide |

### Examples

```tsx
import { component, provide } from 'sigx';

// Create a unique token
const ThemeToken = Symbol('theme');

const App = component(({ signal }) => {
    const theme = signal({ mode: 'dark', primary: '#007bff' });
    
    // Provide to all descendants
    provide(ThemeToken, theme);

    return () => (
        <div>
            <Header />
            <Content />
        </div>
    );
});
```

---

## inject

Inject a value provided by an ancestor component.

```tsx
function inject<T>(token: any): T | undefined;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `token` | `any` | Token used in `provide()` |

### Returns

The provided value, or `undefined` if not found.

### Examples

```tsx
import { component, inject } from 'sigx';

const ThemeToken = Symbol('theme');

const Button = component(({ slots }) => {
    const theme = inject(ThemeToken);

    return () => (
        <button style={{ background: theme?.primary }}>
            {slots.default?.()}
        </button>
    );
});
```

---

## createInjectable

Create a self-providing injectable with automatic token management.

```tsx
function createInjectable<T>(
    token: any,
    factory: () => T
): () => T;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `token` | `any` | Unique token |
| `factory` | `() => T` | Factory function |

### Returns

A hook function that injects the value, creating it if needed.

### Examples

```tsx
import { createInjectable, signal } from 'sigx';

// Define injectable
const useUser = createInjectable(
    Symbol('user'),
    () => signal({ name: '', loggedIn: false })
);

// Use in any component
const Profile = component(() => {
    const user = useUser();

    return () => (
        <div>
            {user.loggedIn 
                ? <span>Welcome, {user.name}</span>
                : <span>Please log in</span>
            }
        </div>
    );
});

const LoginForm = component(({ signal }) => {
    const user = useUser();
    const form = signal({ name: '' });

    const login = () => {
        user.name = form.name;
        user.loggedIn = true;
    };

    return () => (
        <form onSubmit={login}>
            <input 
                value={form.name}
                onInput={(e) => form.name = e.target.value}
            />
            <button type="submit">Login</button>
        </form>
    );
});
```

---

## defineInjectable

Create an injectable factory function. It has two forms.

**Factory form** — pass a factory; the returned hook lazily creates and shares one instance (a module-global singleton by default, or the provided instance when an ancestor called `defineProvide`).

```tsx
function defineInjectable<T>(
    factory: () => T,
    options?: { name?: string },
): () => T;
```

**Required form** — pass a string name to declare a dependency that has *no* fallback and must be provided by an ancestor (or `app.defineProvide`). Injecting it unprovided throws [SIGX202](/errors/SIGX202) — the deliberate guard against a shared singleton leaking state between requests on the server.

```tsx
function defineInjectable<T>(
    name: string,
    options?: { hint?: string },
): () => T;
```

### Options

| Name | Form | Description |
|------|------|-------------|
| `name` | factory | A readable label for diagnostics and stack traces. Defaults to `factory.name`, then a definition-site pointer — set it for inline arrow factories that would otherwise be anonymous. |
| `hint` | required | A custom message appended to the [SIGX202](/errors/SIGX202) "not provided" error in place of the generated suggestion, e.g. `{ hint: 'Wrap the tree in <AuthProvider>.' }`. Read only in development, but the literal still ships in your bundle unless you gate it: `hint: __DEV__ ? '…' : undefined`. |

### Returns

A hook function that returns the injectable instance.

> **Server-safe singleton warning.** The factory form's fallback is a module-global singleton, which can leak state across requests on a server — so in development SignalX warns when one is used on a live client. That check is gated on `isLiveClient()` rather than `typeof window`, so windowless-but-live runtimes (a Lynx background thread, a terminal app, a worker) no longer get a false warning. When you genuinely need per-app state, use the required form (or `defineProvide` per request) instead.

### Examples

```tsx
import { defineInjectable, signal } from 'sigx';

const useCounter = defineInjectable(() => {
    const state = signal({ count: 0 });
    
    return {
        get count() { return state.count; },
        increment: () => state.count++,
        decrement: () => state.count--
    };
});

// Usage - same instance across components
const Display = component(() => {
    const counter = useCounter();
    return () => <div>Count: {counter.count}</div>;
});

const Controls = component(() => {
    const counter = useCounter();
    return () => (
        <div>
            <button onClick={counter.decrement}>-</button>
            <button onClick={counter.increment}>+</button>
        </div>
    );
});
```

Name an otherwise-anonymous factory, or give a required injectable a custom "not provided" hint:

```tsx
// readable in diagnostics despite the inline arrow factory
const useClock = defineInjectable(() => signal(Date.now()), { name: 'clock' });

// required — no fallback; the hint replaces the generated SIGX202 suggestion
const useSession = defineInjectable<Session>('Session', {
    hint: 'Provide it at the root: app.defineProvide(useSession, () => loadSession()).',
});
```

---

## defineProvide

Provide an injectable and return its instance.

```tsx
function defineProvide<T>(useFn: () => T): T;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `useFn` | `() => T` | Injectable created by `defineInjectable` |

### Returns

The created instance (also provided to descendants).

### Examples

```tsx
import { component, defineInjectable, defineProvide } from 'sigx';

const useStore = defineInjectable(() => {
    const state = signal({ items: [] });
    return {
        get items() { return state.items; },
        add: (item) => state.items = [...state.items, item]
    };
});

// Root component creates and provides
const App = component(() => {
    const store = defineProvide(useStore);
    
    // Can use store here
    store.add('Initial item');

    return () => (
        <div>
            <ItemList />
            <AddItemForm />
        </div>
    );
});

// Children inject it
const ItemList = component(() => {
    const store = useStore();
    return () => (
        <ul>
            {store.items.map(item => <li>{item}</li>)}
        </ul>
    );
});
```

---

## injectApp

Inject the application instance.

```tsx
function injectApp(): App | undefined;
```

### Returns

The current app instance, or `undefined` if not in an app context.

### Examples

```tsx
import { component, injectApp } from 'sigx';

const PluginUser = component(() => {
    const app = injectApp();
    
    // Access app-level functionality
    const router = app?.router;
    const config = app?.config;

    return () => <div>...</div>;
});
```

---

## Patterns

### Service Pattern

```tsx
// services/auth.ts
import { defineInjectable, signal } from 'sigx';

export const useAuth = defineInjectable(() => {
    const state = signal({ 
        user: null as User | null,
        loading: false 
    });

    return {
        get user() { return state.user; },
        get isAuthenticated() { return !!state.user; },
        get loading() { return state.loading; },
        
        login: async (email: string, password: string) => {
            state.loading = true;
            try {
                state.user = await authApi.login(email, password);
            } finally {
                state.loading = false;
            }
        },
        
        logout: () => {
            state.user = null;
        }
    };
});
```

### Config Pattern

```tsx
// Provide configuration at app root
const ConfigToken = Symbol('config');

const App = component(() => {
    provide(ConfigToken, {
        apiUrl: 'https://api.example.com',
        debug: true
    });
    
    return () => <Router />;
});

// Inject anywhere
const ApiClient = component(() => {
    const config = inject(ConfigToken);
    // Use config.apiUrl
});
```

### Theme Pattern

```tsx
const ThemeToken = Symbol('theme');

const useTheme = createInjectable(ThemeToken, () => 
    signal({ 
        mode: 'light' as 'light' | 'dark',
        colors: { primary: '#007bff' }
    })
);

const ThemeProvider = component(({ slots }) => {
    const theme = useTheme();
    
    return () => (
        <div class={`theme-${theme.mode}`}>
            {slots.default?.()}
        </div>
    );
});

const ThemeToggle = component(() => {
    const theme = useTheme();
    
    const toggle = () => {
        theme.mode = theme.mode === 'light' ? 'dark' : 'light';
    };
    
    return () => (
        <button onClick={toggle}>
            {theme.mode === 'light' ? '🌙' : '☀️'}
        </button>
    );
});
```

---

## Types

### InjectionKey

For type-safe injection, use typed tokens:

```tsx
import type { InjectionKey } from 'sigx';

interface User {
    id: number;
    name: string;
}

const UserToken: InjectionKey<User> = Symbol('user');

// Type-safe provide/inject
provide(UserToken, { id: 1, name: 'John' });
const user = inject(UserToken); // User | undefined
```

---
url: https://sigx.dev/core/api/app/
title: App
description: SignalX application and plugin API reference
---

# App API

Application creation and plugin system.

## defineApp

Create a SignalX application.

```tsx
function defineApp(options?: AppOptions): App;
```

### Parameters

| Name | Type | Description |
|------|------|-------------|
| `options.plugins` | `Plugin[]` | Plugins to install |
| `options.provide` | `Record<any, any>` | App-level provides |

### Returns

`App` - Application instance.

### App Methods

| Method | Type | Description |
|--------|------|-------------|
| `use(plugin)` | `(plugin: Plugin) => App` | Install a plugin |
| `mount(component, container)` | `(comp, el) => void` | Mount root component |
| `unmount()` | `() => void` | Unmount the application |
| `provide(token, value)` | `(token, value) => App` | Provide app-level value |
| `runWithContext(fn, options?)` | `<T>(fn: () => T, options?: RunWithContextOptions) => T` | Run `fn` with the app's DI context current |

### `runWithContext`

Runs a function with the app's DI context set as current, so use-functions from `defineInjectable` / `defineFactory` (and `inject`) called **outside** component setup — router guards, socket handlers, entry-scope code — resolve to the app's instances instead of a realm-level fallback. The context applies to the synchronous portion only (re-enter after `await`); nested calls restore the previous context.

```tsx
const app = defineApp(<App />);

router.beforeEach((to) =>
    app.runWithContext(() => {
        const auth = useAuthService(); // same instance components see
        return auth.isAuthenticated ? true : '/login';
    })
);
```

#### RunWithContextOptions

```ts
interface RunWithContextOptions {
    /** Dev-only. Replace the async-callback warning's advice, or suppress it. */
    asyncAdvice?: string | false;
}
```

In development, `runWithContext` warns once per app when its callback returns a promise — the context covers only the synchronous portion. `asyncAdvice` is for **libraries** that call `runWithContext` on a user's behalf, where the default advice names an API the reader never called:

| Value | Effect |
|---|---|
| `string` | Replaces the warning's remediation sentence; the sync-only diagnosis stays |
| `false` | Suppresses the warning for this call, without consuming the once-per-app slot |

```ts
app.runWithContext(() => guard(to, from), {
    asyncAdvice: 'Make the navigation guard synchronous, or resolve services before returning a promise.',
});
```

Dev-only and stripped from production builds. Cores older than 0.11 ignore the argument.

See [Resolving DI outside component setup](/core/docs/app-plugins#resolving-di-outside-component-setup) for the full picture.

### Examples

```tsx
import { defineApp, component } from 'sigx';

const App = component(() => {
    return () => <div>Hello, SignalX!</div>;
});

const app = defineApp();

// Install plugins
app.use(routerPlugin);
app.use(storePlugin);

// Provide app-level values
app.provide('config', { apiUrl: '/api' });

// Mount
app.mount(App, document.getElementById('app'));

// Later: unmount
app.unmount();
```

---

## Plugin

Interface for SignalX plugins.

```tsx
interface Plugin {
    name: string;
    install(app: App, options?: any): void;
}
```

### Creating Plugins

```tsx
import type { Plugin } from 'sigx';

const myPlugin: Plugin = {
    name: 'my-plugin',
    install(app, options = {}) {
        // Add app-level functionality
        app.provide('myFeature', createFeature(options));
        
        // Access app context
        console.log('Plugin installed');
    }
};

// Usage
const app = defineApp();
app.use(myPlugin);
```

### Plugin with Options

```tsx
interface LoggerOptions {
    level: 'debug' | 'info' | 'warn' | 'error';
    prefix: string;
}

function createLoggerPlugin(options: LoggerOptions): Plugin {
    return {
        name: 'logger',
        install(app) {
            const logger = {
                log: (msg: string) => {
                    if (shouldLog(options.level)) {
                        console.log(`${options.prefix} ${msg}`);
                    }
                }
            };
            app.provide('logger', logger);
        }
    };
}

// Usage
app.use(createLoggerPlugin({ level: 'info', prefix: '[App]' }));
```

---

## App Context

The app context is available throughout the component tree.

```tsx
import { component, injectApp } from 'sigx';

const MyComponent = component(() => {
    const app = injectApp();
    
    // Access app-level provides
    const config = app?.provides.get('config');
    
    return () => <div>API: {config?.apiUrl}</div>;
});
```

---

## Lifecycle Hooks

Apps support lifecycle hooks:

```tsx
const app = defineApp({
    onMount: () => console.log('App mounted'),
    onUnmount: () => console.log('App unmounted'),
    onError: (err) => console.error('App error:', err)
});
```

---

## Multiple Apps

You can create multiple independent apps:

```tsx
const mainApp = defineApp();
mainApp.mount(MainApp, document.getElementById('main'));

const widgetApp = defineApp();
widgetApp.mount(Widget, document.getElementById('widget'));

// Each app has its own:
// - Component tree
// - Provides
// - Plugins
```

---

## Common Patterns

### Router Plugin

```tsx
import { createRouter } from '@sigx/router';

const routerPlugin: Plugin = {
    name: 'router',
    install(app, { routes }) {
        const router = createRouter({ routes });
        app.provide('router', router);
        app.router = router;
    }
};

const app = defineApp();
app.use(routerPlugin, { 
    routes: [
        { path: '/', component: Home },
        { path: '/about', component: About }
    ]
});
```

### Store Plugin

```tsx
import { createStore } from '@sigx/store';

const storePlugin: Plugin = {
    name: 'store',
    install(app, storeOptions) {
        const store = createStore(storeOptions);
        app.provide('store', store);
        app.store = store;
    }
};
```

### Error Handling Plugin

```tsx
const errorHandlerPlugin: Plugin = {
    name: 'error-handler',
    install(app) {
        const errorState = signal({ 
            hasError: false, 
            error: null as Error | null 
        });
        
        app.provide('errorBoundary', {
            state: errorState,
            handleError: (err: Error) => {
                errorState.hasError = true;
                errorState.error = err;
                console.error('App error:', err);
            },
            reset: () => {
                errorState.hasError = false;
                errorState.error = null;
            }
        });
    }
};
```

---

## Types

### App

```tsx
interface App {
    use(plugin: Plugin, options?: any): App;
    mount(component: ComponentFactory, container: Element): void;
    unmount(): void;
    provide<T>(token: any, value: T): App;
    runWithContext<T>(fn: () => T, options?: RunWithContextOptions): T;
    provides: Map<any, any>;
}
```

### Plugin

```tsx
interface Plugin {
    name: string;
    install(app: App, options?: any): void;
}
```

### AppOptions

```tsx
interface AppOptions {
    plugins?: Plugin[];
    provide?: Record<any, any>;
    onMount?: () => void;
    onUnmount?: () => void;
    onError?: (error: Error) => void;
}
```

### AppContext

```tsx
interface AppContext {
    provides: Map<any, any>;
    plugins: Plugin[];
    root: ComponentFactory | null;
}
```

---
url: https://sigx.dev/ssg/docs/api/
title: API Reference
description: "@sigx/ssg — static site generation with MDX and island hydration — API reference"
---

# API Reference

This page documents the public surface of `@sigx/ssg`, defined by the package `exports` map: the main entry (`@sigx/ssg`), the Vite plugin (`@sigx/ssg/vite`), the build and dev entries (`@sigx/ssg/build`, `@sigx/ssg/dev`), the client helpers (`@sigx/ssg/client`), and the ambient virtual-module types (`@sigx/ssg/virtual`).

For CLI usage see [Commands](/ssg/docs/commands).

## Config

### defineSSGConfig

```ts
function defineSSGConfig(config: SSGConfig): SSGConfig
```

Type-safe SSG config helper. Applies defaults (`pages` `src/pages`, `layouts` `src/layouts`, `content` `src/content`, `defaultLayout` `default`, `outDir` `dist`, `base` `/`, `trailingSlash` `'always'`, `prefetch` true, `spaNavigation` true, `site.lang` `en`, `markdown.shiki` true, `toc.minLevel` 2 / `maxLevel` 3) then merges the user config.

- **config** — the user's SSG configuration.
- **Returns** — the merged config. Export it as the default from `ssg.config.ts`.

### defineConfig

```ts
const defineConfig = defineSSGConfig
```

Alias for `defineSSGConfig`, re-exported under the conventional Vite-style name.

## Build

### build

```ts
function build(options?: BuildOptions): Promise<BuildResult>
```

Programmatic static-site build. Loads config, scans routes, builds the client and SSR Vite bundles, renders every path (including paths expanded from `getStaticPaths`) to static HTML in `outDir`, and writes `sitemap.xml` and `robots.txt`. Also exported via `@sigx/ssg/build`.

- **options** — optional `BuildOptions` (`configPath`, `verbose`, `concurrency`, `drafts`). The effective default concurrency is 20; `drafts: true` includes pages with `draft: true` frontmatter, which are otherwise excluded from production builds and the sitemap.
- **Returns** — a `BuildResult` with the built pages, total time, and warnings.

## Dev server

### dev

```ts
function dev(options?: DevOptions): Promise<void>
```

Starts the SSG dev server. Uses an existing `vite.config` if present, otherwise runs zero-config: it auto-loads `@sigx/vite`, optionally `@tailwindcss/vite`, and the SSG plugins with `oxc` automatic JSX (import source `sigx`). Default port 5173. Also exported via `@sigx/ssg/dev`.

- **options** — optional `DevOptions` (`configPath`, `port`, `host`, `open`, `verbose`).
- **Returns** — a promise that resolves once the server has started.

### preview

```ts
function preview(options?: DevOptions): Promise<void>
```

Previews the production build through the Vite preview server (default port 4173). Also exported via `@sigx/ssg/dev`.

- **options** — optional `DevOptions`.
- **Returns** — a promise that resolves once the preview server has started.

## Sitemap

### generateSitemap

```ts
function generateSitemap(entries: SitemapEntry[], config: SSGConfig): string
```

Builds `sitemap.xml` content (sitemaps.org 0.9 schema) from entries. Each path is prefixed with `site.url` + `base` and normalized per the config's `trailingSlash` policy, byte-identical with the canonical URL emitted in each page's head.

- **entries** — the sitemap entries to include.
- **config** — the SSG config (supplies `site.url`, `base`, and `trailingSlash`).
- **Returns** — the sitemap XML as a string.

### normalizePagePath

```ts
function normalizePagePath(path: string, trailingSlash?: 'always' | 'never'): string
```

Normalizes a route path for public URLs (canonical, `og:url`, sitemap `<loc>`). With `'always'` (the default, matching the `<path>/index.html` output layout) folder routes gain a trailing slash (`/about` → `/about/`); the root `/` and explicit `.html` paths are untouched. With `'never'`, trailing slashes are stripped instead. The `TrailingSlash` union type is also exported.

- **path** — the route path to normalize.
- **trailingSlash** — the policy (defaults to `'always'`).
- **Returns** — the normalized path.

### generateRobotsTxt

```ts
function generateRobotsTxt(config: SSGConfig, sitemapPath?: string): string
```

Builds `robots.txt` content (an `Allow: /` line and a `Sitemap:` line).

- **config** — the SSG config.
- **sitemapPath** — path to the sitemap (defaults to `/sitemap.xml`).
- **Returns** — the robots.txt content as a string.

### writeSitemap

```ts
function writeSitemap(
    pages: PageBuildResult[],
    config: SSGConfig,
    outDir: string,
    options?: SitemapOptions,
): Promise<{ sitemapPath: string; robotsPath: string }>
```

Converts built pages to entries and writes `sitemap.xml` and `robots.txt` to `outDir`. Called automatically at the end of `build()`.

- **pages** — the build results to map.
- **config** — the SSG config.
- **outDir** — the output directory.
- **options** — optional `SitemapOptions`.
- **Returns** — the written `sitemapPath` and `robotsPath`.

### pagesToSitemapEntries

```ts
function pagesToSitemapEntries(
    pages: PageBuildResult[],
    options?: SitemapOptions,
): SitemapEntry[]
```

Maps build results to sitemap entries, applying `exclude` globs and depth-based priority (`/` = 1.0, depth 1 = 0.8, depth 2 = 0.6, otherwise `defaultPriority` 0.5) and `defaultChangefreq` `weekly`.

- **pages** — the build results to map.
- **options** — optional `SitemapOptions`.
- **Returns** — the derived `SitemapEntry[]`.

### loadThemeModule / applyThemeConfig / resolveThemeConfig

```ts
function loadThemeModule(themeName: string, root: string): Promise<ThemeModule>
function applyThemeConfig(config: SSGConfig, theme: ThemeModule): SSGConfig
function resolveThemeConfig(config: SSGConfig, root: string): Promise<SSGConfig>
```

Theme loading and config-contribution merging: a theme's exported `config` can contribute markdown plugins (run before the site's), build hooks (run before the site's), head tags (prepended to `site.head`), CSS import specifiers (prepended to `clientImports`), and a `defaultLayout` (used when the site doesn't set one). `resolveThemeConfig` combines both: it loads `config.theme` (if set) and applies it. Build and dev call this automatically; the exports exist for tooling.

## Redirects, search, data, link checking

These build-time helpers back the corresponding config options; the build calls them for you, and they are exported for programmatic use.

### Redirects

```ts
function generateRedirectHtml(target: string, config: SSGConfig): string
function generateRedirectsFile(redirects: Record<string, string>, config: SSGConfig): string
function writeRedirects(
    redirects: Record<string, string>,
    config: SSGConfig,
    outDir: string,
    renderedPaths?: Iterable<string>,
): Promise<void>
```

Emit the per-path meta-refresh pages and the Netlify/Cloudflare `_redirects` file. Relative targets are prefixed with `base`; a redirect colliding with a rendered page throws. See [Configuration → Redirects](/ssg/docs/configuration#redirects).

### Search

```ts
function extractSearchText(html: string): string
function buildSearchIndex(pages: PageBuildResult[], options?: SearchOptions): SearchIndexEntry[]
function writeSearchIndex(/* … */): Promise<void>
```

Build the `search-index.json` over rendered pages. Consume it on the client with `loadSearchIndex` / `searchPages` from `@sigx/ssg/client`.

### LLM output

```ts
function getMarkdownPath(urlPath: string): string
function prepareLlmsPages(
    pages: PageBuildResult[],
    config: SSGConfig,
    options?: LlmsOptions,
    readSource?: (file: string) => Promise<string | null>,
): Promise<LlmsPage[]>
function renderPageMarkdown(source: string, options: RenderPageMarkdownOptions): string
function buildLlmsIndex(pages: LlmsPage[], config: SSGConfig, options?: LlmsOptions): string
function buildLlmsFullText(pages: LlmsPage[], options?: LlmsFullOptions): string
function writeLlmsOutputs(
    pages: PageBuildResult[],
    config: SSGConfig,
    outDir: string,
    options?: LlmsOptions,
    publicDir?: string,
): Promise<{ files: string[]; warnings: string[] }>
```

The helper family behind the [`llms` config option](/ssg/docs/configuration#llm-friendly-output-llmstxt). `getMarkdownPath` maps a route to its `.md` rendition path (`/docs/guide/` → `docs/guide.md`, `/` → `index.md`). `prepareLlmsPages` filters the built pages to the llms-visible set (sitemap rules + `exclude` globs + frontmatter `llms: false` + `transform`) and renders each markdown-sourced page's rendition once; `buildLlmsIndex` and `buildLlmsFullText` are pure over the prepared pages, so per-area files are filtered re-invocations. `renderPageMarkdown` is the per-page rendition: frontmatter replaced with a `---\nurl/title/description\n---` header, MDX syntax stripped by a fence-aware line scanner (fence contents are never touched), and fence info strings normalized to the bare language. `writeLlmsOutputs` writes everything into `outDir` — a `llms*` file you ship via `public/` is never overwritten.

### Data loaders

```ts
function runDataLoaders(loaders: DataLoaders): Promise<Record<string, unknown>>
function generateDataModule(values: Record<string, unknown>): string
```

Run the config's `data` loaders and emit the `virtual:ssg-data` module source. Values must be JSON-serializable.

### Link checking

```ts
function checkLinks(
    docs: Array<{ path: string; html: string }>,
    options?: LinkCheckOptions,
): BrokenLink[]
function extractLocalLinks(html: string): string[]
function extractElementIds(html: string): Set<string>
function formatLinkCheckReport(broken: BrokenLink[]): string
```

Validate internal links and `#fragment` anchors across rendered pages. `linkCheck: 'warn' | 'error'` in the config drives whether findings warn or fail the build.

### Other build helpers

```ts
function generateDefault404(config: SSGConfig): string
function gitLastModifiedMap(root: string): Map<string, string>
function resolveLastmods(/* … */): Map<string, string>
```

`generateDefault404` produces the fallback `404.html` when no `/404` page exists; `gitLastModifiedMap` / `resolveLastmods` back `sitemap.lastmod`.

## Vite plugin

### ssgPlugin

```ts
function ssgPlugin(options?: SSGPluginOptions): Plugin[]
```

The main Vite plugin, exported from `@sigx/ssg/vite`. Returns an **array** of Vite plugins: file-based routing, layouts, navigation, and zero-config entry generation, plus the MDX plugin (unless `enableMdx: false`). It serves the `virtual:ssg-routes`, `virtual:ssg-navigation`, `virtual:ssg-config`, `virtual:generated-layouts`, and virtual client/server entry modules, and handles HMR for pages, layouts, and MDX frontmatter.

- **options** — optional `SSGPluginOptions` (`Partial<SSGConfig>` plus `configPath` and `enableMdx`, default `true`).
- **Returns** — an array of Vite plugins; spread it or pass it directly to Vite's `plugins`.

### default export of `@sigx/ssg/vite`

```ts
export default ssgPlugin
```

The default export of `@sigx/ssg/vite` is `ssgPlugin`.

## Build hooks

`SSGConfig.hooks` carries `BuildHooks` — `transformHtml(html, page)`, `onPageRendered(page & { html })`, and `postBuild(result, ctx)`. See [Configuration & Content → Build hooks](/ssg/docs/configuration#build-hooks) for semantics (per-page hooks run concurrently; a throwing hook fails the build).

## Errors

### SSGError

```ts
class SSGError extends Error {
    readonly code: string;
    readonly file?: string;
    readonly line?: number;
    readonly suggestion?: string;
    constructor(message: string, options: {
        code: string;
        file?: string;
        line?: number;
        suggestion?: string;
        cause?: Error;
    });
    format(root?: string): string;
}
```

Structured SSG error carrying a code, an optional file and line, and a suggestion. `format()` renders a console-friendly message with the relative path and a hint.

### ErrorCodes

```ts
const ErrorCodes: {
    readonly CONFIG_NOT_FOUND: 'SSG001';
    readonly CONFIG_INVALID: 'SSG002';
    readonly CONFIG_THEME_NOT_FOUND: 'SSG003';
    readonly PAGE_NOT_FOUND: 'SSG100';
    readonly PAGE_INVALID_EXPORT: 'SSG101';
    readonly DYNAMIC_ROUTE_NO_PATHS: 'SSG102';
    readonly LAYOUT_NOT_FOUND: 'SSG103';
    readonly BUILD_RENDER_FAILED: 'SSG300';
    readonly BUILD_VITE_FAILED: 'SSG301';
    readonly MDX_PARSE_ERROR: 'SSG400';
    readonly MDX_FRONTMATTER_ERROR: 'SSG401';
}
```

Catalog of SSG diagnostic codes used in error and warning messages (for example, `SSG102` means a dynamic route is missing `getStaticPaths`).

### handleError

```ts
function handleError(error: unknown, root?: string): never
```

Formats and logs an error (an `SSGError` gets pretty output, including its cause), then calls `process.exit(1)`. Terminal helper for CLI entry points.

- **error** — the error to report.
- **root** — optional project root, used to render relative paths.

## Client helpers

These are exported from `@sigx/ssg/client`.

### prefetch

```ts
function prefetch(path: string): void
```

Appends a `<link rel="prefetch">` for the given path to `<head>`.

- **path** — the internal path to prefetch.

### setupPrefetch

```ts
function setupPrefetch(options?: { delay?: number }): void
```

Prefetches internal links on hover (default delay 100 ms), skipping external and hash links and already-prefetched paths. Wired automatically in the generated client entry when `config.prefetch` is enabled.

- **options.delay** — hover delay in milliseconds before prefetching.

### installSpaNavigation

```ts
function installSpaNavigation(
    router: { push(path: string): unknown },
    options?: { base?: string; trailingSlash?: TrailingSlash },
): () => void
```

Routes same-origin internal anchor clicks (including plain markdown links) through the router instead of full page reloads. The browser keeps handling modified clicks, external/`mailto:` links, `target`/`download` anchors, same-document `#hash` scrolls, `data-no-spa` opt-outs, and anything that already called `preventDefault()`. Wired automatically into the generated client entry (`spaNavigation: false` disables); call it yourself in custom entries. Returns an uninstall function.

- **router** — anything with a `push(path)` method.
- **options.base** — the site base path on subpath deploys (stripped before push).
- **options.trailingSlash** — `'always'` (the default) pushes the canonical trailing-slash URL for folder routes so SPA navigation matches the hard-load form; paths with a file extension (e.g. `/sitemap.xml`) are pushed verbatim. `'never'` strips the slash instead. Set it from the same config value as the build.

### isStaticPage

```ts
function isStaticPage(): boolean
```

Returns `true` when the document has no `data-ssr` attribute (statically generated rather than server-rendered).

### getInitialState

```ts
function getInitialState<T = Record<string, unknown>>(): T | null
```

Parses the JSON embedded in the `#__SSG_STATE__` script element, or returns `null`.

- **Returns** — the parsed state, or `null` if absent.

### Package-manager API

```ts
function getPackageManager(): Pm
function setPackageManager(pm: Pm): void
function onPackageManagerChange(listener: (pm: Pm) => void): () => void
function installPackageManagerSwitcher(): () => void

// pure command helpers
function parsePackageManagerCommand(command: string): ParsedPackageManagerCommand | null
function renderPackageManagerCommand(parsed: ParsedPackageManagerCommand, pm: Pm): string
function translatePackageManagerCommand(command: string, pm: Pm): string
const PACKAGE_MANAGERS: readonly Pm[]   // 'pnpm' | 'npm' | 'yarn' | 'bun'
const DEFAULT_PACKAGE_MANAGER: Pm       // 'pnpm'
type Pm = 'pnpm' | 'npm' | 'yarn' | 'bun'
```

The npm/pnpm/yarn/bun switcher behind package-manager code fences. `getPackageManager` reads the current selection (in-page → persisted → server default → `'pnpm'`); `setPackageManager` selects one, updating every switcher window, persisting the choice, and notifying subscribers; `onPackageManagerChange` subscribes (returns an unsubscribe). `installPackageManagerSwitcher` wires the tab clicks, cross-tab sync, and late-mounted windows — wired automatically in the generated client entry. The pure `parse`/`render`/`translate` helpers convert a single command between managers without touching the DOM. See [Client runtime](/ssg/docs/client-runtime#package-manager-switcher).

### loadSearchIndex

```ts
function loadSearchIndex(options?: { base?: string; url?: string }): Promise<SearchIndexEntry[]>
```

Fetches the emitted `search-index.json` (built when `search: true`). Pass `base` for subpath deploys, or `url` to override the location. Throws with a hint if the index is missing.

### searchPages

```ts
function searchPages(
    entries: SearchIndexEntry[],
    query: string,
    options?: { limit?: number },
): SearchResult[]
```

Ranks index entries against a query (AND semantics across whitespace-separated terms; title matches outrank headings outrank description outrank body). Each `SearchResult` carries `path`, `title`, `score`, an optional body `excerpt`, and an optional heading `anchor` for deep links. Pure and dependency-free. See [Client runtime → Search](/ssg/docs/client-runtime#search).

### installCodeCopy

```ts
function installCodeCopy(): () => void
```

Wires the copy buttons Shiki emits in every code-window header (package-manager windows copy only the visible variant). One delegated listener; returns a disposer; safe on pages without code blocks. Wired automatically in the generated client entry.

### ssrClientPlugin

```ts
export { ssrClientPlugin } from '@sigx/server-renderer/client'
```

Re-exported from `@sigx/ssg/client`. The SignalX app plugin that enables client-side hydration of server-rendered HTML; the generated client entry uses it via `.use(ssrClientPlugin)`.

## Types

The following interfaces and types are part of the public surface.

### SSGConfig

```ts
interface SSGConfig {
    pages?: string;
    layouts?: string;
    content?: string;
    theme?: string;
    defaultLayout?: string;
    outDir?: string;
    base?: string;
    trailingSlash?: 'always' | 'never';
    site?: SiteConfig;
    markdown?: MarkdownConfig;
    clientEntry?: string;
    clientImports?: string[];
    serverEntry?: string;
    htmlTemplate?: string | false;
    prefetch?: boolean | { delay?: number };
    spaNavigation?: boolean;
    collections?: Record<string, CollectionConfig>;
    navigation?: NavigationConfig;
    toc?: TOCConfig;
    sitemap?: SitemapOptions | false;
    hooks?: BuildHooks;
    redirects?: Record<string, string>;
    search?: boolean | SearchOptions;
    linkCheck?: 'off' | 'warn' | 'error';
    routes?: (ctx: RoutesContext) => ProgrammaticRoute[] | Promise<ProgrammaticRoute[]>;
    data?: DataLoaders;
}
```

The full SSG configuration object accepted by `defineSSGConfig`. `redirects` maps old paths to new (see [Configuration → Redirects](/ssg/docs/configuration#redirects)); `search` enables the built-in search index; `linkCheck` (default `'warn'`) validates internal links and anchors; `routes` adds programmatic pages; `data` registers build-time data loaders exposed via `virtual:ssg-data`.

### SiteConfig

```ts
interface SiteConfig {
    title?: string;
    description?: string;
    author?: string;
    url?: string;
    lang?: string;
    favicon?: string;
    ogImage?: string;
    twitter?: string;
    fonts?: string[];
    themeColor?: string;
    jsonLd?: object | object[];
    nav?: NavItem[];
    logo?: string;
    repo?: string;
    head?: HeadTag[];
    search?: boolean | { base?: string; url?: string };
    editBase?: string;
    announcement?: { text: string; href?: string; id?: string };
}
```

Site-wide metadata used for head tags, canonical URLs, and the sitemap, plus the fields layouts/themes render: `nav`, `logo`, `repo`, `head`, global `jsonLd`, the `search` UI flag, an `editBase` for edit-this-page links, and an `announcement` bar. Reaches layouts via `LayoutProps.site`.

### HeadTag

```ts
interface HeadTag {
    tag: string;
    attrs?: Record<string, string>;
    children?: string;
}
```

A raw tag injected into `<head>`. `attrs` values are HTML-escaped; `children` is emitted verbatim, so it can hold inline JSON, CSS, or script content.

### CollectionConfig

```ts
interface CollectionConfig {
    path: string;
    layout?: string;
    showDrafts?: 'dev' | 'never';
    sectionOrder?: Record<string, number> | string[];
}
```

Configuration for a single content collection, keyed by name under `collections`. `sectionOrder` (a name → weight map or an explicit list) overrides the site-wide `navigation.sectionOrder` for this collection's sidebar.

### NavigationConfig

```ts
interface NavigationConfig {
    sidebar?: NavSection[];
    autoGenerate?: boolean;
    showDrafts?: 'dev' | 'never';
    sectionOrder?: Record<string, number> | string[];
}
```

Navigation configuration: explicit sections, auto-generation (default `true`), draft handling, and `sectionOrder` — a name → weight map (lower first, merged over the built-in defaults) or an explicit category list (listed first in order, then the rest per the defaults). A collection can override it with its own `sectionOrder`.

### NavSection

```ts
interface NavSection {
    title: string;
    items: NavItem[];
    order?: number;
}
```

A titled group of navigation items.

### NavItem

```ts
interface NavItem {
    title: string;
    href?: string;
    items?: NavItem[];
    order?: number;
}
```

A single navigation entry, optionally nesting child items.

### PageMeta

```ts
interface PageMeta {
    title?: string;
    description?: string;
    layout?: string;
    draft?: boolean;
    date?: string | Date;
    tags?: string[];
    ssr?: boolean;
    category?: string | string[];
    order?: number;
    sidebar?: boolean;
    toc?: boolean | { minLevel?: number; maxLevel?: number };
    headings?: TocHeading[];
    [key: string]: unknown;
}
```

Per-page metadata, sourced from frontmatter or an exported `meta`.

### PageModule

```ts
interface PageModule {
    default: ComponentFactory<any, any, any>;
    getStaticPaths?: GetStaticPaths;
    layout?: string;
    frontmatter?: PageMeta;
}
```

The shape of a page module: a default component, optional `getStaticPaths`, an optional layout, and frontmatter.

### GetStaticPaths

```ts
type GetStaticPaths = () => StaticPath[] | Promise<StaticPath[]>
```

A function a dynamic route exports to enumerate the paths to pre-render.

### StaticPath

```ts
interface StaticPath {
    params: Record<string, string>;
    props?: Record<string, unknown>;
}
```

One pre-rendered path: the route `params` and optional `props` passed to the page.

### SSGRoute

```ts
interface SSGRoute {
    path: string;
    file: string;
    name: string;
    layout?: string;
    component?: ComponentFactory<any, any, any>;
    meta?: PageMeta;
    children?: SSGRoute[];
}
```

A resolved route produced by scanning `src/pages`.

### LayoutModule

```ts
interface LayoutModule {
    default: ComponentFactory<LayoutProps, unknown, LayoutSlots>;
}
```

The shape of a layout module.

### LayoutProps

```ts
interface LayoutProps {
    meta?: PageMeta;
    path?: string;
    site?: SiteConfig;
}
```

Props passed to a layout component: the current page `meta`, the route `path`, and the whole `site` config so layouts/themes can render branding, search UI, announcement bars, and edit-this-page links without hardcoding them.

### LayoutSlots

```ts
interface LayoutSlots {
    default: () => unknown;
}
```

Slots provided to a layout; `default()` renders the page content.

### ThemeModule

```ts
interface ThemeModule {
    layouts?: Record<string, ComponentFactory<LayoutProps, unknown, LayoutSlots>>;
    components?: Record<string, ComponentFactory<any, any, any>>;
    config?: ThemeConfig;
}
```

The shape of a theme package referenced through the config `theme` field.

### ThemeConfig

```ts
interface ThemeConfig {
    defaultLayout?: string;
    hooks?: BuildHooks;
    markdown?: Pick<MarkdownConfig, 'remarkPlugins' | 'rehypePlugins'>;
    head?: HeadTag[];
    css?: string[];
}
```

Config a theme contributes, merged so the site's own config always wins: a `defaultLayout` (used when the site doesn't set one), build `hooks` (run before the site's), `markdown` plugins (run before the site's), `head` tags (prepended to `site.head`), and `css` import specifiers (prepended to `clientImports`). See [Themes](/ssg/docs/themes).

### MarkdownConfig

```ts
interface MarkdownConfig {
    shiki?: boolean | ShikiConfig;
    remarkPlugins?: unknown[];
    rehypePlugins?: unknown[];
}
```

Markdown / MDX processing options.

### ShikiConfig

```ts
interface ShikiConfig {
    light?: string;
    dark?: string;
    langs?: string[];
    triggerLabel?: string;
    defaultPackageManager?: 'pnpm' | 'npm' | 'yarn' | 'bun';
    transformers?: ShikiTransformer[];
    skipLanguages?: string[];
}
```

Shiki highlighting options. `transformers` (from `shiki`) are applied to every highlighted block, with the raw fence meta exposed as `options.meta.__raw`; `skipLanguages` leaves listed fences untouched for a downstream rehype plugin/island (e.g. `['mermaid', 'math']` — see [`@sigx/mermaid`](/mermaid/docs/ssg)); `defaultPackageManager` (default `'pnpm'`) chooses the first variant on package-manager fences; `triggerLabel` is the live-code "Try Live" button label.

### TOCConfig

```ts
interface TOCConfig {
    minLevel?: number;
    maxLevel?: number;
}
```

Heading levels included when extracting a table of contents (defaults: 2 to 3).

### TocHeading

```ts
interface TocHeading {
    id: string;
    text: string;
    level: number;
}
```

A single extracted heading.

### BuildOptions

```ts
interface BuildOptions {
    configPath?: string;
    verbose?: boolean;
    concurrency?: number;
    drafts?: boolean;
}
```

Options for `build()`. The effective default `concurrency` is 20; `drafts: true` includes pages with `draft: true` frontmatter, otherwise excluded from production builds and the sitemap.

### BuildResult

```ts
interface BuildResult {
    pages: PageBuildResult[];
    totalTime: number;
    warnings: string[];
}
```

The result of `build()`.

### PageBuildResult

```ts
interface PageBuildResult {
    path: string;
    file: string;
    time: number;
    size: number;
    meta?: PageMeta;
    source?: string;
}
```

Per-page build statistics, carrying the page `meta` and the absolute `source` file path (read by `sitemap.lastmod` git/mtime derivation).

### DevOptions

```ts
interface DevOptions {
    configPath?: string;
    port?: number;
    host?: string | boolean;
    open?: boolean;
    verbose?: boolean;
}
```

Options for `dev()` and `preview()`.

### SSGContext

```ts
interface SSGContext {
    site: SiteConfig;
    page: PageMeta;
    params: Record<string, string>;
    isDev: boolean;
    base: string;
}
```

The rendering context exposed to pages.

### SSGPluginOptions

```ts
interface SSGPluginOptions extends Partial<SSGConfig> {
    configPath?: string;
    enableMdx?: boolean; // default true
}
```

Options for `ssgPlugin()`.

### SitemapEntry

```ts
interface SitemapEntry {
    path: string;
    lastmod?: Date | string;
    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
    priority?: number;
}
```

A single sitemap URL entry.

### SitemapOptions

```ts
interface SitemapOptions {
    includePages?: boolean;
    additionalUrls?: SitemapEntry[];
    exclude?: string[];
    defaultChangefreq?: SitemapEntry['changefreq'];
    defaultPriority?: number;
    lastmod?: 'git' | 'mtime' | false;
    transform?: (entry: SitemapEntry, page: PageBuildResult) => SitemapEntry | null | undefined;
}
```

Options for sitemap generation. `lastmod` derives each `<lastmod>` from the source file — `'git'` from the last commit date (needs full history), `'mtime'` from the filesystem timestamp (default `false`); explicit per-page `meta.lastmod` always wins. `transform` runs last per entry — adjust it, or return `null`/`undefined` to drop it.

### BuildHooks

```ts
interface BuildHooks {
    transformHtml?: (html: string, page: BuildHookPage) => string | Promise<string>;
    onPageRendered?: (page: PageBuildResult & { html: string }) => void | Promise<void>;
    postBuild?: (
        result: { pages: PageBuildResult[]; warnings: string[] },
        ctx: { outDir: string; config: SSGConfig },
    ) => void | Promise<void>;
}
```

Build pipeline hooks (production builds only). The per-page hooks run concurrently and in no guaranteed order; `postBuild` runs exactly once. See [Configuration → Build hooks](/ssg/docs/configuration#build-hooks).

### BuildHookPage

```ts
interface BuildHookPage {
    path: string;
    params: Record<string, string>;
    props?: Record<string, unknown>;
    meta?: PageMeta;
    route: SSGRoute;
}
```

The page context passed to per-page build hooks.

### SearchOptions

```ts
interface SearchOptions {
    output?: string;
    maxTextLength?: number;
}
```

Built-in search options: the index filename inside `outDir` (default `'search-index.json'`) and the per-page visible-text cap in characters (default `8000`).

### SearchIndexEntry

```ts
interface SearchIndexEntry {
    path: string;
    title: string;
    description?: string;
    headings: TocHeading[];
    text: string;
    tags?: string[];
}
```

One page in the emitted search index. Also exported from `@sigx/ssg/client`.

### LlmsOptions

```ts
interface LlmsOptions {
    index?: boolean;                       // llms.txt (default true)
    title?: string;                        // default site.title
    description?: string;                  // default site.description
    intro?: string;                        // markdown emitted after the blockquote
    sections?: LlmsSection[];              // curated index; default: auto per collection
    full?: boolean | LlmsFullOptions;      // llms-full.txt (default true)
    pageMd?: boolean;                      // per-page .md renditions (default true)
    areas?: Record<string, LlmsAreaOptions>; // per-area sub-indexes; key = path prefix
    exclude?: string[];                    // route globs excluded from ALL llms outputs
    transform?: (md: string, page: PageBuildResult) => string | null | undefined;
}

interface LlmsSection {
    title: string;            // emitted as `## title`
    collections?: string[];   // those collections' pages, in sidebar order
    pages?: string[];         // explicit route paths
    links?: LlmsLink[];       // hand-authored entries
}

interface LlmsLink {
    title: string;
    href: string;             // route path (resolved to its .md rendition) or external URL
    note?: string;            // rendered as the `: note` suffix
}

interface LlmsFullOptions {
    output?: string;          // default 'llms-full.txt'
    include?: string[];       // route globs (default: every markdown-sourced page)
    exclude?: string[];
}

type LlmsAreaOptions = Omit<LlmsOptions, 'areas' | 'pageMd' | 'transform'>;
```

Configuration for the [LLM-friendly output](/ssg/docs/configuration#llm-friendly-output-llmstxt). An area's `full` defaults to `false` (per-area `llms-full.txt` is opt-in); the global `transform` receives every page and can branch on `page.path`.

### LlmsPage

```ts
interface LlmsPage {
    page: PageBuildResult;
    url: string;         // absolute HTML URL
    mdPath?: string;     // outDir-relative .md rendition path (markdown-sourced pages only)
    markdown?: string;   // the rendition, header block included
}
```

A built page prepared for the llms outputs by `prepareLlmsPages`.

### RoutesContext / ProgrammaticRoute / DataLoaders

```ts
interface RoutesContext {
    config: SSGConfig;
    root: string;
}

interface ProgrammaticRoute {
    path: string;
    file: string;
    layout?: string;
    meta?: PageMeta;
}

type DataLoaders = Record<string, () => unknown | Promise<unknown>>;
```

`config.routes` is `(ctx: RoutesContext) => ProgrammaticRoute[] | Promise<…>` — pages added outside the filesystem scan. `config.data` is a `DataLoaders` map exposed via `virtual:ssg-data`. See [Configuration → Programmatic routes](/ssg/docs/configuration#programmatic-routes) and [Build-time data loaders](/ssg/docs/configuration#build-time-data-loaders).

### BrokenLink / LinkCheckOptions

```ts
interface BrokenLink {
    page: string;
    href: string;
    reason: 'missing-page' | 'missing-anchor';
}

interface LinkCheckOptions {
    base?: string;
    redirects?: Record<string, string>;
    fileExists?: (path: string) => boolean;
}
```

Returned and accepted by `checkLinks` (see [Link checking](#link-checking)).

## Virtual modules

Ambient declarations are available by adding `@sigx/ssg/virtual` to `compilerOptions.types`. These modules are served by the Vite plugin at runtime.

### virtual:ssg-routes

```ts
declare module 'virtual:ssg-routes' {
    interface SSGRouteRecord {
        path: string;
        name: string;
        file: string;
        component: unknown;
        meta: Record<string, unknown> & { headings?: unknown };
        layout?: string;
    }
    const routes: SSGRouteRecord[];
    export default routes;
}
```

The generated list of routes; default-exported as an array of `SSGRouteRecord`.

### virtual:ssg-navigation

```ts
declare module 'virtual:ssg-navigation' {
    interface CollectionNavigation { sidebar: NavSection[] }
    export const navigation: Record<string, CollectionNavigation>;
    export function getCollectionNav(name: string): CollectionNavigation | undefined;
    export function detectCollection(path: string): string | undefined;
    export function getSidebar(name: string): NavSection[];
    const _default: {
        navigation: typeof navigation;
        collections: Record<string, CollectionConfig>;
        getCollectionNav: typeof getCollectionNav;
        detectCollection: typeof detectCollection;
        getSidebar: typeof getSidebar;
    };
    export default _default;
}
```

Runtime navigation helpers: look up a collection's sidebar, detect the collection for a path, and access the full navigation map.

### virtual:ssg-data

```ts
declare module 'virtual:ssg-data' {
    const data: Record<string, unknown>;
    export default data;
}
```

The results of the config's build-time `data` loaders. The module also emits one named export per key, but only the default export is typed here — augment `virtual:ssg-data` in your project for typed named imports. See [Configuration → Build-time data loaders](/ssg/docs/configuration#build-time-data-loaders).

### virtual:generated-layouts

```ts
declare module 'virtual:generated-layouts' {
    export function setupLayouts<T>(routes: T): T;
    export const LayoutRouter: unknown;
    export function setPageProps(path: string, props: Record<string, unknown> | undefined): void;
}
```

Layout wiring used by the generated client and server entries: `setupLayouts` wraps routes with their layouts, `LayoutRouter` is the root component, and `setPageProps` registers a route's `getStaticPaths` props so the `LayoutRouter` passes them to the page (the generated entries call it; you only call it in custom entries).

---
url: https://sigx.dev/actors/packages/
title: Actors packages - backends, transports & tooling for @sigx/actors
description: Browse the actors packages — Redis, Postgres, SurrealDB and Kubernetes providers for membership, directory and storage; TCP and WebSocket host transports; the Cloudflare Durable Objects backend; and the CLI dashboard and OpenTelemetry exporters.
---

---
url: https://sigx.dev/errors/SIGX001/
title: SIGX001 · No mount function
description: SIGX001 — no mount function was provided and no platform package set a default
---

# SIGX001 · No mount function

**Dev message**

```
No mount function provided and no default mount function set.
```

**Suggestion**

> Either pass a mount function to app.mount(), or import a platform package (e.g., @sigx/runtime-dom) that sets the default.

## What happened

`app.mount()` needs a renderer to turn your component tree into something a platform can display. SignalX's core is renderer-agnostic, so it ships no mount function of its own — a platform package supplies one.

Importing a platform package registers its mount function as the default. That import is usually implicit: the `sigx` umbrella pulls in `@sigx/runtime-dom` for you, which is why web apps never see this error. It shows up when you're on core alone, or on a platform whose package hasn't been imported.

## Fix it

Import a platform package so it can install the default:

```ts
import { createApp } from '@sigx/runtime-core';
import '@sigx/runtime-dom';   // registers the DOM mount function

createApp(App).mount('#app');
```

On the web, importing from the `sigx` umbrella does this for you:

```ts
import { createApp } from 'sigx';

createApp(App).mount('#app');
```

Or pass a mount function explicitly — this is the path a custom renderer takes:

```ts
createApp(App).mount(myMountFunction);
```

## Related

- [Installation](/core/docs/installation)
- [Runtime Core](/core/packages/runtime-core/overview) — the renderer-agnostic base
- [Runtime DOM](/core/packages/runtime-dom/overview) — the web renderer

---
url: https://sigx.dev/errors/SIGX100/
title: SIGX100 · Render target not found
description: SIGX100 — the selector passed to render() matched no element
---

# SIGX100 · Render target not found

**Dev message**

```
Render target "#app" not found.
```

**Suggestion**

> Make sure the element exists in your HTML: `<div id="app"></div>`

## What happened

`render()` was given a selector that matched nothing in the document. The selector itself is usually right — the element just isn't there *yet* at the moment the query runs.

Three things cause that, in rough order of likelihood:

- The script runs before the element is parsed. A classic `<script>` in `<head>` executes while `<body>` is still empty.
- The `id` in the markup and the selector have drifted apart — a typo, or one was renamed.
- The element is created later by other code that hasn't run.

## Fix it

Make sure the target exists in your HTML:

```html
<body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
</body>
```

Keeping the script tag *after* the element — or marking it `type="module"`, which defers by default — is what guarantees the element is parsed before the query runs.

You can also pass the element itself rather than a selector, which sidesteps the timing question entirely:

```ts
const target = document.getElementById('app');
if (target) render(<App />, target);
```

## Related

- [SIGX101](/errors/SIGX101/) — the same problem for `app.mount()`
- [Getting started](/core/docs/getting-started)

---
url: https://sigx.dev/errors/SIGX101/
title: SIGX101 · Mount target not found
description: SIGX101 — the selector passed to app.mount() matched no element
---

# SIGX101 · Mount target not found

**Dev message**

```
Mount target "#app" not found.
```

**Suggestion**

> Make sure the element exists in your HTML: `<div id="app"></div>`

## What happened

`app.mount()` was given a selector that matched nothing in the document. The selector is usually correct — the element just isn't in the DOM at the moment the query runs.

The usual causes:

- The script executes before the element is parsed (a plain `<script>` in `<head>`, for instance).
- The `id` in the markup and the selector have drifted apart.
- The element is injected later by code that hasn't run yet.

## Fix it

Make sure the target exists, and that your script runs after it is parsed:

```html
<body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
</body>
```

`type="module"` scripts defer by default, so the document is parsed before your code runs. That is why the Vite starter template never hits this.

You can also hand `mount()` the element directly:

```ts
const target = document.getElementById('app');
if (target) createApp(App).mount(target);
```

To handle it in code, branch on the code rather than the message:

```ts
import { SigxError } from 'sigx';

try {
    createApp(App).mount('#app');
} catch (e) {
    if (e instanceof SigxError && e.code === 'SIGX101') {
        // the target isn't in the document
    }
}
```

## Related

- [SIGX100](/errors/SIGX100/) — the same problem for `render()`
- [Getting started](/core/docs/getting-started)

---
url: https://sigx.dev/errors/SIGX103/
title: SIGX103 · errorScope() outside setup
description: SIGX103 — errorScope() must be called synchronously during component setup
---

# SIGX103 · errorScope() outside setup

**Dev message**

```
errorScope() must be called synchronously during component setup.
```

**Suggestion**

> Move the errorScope() call into the component's setup function (before returning the render function).

## What happened

`errorScope()` was called somewhere other than the synchronous body of a component's setup function.

`errorScope` scopes the **calling component's own subtree**, so it needs to know which component is calling. SignalX tracks that through the component currently being set up — which means the call has to happen while setup is on the stack. Outside that window there is no owner to attach the scope to.

Three placements break this:

- Inside the returned render function, rather than in setup.
- Inside an event handler or a lifecycle callback.
- After an `await` in setup — the synchronous portion has already ended.

## Fix it

Call it in setup, before returning the render function:

```tsx
import { component, errorScope } from 'sigx';

const Widget = component(() => {
    errorScope({
        fallback: (err, retry) => (
            <div>
                <p>{err.message}</p>
                <button onClick={retry}>Try again</button>
            </div>
        ),
    });

    return () => <RiskySubtree />;
});
```

The scope is set up once and covers every render of the subtree from then on — including reactive re-renders — so there is no reason to call it per render.

## Related

- [Error handling](/core/docs/error-handling) — `errorScope` and `app.onError`
- [SIGX300](/errors/SIGX300/) — the same rule for hooks

---
url: https://sigx.dev/errors/SIGX102/
title: SIGX102 · Async setup is SSR-only
description: "SIGX102 — a component's setup function returned a promise on the client"
---

# SIGX102 · Async setup is SSR-only

**Dev message**

```
Async setup in component "UserCard" is only supported during SSR.
```

**Suggestion**

> On the client, use pre-loaded data from hydration or fetch in onMounted.

## What happened

A component's setup function is `async` (or returned a promise), and it ran on the client.

An async setup blocks the component from producing a render function until it resolves. On the server that is exactly what you want — the renderer awaits the work and streams complete HTML. On the client the same pattern would stall the tree with nothing on screen, so SignalX doesn't allow it.

## Fix it

The right fix depends on what the setup was awaiting.

**Fetching data?** Use `useData`, which is designed for this. It returns immediately with a cell you render through `.match()`, so there is a loading state instead of a stall — and on SSR its result transfers to the client, so hydration doesn't refetch:

```tsx
import { component, useData } from 'sigx';

const UserCard = component(() => {
    const user = useData('user', () => fetch('/api/user').then((r) => r.json()));

    return () =>
        user.match({
            pending: () => <Spinner />,
            error: (e) => <p>Couldn't load: {e.message}</p>,
            ready: (u) => <h1>{u.name}</h1>,
        });
});
```

**Doing setup work that must happen after mount?** Move it into `onMounted`, which runs once the component is live:

```tsx
const Chart = component((ctx) => {
    onMounted(async () => {
        const { renderChart } = await import('./chart.js');
        renderChart(ctx.el);
    });

    return () => <div />;
});
```

Both keep setup synchronous, so the component renders straight away on either platform.

## Related

- [Data loading](/core/docs/data-loading) — `useData`, `useAction` and `.match()`
- [Lifecycle](/core/docs/lifecycle) — `onMounted` and friends

---
url: https://sigx.dev/errors/SIGX202/
title: SIGX202 · Required injectable not provided
description: SIGX202 — a required injectable was used without ever being provided
---

# SIGX202 · Required injectable not provided

**Dev message**

```
Injectable "Router" was used without being provided.
```

**Suggestion**

> Provide it before use: app.defineProvide(useRouter, () => ...) before mount/hydrate, or defineProvide(useRouter, () => ...) in an ancestor component's setup.

## What happened

A **required** injectable was resolved before anything provided it.

Injectables come in two forms, and the difference is what happens when nobody provides one:

```ts
// Factory form — carries its own fallback.
const useLogger = defineInjectable(() => new Logger());

// Required form — declared by name, no fallback.
const useRouter = defineInjectable<Router>('Router');
```

The factory form can always fall back to a module-global singleton built from its own factory. The required form deliberately cannot: it declares that the value is per-app and must come from somewhere specific. Using it unprovided has no sensible answer, so it throws rather than inventing one.

This is the point of the required form. A silent global fallback is precisely the bug you don't want on a server, where one process handles many requests and a shared singleton leaks state between them.

## Fix it

Provide it before anything resolves it. For an app-wide dependency, that means before `mount()` or `hydrate()`:

```ts
const useRouter = defineInjectable<Router>('Router');

const app = createApp(App);
app.defineProvide(useRouter, () => createRouter(url));
app.mount('#app');
```

On the server, build the app **per request** so each gets its own instance:

```ts
function createRequestApp(url: string) {
    const app = createApp(App);
    app.defineProvide(useRouter, () => createRouter(url));
    return app;
}
```

If the dependency belongs to one subtree rather than the app, provide it in an ancestor's setup:

```tsx
const Dashboard = component(() => {
    defineProvide(usePanelState, () => createPanelState());

    return () => <Panel />;
});
```

Resolving outside any component — in a route guard or a socket handler — works too, as long as you enter the app's context first:

```ts
app.runWithContext(() => {
    const router = useRouter();
});
```

Note the name you pass to `defineInjectable('Router')` is what appears in this message, so give it something you'd want to read in a stack trace. To replace the generated *Suggestion* above with your own, pass a `hint`:

```ts
const useRouter = defineInjectable<Router>('Router', {
    hint: 'Provide it before mount: app.defineProvide(useRouter, () => createRouter(url)).',
});
```

The hint is read only in development, but the string still ships in your bundle unless you gate it (`hint: __DEV__ ? '…' : undefined`).

## Related

- [App & plugins](/core/docs/app-plugins) — app provides, `runWithContext`, plugin authoring
- [Dependency injection](/core/api/di) — the full API

---
url: https://sigx.dev/errors/SIGX201/
title: SIGX201 · defineProvide with an invalid injectable
description: SIGX201 — defineProvide needs a function created by defineInjectable or defineFactory
---

# SIGX201 · defineProvide with an invalid injectable

**Dev message**

```
defineProvide must be called with a function created by defineInjectable or defineFactory.
```

**Suggestion**

> Create an injectable or factory first:
> ```
> const useMyService = defineInjectable(() => new MyService());
> // or: const useMyService = defineFactory(setup, 'scoped');
> defineProvide(useMyService);
> ```

## What happened

`defineProvide` was handed something that isn't an injectable.

Injectables aren't plain functions. `defineInjectable` and `defineFactory` return a function carrying a hidden token that identifies the dependency — that token is what `defineProvide` registers under and what the use-function looks up. A function without one has no identity to provide.

The usual causes:

- Passing the **service** where the injectable was meant: `defineProvide(new MyService())`.
- Passing a bare function that was never wrapped: `const useThing = () => new Thing()`.
- Passing the injectable's **result** instead of the injectable: `defineProvide(useMyService())`.

## Fix it

Create the injectable first, then provide it:

```ts
import { defineInjectable, defineProvide } from 'sigx';

const useMyService = defineInjectable(() => new MyService());

// in a component's setup:
defineProvide(useMyService, () => new MyService({ scope: 'panel' }));
```

The second argument is the factory for *this* provide. Omit it and the injectable's own factory is used:

```ts
defineProvide(useMyService);
```

## Related

- [Dependency injection](/core/api/di) — `defineInjectable`, `defineFactory`, provide/inject
- [Factories](/core/docs/advanced/factories) — `defineFactory` in depth
- [SIGX200](/errors/SIGX200/) — calling `defineProvide` outside setup

---
url: https://sigx.dev/errors/SIGX200/
title: SIGX200 · defineProvide outside setup
description: SIGX200 — defineProvide must be called inside a component setup function
---

# SIGX200 · defineProvide outside setup

**Dev message**

```
defineProvide must be called inside a component setup function.
```

**Suggestion**

> Move the defineProvide() call inside your component's setup function, or use app.defineProvide() at the app level.

## What happened

`defineProvide` was called outside the synchronous body of a component's setup function.

`defineProvide` provides a value **to the calling component's subtree**, so it needs an owner — the component currently being set up. Outside setup there is no such component, and nowhere to attach the value.

## Fix it

If the value belongs to one subtree, provide it in that component's setup:

```tsx
import { component, defineProvide } from 'sigx';

const Dashboard = component(() => {
    defineProvide(useTheme, () => createTheme('dark'));

    return () => <Panel />;   // and everything below it
});
```

If it belongs to the whole app, provide it on the app instead — this is the right home for routers, stores and API clients:

```ts
const app = createApp(App);
app.defineProvide(useRouter, () => createRouter());
app.mount('#app');
```

App-level provides are looked up live, so a `defineProvide` call after `mount()` is still visible to components mounted afterwards.

## Related

- [App & plugins](/core/docs/app-plugins) — app-level provides and plugin authoring
- [Dependency injection](/core/api/di) — the full API
- [SIGX201](/errors/SIGX201/) — providing something that isn't an injectable

---
url: https://sigx.dev/errors/SIGX203/
title: SIGX203 · defineFactory returned a primitive
description: SIGX203 — a defineFactory setup must return an object or a function
---

# SIGX203 · defineFactory returned a primitive

**Dev message**

```
[sigx] defineFactory setup must return an object or function, got number.
```

**Suggestion**

> Return the service object (or callable) from the factory setup — primitives cannot carry the dispose contract factories rely on.

## What happened

A `defineFactory` setup returned a primitive — a number, string, boolean, `null` or `undefined`.

Factories manage a lifecycle, not just a value: a scoped factory instance is created on first use and disposed when its scope ends. SignalX tracks that by hanging a dispose contract off the returned value, which only works for objects and functions. A primitive has nowhere to put it, so there'd be no way to ever clean the instance up.

## Fix it

Return the service itself:

```ts
import { defineFactory } from 'sigx';

const useCounter = defineFactory(() => {
    const count = signal(0);

    return {
        get value() { return count.value; },
        increment() { count.value++; },
    };
}, 'scoped');
```

If what you want really is a single primitive, wrap it in an object so it has an identity to hang the lifecycle on:

```ts
const useRequestId = defineFactory(() => ({ id: crypto.randomUUID() }), 'scoped');
```

A callable works too, when the service is naturally one function:

```ts
const useTrack = defineFactory(() => {
    const queue: Event[] = [];
    return (e: Event) => queue.push(e);
}, 'scoped');
```

For a plain constant with no lifecycle, you don't need a factory at all — a module export or a `defineInjectable` is simpler.

## Related

- [Factories](/core/docs/advanced/factories) — `defineFactory` in depth
- [Dependency injection](/core/api/di) — the full API

---
url: https://sigx.dev/errors/SIGX300/
title: SIGX300 · Hook called outside setup
description: SIGX300 — useData, useAction and useStream must be called synchronously during setup
---

# SIGX300 · Hook called outside setup

**Dev message**

```
useData() must be called synchronously during component setup.
```

**Suggestion**

> Move the useData() call into the component's setup function (before returning the render function).

## What happened

A hook — `useData`, `useAction`, `useStream` — was called somewhere other than the synchronous body of a component's setup function.

Hooks bind to the component being set up: that's how the cell gets torn down with the component, and how SSR knows which component's data to transfer. SignalX tracks the owner through the setup call currently on the stack, so a hook called outside that window has nothing to bind to.

The message names whichever hook you called.

The placements that break it:

- Inside the returned render function.
- Inside an event handler or lifecycle callback.
- After an `await` in setup — the synchronous portion has already ended, and the owner is gone.
- At module top level, outside any component.

## Fix it

Call the hook in setup and read it in the render function:

```tsx
import { component, useData, match } from 'sigx';

const UserCard = component(() => {
    const user = useData('user', () => fetch('/api/user').then((r) => r.json()));

    return () =>
        user.match({
            pending: () => <Spinner />,
            error: (e) => <p>{e.message}</p>,
            ready: (u) => <h1>{u.name}</h1>,
        });
});
```

**Fetching in response to a click?** You don't need a hook in the handler — declare the action in setup and call it from the handler:

```tsx
const SaveButton = component(() => {
    const save = useAction((draft: Draft) => api.save(draft));

    return () => <button onClick={() => save.run(draft)}>Save</button>;
});
```

**Fetching depends on state?** Keep the hook in setup and let the key be reactive — it refetches when the key changes:

```tsx
const Profile = component((ctx) => {
    const id = ctx.signal(1);
    const user = useData(() => ['user', id.value], ([, id]) => api.getUser(id));

    return () => user.match({ /* … */ });
});
```

## Related

- [Data loading](/core/docs/data-loading) — `useData`, `useAction`, `useStream`
- [SIGX103](/errors/SIGX103/) — the same rule for `errorScope()`

---
url: https://sigx.dev/errors/SIGX400/
title: SIGX400 · Subscribed to a destroyed topic
description: SIGX400 — subscriptions made after a topic is destroyed can never fire
---

# SIGX400 · Subscribed to a destroyed topic

**Dev message**

```
[sigx] Cannot subscribe to destroyed topic "user:updated".
```

**Suggestion**

> Subscriptions made after destroyTopic()/group.destroy() can never fire. Subscribe before teardown, or create a new topic.

## What happened

Something subscribed to a topic after `destroyTopic()` — or the owning group's `destroy()` — had already run.

A destroyed topic has dropped its subscriber list and will never deliver again. SignalX throws rather than accepting the subscription, because a handler that silently never fires is far harder to debug than an error at the call site.

This almost always means a teardown-ordering problem: something outlived the topic it depends on. Common shapes:

- A component subscribes in `onMounted` while an ancestor destroys the group during its own teardown.
- An async callback lands after teardown — the subscribe call was queued before, but ran after.
- A module-scoped topic was destroyed by a hot reload while a component still holds a reference.

## Fix it

Subscribe while the topic is alive, and tie the subscription's lifetime to the component:

```ts
import { component, onMounted, onUnmounted } from 'sigx';

const Inbox = component(() => {
    onMounted(() => {
        const off = topic.subscribe(handleMessage);
        onUnmounted(off);
    });

    return () => <List />;
});
```

If the topic legitimately outlives nothing and you're re-entering a fresh lifecycle, create a new topic instead of reviving the old one — destruction is final by design:

```ts
const topic = createTopic<Message>('user:updated');
```

## Related

- [Messaging](/core/docs/advanced/messaging) — topics and groups
- [SIGX401](/errors/SIGX401/) — creating a topic on a destroyed group

---
url: https://sigx.dev/errors/SIGX500/
title: SIGX500 · Write to a read-only property signal
description: SIGX500 — toSignal cannot write back to a property whose source object rejects the assignment
---

# SIGX500 · Write to a read-only property signal

**Dev message**

```
[sigx] toSignal: cannot write to read-only property "count".
```

## What happened

A [`toSignal`](/core/api/reactivity#tosignal) view was assigned to, and the underlying object refused the write.

`toSignal(source, key)` is a two-way *view* onto one property, not a copy of it. Reading `view.value` reads `source[key]`; assigning `view.value` assigns `source[key]`. When that assignment cannot land, the write is a silent data loss — the signal would report a value the object never took — so SignalX throws instead.

The property rejects the write when it is:

- **non-writable** — defined with `writable: false` via `Object.defineProperty`
- **getter-only** — an accessor with a `get` but no `set`
- **frozen or sealed** — the whole object went through `Object.freeze()`
- **a Proxy trap that returns `false`** from its `set` handler

```ts
const state = Object.freeze({ count: 0 });
const count = toSignal(state, 'count');

count.value;       // 0 — reading is fine
count.value = 1;   // SIGX500
```

## Fix it

**If the value is meant to change**, make the source writable — usually by building it with [`signal()`](/core/api/reactivity#signal) rather than freezing a plain object:

```ts
const state = signal({ count: 0 });
const count = toSignal(state, 'count');

count.value = 1;   // fine — and `state.count` is now 1
```

For a getter-only property, give it a setter, or point `toSignal` at the backing field the getter reads.

**If the value is genuinely read-only**, don't route writes through it. Derive with [`computed()`](/core/api/reactivity#computed) instead — a computed has no setter to misuse:

```ts
const total = computed(() => config.items.length);
```

## Not a SigxError

This one throws a plain `Error`, not a [`SigxError`](/errors/) — `@sigx/reactivity` sits below the error class and does not depend on it. There is no `error.code` to branch on here; match on the message, or better, fix the write.

## Related

- [Reactivity API](/core/api/reactivity/) — `toSignal`, `toSignals` and `computed`
- [Signals](/core/docs/signals) — the reactive primitives

---
url: https://sigx.dev/errors/SIGX401/
title: SIGX401 · Topic created on a destroyed group
description: SIGX401 — a topic group cannot create new topics after it is destroyed
---

# SIGX401 · Topic created on a destroyed group

**Dev message**

```
[sigx] Cannot create topic "user:updated" on a destroyed topic group.
```

**Suggestion**

> The group was destroyed; create its topics before destroy(), or recreate the group.

## What happened

A topic group was asked for a topic after its `destroy()` had run.

A group owns its topics: destroying it destroys all of them, and it stops handing out new ones. Any topic it created now would be born with no path to a subscriber, so SignalX throws at the call site rather than returning a dead object.

Like [SIGX400](/errors/SIGX400/), this is a teardown-ordering problem — something is still reaching for the group after the code that owns it has torn it down. Usually:

- A late async callback creates its topic after teardown.
- A component asks the group for a topic while an ancestor is unmounting.
- A group is stored at module scope and destroyed on hot reload, while live code still holds it.

## Fix it

Create the group's topics while it's alive, and don't reach for it after teardown:

```ts
const group = createTopicGroup();
const updated = group.topic<User>('user:updated');

// … later, on teardown:
group.destroy();   // `updated` is destroyed too
```

If a new lifecycle begins, create a new group rather than reusing the destroyed one:

```ts
let group = createTopicGroup();

function restart() {
    group.destroy();
    group = createTopicGroup();   // fresh group, fresh topics
}
```

## Related

- [Messaging](/core/docs/advanced/messaging) — topics and groups
- [SIGX400](/errors/SIGX400/) — subscribing to a destroyed topic

---
url: https://sigx.dev/errors/SIGX600/
title: SIGX600 · Hydration container not found
description: "SIGX600 — app.hydrate() was given a container that isn't in the document"
---

# SIGX600 · Hydration container not found

**Dev message**

```
[ssrClientPlugin] Cannot find container: #app. Make sure the element exists in the DOM before calling hydrate().
```

## What happened

`app.hydrate(container)` was called with a selector or element that does not resolve to a node in the document.

Hydration is not mounting. `mount()` creates DOM; `hydrate()` *adopts* the DOM the server already sent, attaching event handlers and wiring reactivity to nodes that are supposed to be there. With no container there is nothing to adopt, and silently falling back to a fresh mount would throw away the server's HTML and double-render the page — so the plugin throws.

The usual causes:

- The selector doesn't match the server template's outlet wrapper (`#app` on the client, `#root` in the HTML).
- The script runs before the element parses — a `<script>` in `<head>` without `type="module"` or `defer`.
- The container is rendered by another framework, or injected later by a script that hasn't run yet.

## Fix it

Point `hydrate()` at the element the server actually rendered into, and make sure the script runs after it exists:

```html
<body>
    <div id="app"><!--ssr-outlet--></div>
    <script type="module" src="/src/entry.client.ts"></script>
</body>
```

```tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';

const app = defineApp(<App />);
app.use(ssrClientPlugin).hydrate!('#app');
```

`type="module"` scripts are deferred by default, so the body has parsed by the time the entry runs. A classic `<script>` in `<head>` needs `defer`.

If you pass an element rather than a selector, check it isn't `null` first — `document.getElementById('app')!` asserts away exactly the failure this code reports.

## Related

- [Hydration & head](/server/packages/server-renderer/hydration) — the client half of SSR
- [SIGX601](/errors/SIGX601/) — no root component on the app
- [SIGX602](/errors/SIGX602/) — the document template has no outlet marker

---
url: https://sigx.dev/errors/SIGX601/
title: SIGX601 · No root component to hydrate
description: SIGX601 — app.hydrate() was called on an app created without a root component
---

# SIGX601 · No root component to hydrate

**Dev message**

```
[ssrClientPlugin] No root component found on app. Make sure you created the app with defineApp(<Component />).
```

## What happened

`app.hydrate(container)` found its container, but the app has no root component to hydrate into it.

`defineApp()` records the element it is given as the app's root. Hydration walks that root against the server's DOM, node for node. An app created without one has nothing to walk — there is no tree to reconcile against the markup — so the plugin throws rather than leaving a page of inert HTML.

In practice this means `defineApp()` was called with nothing:

```tsx
const app = defineApp();                      // no root
app.use(ssrClientPlugin).hydrate!('#app');    // SIGX601
```

## Fix it

Pass the root element to `defineApp()`:

```tsx
import { defineApp } from 'sigx';
import { ssrClientPlugin } from '@sigx/server-renderer/client';
import { App } from './App';

const app = defineApp(<App />);
app.use(ssrClientPlugin).hydrate!('#app');
```

The client's root must be the same component the server rendered. If the server entry renders `<App />` and the client hydrates `<Root />`, hydration mismatches even when this error doesn't fire — keep both entries importing the same root.

## Related

- [Hydration & head](/server/packages/server-renderer/hydration) — the client half of SSR
- [Building a full SSR app](/server/packages/server-renderer/full-app) — matching server and client entries
- [SIGX600](/errors/SIGX600/) — the hydration container was not found

---
url: https://sigx.dev/errors/SIGX602/
title: SIGX602 · Outlet marker not found in template
description: SIGX602 — renderDocument could not find the outlet marker it replaces with the app HTML
---

# SIGX602 · Outlet marker not found in template

**Dev message**

```
renderDocument: outlet marker "<!--ssr-outlet-->" not found in template
```

## What happened

`renderDocument()` was given an HTML template that does not contain its outlet marker.

The marker is where the rendered app goes. `renderDocument` splits the template on it and streams the head, then the shell, then the tail — so a template without one has no insertion point. Rather than emit a document with the app missing (a blank page that looks like a rendering bug), the renderer throws at the split.

The default marker is `<!--ssr-outlet-->`. Common causes:

- The template is `index.html` straight from a client-only setup, which never had a marker.
- An HTML minifier stripped the comment. Most minifiers remove comments by default.
- The marker is spelled differently — `<!-- ssr-outlet -->` with spaces does not match.
- A custom `outlet` option was configured, but the template still carries the default.

## Fix it

Put the marker in the template, inside the element you hydrate:

```html
<!doctype html>
<html>
    <head><title>My app</title></head>
    <body>
        <div id="app"><!--ssr-outlet--></div>
        <script type="module" src="/src/entry.client.ts"></script>
    </body>
</html>
```

If your build minifies HTML, tell it to preserve this comment — or set an outlet it won't touch:

```ts
await renderDocument(app, { template, outlet: '<div id="ssr-outlet"></div>' });
```

Whatever you choose, the string must appear in the template **verbatim** — the match is exact, not a pattern.

## Related

- [Rendering & streaming](/server/packages/server-renderer/rendering) — `renderDocument` and the shell
- [The request lifecycle](/server/packages/server-renderer/request-lifecycle) — where the template is assembled
- [SIGX600](/errors/SIGX600/) — the client half, when hydration can't find its container

---
url: https://sigx.dev/errors/SIGX700/
title: SIGX700 · Revalidation trigger threw while subscribing
description: SIGX700 — the @sigx/cache revalidateTrigger threw when the store tried to install it
---

# SIGX700 · Revalidation trigger threw while subscribing

**Dev message**

```
[sigx-cache] revalidateTrigger threw while subscribing:
```

The thrown error is logged as a second argument, so the original stack is in the console next to the code.

## What happened

`@sigx/cache` tried to install its attention-revalidation trigger and the trigger function threw.

The store subscribes one "revalidate now" callback per app, lazily — on the first read that opts in with `revalidateOnFocus`. The trigger is the platform's: DOM `focus` + `visibilitychange` by default, or whatever `cachePlugin({ revalidateTrigger })` supplied for a non-DOM runtime.

**This is logged, not thrown.** A cache that cannot hear about window focus is degraded, not broken — so the store marks the trigger uninstalled, logs, and carries on. Everything else keeps working: reads still fetch, `staleTime` still applies, `invalidate()` still works. What you lose is revalidation on focus; `revalidateOnInterval` and manual invalidation are unaffected.

Because it never throws, this one shows up in logs rather than in a stack trace, and it is easy to miss.

## Fix it

Almost always the trigger touched a global its runtime doesn't have. The default trigger installs only when a DOM is present, so this normally means a **custom** trigger reaching for one:

```ts
// ✗ throws under lynx, terminal, or a Node/edge SSR pass
cachePlugin({
    revalidateTrigger: (revalidate) => {
        window.addEventListener('focus', revalidate);
        return () => window.removeEventListener('focus', revalidate);
    },
});
```

Subscribe to the event source the runtime actually has, and return its unsubscribe — whatever that runtime calls it:

```ts
cachePlugin({
    revalidateTrigger: (revalidate) => {
        const subscription = appState.on('resume', revalidate);
        return () => subscription.remove();
    },
});
```

If the trigger has to run on more than one target, guard the capability rather than the platform name, and return nothing when there is no source to subscribe to — returning `undefined` is valid and simply means "nothing to unsubscribe":

```ts
cachePlugin({
    revalidateTrigger: (revalidate) => {
        if (typeof document === 'undefined') return;
        document.addEventListener('visibilitychange', revalidate);
        return () => document.removeEventListener('visibilitychange', revalidate);
    },
});
```

## Related

- [Cache overview](/core/packages/cache/overview) — the cache-policy pack
- [Cache API](/core/packages/cache/api) — `cachePlugin`, `revalidateTrigger`, `revalidateOnFocus`
- [Data loading](/core/docs/data-loading) — `useData` and the async state model

---
url: https://sigx.dev/daisyui/api/
title: API Reference
description: API reference for @sigx/daisyui
---

# DaisyUI API Reference

Complete API reference for `@sigx/daisyui`.

## Theme Functions

### initializeTheme

Initializes the theme system. Call on app mount.

```tsx
import { initializeTheme } from '@sigx/daisyui';

initializeTheme({
    defaultTheme?: string,  // Default: 'light'
    storageKey?: string,    // Default: 'theme'
});
```

### setTheme

Sets the current theme.

```tsx
import { setTheme } from '@sigx/daisyui';

setTheme('dark');
```

### getTheme

Gets the current theme.

```tsx
import { getTheme } from '@sigx/daisyui';

const theme = getTheme(); // 'dark'
```

---

## Components

### Button

```tsx
interface ButtonProps {
    variant?: 'primary' | 'secondary' | 'accent' | 'ghost' | 'link' | 'info' | 'success' | 'warning' | 'error';
    size?: 'xs' | 'sm' | 'md' | 'lg';
    outline?: boolean;
    loading?: boolean;
    disabled?: boolean;
    onClick?: () => void;
}
```

### Modal

```tsx
interface ModalProps {
    isOpen: boolean;
    onClose: () => void;
    closeOnBackdrop?: boolean;  // Default: true
    closeOnEscape?: boolean;    // Default: true
}

// Sub-components
Modal.Header
Modal.Body  
Modal.Actions
```

### Card

```tsx
interface CardProps {
    compact?: boolean;
    bordered?: boolean;
    imageFull?: boolean;
}

// Sub-components
Card.Image
Card.Body
Card.Title
Card.Actions
```

### Input

```tsx
interface InputProps {
    type?: string;           // Default: 'text'
    placeholder?: string;
    label?: string;
    error?: string;
    size?: 'xs' | 'sm' | 'md' | 'lg';
    variant?: 'bordered' | 'ghost';
    value?: string;
    onInput?: (value: string) => void;
}
```

### Alert

```tsx
interface AlertProps {
    variant?: 'info' | 'success' | 'warning' | 'error';
    dismissible?: boolean;
    onDismiss?: () => void;
}
```

### Badge

```tsx
interface BadgeProps {
    variant?: 'primary' | 'secondary' | 'accent' | 'ghost' | 'info' | 'success' | 'warning' | 'error';
    size?: 'xs' | 'sm' | 'md' | 'lg';
    outline?: boolean;
}
```

### ThemeToggle

```tsx
interface ThemeToggleProps {
    themes?: string[];  // Default: ['light', 'dark']
}
```

### Dropdown

```tsx
interface DropdownProps {
    position?: 'top' | 'bottom' | 'left' | 'right';
    align?: 'start' | 'end';
    hover?: boolean;
}

// Sub-components
Dropdown.Toggle
Dropdown.Menu
Dropdown.Item
```

### Tabs

```tsx
interface TabsProps {
    variant?: 'boxed' | 'bordered' | 'lifted';
    size?: 'xs' | 'sm' | 'md' | 'lg';
}

// Sub-components
Tabs.Tab: { active?: boolean; disabled?: boolean }
```

### Progress

```tsx
interface ProgressProps {
    value: number;
    max?: number;       // Default: 100
    variant?: 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error';
}
```

---
url: https://sigx.dev/core/api/
title: Overview
description: Complete SignalX API reference
---

# API Reference

Complete reference for all SignalX (`sigx`) exports. SignalX re-exports everything from:
- `@sigx/reactivity` - Reactive primitives
- `@sigx/runtime-core` - Component system
- `@sigx/runtime-dom` - DOM rendering

## Quick Navigation

### Reactivity
- [`signal`](/core/api/reactivity#signal) - Create reactive state
- [`effect`](/core/api/reactivity#effect) - Run side effects
- [`computed`](/core/api/reactivity#computed) - Derived values
- [`watch`](/core/api/reactivity#watch) - Watch with callbacks
- [`batch`](/core/api/reactivity#batch) - Batch updates
- [`untrack`](/core/api/reactivity#untrack) - Read without tracking
- [`toRaw`](/core/api/reactivity#toraw) - Get raw object
- [`isReactive`](/core/api/reactivity#isreactive) - Check if reactive
- [`effectScope`](/core/api/reactivity#effectscope) - Group effects
- [`toSignal`](/core/api/reactivity#tosignal) - Signal-shaped view over one property
- [`toSignals`](/core/api/reactivity#tosignals) - Signal-shaped views for every property

### Components
- [`component`](/core/api/components#component) - Define component
- [`Fragment`](/core/api/components#fragment) - Render without wrapper
- [`lazy`](/core/api/components#lazy) - Lazy load component
- [`Defer`](/core/api/components#defer) - Chunk-loading boundary
- [`Portal`](/core/api/components#portal) - Render to different DOM location
- [`mergeProps`](/core/api/components#mergeprops) - Combine prop sources without collisions

### Data Loading
- [`useData`](/core/api/components#usedata) - Keyed async read, SSR-transferable
- [`useAction`](/core/api/components#useaction) - Async write, triggered by `run()`
- [`all`](/core/api/components#all) - Combine reads into one state
- [`useStream`](/core/api/components#usestream) - Progressive text streaming
- [`errorScope`](/core/docs/error-handling) - Subtree error boundary

### Lifecycle
- [`onMounted`](/core/api/lifecycle#onmounted) - After mount
- [`onUnmounted`](/core/api/lifecycle#onunmounted) - Before unmount
- [`onCreated`](/core/api/lifecycle#oncreated) - After creation
- [`onUpdated`](/core/api/lifecycle#onupdated) - After update

### Dependency Injection
- [`provide`](/core/api/di#provide) - Provide value to descendants
- [`inject`](/core/api/di#inject) - Inject from ancestors
- [`createInjectable`](/core/api/di#createinjectable) - Create injectable
- [`defineProvide`](/core/api/di#defineprovide) - Provide + create

### App & Plugins
- [`defineApp`](/core/api/app#defineapp) - Create application
- [`Plugin`](/core/api/app#plugin) - Plugin type

### Advanced
- [`defineFactory`](/core/api/advanced#definefactory) - Injectable factory with real lifetimes
- [`Lifetime`](/core/api/advanced#lifetime) - `'singleton' | 'scoped' | 'transient'`
- [`createTopic`](/core/api/advanced#createtopic) - Pub/sub messaging
- [`createTopicGroup`](/core/api/advanced#createtopicgroup) - Typed group of topics
- [`toSubscriber`](/core/api/advanced#tosubscriber) - Read-only subscriber

### Types
- [`Define.Prop`](/core/api/types#defineprop) - Prop type helper
- [`Define.Event`](/core/api/types#defineevent) - Event type helper
- [`Define.Slot`](/core/api/types#defineslot) - Slot type helper
- [`Define.Model`](/core/api/types#definemodel) - Two-way binding helper
- [`Define.Expose`](/core/api/types#defineexpose) - Exposed API helper
- [`Define.Attrs`](/core/api/types#defineattrs) - Accept host attributes
- [`Define.WithAttrs`](/core/api/types#definewithattrs) - Host attributes with a colliding own prop
- [`ComponentRef`](/core/api/types#componentref) - Component ref type
- [`Exposed`](/core/api/types#exposed) - Extract exposed type

## Import

All APIs are available from the main `sigx` package:

```tsx
import { 
    // Reactivity
    signal, effect, computed, watch,
    batch, untrack, toRaw, isReactive, effectScope,
    toSignal, toSignals,
    
    // Components
    component, Fragment, lazy, Defer, Portal,
    
    // Data loading
    useData, useAction, all, useStream, errorScope,
    
    // Lifecycle
    onMounted, onUnmounted, onCreated, onUpdated,
    
    // DI
    provide, inject, createInjectable, defineProvide,
    
    // App
    defineApp,
    
    // Types
    type Define, ComponentRef, Exposed,
    
    // Advanced
    defineFactory, createTopic, createTopicGroup, toSubscriber,
    type Lifetime
} from 'sigx';
```

The inspection-only topic registry for tooling lives on its own entry:

```tsx
import { getTopic, listTopics, subscribeTopics, onTopicCreated } from '@sigx/runtime-core/inspect';
```

## TypeScript

SignalX is written in TypeScript and provides full type inference. All component props, events, slots, and exposed APIs are fully typed.

```tsx
// Full type safety
type MyProps = 
    & Define.Prop<'name', string, true>
    & Define.Prop<'count', number>
    & Define.Event<'change', number>
    & Define.Slot<'header'>
    & Define.Expose<{ reset: () => void }>;

const MyComponent = component<MyProps>(({ props, emit, slots, expose }) => {
    // props.name is string (required)
    // props.count is number | undefined (optional)
    // emit('change', 5) is type-checked
    // slots.header is typed correctly
    
    expose({ reset: () => {} }); // Type-checked
    
    return () => <div>{props.name}</div>;
});
```

---
url: https://sigx.dev/router/api/
title: API Reference
description: API reference for @sigx/router
---

# Router API Reference

Complete API reference for `@sigx/router`.

---

## Router Creation

### createRouter

Creates a new router instance.

```tsx
import { createRouter, createWebHistory } from '@sigx/router';

const router = createRouter({
    routes: [
        { path: '/', component: Home },
        { path: '/about', component: About },
    ],
    history: createWebHistory(),
    base: '/',
    scrollBehavior(to, from, savedPosition) {
        if (savedPosition) return savedPosition;
        if (to.hash) return { el: to.hash };
        return { top: 0 };
    },
});
```

#### RouterOptions

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `routes` | `RouteRecordRaw[]` | Required | Array of route definitions |
| `history` | `RouterHistory` | Required | History implementation (`createWebHistory`, `createHashHistory`, or `createMemoryHistory`) |
| `base` | `string` | `undefined` | Base URL for the application |
| `scrollBehavior` | `ScrollBehaviorHandler` | `undefined` | Callback to control scroll position after each navigation |

---

## History

### createWebHistory

Creates a history implementation using the HTML5 History API. Suitable for browser environments.

```tsx
import { createWebHistory } from '@sigx/router';

const history = createWebHistory();
const history = createWebHistory({ base: '/app' });
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `base` | `string` | `undefined` | Base path prepended to all URLs |

### createMemoryHistory

Creates an in-memory history implementation. Suitable for SSR or testing.

```tsx
import { createMemoryHistory } from '@sigx/router';

const history = createMemoryHistory();
const history = createMemoryHistory({ base: '/app', initialLocation: '/home' });
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `base` | `string` | `undefined` | Base path prepended to all URLs |
| `initialLocation` | `string` | `undefined` | Initial URL location |

### createHashHistory

Creates a hash-based history implementation. Uses `/#/path` URLs so the server never sees the route path — ideal for static hosting (GitHub Pages, S3), Electron, and environments without SPA server-side fallback.

```tsx
import { createHashHistory } from '@sigx/router';

const history = createHashHistory();
const history = createHashHistory({ base: '/app' });
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `base` | `string` | `undefined` | Base path within the hash (e.g. `/#/app/about`) |

---

## Router Instance

The object returned by `createRouter`. Access it via `useRouter()` inside components.

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `currentRoute` | `RouteLocation` | Reactive current route location |

### Navigation Methods

#### router.push

Navigate to a new location, adding an entry to the history stack.

```tsx
router.push('/about');
router.push({ name: 'user', params: { id: '1' } });
```

**Signature:** `push(to: RouteLocationRaw): Promise<RouteLocation | void>`

#### router.replace

Navigate to a new location, replacing the current history entry.

```tsx
router.replace('/login');
```

**Signature:** `replace(to: RouteLocationRaw): Promise<RouteLocation | void>`

#### router.back

Go back one step in the history stack.

**Signature:** `back(): void`

#### router.forward

Go forward one step in the history stack.

**Signature:** `forward(): void`

#### router.go

Move forward or backward by a given number of entries in the history stack.

```tsx
router.go(-2); // Go back two entries
```

**Signature:** `go(delta: number): void`

### Guard Methods

#### router.beforeEach

Register a global navigation guard that runs before every navigation. Returns a function to remove the guard.

```tsx
const removeGuard = router.beforeEach((to, from, next) => {
    if (!isAuthenticated && to.path !== '/login') {
        next('/login');
    } else {
        next();
    }
});
```

**Signature:** `beforeEach(guard: NavigationGuard): () => void`

#### router.beforeResolve

Register a global guard that runs after per-route guards but before navigation is confirmed. Returns a function to remove the guard.

**Signature:** `beforeResolve(guard: NavigationGuard): () => void`

#### router.afterEach

Register a global hook that runs after every navigation. Returns a function to remove the hook.

```tsx
const removeHook = router.afterEach((to, from) => {
    trackPageView(to.path);
});
```

**Signature:** `afterEach(hook: NavigationHookAfter): () => void`

### Route Management Methods

#### router.addRoute

Dynamically add a route. Optionally nest it under a parent by name. Returns a function to remove the added route.

```tsx
const removeRoute = router.addRoute({ path: '/new', component: NewPage });
router.addRoute({ path: 'profile', component: Profile }, 'user');
```

**Signature:** `addRoute(route: RouteRecordRaw, parentName?: string): () => void`

#### router.removeRoute

Remove a route by name.

**Signature:** `removeRoute(name: string): void`

#### router.hasRoute

Check if a route with the given name exists.

**Signature:** `hasRoute(name: string): boolean`

#### router.getRoutes

Return the full list of registered route records.

**Signature:** `getRoutes(): RouteRecordRaw[]`

### Other Methods

#### router.resolve

Resolve a route location to a normalized `RouteLocation` object without navigating.

```tsx
const resolved = router.resolve({ name: 'user', params: { id: '1' } });
```

**Signature:** `resolve(to: RouteLocationRaw): RouteLocation`

#### router.match

Match the current route against a set of patterns and return the corresponding value.

```tsx
const result = router.match({
    '/': () => 'home',
    '/about': () => 'about',
});
```

**Signature:** `match<T>(patterns: RouteMatchPatterns<T>): T | undefined`

#### router.install

Install the router into an application instance. Called automatically when passed to the app.

**Signature:** `install(app: App): void`

#### router.isReady

Returns a promise that resolves once the **initial navigation has completed** — including any guards and redirects that ran on the first route resolution. On the server, `await router.isReady()` before reading `currentRoute` to detect redirects (see [SSR Routing](/router/docs/ssr#redirects-during-ssr)).

```tsx
await router.isReady();
```

**Signature:** `isReady(): Promise<void>`

---

## Components

### RouterView

Renders the component matched by the current route.

```tsx
import { RouterView } from '@sigx/router';

<RouterView />
<RouterView name="sidebar" />
<RouterView pageProps={{ theme: 'dark' }} />
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `undefined` | Named view to render |
| `pageProps` | `Record<string, unknown>` | `undefined` | Additional props passed to the rendered component |

### Link / RouterLink

Navigation link component. Available as both `Link` and `RouterLink`.

```tsx
import { Link, RouterLink } from '@sigx/router';

<Link to="/about">About</Link>
<RouterLink to={{ name: 'user', params: { id: '1' } }} activeClass="active">
    User
</RouterLink>
```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `to` | `RouteLocationRaw` | Required | Target location |
| `replace` | `boolean` | `false` | Use `router.replace` instead of `router.push` |
| `activeClass` | `string` | `undefined` | Class applied when the link is active |
| `exactActiveClass` | `string` | `undefined` | Class applied when the link is an exact active match |
| `ariaCurrentValue` | `string` | `undefined` | Value for the `aria-current` attribute when the link is active |

---

## Hooks

### useRouter

Returns the router instance for programmatic navigation.

```tsx
import { useRouter } from '@sigx/router';

const router = useRouter();
router.push('/about');
```

**Signature:** `useRouter(): Router`

### useRoute

Returns reactive route information for the current location.

```tsx
import { useRoute } from '@sigx/router';

const route = useRoute();

route.path;      // Current path
route.params;    // Route parameters
route.query;     // Query parameters
route.hash;      // URL hash
route.meta;      // Route metadata
route.name;      // Route name
```

**Signature:** `useRoute(): RouteLocation`

### useParams

Returns reactive route parameters.

```tsx
import { useParams } from '@sigx/router';

const params = useParams();
// params.id, params.slug, etc.
```

**Signature:** `useParams(): RouteParams`

### useQuery

Returns reactive query parameters.

```tsx
import { useQuery } from '@sigx/router';

const query = useQuery();
// query.search, query.page, etc.
```

**Signature:** `useQuery(): RouteQuery`

### useNavigate

Returns a navigation function.

```tsx
import { useNavigate } from '@sigx/router';

const navigate = useNavigate();
navigate('/about');
navigate({ name: 'user', params: { id: '1' } });
```

**Signature:** `useNavigate(): (to: RouteLocationRaw) => Promise<RouteLocation | void>`

### onBeforeRouteLeave

Register a guard that runs when the component's route is about to be navigated away from. Can only be used inside a component rendered by `RouterView`.

```tsx
import { onBeforeRouteLeave } from '@sigx/router';

onBeforeRouteLeave((to, from, next) => {
    if (hasUnsavedChanges) {
        next(false);
    } else {
        next();
    }
});
```

**Signature:** `onBeforeRouteLeave(guard: NavigationGuard): void`

### onBeforeRouteUpdate

Register a guard that runs when the component's route params or query change but the component is reused. Can only be used inside a component rendered by `RouterView`.

```tsx
import { onBeforeRouteUpdate } from '@sigx/router';

onBeforeRouteUpdate((to, from, next) => {
    fetchData(to.params.id);
    next();
});
```

**Signature:** `onBeforeRouteUpdate(guard: NavigationGuard): void`

---

## Utility Functions

### parseQuery

Parse a query string into a `RouteQuery` object.

```tsx
import { parseQuery } from '@sigx/router';

parseQuery('?page=1&sort=name');
// { page: '1', sort: 'name' }
```

**Signature:** `parseQuery(queryString: string): RouteQuery`

### stringifyQuery

Serialize a `RouteQuery` object into a query string.

```tsx
import { stringifyQuery } from '@sigx/router';

stringifyQuery({ page: '1', sort: 'name' });
// 'page=1&sort=name'
```

**Signature:** `stringifyQuery(query: RouteQuery): string`

### parseURL

Parse a URL string into its constituent parts.

```tsx
import { parseURL } from '@sigx/router';

parseURL('/about?page=1#section');
// { path: '/about', query: { page: '1' }, hash: '#section' }
```

**Signature:** `parseURL(url: string): { path: string; query: RouteQuery; hash: string }`

### buildPath

Build a full URL path from parts.

```tsx
import { buildPath } from '@sigx/router';

buildPath('/about', { page: '1' }, '#section');
// '/about?page=1#section'
```

**Signature:** `buildPath(path: string, query?: RouteQuery, hash?: string): string`

---

## Types

### RouteRecordRaw

Route definition used when configuring the router.

```tsx
interface RouteRecordRaw {
    path: string;
    name?: string;
    component?: ComponentFactory | (() => Promise<{ default: ComponentFactory }>);
    children?: RouteRecordRaw[];
    redirect?: RouteLocationRaw | ((to: RouteLocation) => RouteLocationRaw);
    meta?: RouteMeta;
    beforeEnter?: NavigationGuard | NavigationGuard[];
    props?: boolean | Record<string, any> | ((route: RouteLocation) => Record<string, any>);
}
```

| Property | Type | Description |
|----------|------|-------------|
| `path` | `string` | URL path pattern (e.g. `'/users/:id'`) |
| `name` | `string` | Optional unique name for the route |
| `component` | `ComponentFactory \| () => Promise<{ default: ComponentFactory }>` | Component to render, supports lazy loading |
| `children` | `RouteRecordRaw[]` | Nested child routes |
| `redirect` | `RouteLocationRaw \| ((to: RouteLocation) => RouteLocationRaw)` | Redirect target or function |
| `meta` | `RouteMeta` | Arbitrary metadata attached to the route |
| `beforeEnter` | `NavigationGuard \| NavigationGuard[]` | Per-route navigation guard(s) |
| `props` | `boolean \| Record<string, any> \| ((route: RouteLocation) => Record<string, any>)` | Pass route params as component props |

### RouteLocationRaw

A route location that can be passed to `router.push`, `router.replace`, or the `Link` `to` prop.

```tsx
type RouteLocationRaw = string | {
    name?: string;
    path?: string;
    params?: Record<string, string>;
    query?: Record<string, string>;
    hash?: string;
};
```

### RouteLocation

A normalized, resolved route location.

```tsx
interface RouteLocation {
    fullPath: string;            // path including query and hash
    path: string;
    name?: string;
    params: Record<string, string>;
    query: Record<string, string>;
    hash: string;
    meta: RouteMeta;
    matched: RouteRecordRaw[];
    redirectedFrom?: RouteLocation;  // set when a guard or redirect sent the navigation here
}
```

`redirectedFrom` is the basis for emitting real 30x redirects during SSR — see [SSR Routing](/router/docs/ssr#redirects-during-ssr).

### NavigationGuard

A guard signals its decision through its **return value** (no `next` callback). `from`
is `null` on the initial route resolution — guards run on the first load too. Guards run
inside the app's DI context (synchronous portion only); see [Route Guards](/router/docs/guards#guards-run-in-the-apps-di-context).

```tsx
type NavigationGuardReturn =
    | void                 // allow (same as true)
    | boolean              // true = allow, false = abort
    | string               // redirect to this path
    | RouteLocationRaw     // redirect to this location
    | Promise<void | boolean | string | RouteLocationRaw>;

type NavigationGuard = (
    to: RouteLocation,
    from: RouteLocation | null    // null on the initial navigation
) => NavigationGuardReturn;
```

### NavigationHookAfter

```tsx
type NavigationHookAfter = (
    to: RouteLocation,
    from: RouteLocation | null    // null on the initial navigation
) => void;
```

### ScrollPosition

Returned by the `scrollBehavior` callback to control where the page scrolls after navigation.

```tsx
interface ScrollPosition {
    left?: number;
    top?: number;
    el?: string | Element;
    behavior?: 'auto' | 'smooth';
}
```

| Property | Type | Description |
|----------|------|-------------|
| `left` | `number` | Pixels from the left edge |
| `top` | `number` | Pixels from the top edge |
| `el` | `string \| Element` | CSS selector or DOM element to scroll into view |
| `behavior` | `'auto' \| 'smooth'` | Scroll behavior (defaults to `'auto'`) |

When `el` is provided, the element is scrolled into view first; `top` and `left` are then applied as additional offsets (useful for fixed headers).

### ScrollBehaviorHandler

The function signature for the `scrollBehavior` option in `RouterOptions`.

```tsx
type ScrollBehaviorHandler = (
    to: RouteLocation,
    from: RouteLocation | null,
    savedPosition: { left: number; top: number } | null
) => ScrollPosition | false | void | Promise<ScrollPosition | false | void>;
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `to` | `RouteLocation` | Target route |
| `from` | `RouteLocation \| null` | Previous route (`null` on initial navigation) |
| `savedPosition` | `{ left: number; top: number } \| null` | Saved viewport position for back/forward, `null` for push/replace |

**Return values:**
- `ScrollPosition` — scroll to the given position
- `false` — skip scrolling entirely
- `void` / `undefined` — do nothing
- `Promise<...>` — async scrolling (e.g., wait for content to load)

---
url: https://sigx.dev/actors/
title: SignalX Actors - addressable, single-threaded server state
description: Virtual actors for SignalX — one activation per key, turn-based concurrency with no locks, persistent state with optimistic concurrency, and clustering when one process stops being enough.
---

---
url: https://sigx.dev/errors/
title: Error codes
description: "Every SignalX runtime error code (SIGX###) — what it means, why it fired, and how to fix it"
---

# Error codes

Every error the SignalX runtime throws carries a unique code, `SIGX001` through `SIGX999`. Production builds print that code with a link back to this reference:

```
SIGX101 "#app" — see https://sigx.dev/errors/SIGX101/
```

Follow the link for the code you hit, or find it in the table below.

## Dev builds vs production builds

The two builds report the same error differently, and each is tuned for where you read it.

**Development** gives you the full message plus a `suggestion` naming the fix:

```
Mount target "#app" not found.
```

**Production** gives you the code, the runtime detail, and this URL. The human-readable messages and suggestions are stripped — they sit behind a compile-time `__DEV__` branch that folds away during the build, so those strings never reach your production bundle. That is what keeps the runtime small, and it is why this page exists: in production the link *is* the message.

## Handling errors in code

Every runtime error is a `SigxError`, so you can branch on `code` rather than matching message text:

```ts
import { SigxError } from 'sigx';

try {
    app.mount('#app');
} catch (e) {
    if (e instanceof SigxError && e.code === 'SIGX101') {
        // the mount target isn't in the document yet
    }
}
```

| Property | Type | Notes |
|---|---|---|
| `code` | `string` | The `SIGX###` code — stable across dev and production |
| `message` | `string` | Full text in dev; code + detail + docs link in production |
| `suggestion` | `string \| undefined` | The fix hint. Dev builds only |
| `cause` | `Error \| undefined` | The underlying error, when there is one |
| `name` | `string` | Always `'SigxError'` |

`code` is the only field worth branching on. Treat `message` and `suggestion` as diagnostics for humans, not as a contract.

### Two codes that aren't SigxErrors

Most coded failures are thrown `SigxError`s. Two are not, because the packages that raise them sit outside that class:

| Code | Shape |
|---|---|
| [SIGX500](/errors/SIGX500/) | A plain `Error` — `@sigx/reactivity` sits below `SigxError` and takes no dependency on it. No `error.code`. |
| [SIGX700](/errors/SIGX700/) | Not thrown at all — `@sigx/cache` logs it with `console.error` and degrades. Nothing to catch. |

Both still print the same `SIGX### — see …` line in production, so the code is how you find them; you just can't `instanceof`-narrow to them.

## Every code

Codes are grouped into ranges by subsystem, so the number alone tells you roughly where to look.

### App lifecycle · 001–099

| Code | Meaning |
|---|---|
| [SIGX001](/errors/SIGX001/) | No mount function provided and no default set |

### Rendering & mounting · 100–199

| Code | Meaning |
|---|---|
| [SIGX100](/errors/SIGX100/) | Render target not found |
| [SIGX101](/errors/SIGX101/) | Mount target not found |
| [SIGX102](/errors/SIGX102/) | Async setup is SSR-only |
| [SIGX103](/errors/SIGX103/) | `errorScope()` called outside setup |

### Dependency injection · 200–299

| Code | Meaning |
|---|---|
| [SIGX200](/errors/SIGX200/) | `defineProvide` called outside setup |
| [SIGX201](/errors/SIGX201/) | `defineProvide` called with something that isn't an injectable |
| [SIGX202](/errors/SIGX202/) | A required injectable was never provided |
| [SIGX203](/errors/SIGX203/) | `defineFactory` setup returned a primitive |

### Hooks & async · 300–399

| Code | Meaning |
|---|---|
| [SIGX300](/errors/SIGX300/) | A hook was called outside setup |

### Messaging · 400–499

| Code | Meaning |
|---|---|
| [SIGX400](/errors/SIGX400/) | Subscribed to a destroyed topic |
| [SIGX401](/errors/SIGX401/) | Created a topic on a destroyed group |

### Reactivity · 500–599

| Code | Meaning |
|---|---|
| [SIGX500](/errors/SIGX500/) | `toSignal` wrote to a read-only property |

### Server rendering · 600–699

| Code | Meaning |
|---|---|
| [SIGX600](/errors/SIGX600/) | `hydrate()` could not find its container |
| [SIGX601](/errors/SIGX601/) | `hydrate()` found no root component on the app |
| [SIGX602](/errors/SIGX602/) | `renderDocument` found no outlet marker in the template |

### Cache · 700–799

| Code | Meaning |
|---|---|
| [SIGX700](/errors/SIGX700/) | The `@sigx/cache` revalidation trigger threw while subscribing |

## Related

- [Error handling](/core/docs/error-handling) — `errorScope` and `app.onError`, the value-first error model
- [App & plugins](/core/docs/app-plugins) — providing injectables before mount

---
url: https://sigx.dev/llms/
title: SignalX for LLMs
description: A condensed SignalX cheatsheet for AI assistants and code generators — the core API and the semantics that differ from React, Vue, and Solid
---

# SignalX for LLMs

This page is a condensed cheatsheet for AI assistants generating SignalX code. It covers the core API and — most importantly — the semantics that differ from React, Vue, and Solid.

## What SignalX is

SignalX (npm package `sigx`) is a fine-grained reactive component framework with a small tree-shakeable core. Components are TSX; state is signals; the component function never re-runs — only the exact DOM nodes that read a changed signal update. The same component model renders to the browser, native iOS/Android, terminals, and the server.

| Area | Package | Docs |
| --- | --- | --- |
| Core framework (web) | `sigx` | [/core/docs/getting-started/](/core/docs/getting-started/) |
| Router | `@sigx/router` | [/router/docs/getting-started/](/router/docs/getting-started/) |
| Store | `@sigx/store` | [/store/docs/getting-started/](/store/docs/getting-started/) |
| daisyUI components | `@sigx/daisyui` | [/daisyui/docs/getting-started/](/daisyui/docs/getting-started/) |
| Static-site generator | `@sigx/ssg` | [/ssg/docs/getting-started/](/ssg/docs/getting-started/) |
| SSR / islands | `@sigx/server-renderer`, `@sigx/ssr-islands` | [/server/](/server/) |
| Native iOS & Android | `@sigx/lynx` | [/lynx/docs/overview/](/lynx/docs/overview/) |
| Terminal UIs | `@sigx/terminal` | [/terminal/docs/getting-started/](/terminal/docs/getting-started/) |
| CLI | `@sigx/cli` | [/cli/docs/getting-started/](/cli/docs/getting-started/) |

## Quick start

```bash
npm create @sigx@latest my-app
```

Or add to an existing Vite project (`sigx` bundles the reactivity and runtime — never install `@sigx/reactivity` or `@sigx/runtime-*` directly):

```bash
npm install sigx @sigx/vite
```

```tsx
import { defineApp, component } from 'sigx';

const Counter = component(({ signal }) => {
    const state = signal({ count: 0 });

    return () => (
        <div>
            <p>Count: {state.count}</p>
            <button onClick={() => state.count++}>Increment</button>
        </div>
    );
});

defineApp(<Counter />).mount('#app');
```

## Signals — the semantics LLMs get wrong

`signal()` behaves differently depending on the value type. **This is the #1 source of generated-code bugs.**

### Primitives are wrapped in `{ value: T }`

```tsx
import { signal } from 'sigx';

const count = signal(0);       // { value: 0 }
count.value = 5;               // write via .value
count.value++;                 // read + write via .value
```

### Objects and arrays become reactive proxies — no `.value`

```tsx
import { signal } from 'sigx';

const user = signal({ id: 1, name: 'John' });
user.name = 'Jane';            // direct property access — reactive

const items = signal([1, 2, 3]);
items.push(4);                 // array mutators are reactive and batched
items[0] = 10;                 // index writes are reactive
```

Reactivity is **deep**: nested properties are reactive too. `Map`, `Set`, `WeakMap`, and `WeakSet` values are also supported (`map.set(...)` is reactive).

### `$set()` replaces a whole object/array — and exists ONLY on object/array signals

```tsx
const user = signal({ name: 'John', age: 25 });
user.$set({ name: 'Jane', age: 30 });   // replace entirely

const items = signal([1, 2, 3]);
items.$set([4, 5]);                     // items.length is now 2

const count = signal(0);
count.value = 1;                        // primitives: assign .value — count.$set() does NOT exist
```

### Destructuring a proxy loses reactivity

`const { count } = state` snapshots a plain value. Use `toSignal` / `toSignals` for live `{ value }` views that read and write through:

```tsx
import { signal, toSignal, toSignals } from 'sigx';

const state = signal({ count: 0, name: 'Ada' });
const count = toSignal(state, 'count');
count.value++;                 // state.count is now 1

const { name } = toSignals(state);
name.value = 'Grace';          // state.name is now "Grace"
```

### If you're coming from another framework

| Habit from | Wrong in SignalX | Correct in SignalX |
| --- | --- | --- |
| React | `const [count, setCount] = useState(0)`, `setCount(c => c + 1)`, re-running component body, hooks rules | `const state = signal({ count: 0 })`, then `state.count++`. The component body runs **once**; there are no hooks or dependency arrays. |
| React | Immutable updates: `setState({ ...state, x })` | Mutate directly: `state.x = value`. Use `$set()` only to replace the whole object. |
| Vue | `user.value.name` (treating `signal(object)` like a `ref`) | `signal(object)` is like Vue's `reactive()`, not `ref()` — `user.name`, no `.value`. Only primitives and `computed` use `.value`. |
| Vue | Templates, `v-model`, `v-if` | TSX: `model={() => state.name}` for two-way binding, `{cond && <X />}` for conditionals. |
| Solid | Calling signals as getters: `count()` | Signals are never functions. Primitives: `count.value`. Objects: `user.name`. |
| Solid | `const [count, setCount] = createSignal(0)` | No tuple API — `signal()` returns one wrapper/proxy object. |
| Any | Destructuring reactive state | Loses reactivity — read `state.x` in place, or use `toSignal`/`toSignals`. |

Other signal utilities: `toRaw(proxy)` (raw object), `isReactive(v)`, `untrack(() => ...)` (read without subscribing), `batch(() => ...)` (group updates).

## Computed and effects

`computed` derives a lazy, cached value — always read via `.value` (even when the dependencies are object signals):

```tsx
import { signal, computed } from 'sigx';

const state = signal({ firstName: 'John', lastName: 'Doe' });
const fullName = computed(() => `${state.firstName} ${state.lastName}`);

console.log(fullName.value);   // "John Doe"
state.firstName = 'Jane';
console.log(fullName.value);   // "Jane Doe"
```

`effect` runs immediately and re-runs when any signal it read changes; `watch` observes a specific source:

```tsx
import { signal, effect, watch } from 'sigx';

const state = signal({ count: 0 });

const runner = effect(() => {
    console.log('Count is:', state.count);
});
runner.stop();

const w = watch(
    () => state.count,
    (newValue, oldValue, onCleanup) => { /* ... */ },
    { immediate: true },
);
w.stop();   // also: w.pause(), w.resume()
```

Created **directly in a component's setup body**, both stop automatically on unmount — no handle to keep. Reactions created inside `onMounted` or an async callback are not captured; stop those in `onUnmounted`. `computed` never needs disposal.

Dependencies are tracked automatically — there are no dependency arrays.

## Components

`component()` takes a **setup function** that runs **once** (untracked) and returns a **render function**. Reactive reads belong inside the returned render closure (or in a `computed`/`watch`), not bare in setup:

```tsx
import { component, type Define } from 'sigx';

type CounterProps =
    & Define.Prop<'initial', number, false>       // optional prop (false = optional, true = required)
    & Define.Event<'change', number>              // emitted event
    & Define.Slot<'default'>;                     // slot

const Counter = component<CounterProps>(({ signal, props, emit, slots }) => {
    // setup: runs once
    const state = signal({ count: props.initial ?? 0 });

    // render closure: re-evaluated reactively where signals are read
    return () => (
        <div>
            <span>{state.count}</span>
            <button onClick={() => { state.count++; emit('change', state.count); }}>+</button>
            {slots.default?.()}
        </div>
    );
});
```

Rules that trip up generators:

- **Props stay reactive through the accessor** — read `props.x` inside the render closure; don't destructure props in setup.
- **Slots are called optionally**: `slots.default?.()`. Calling a slot the parent never passed throws. Presence check: `slots.header && <header>{slots.header?.()}</header>`.
- **Events**: declare with `Define.Event<'change', T>`, emit with `emit('change', value)`, parents listen with `onChange={...}` (camelCase `on` + capitalized event name).
- **Two-way binding**: `<input model={() => state.name} />` — a thunk returning the property, not a value.
- **Lifecycle** from the setup context: `onMounted(fn)`, `onUnmounted(fn)`, `onCreated(fn)`, `onUpdated(fn)`. Expose an API to the parent with `expose({...})` + `ref`.
- **Host attributes on a component are an opt-in**: `id`, `class`, `style`, `title`, DOM handlers and friends are accepted only when the component declares `& Define.Attrs` and forwards its leftover props. On an intrinsic element they always work.
- **Forwarding props**: `const { own, ...rest } = ctx.props` then `<el {...rest} />`. `ctx.props` never carries `key` or `ref`. To combine two sources without one clobbering the other (`class`, `style`, `on*`, `ref`), use `mergeProps(...sources)` — called once in setup, not per render.
- **Multiple roots**: wrap in `<Fragment>` (or `<>...</>`).
- **Keys**: give list items a stable `key` when mapping.

## Where to go deeper

- **Machine-readable docs:** [https://sigx.dev/llms.txt](https://sigx.dev/llms.txt) — the full index of every page's markdown rendition (per-area indexes: [/core/llms.txt](https://sigx.dev/core/llms.txt), [/lynx/llms.txt](https://sigx.dev/lynx/llms.txt)). The whole corpus in one file: [https://sigx.dev/llms-full.txt](https://sigx.dev/llms-full.txt). Any docs page is fetchable as markdown by replacing its trailing slash with `.md` (this page: [/llms.md](https://sigx.dev/llms.md)).
- [Signals](/core/docs/signals/) — full reactivity semantics
- [Computed](/core/docs/computed/) · [Effects](/core/docs/effects/) · [Components](/core/docs/components/) · [Two-way binding](/core/docs/two-way-binding/)
- [Core API reference](/core/api/)
- Every area in the table above has its own Docs and API sections under the same URL pattern